NAMESPACES 63

generated output:
fun called for 0
*/
The compiler is rather smart when handling namespaces. If Value in the namespace FBB would
have been defined as typedef int Value then FBB::Value would be recognized as int, thus
causing the Koenig lookup to fail.
As another example, consider the next program. Here two namespaces are involved, each defining
their own fun function. There is no ambiguity, since the argument defines the namespace and
FBB::fun is called:
#include <iostream>
namespace FBB
{
enum Value // defines FBB::Value
{
FIRST
};
void fun(Value x)
{
std::cout << "FBB::fun() called for " << x << ’\n’;
}
}
namespace ES
{
void fun(FBB::Value x)
{
std::cout << "ES::fun() called for " << x << ’\n’;
}
}
int main()
{
fun(FBB::FIRST); // No ambiguity: argument determines
// the namespace
}
/*
generated output:
FBB::fun() called for 0
*/
Here is an example in which there is an ambiguity: fun has two arguments, one from each namespace.
The ambiguity must be resolved by the programmer:
#include <iostream>
namespace ES
{
enum Value // defines ES::Value
{
64 CHAPTER 4. NAMESPACES
FIRST
};
}
namespace FBB
{
enum Value // defines FBB::Value
{
FIRST
};
void fun(Value x, ES::Value y)
{
std::cout << "FBB::fun() called\n";
}
}
namespace ES
{
void fun(FBB::Value x, Value y)
{
std::cout << "ES::fun() called\n";
}
}
int main()
{
// fun(FBB::FIRST, ES::FIRST); ambiguity: resolved by
// explicitly mentioning
// the namespace
ES::fun(FBB::FIRST, ES::FIRST);
}
/*
generated output:
ES::fun() called
*/
An interesting subtlety with namespaces is that definitions in one namespace may break the code
defined in another namespace. It shows that namespacesmay affect each other and that namespaces
may backfire if we’re not aware of their peculiarities. Consider the following example:
namespace FBB
{
struct Value
{};
void fun(int x);
void gun(Value x);
}
namespace ES
{
void fun(int x)
{
4.1. NAMESPACES 65
fun(x);
}
void gun(FBB::Value x)
{
gun(x);
}
}
Whatever happens, the programmer’d better not use any of the ES::fun functions since it results
in infinite recursion. However, that’s not the point. The point is that the programmer won’t even be
given the opportunity to call ES::fun since the compilation fails.
Compilation fails for gun but not for fun. But why is that so? Why is ES::fun flawlessly compiling
while ES::gun isn’t? In ES::fun fun(x) is called. As x’s type is not defined in a namespace the
Koenig lookup does not apply and fun calls itself with infinite recursion.
With ES::gun the argument is defined in the FBB namespace. Consequently, the FBB::gun function
is a possible candidate to be called. But ES::gun itself also is possible as ES::gun’s prototype
perfectly matches the call gun(x).
Now consider the situation where FBB::gun has not yet been declared. Then there is of course
no ambiguity. The programmer responsible for the ES namespace is resting happily. Some time
after that the programmer who’s maintaining the FBB namespace decides it may be nice to add
a function gun(Value x) to the FBB namespace. Now suddenly the code in the namespace ES
breaks because of an addition in a completely other namespace (FBB). Namespaces clearly are not
completely independent of each other and we should be aware of subtleties like the above. Later in
the C++ Annotations (chapter 11) we’ll return to this issue.
4.1.3 The standard namespace
The std namespace is reserved by C++. The standard defines many entities that are part of the
runtime available software (e.g., cout, cin, cerr); the templates defined in the Standard Template
Library (cf. chapter 18); and the Generic Algorithms (cf. chapter 19) are defined in the std
namespace.
Regarding the discussion in the previous section, using declarations may be used when referring
to entities in the std namespace. For example, to use the std::cout stream, the code may declare
this object as follows:
#include <iostream>
using std::cout;
Often, however, the identifiers defined in the std namespace can all be accepted without much
thought. Because of that, one frequently encounters a using directive, allowing the programmer
to omit a namespace prefix when referring to any of the entities defined in the namespace specified
with the using directive. Instead of specifying using declarations the following using directive is
frequently encountered: construction like
#include <iostream>
using namespace std;
Should a using directive, rather than using declarations be used? As a rule of thumb one might
decide to stick to using declarations, up to the point where the list becomes impractically long, at
which point a using directive could be considered.
66 CHAPTER 4. NAMESPACES
Two restrictions apply to using directives and declarations:
• Programmers should not declare or define anything inside the namespace std. This is not
compiler enforced but is imposed upon user code by the standard;
• Using declarations and directives should not be imposed upon code written by third parties.
In practice this means that using directives and declarations should be banned from header
files and should only be used in source files (cf. section 7.11.1).
4.1.3.1 The std::placeholders namespace
This section contains quite a few forward references. It merely introduces the placeholders namespace,
which is nested under the std namespace; this section can be skipped without loss of continuity.
Before using the namespace std::placeholders the <functional> header file must be included.
Further down the C++ Annotations we will encounter function objects (section 11.10), which are
‘objects’ that can be used as functions. Such function objects (also called functors) are extensively
used in the Standard Template Library (STL, chapter 18). The STL offers a function (bind, see
section 18.1.4.1), returning a function adaptor in which a function is called which may or may not
already have received its arguments. If not, then placeholders for arguments must be used, for
which actual arguments must be specified once the functor that is returned by bind is called.
Such placeholders have predefined names: _1, _2, _3, etc. These placeholders are defined in the
std::placeholders namespace. Several illustrations of the use of these placeholders are found in
section 18.1.4.1.
4.1.4 Nesting namespaces and namespace aliasing
Namespaces can be nested. Here is an example:
namespace CppAnnotations
{
int value;
namespace Virtual
{
void *pointer;
}
}
The variable value is defined in the CppAnnotations namespace. Within the CppAnnotations
namespace another namespace (Virtual) is nested. Within that latter namespace the variable
pointer is defined. To refer to these variable the following options are available:
• The fully qualified names can be used. A fully qualified name of an entity is a list of all the
namespaces that are encountered until reaching the definition of the entity. The namespaces
and entity are glued together by the scope resolution operator:
int main()
{
4.1. NAMESPACES 67
CppAnnotations::value = 0;
CppAnnotations::Virtual::pointer = 0;
}
• A using namespace CppAnnotations directive can be provided. Now value can be used
without any prefix, but pointer must be used with the Virtual:: prefix:
using namespace CppAnnotations;
int main()
{
value = 0;
Virtual::pointer = 0;
}
• A using namespace directive for the full namespace chain can be used. Now value needs its
CppAnnotations prefix again, but pointer doesn’t require a prefix anymore:
using namespace CppAnnotations::Virtual;
int main()
{
CppAnnotations::value = 0;
pointer = 0;
}
• When using two separate using namespace directives none of the namespace prefixes are
required anymore:
using namespace CppAnnotations;
using namespace Virtual;
int main()
{
value = 0;
pointer = 0;
}
• The same can be accomplished (i.e., no namespace prefixes) for specific variables by providing
specific using declarations:
using CppAnnotations::value;
using CppAnnotations::Virtual::pointer;
int main()
{
value = 0;
pointer = 0;
}
• A combination of using namespace directives and using declarations can also be used. E.g.,
a using namespace directive can be used for the CppAnnotations::Virtual namespace,
and a using declaration can be used for the CppAnnotations::value variable:
using namespace CppAnnotations::Virtual;
68 CHAPTER 4. NAMESPACES
using CppAnnotations::value;
int main()
{
pointer = 0;
}
Following a using namespace directive all entities of that namespace can be used without any
further prefix. If a single using namespace directive is used to refer to a nested namespace, then
all entities of that nested namespace can be used without any further prefix. However, the entities
defined in the more shallow namespace(s) still need the shallow namespace’s name(s). Only after
providing specific using namespace directives or using declarations namespace qualifications can
be omitted.
When fully qualified names are preferred but a long name like
CppAnnotations::Virtual::pointer
is considered too long, a namespace alias may be used:
namespace CV = CppAnnotations::Virtual;
This defines CV as an alias for the full name. The variable pointer may now be accessed using:
CV::pointer = 0;
A namespace alias can also be used in a using namespace directive or using declaration:
namespace CV = CppAnnotations::Virtual;
using namespace CV;
4.1.4.1 Defining entities outside of their namespaces
It is not strictly necessary to define members of namespaces inside a namespace region. But before
an entity is defined outside of a namespace it must have been declared inside its namespace.
To define an entity outside of its namespace its name must be fully qualified by prefixing the member
by its namespaces. The definition may be provided at the global level or at intermediate levels in the
case of nested namespaces. This allows us to define an entity belonging to namespace A::B within
the region of namespace A.
Assume the type int INT8[8] is defined in the CppAnnotations::Virtual namespace. Furthermore
assume that it is our intent to define a function squares, inside the namespace
CppAnnotations::Virtual returning a pointer to CppAnnotations::Virtual::INT8.
Having defined the prerequisites within the CppAnnotations::Virtual namespace, our function
could be defined as follows (cf. chapter 9 for coverage of the memory allocation operator new[]):
namespace CppAnnotations
{
namespace Virtual
4.1. NAMESPACES 69
{
void *pointer;
typedef int INT8[8];
INT8 *squares()
{
INT8 *ip = new INT8[1];
for (size_t idx = 0; idx != sizeof(INT8) / sizeof(int); ++idx)
(*ip)[idx] = (idx + 1) * (idx + 1);
return ip;
}
}
}
The function squares defines an array of one INT8 vector, and returns its address after initializing
the vector by the squares of the first eight natural numbers.
Now the function squares can be defined outside of the CppAnnotations::Virtual namespace:
namespace CppAnnotations
{
namespace Virtual
{
void *pointer;
typedef int INT8[8];
INT8 *squares();
}
}
CppAnnotations::Virtual::INT8 *CppAnnotations::Virtual::squares()
{
INT8 *ip = new INT8[1];
for (size_t idx = 0; idx != sizeof(INT8) / sizeof(int); ++idx)
(*ip)[idx] = (idx + 1) * (idx + 1);
return ip;
}
In the above code fragment note the following:
• squares is declared inside of the CppAnnotations::Virtual namespace.
• The definition outside of the namespace region requires us to use the fully qualified name of
the function and of its return type.
• Inside the body of the function squares we are within the CppAnnotations::Virtual
namespace, so inside the function fully qualified names (e.g., for INT8) are not required any
more.
70 CHAPTER 4. NAMESPACES
Finally, note that the function could also have been defined in the CppAnnotations region. In
that case the Virtual namespace would have been required when defining squares() and when
specifying its return type, while the internals of the function would remain the same:
namespace CppAnnotations
{
namespace Virtual
{
void *pointer;
typedef int INT8[8];
INT8 *squares();
}
Virtual::INT8 *Virtual::squares()
{
INT8 *ip = new INT8[1];
for (size_t idx = 0; idx != sizeof(INT8) / sizeof(int); ++idx)
(*ip)[idx] = (idx + 1) * (idx + 1);
return ip;
}
}

Chapter 5
The ‘string’ Data Type
C++ offers many solutions for common problems. Most of these facilities are part of the Standard
Template Library or they are implemented as generic algorithms (see chapter 19).
Among the facilities C++ programmers have developed over and over again are those manipulating
chunks of text, commonly called strings. The C programming language offers rudimentary string
support. C’s NTBS is the foundation upon which an enormous amount of code has been built1.
To process text C++ offers a std::string type. In C++ the traditional C library functions manipulating
NTB strings are deprecated in favor of using string objects. Many problems in C programs
are caused by buffer overruns, boundary errors and allocation problems that can be traced back
to improperly using these traditional C string library functions. Many of these problems can be
prevented using C++ string objects.
Actually, string objects are class type variables, and in that sense they are comparable to stream
objects like cin and cout. In this section the use of string type objects is covered. The focus is on
their definition and their use. When using string objects the member function syntax is commonly
used:
stringVariable.operation(argumentList)
For example, if string1 and string2 are variables of type std::string, then
string1.compare(string2)
can be used to compare both strings.
In addition to the commonmember functions the string class also offers a wide variety of operators,
like the assignment (=) and the comparison operator (==). Operators often result in code that is
easy to understand and their use is generally preferred over the use of member functions offering
comparable functionality. E.g., rather than writing
if (string1.compare(string2) == 0)
the following is generally preferred:
if (string1 == string2)
1An NTBS (null-terminated byte string, also NTB string) is a character sequence whose highest-addressed element with
defined content has the value zero (the terminating null character); no other character in the sequence has the value zero.
71
72 CHAPTER 5. THE ‘STRING’ DATA TYPE
To define and use string-type objects, sources must include the header file <string>. To merely
declare the string type the header iosfwd can be included.
In addition to std::string, the header file string defines the following string types:
• std::wstring, a string type consisting of wchar_t characters;
• std::u16string, a string type consisting of char16_t characters;
• std::u32string, a string type consisting of char32_t characters.
5.1 Operations on strings
Some of the operations that can be performed on strings return indices within the strings. Whenever
such an operation fails to find an appropriate index, the value string::npos is returned. This
value is a symbolic value of type string::size_type, which is (for all practical purposes) an
(unsigned) int.
All string members accepting string objects as arguments also accept char const _ (NTBS)
arguments. The same usually holds true for operators accepting string objects.
Some string-members use iterators. Iterators are formally introduced in section 18.2. Member
functions using iterators are listed in the next section (5.2), but the iterator concept itself is not
further covered by this chapter.
Strings support a large variety of members and operators. A short overview listing their capabilities
is provided in this section, with subsequent sections offering a detailed discussion. The bottom line:
C++ strings are extremely versatile and there is hardly a reason for falling back on the C library to
process text. C++ strings handle all the required memory management and thus memory related
problems, which is the #1 source of problems in C programs, can be prevented when C++ strings are
used. Strings do come at a price, though. The class’s extensive capabilities have also turned it into
a beast. It’s hard to learn and master all its features and in the end you’ll find that not all that you
expected is actually there. For example, std::string doesn’t offer case-insensitive comparisons.
But in the end it isn’t even as simple as that. It is there, but it is somewhat hidden and at this
point in the C++ Annotations it’s too early to study into that hidden corner yet. Instead, realize
that C’s standard library does offer useful functions that can be used as long as we’re aware of their
limitations and are able to avoid their traps. So for now, to perform a traditional case-insensitive
comparison of the contents of two std::string objects str1 and str2 the following will do:
strcasecmp(str1.c_str(), str2.c_str());
Strings support the following functionality:
• initialization:
when string objects are defined they are always properly initialized. In other words,
they are always in a valid state. Strings may be initialized empty or already existing
text can be used to initialize strings.
• assignment:
strings may be given new values. New values may be assigned using member functions
(like assign) but a plain assignment operator (i.e., =)may also be used. Furthermore,
assignment to a character buffer is also supported.
5.2. A STD::STRING REFERENCE 73
• conversions:
the partial or complete contents of string objects may be interpreted as C strings
but the string’s contents may also be processed as a series of raw binary bytes, not
necessarily terminating in a 0-valued character. Furthermore, in many situations
plain characters and C strings may be used where std::strings are accepted as
well.
• breakdown:
the individual characters stored in a string can be accessed using the familiar index
operator ([]) allowing us to either access or modify information in the middle of a
string.
• comparisons:
strings may be compared to other strings (NTB strings) using the familiar logical
comparison operators ==, !=, <, <=, > and >=. There are also member functions
available offering a more fine-grained comparison.
• modification:
the contents of strings may be modified in many ways. Operators are available to add
information to string objects, to insert information in the middle of string objects, or
to replace or erase (parts of) a string’s contents.
• swapping:
the string’s swapping capability allows us in principle to exchange the contents of two
string objects without a byte-by-byte copying operation of the string’s contents.
• searching:
the locations of characters, sets of characters, or series of characters may be searched
for from any position within the string object and either searching in a forward or
backward direction.
• housekeeping:
several housekeeping facilities are offered: the string’s length, or its empty-state may
be interrogated. But string objects may also be resized.
• stream I/O:
strings may be extracted from or inserted into streams. In addition to plain string
extraction a line of a text file may be read without running the risk of a buffer overrun.
Since extraction and insertion operations are stream based the I/O facilities are
device independent.
5.2 A std::string reference
In this section the string members and string-related operations are referenced. The subsections
cover, respectively the string’s initializers, iterators, operators, and member functions. The following
terminology is used throughout this section:
• object is always a string-object;
74 CHAPTER 5. THE ‘STRING’ DATA TYPE
• argument is a string const & or a char const _ unless indicated otherwise. The contents
of an argument never is modified by the operation processing the argument;
• opos refers to an offset into an object string;
• apos refers to an offset into an argument;
• on represents a number of characters in an object (starting at opos);
• an represents a number of characters in an argument (starting at apos).
Both opos and apos must refer to existing offsets, or an exception (cf. chapter 10) is generated. In
contrast, an and on may exceed the number of available characters, in which case only the available
characters are considered.
Many members declare default values for on, an and apos. Some members declare default values
for opos. Default offset values are 0, the default values of on and an is string::npos, which can
be interpreted as ‘the required number of characters to reach the end of the string’.
With members starting their operations at the end of the string object’s contents proceeding backwards,
the default value of opos is the index of the object’s last character, with on by default equal
to opos + 1, representing the length of the substring ending at opos.
In the overview of member functions presented below it may be assumed that all these parameters
accept default values unless indicated otherwise. Of course, the default argument values cannot be
used if a function requires additional arguments beyond the ones otherwise accepting default values.
Some members have overloaded versions expecting an initial argument of type char const _. But
even if that is not the case the first argument can always be of type char const _ where a parameter
of std::string is defined.
Several member functions accept iterators. Section 18.2 covers the technical aspects of iterators,
but these may be ignored at this point without loss of continuity. Like apos and opos, iterators
must refer to existing positions and/or to an existing range of characters within the string object’s
contents.
All string-member functions computing indices return the predefined constant string::npos on
failure.
The C++14 standard offers the s literal suffix to indicate that a std::string constant is intended
when a string literal (like "hello world") is used. When string literals are used in the context of
std::string objects, this literal suffix is hardly ever required, but it may come in handy when using
the auto keyword. E.g., auto str = "hello world"s defines std::string str, whereas
it would have been a char const _ if the literal suffix had been omitted.
5.2.1 Initializers
After defining string objects they are guaranteed to be in a valid state. At definition time string
objects may be initialized in one of the following ways: The following string constructors are available:
• string object:
initializes object to an empty string. When defining a string this way no argument
list may be specified;
5.2. A STD::STRING REFERENCE 75
• string object(string::size_type count, char ch):
initializes object with count characters ch;
• string object(string const &argument):
initializes object with argument;
• string object(std::string const &argument, string::size_type apos,
string::size_type an):
initializes object with argument’s contents starting at index position apos, using
at most an of argument’s characters;
• string object(InputIterator begin, InputIterator end):
initializes object with the characters in the range of characters defined by the two
InputIterators.
5.2.2 Iterators
See section 18.2 for details about iterators. As a quick introduction to iterators: an iterator acts
like a pointer, and pointers can often be used in situations where iterators are requested. Iterators
usually come in pairs, defining a range of entities. The begin-iterator points to the first entity, the
end-iterator points just beyond the last entity of the range. Their difference is equal to the number
of entities in the iterator-range.
Iterators play an important role in the context of generic algorithms (cf. chapter 19). The class
std::string defines the following iterator types:
• string::iterator and string::const_iterator:
these iterators are forward iterators. The const_iterator is returned by string
const objects, the plain iterator is returned by non-const string objects. Characters
referred to by iterators may be modified;
• string::reverse_iterator and string::reverse_const_iterator:
these iterators are also forward iterators but when incrementing the iterator the previous
character in the string object is reached. Other than that they are comparable
to, respectively, string::iterator and string::const_iterator.
5.2.3 Operators
String objects may be manipulated by member functions but also by operators. Using operators
often results in more natural-looking code. In cases where operators are available having equivalent
functionality as member function the operator is practically always preferred.
The following operators are available for string objects (in the examples ‘object’ and ‘argument’
refer to existing std::string objects).
• plain assignment:
a character, C or C++ string may be assigned to a string object. The assignment
operator returns its left-hand side operand. Example:
object = argument;
76 CHAPTER 5. THE ‘STRING’ DATA TYPE
object = "C string";
object = ’x’;
object = 120; // same as object = ’x’
• addition:
the arithmetic additive assignment operator and the addition operator add text to
a string object. The compound assignment operator returns its left-hand side
operand, the addition operator returns its result in a temporary string object. When
using the addition operator either the left-hand side operand or the right-hand side
operandmust be a std::string object. The other operand may be a char, a C string
or a C++ string. Example:
object += argument;
object += "hello";
object += ’x’; // integral expressions are OK
argument + otherArgument; // two std::string objects
argument + "hello"; // using + at least one
"hello" + argument; // std::string is required
argument + ’a’; // integral expressions are OK
’a’ + argument;
• index operator:
The index operator may be used to retrieve object’s individual characters, or to
assign new values to individual characters of a non-const string object. There is no
range-checking (use the at() member function for that). This operator returns a
char & or char const &. Example:
object[3] = argument[5];
• logical operators:
the logical comparison operators may be applied to two string objects or to a string
object and a C string to compare their contents. These operators return a bool value.
The ==, !=, >, >=, <, and <= operators are available. The ordering operators
perform a lexicographical comparison of their contents using the ASCII character
collating sequence. Example:
object == object; // true
object != (object + ’x’); // true
object <= (object + ’x’); // true
• stream related operators:
the insertion-operator (cf. section 3.1.4) may be used to insert a string object into
an ostream, the extraction-operator may be used to extract a string object from an
istream. The extraction operator by default first ignores all white space characters
and then extracts all consecutively non-blank characters from an istream. Instead
of a string a character array may be extracted as well, but the advantage of using a
string object should be clear: the destination string object is automatically resized to
the required number of characters. Example:
cin >> object;
cout << object;
5.2. A STD::STRING REFERENCE 77
5.2.4 Member functions
The std::string class offers many member function as well as additional non-member functions
that should be considered part of the string class. All these functions are listed below in alphabetic
order.
The symbolic value string::npos is defined by the string class. It represents ‘index-not-found’
when returned by member functions returning string offset positions. Example: when calling
‘object.find(’x’)’ (see below) on a string object not containing the character ’x’, npos is returned,
as the requested position does not exist.
The final 0-byte used in C strings to indicate the end of an NTBS is not considered part of a C++
string, and so the member function will return npos, rather than length() when looking for 0 in a
string object containing the characters of a C string.
Here are the standard functions that operate on objects of the class string. When a parameter
of size_t is mentioned it may be interpreted as a parameter of type string::size_type,
but without defining a default argument value. The type size_type should be read as
string::size_type. With size_type the default argument values mentioned in section 5.2 apply.
All quoted functions are member functions of the class std::string, except where indicated
otherwise.
• char &at(size_t opos):
a reference to the character at the indicated position is returned. When called with
string const objects a char const & is returned. The member function performs
range-checking, raising an exception (that by default aborts the program) if an invalid
index is passed.
• string &append(InputIterator begin, InputIterator end):
the characters in the range defined by begin and end are appended to the current
string object.
• string &append(string const &argument, size_type apos, size_type an):
argument (or a substring) is appended to the current string object.
• string &append(char const _argument, size_type an):
the first an characters of argument are appended to the string object.
• string &append(size_type n, char ch):
n characters ch are appended to the current string object.
• string &assign(string const &argument, size_type apos, size_type an):
argument (or a substring) is assigned to the string object. If argument is of type
char const _ and one additional argument is provided the second argument is interpreted
as a value initializing an, using 0 to initialize apos.
• string &assign(size_type n, char ch):
n characters ch are assigned to the current string object.
• char &back():
returns a reference to the last char stored inside the string object. The result is
undefined for empty strings.
78 CHAPTER 5. THE ‘STRING’ DATA TYPE
• string::iterator begin():
an iterator referring to the first character of the current string object is returned.
With const string objects a const_iterator is returned.
• size_type capacity() const:
the number of characters that can currently be stored in the string object without
needing to resize it is returned.
• string::const_iterator cbegin():
a const_iterator referring to the first character of the current string object is
returned.
• string::const_iterator cend():
a const_iterator referring to the end of the current string object is returned.
• int compare(string const &argument) const:
the text stored in the current string object and the text stored in argument is compared
using a lexicographical comparison using the ASCII character collating sequence.
zero is returned if the two strings have identical contents, a negative value
is returned if the text in the current object should be ordered before the text in
argument; a positive value is returned if the text in the current object should be
ordered beyond the text in argument.
• int compare(size_t opos, size_t on, string const &argument) const:
a substring of the text stored in the current string object is compared to the text
stored in argument. At most on characters starting at offset opos are compared to
the text in argument.
• int compare(size_t opos, size_t on, string const &argument, size_type
apos, size_type an):
a substring of the text stored in the current string object is compared to a substring
of the text stored in argument. At most on characters of the current string object,
starting at offset opos, are compared to at most an characters of argument, starting
at offset apos. In this case argument must be a string object.
• int compare(size_t opos, size_t on, char const _argument, size_t an):
a substring of the text stored in the current string object is compared to a substring of
the text stored in argument. At most on characters of the current string object starting
at offset opos are compared to at most an characters of argument. Argument
must have at least an characters. The characters may have arbitrary values: 0-
valued characters have no special meanings.
• size_t copy(char _argument, size_t on, size_type opos) const:
the contents of the current string object are (partially) copied into argument. The
actual number of characters copied is returned. The second argument, specifying the
number of characters to copy, from the current string object is required. No 0-valued
character is appended to the copied string but can be appended to the copied text
using an idiom like the following:
argument[object.copy(argument, string::npos)] = 0;
Of course, the programmer should make sure that argument’s size is large enough
to accomodate the additional 0-byte.
5.2. A STD::STRING REFERENCE 79
• string::const_reverse_iterator crbegin():
a const_reverse_iterator referring to the last character of the current string
object is returned.
• string::const_reverse_iterator crend():
a const_reverse_iterator referring to the begin of the current string object is
returned.
• char const _c_str() const:
the contents of the current string object as an NTBS.
• char const _data() const:
the raw contents of the current string object are returned. Since thismember does not
return an NTBS (as c_str does), it can be used to retrieve any kind of information
stored inside the current string object including, e.g., series of 0-bytes:
string s(2, 0);
cout << static_cast<int>(s.data()[1]) << ’\n’;
• bool empty() const:
true is returned if the current string object contains no data.
• string::iterator end():
an iterator referring to the position just beyond the last character of the current
string object is returned. With const string objects a const_iterator is returned.
• string &erase(size_type opos, size_type on):
a (sub)string of the information stored in the current string object is erased.
• string::iterator erase(string::iterator begin, string::iterator end):
the parameter end is optional. If omitted the value returned by the current object’s
end member is used. The characters defined by the begin and end iterators are
erased. The iterator begin is returned, which is then referring to the position immediately
following the last erased character.
• size_t find(string const &argument, size_type opos) const:
the first index in the current string object where argument is found is returned.
• size_t find(char const _argument, size_type opos, size_type an) const:
the first index in the current string object where argument is found is returned.
When all three arguments are specified the first argument must be a char const
_.
• size_t find(char ch, size_type opos) const:
the first index in the current string object where ch is found is returned.
• size_t find_first_of(string const &argument, size_type opos) const:
the first index in the current string object where any character in argument is found
is returned.
80 CHAPTER 5. THE ‘STRING’ DATA TYPE
• size_type find_first_of(char const _argument, size_type opos, size_type
an) const:
the first index in the current string object where any character in argument is found
is returned. If opos is provided it refers to the first index in the current string object
where the search for argument should start. If omitted, the string object is scanned
completely. If an is provided it indicates the number of characters of the char const
_ argument that should be used in the search. It defines a substring starting at the
beginning of argument. If omitted, all of argument’s characters are used.
• size_type find_first_of(char ch, size_type opos):
the first index in the current string object where character ch is found is returned.
• size_t find_first_not_of(char ch, size_type opos) const:
the first index in the current string object where another character than ch is found
is returned.
• size_t find_last_of(string const &argument, size_type opos) const:
the last index in the current string object where any character in argument is found
is returned.
• size_type find_last_of(char const _argument, size_type opos, size_type
an) const:
the last index in the current string object where any character in argument is found
is returned. If opos is provided it refers to the last index in the current string object
where the search for argument should start. If omitted, the string object is scanned
completely. If an is provided it indicates the number of characters of the char const
_ argument that should be used in the search. It defines a substring starting at the
beginning of argument. If omitted, all of argument’s characters are used.
• size_type find_last_of(char ch, size_type opos):
the last index in the current string object where character ch is found is returned.
• size_t find_last_not_of(string const &argument, size_type opos) const:
the last index in the current string object where any character not appearing in
argument is found is returned.
• char &front():
returns a reference to the first char stored inside the string object. The result is
undefined for empty strings.
• allocator_type get_allocator():
returns the allocator of the class std::string
• istream &std::getline(istream &istr, string &object, char delimiter =
’\n’):
Note: this is not a member function of the class string.
A line of text is read from istr. All characters until delimiter (or the end of the
stream, whichever comes first) are read from istr and are stored in object. If the
delimiter is encountered it is removed from the stream, but is not stored in line.
If the delimiter is not found, istr.eof returns true (see section 6.3.1). Since
5.2. A STD::STRING REFERENCE 81
streams may be interpreted as bool values (cf. section 6.3.1) a commonly encountered
idiom to read all lines from a stream successively into a string object line
looks like this:
while (getline(istr, line))
process(line);
The contents of the last line, whether or not it was terminated by a delimiter, is
eventually also assigned to object.
• string &insert(size_t opos, string const &argument, size_type apos,
size_type an):
a (sub)string of argument is inserted into the current string object at the current
string object’s index position opos. Arguments for apos and an must either both be
provided or they must both be omitted.
• string &insert(size_t opos, char const _argument, size_type an):
argument (of type char const _) is inserted at index opos into the current string
object.
• string &insert(size_t opos, size_t count, char ch):
Count characters ch are inserted at index opos into the current string object.
• string::iterator insert(string::iterator begin, char ch):
the character ch is inserted at the current object’s position referred to by begin.
Begin is returned.
• string::iterator insert(string::iterator begin, size_t count, char ch):
Count characters ch are inserted at the current object’s position referred to by begin.
Begin is returned.
• string::iterator insert(string::iterator begin, InputIterator abegin,
InputIterator aend):
the characters in the range defined by the InputIterators abegin and aend are
inserted at the current object’s position referred to by begin. Begin is returned.
• size_t length() const:
the number of characters stored in the current string object is returned.
• size_t max_size() const:
the maximum number of characters that can be stored in the current string object is
returned.
• void pop_back():
The string’s last character is removed from the string object.
• void push_back(char ch):
The character ch is appended to the string object.
• string::reverse_iterator rbegin():
a reverse iterator referring to the last character of the current string object is returned.
With const string objects a reverse_const_iterator is returned.
82 CHAPTER 5. THE ‘STRING’ DATA TYPE
• string::iterator rend():
a reverse iterator referring to the position just before the first character of the current
string object is returned. With const string objects a reverse_const_iterator is
returned.
• string &replace(size_t opos, size_t on, string const &argument,
size_type apos, size_type an):
a (sub)string of characters in object are replaced by the (subset of) characters of
argument. If on is specified as 0 argument is inserted into object at offset opos.
• string &replace(size_t opos, size_t on, char const _argument, size_type
an):
a series of characters in object are replaced by the first an characters of char
const _ argument.
• string &replace(size_t opos, size_t on, size_type count, char ch):
on characters of the current string object, starting at index position opos, are replaced
by count characters ch.
• string &replace(string::iterator begin, string::iterator end, string
const &argument):
the series of characters in the current string object defined by the iterators begin
and end are replaced by argument. If argument is a char const _, an additional
argument an may be used, specifying the number of characters of argument that are
used in the replacement.
• string &replace(string::iterator begin, string::iterator end, size_type
count, char ch):
the series of characters in the current string object defined by the iterators begin
and end are replaced by count characters having values ch.
• string &replace(string::iterator begin, string::iterator end,
InputIterator abegin, InputIterator aend):
the series of characters in the current string object defined by the iterators begin
and end are replaced by the characters in the range defined by the InputIterators
abegin and aend.
• void reserve(size_t request):
the current string object’s capacity is changed to at least request. After calling
this member, capacity’s return value will be at least request. A request
for a smaller size than the value returned by capacity is ignored. A
std::length_error exception is thrown if request exceeds the value returned
by max_size (std::length_error is defined in the stdexcept header). Calling
reserve() has the effect of redefining a string’s capacity, not of actually making
available the memory to the program. This is illustrated by the exception thrown by
the string’s at() member when trying to access an element exceeding the string’s
size but not the string’s capacity.
• void resize(size_t size, char ch = 0):
the current string object is resized to size characters. If the string object is resized
to a size larger than its current size the additional characters will be initialized to
ch. If it is reduced in size the characters having the highest indices are chopped off.
5.2. A STD::STRING REFERENCE 83
• size_t rfind(string const &argument, size_type opos) const:
the last index in the current string object where argument is found is returned.
Searching proceeds from the current object’s offset opos back to its beginning.
• size_t rfind(char const _argument, size_type opos, size_type an) const:
the last index in the current string object where argument is found is returned.
Searching proceeds from the current object’s offset opos back to its beginning. The
parameter an specifies the length of the substring of argument to look for, starting
at argument’s beginning.
• size_t rfind(char ch, size_type opos)const:
the last index in the current string object where ch is found is returned. Searching
proceeds from the current object’s offset opos back to its beginning.
• void shrink_to_fit():
optionally reduces the amount of memory allocated by a vector to its current size.
The implementor is free to ignore or otherwise optimize this request. In order to
guarantee a ‘shrink to fit’ operation the
string(stringObject).swap(stringObject)
idiom can be used.
• size_t size() const:
the number of characters stored in the current string object is returned. This member
is a synonym of length().
• string substr(size_type opos, size_type on) const:
a substring of the current string object of at most on characters starting at index
opos is returned.
• void swap(string &argument):
the contents of the current string object are swapped with the contents of argument.
For this member argument must be a string object and cannot be a char const _.
5.2.5 Conversion functions
Several string conversion functions are available operating on or producing std::string objects.
These functions are listed below in alphabetic order. They are not member functions, but class-less
(free) functions declared in the std namespace. The <string> header file must be included before
they can be used.
• float stof(std::string const &str, size_t _pos = 0):
Initial white space characters in str are ignored. Then the following sequences of
characters are converted to a float value, which is returned:
– A decimal floating point constant:
_ An optional + or - character
_ A series of decimal digits, possibly containing one decimal point character
_ An optional e or E character, followed by an optional - or + character, followed
by a series of decimal digits
84 CHAPTER 5. THE ‘STRING’ DATA TYPE
– A hexadecimal floating point constant:
_ An optional + or - character
_ 0x or 0X
_ A series of hexadecimal digits, possibly containing one decimal point character
_ An optional p or P character, followed by an optional - or + character, followed
by a series of decimal digits
– An infinity expression:
_ An optional + or - character
_ The words inf or infinity (case insensitive words)
– A ‘not a number’ expression:
_ An optional + or - character
_ The words nan or nan(alphanumeric character sequence) (nan is a
case insensitive word), resulting in a NaN floating point value
If pos != 0 the index of the first character in str which was not converted is returned
in _pos. A std::invalid_argument exception is thrown if the characters
in str could not be converted to a float, a std::out_of_range exception is thrown
if the converted value would have exceeded the range of float values.
• double stod(std::string const &str, size_t _pos = 0):
A conversion as described with stof is performed, but now to a value of type double.
• double stold(std::string const &str, size_t _pos = 0):
A conversion as described with stof is performed, but now to a value of type long
double.
• int stoi(std::string const &str, size_t _pos = 0, int base = 10):
Initial white space characters in str are ignored. Then all characters representing
numeric constants of the number system whose base is specified are converted to
an int value, which is returned. An optional + or - character may prefix the numeric
characters. Values starting with 0 are automatically interpreted as octal values,
values starting with 0x or 0X as hexadecimal characters. The value base must
be between 2 and 36. If pos != 0 the index of the first character in str which was
not converted is returned in _pos. A std::invalid_argument exception is thrown
if the characters in str could not be converted to an int, a std::out_of_range
exception is thrown if the converted value would have exceeded the range of int
values.
Here is an example of its use:
int value = stoi(string(" -123")); // assigns value -123
value = stoi(string(" 123"), 0, 5); // assigns value 38
• long stol(std::string const &str, size_t _pos = 0, int base = 10):
A conversion as described with stoi is performed, but now to a value of type long.
• long long stoll(std::string const &str, size_t _pos = 0, int base = 10):
A conversion as described with stoi is performed, but now to a value of type long
long.
• unsigned long stoul(std::string const &str, size_t _pos = 0, int base =
10):
A conversion as described with stoi (not allowing an initial + or - character) is performed,
but now to a value of type unsigned long.
5.2. A STD::STRING REFERENCE 85
• unsigned long long stoull(std::string const &str, size_t _pos = 0, int
base = 10):
A conversion as described with stoul is performed, but now to a value of type
unsigned long long.
• std::string to_string(Type value):
Type can be of the types int, long, long long, unsigned, unsigned long,
unsigned long long, float, double, or long double. The value of the argument
is converted to a textual representation, which is returned as a std::string
value.
• std::string to_wstring(Type value):
The conversion as described at to_string is performed, returning a std::wstring.
86 CHAPTER 5. THE ‘STRING’ DATA TYPE

Chapter 6
The IO-stream Library
Extending the standard stream (FILE) approach, well known from the C programming language,
C++ offers an input/output (I/O) library based on class concepts.
All C++ I/O facilities are defined in the namespace std. The std:: prefix is omitted below, except
for situations where this would result in ambiguities.
Earlier (in chapter 3) we’ve seen several examples of the use of the C++ I/O library, in particular
showing insertion operator (<<) and the extraction operator (>>). In this chapter we’ll cover I/O in
more detail.
The discussion of input and output facilities provided by the C++ programming language heavily
uses the class concept and the notion of member functions. Although class construction has not
yet been covered (for that see chapter 7) and although inheritance is not covered formally before
chapter 13, it is quite possible to discuss I/O facilities long before the technical background of class
construction has been covered.
Most C++ I/O classes have names starting with basic_ (like basic_ios). However, these basic_
names are not regularly found in C++ programs, as most classes are also defined using typedef
definitions like:
typedef basic_ios<char> ios;
Since C++ supports various kinds of character types (e.g., char, wchar_t), I/O facilities were developed
using the template mechanism allowing for easy conversions to character types other than the
traditional char type. As elaborated in chapter 21, this also allows the construction of generic software,
that could thereupon be used for any particular type representing characters. So, analogously
to the above typedef there exists a
typedef basic_ios<wchar_t> wios;
This type definition can be used for the wchar_t type. Because of the existence of these type definitions,
the basic_ prefix was omitted from the C++ Annotations without loss of continuity. The C++
Annotations primarily focus on the standard 8-bits char type.
Iostream objects cannot be declared using standard forward declarations, like:
class std::ostream; // now erroneous
87
88 CHAPTER 6. THE IO-STREAM LIBRARY
Instead, to declare iostream classes the <iosfwd> header file should be included:
#include <iosfwd> // correct way to declare iostream classes
Using C++ I/O offers the additional advantage of type safety. Objects (or plain values) are inserted
into streams. Compare this to the situation commonly encountered in C where the fprintf function
is used to indicate by a format string what kind of value to expect where. Compared to this latter
situation C++’s iostream approach immediately uses the objects where their values should appear,
as in
cout << "There were " << nMaidens << " virgins present\n";
The compiler notices the type of the nMaidens variable, inserting its proper value at the appropriate
place in the sentence inserted into the cout iostream.
Compare this to the situation encountered in C. Although C compilers are getting smarter and
smarter, and although a well-designed C compiler may warn you for a mismatch between a format
specifier and the type of a variable encountered in the corresponding position of the argument list
of a printf statement, it can’t do much more than warn you. The type safety seen in C++ prevents
you from making type mismatches, as there are no types to match.
Apart from this, iostreams offer more or less the same set of possibilities as the standard FILE-
based I/O used in C: files can be opened, closed, positioned, read, written, etc.. In C++ the basic
FILE structure, as used in C, is still available. But C++ adds to this I/O based on classes, resulting
in type safety, extensibility, and a clean design.
In the ANSI/ISO standard the intent was to create architecture independent I/O. Previous implementations
of the iostreams library did not always comply with the standard, resulting in many
extensions to the standard. The I/O sections of previously developed software may have to be partially
rewritten. This is tough for those who are now forced to modify old software, but every feature
and extension that was once available can be rebuilt easily using ANSI/ISO standard conforming
I/O. Not all of these reimplementations can be covered in this chapter, as many reimplementations
rely on inheritance and polymorphism, which topics are formally covered by chapters 13 and 14.
Selected reimplementations are provided in chapter 24, and in this chapter references to particular
sections in other chapters are given where appropriate. This chapter is organized as follows (see
also Figure 6.1):
• The class ios_base is the foundation upon which the iostreams I/O library was built. It
defines the core of all I/O operations and offers, among other things, facilities for inspecting
the state of I/O streams and for output formatting.
• The class ios was directly derived fromios_base. Every class of the I/O library doing input or
output is itself derived fromthis ios class, and so inherits its (and, by implication, ios_base’s)
capabilities. The reader is urged to keep this in mind while reading this chapter. The concept
of inheritance is not discussed here, but rather in chapter 13.
The class ios is important in that it implements the communication with a buffer that is
used by streams. This buffer is a streambuf object which is responsible for the actual I/O
to/from the underlying device. Consequently iostream objects do not perform I/O operations
themselves, but leave these to the (stream)buffer objects with which they are associated.
• Next, basic C++ output facilities are discussed. The basic class used for output operations
is ostream, defining the insertion operator as well as other facilities writing information to
streams. Apart from inserting information into files it is possible to insert information into
memory buffers, for which the ostringstream class is available. Formatting output is to a
89
Figure 6.1: Central I/O Classes
90 CHAPTER 6. THE IO-STREAM LIBRARY
great extent possible using the facilities defined in the ios class, but it is also possible to insert
formatting commands directly into streams using manipulators. This aspect of C++ output is
discussed as well.
• Basic C++ input facilities are implemented by the istream class. This class defines the extraction
operator and related input facilities. Comparably to inserting information into memory
buffers (using ostringstream) a class istringstream is available to extract information
from memory buffers.
• Finally, several advanced I/O-related topics are discussed. E.g., reading and writing from the
same stream and mixing C and C++ I/O using filebuf objects. Other I/O related topics are
covered elsewhere in the C++ Annotations, e.g., in chapter 24.
Stream objects have a limited but important role: they are the interface between, on the one hand,
the objects to be input or output and, on the other hand, the streambuf, which is responsible for
the actual input and output to the device accessed by a streambuf object.
This approach allows us to construct a new kind of streambuf for a new kind of device, and use that
streambuf in combination with the ‘good old’ istream- and ostream-class facilities. It is important
to understand the distinction between the formatting roles of iostream objects and the buffering
interface to an external device as implemented in a streambuf object. Interfacing to new devices
(like sockets or file descriptors) requires the construction of a new kind of streambuf, rather than a
new kind of istream or ostream object. A wrapper class may be constructed around the istream
or ostream classes, though, to ease the access to a special device. This is how the stringstream
classes were constructed.
6.1 Special header files
Several iostream related header files are available. Depending on the situation at hand, the following
header files should be used:
• iosfwd: sources should include this header file if only a declaration of the stream classes is
required. For example, if a function defines a reference parameter to an ostream then the
compiler does not need to know exactly what an ostream is. When declaring such a function
the ostream class merely needs to be be declared. One cannot use
class std::ostream; // erroneous declaration
void someFunction(std::ostream &str);
but, instead, one should use:
#include <iosfwd> // correctly declares class ostream
void someFunction(std::ostream &str);
• <ios>: sources should include this header file when using types and facilites (like
ios::off_type, see below) defined in the ios class.
• <streambuf>: sources should include this header file when using streambuf or filebuf
classes. See sections 14.8 and 14.8.2.
• <istream>: sources should include this preprocessor directive when using the class istream
or when using classes that do both input and output. See section 6.5.1.
6.2. THE FOUNDATION: THE CLASS ‘IOS_BASE’ 91
• <ostream>: sources should include this header file when using the class ostream class or
when using classes that do both input and output. See section 6.4.1.
• <iostream>: sources should include this header file when using the global stream objects
(like cin and cout).
• <fstream>: sources should include this header file when using the file stream classes. See
sections 6.4.2, 6.5.2, and 6.6.3.
• <sstream>: sources should include this header file when using the string stream classes. See
sections 6.4.3 and 6.5.3.
• <iomanip>: sources should include this header file when using parameterized manipulators.
See section 6.3.2.
6.2 The foundation: the class ‘ios_base’
The class std::ios_base forms the foundation of all I/O operations, and defines, among other
things, facilities for inspecting the state of I/O streams and most output formatting facilities. Every
stream class of the I/O library is, through the class ios, derived from this class, and inherits its
capabilities. As ios_base is the foundation on which all C++ I/O was built, we introduce it here as
the first class of the C++ I/O library.
Note that, as in C, I/O in C++ is not part of the language (although it is part of the ANSI/ISO
standard on C++). Although it is technically possible to ignore all predefined I/O facilities, nobody
does so, and the I/O library therefore represents a de facto I/O standard for C++. Also note that,
as mentioned before, the iostream classes themselves are not responsible for the eventual I/O, but
delegate this to an auxiliary class: the class streambuf or its derivatives.
It is neither possible nor required to construct an ios_base object directly. Its construction is
always a side-effect of constructing an object further down the class hierarchy, like std::ios. Ios
is the next class down the iostream hierarchy (see figure 6.1). Since all stream classes in turn inherit
from ios, and thus also from ios_base, the distinction between ios_base and ios is in practice
not important. Therefore, facilities actually provided by ios_base will be discussed as facilities
provided by ios. The reader who is interested in the true class in which a particular facility is
defined should consult the relevant header files (e.g., ios_base.h and basic_ios.h).
6.3 Interfacing ‘streambuf’ objects: the class ‘ios’
The std::ios class is derived directly from ios_base, and it defines de facto the foundation for all
stream classes of the C++ I/O library.
Although it is possible to construct an ios object directly, this is seldom done. The purpose of the
class ios is to provide the facilities of the class basic_ios, and to add several new facilites, all
related to the streambuf object which is managed by objects of the class ios.
All other stream classes are either directly or indirectly derived fromios. This implies, as explained
in chapter 13, that all facilities of the classes ios and ios_base are also available to other stream
classes. Before discussing these additional stream classes, the features offered by the class ios (and
by implication: by ios_base) are now introduced.
In some cases it may be required to include ios explicitly. An example is the situations where the
formatting flags themselves (cf. section 6.3.2.2) are referred to in source code.
92 CHAPTER 6. THE IO-STREAM LIBRARY
The class ios offers several member functions, most of which are related to formatting. Other
frequently used member functions are:
• std::streambuf _ios::rdbuf():
A pointer to the streambuf object forming the interface between the ios object and
the device with which the ios object communicates is returned. See sections 14.8
and 24.1.2 for more information about the class streambuf.
• std::streambuf _ios::rdbuf(std::streambuf _new):
The current ios object is associated with another streambuf object. A pointer to the
ios object’s original streambuf object is returned. The object to which this pointer
points is not destroyed when the stream object goes out of scope, but is owned by the
caller of rdbuf.
• std::ostream _ios::tie():
A pointer to the ostream object that is currently tied to the ios object is returned
(see the nextmember). The return value 0 indicates that currently no ostream object
is tied to the ios object. See section 6.5.5 for details.
• std::ostream _ios::tie(std::ostream _outs):
The ostream object is tied to current ios object. This means that the ostream object
is flushed every time before an input or output action is performed by the current ios
object. A pointer to the ios object’s original ostream object is returned. To break
the tie, pass the argument 0. See section 6.5.5 for an example.
6.3.1 Condition states
Operations on streams may fail for various reasons. Whenever an operation fails, further operations
on the stream are suspended. It is possible to inspect, set and possibly clear the condition state
of streams, allowing a program to repair the problem rather than having to abort. The members
that are available for interrogating or manipulating the stream’s state are described in the current
section.
Conditions are represented by the following condition flags:
• ios::badbit:
if this flag has been raised an illegal operation has been requested at the level of the
streambuf object to which the stream interfaces. See the member functions below
for some examples.
• ios::eofbit:
if this flag has been raised, the ios object has sensed end of file.
• ios::failbit:
if this flag has been raised, an operation performed by the stream object has failed
(like an attempt to extract an int when no numeric characters are available on input).
In this case the stream itself could not performthe operation that was requested
of it.
6.3. INTERFACING ‘STREAMBUF’ OBJECTS: THE CLASS ‘IOS’ 93
• ios::goodbit:
this flag is raised when none of the other three condition flags were raised.
Several condition member functions are available to manipulate or determine the states of ios
objects. Originally they returned int values, but their current return type is bool:
• bool ios::bad():
the value true is returned when the stream’s badbit has been set and false otherwise.
If true is returned it indicates that an illegal operation has been requested
at the level of the streambuf object to which the stream interfaces. What does this
mean? It indicates that the streambuf itself is behaving unexpectedly. Consider the
following example:
std::ostream error(0);
Here an ostream object is constructed without providing it with a working
streambuf object. Since this ‘streambuf’ will never operate properly, its badbit
flag is raised from the very beginning: error.bad() returns true.
• bool ios::eof():
the value true is returned when end of file (EOF) has been sensed (i.e., the eofbit
flag has been set) and false otherwise. Assume we’re reading lines line-by-line
from cin, but the last line is not terminated by a final \n character. In that case
std::getline attempting to read the \n delimiter hits end-of-file first. This raises
the eofbit flag and cin.eof() returns true. For example, assume std::string
str and main executing the statements:
getline(cin, str);
cout << cin.eof();
Then
echo "hello world" | program
prints the value 0 (no EOF sensed). But after
echo -n "hello world" | program
the value 1 (EOF sensed) is printed.
• bool ios::fail():
the value true is returned when bad returns true or when the failbit flag was
set. The value false is returned otherwise. In the above example, cin.fail()
returns false, whether we terminate the final line with a delimiter or not (as we’ve
read a line). However, executing another getline results in raising the failbit
flag, causing cin::fail() to return true. In general: fail returns true if the
requested stream operation failed. A simple example showing this consists of an
attempt to extract an int when the input stream contains the text hello world.
The value not fail() is returned by the bool interpretation of a stream object (see
below).
• ios::good():
the value of the goodbit flag is returned. It equals true when none of the other
condition flags (badbit, eofbit, failbit) was raised. Consider the following
little program:
#include <iostream>
94 CHAPTER 6. THE IO-STREAM LIBRARY
#include <string>
using namespace std;
void state()
{
cout << "\n"
"Bad: " << cin.bad() << " "
"Fail: " << cin.fail() << " "
"Eof: " << cin.eof() << " "
"Good: " << cin.good() << ’\n’;
}
int main()
{
string line;
int x;
cin >> x;
state();
cin.clear();
getline(cin, line);
state();
getline(cin, line);
state();
}
When this program processes a file having two lines, containing, respectively, hello
and world, while the second line is not terminated by a \n character the following is
shown:
Bad: 0 Fail: 1 Eof: 0 Good: 0
Bad: 0 Fail: 0 Eof: 0 Good: 1
Bad: 0 Fail: 0 Eof: 1 Good: 0
Thus, extracting x fails (good returning false). Then, the error state is cleared, and
the first line is successfully read (good returning true). Finally the second line is
read (incompletely): good returning false, and eof returning true.
• Interpreting streams as bool values:
streams may be used in expressions expecting logical values. Some examples are:
if (cin) // cin itself interpreted as bool
if (cin >> x) // cin interpreted as bool after an extraction
if (getline(cin, str)) // getline returning cin
When interpreting a stream as a logical value, it is actually ‘not fail()’ that is
interpreted. The above examples may therefore be rewritten as:
if (not cin.fail())
if (not (cin >> x).fail())
if (not getline(cin, str).fail())
The former incantation, however, is used almost exclusively.
6.3. INTERFACING ‘STREAMBUF’ OBJECTS: THE CLASS ‘IOS’ 95
The following members are available to manage error states:
• void ios::clear():
When an error condition has occurred, and the condition can be repaired, then clear
can be used to clear the error state of the file. An overloaded version exists accepting
state flags, that are set after first clearing the current set of flags: clear(int
state). Its return type is void
• ios::iostate ios::rdstate():
The current set of flags that are set for an ios object are returned (as an int). To
test for a particular flag, use the bitwise and operator:
if (!(iosObject.rdstate() & ios::failbit))
{
// last operation didn’t fail
}
Note that this test cannot be performed for the goodbit flag as its value equals zero.
To test for ‘good’ use a construction like:
if (iosObject.rdstate() == ios::goodbit)
{
// state is ‘good’
}
• void ios::setstate(ios::iostate state):
A stream may be assigned a certain set of states using setstate. Its return type is
void. E.g.,
cin.setstate(ios::failbit); // set state to ‘fail’
To set multiple flags in one setstate() call use the bitor operator:
cin.setstate(ios::failbit | ios::eofbit)
The member clear is a shortcut to clear all error flags. Of course, clearing the flags doesn’t
automatically mean the error condition has been cleared too. The strategy should be:
– An error condition is detected,
– The error is repaired
– The member clear is called.
C++ supports an exception mechanism to handle exceptional situations. According to the ANSI/ISO
standard, exceptions can be used with stream objects. Exceptions are covered in chapter 10. Using
exceptions with stream objects is covered in section 10.7.
6.3.2 Formatting output and input
The way information is written to streams (or, occasionally, read from streams) is controlled by
formatting flags.
Formatting is used when it is necessary to, e.g., set the width of an output field or input buffer and to
determine the form (e.g., the radix) in which values are displayed. Most formatting features belong
to the realm of the ios class. Formatting is controlled by flags, defined by the ios class. These flags
may be manipulated in two ways: using specialized member functions or using manipulators, which
96 CHAPTER 6. THE IO-STREAM LIBRARY
are directly inserted into or extracted from streams. There is no special reason for using either
method; usually both methods are possible. In the following overview the various member functions
are first introduced. Following this the flags and manipulators themselves are covered. Examples
are provided showing how the flags can be manipulated and what their effects are.
Many manipulators are parameterless and are available once a stream header file (e.g., iostream)
has been included. Some manipulators require arguments. To use the latter manipulators the
header file iomanip must be included.
6.3.2.1 Format modifying member functions
#ifndef INCLUDED_FORMATMEMBERS_YO_ #define INCLUDED_FORMATMEMBERS_YO_
Several member functions are available manipulating the I/O formatting flags. Instead of using
the members listed below manipulators are often available that may directly be inserted into or
extracted from streams. The available members are listed in alphabetical order, but the most important
ones in practice are setf, unsetf and width.
• ios &ios::copyfmt(ios &obj):
all format flags of obj are copied to the current ios object. The current ios object is
returned.
• ios::fill() const:
the current padding character is returned. By default, this is the blank space.
• ios::fill(char padding):
the padding character is redefined, the previous padding character is returned. Instead
of using this member function the setfill manipulator may be inserted directly
into an ostream. Example:
cout.fill(’0’); // use ’0’ as padding char
cout << setfill(’+’); // use ’+’ as padding char
• ios::fmtflags ios::flags() const:
the current set of flags controlling the format state of the stream for which the member
function is called is returned. To inspect whether a particular flag was set, use
the bit_and operator. Example:
if (cout.flags() & ios::hex)
cout << "Integral values are printed as hex numbers\n"
• ios::fmtflags ios::flags(ios::fmtflags flagset):
the previous set of flags are returned and the new set of flags are defined by flagset.
Multiple flags are specified using the bitor operator. Example:
// change the representation to hexadecimal
cout.flags(ios::hex | cout.flags() & ~ios::dec);
• int ios::precision() const:
the number of significant digits used when outputting floating point values is returned
(default: 6).
6.3. INTERFACING ‘STREAMBUF’ OBJECTS: THE CLASS ‘IOS’ 97
• int ios::precision(int signif):
the number of significant digits to use when outputting real values is set to signif.
The previously used number of significant digits is returned. If the number of required
digits exceeds signif then the number is displayed in ‘scientific’ notation (cf.
section 6.3.2.2). Manipulator: setprecision. Example:
cout.precision(3); // 3 digits precision
cout << setprecision(3); // same, using the manipulator
cout << 1.23 << " " << 12.3 << " " << 123.12 << " " << 1234.3 << ’\n’;
// displays: 1.23 12.3 123 1.23e+03
• Type std::put_time(std::tm const _tm, char const _fmt):
The function put_time can be used to display (elements of) the current time. Time
elements are provided in a std::tm object, and the way the time is displayed is
defined by the format string fmt.
In the next example put_time is used to display the current date and time:
#include <iostream>
#include <ctime>
int main()
{
std::time_t tm {time(0)};
std::cout << std::put_time(std::localtime(&tm), "%c") << ’\n’;
}
// displays, e.g., Sun Dec 20 15:05:18 2015
The function put_time, as well as std::localtime and gmtime is described in
more detail in section 20.1.5.
• ios::fmtflags ios::setf(ios::fmtflags flags):
sets one or more formatting flags (use the bitor operator to combine multiple flags).
Already set flags are not affected. The previous set of flags is returned. Instead of
using this member function the manipulator setiosflags may be used. Examples
are provided in the next section (6.3.2.2).
• ios::fmtflags ios::setf(ios::fmtflags flags, ios::fmtflags mask):
clears all flags mentioned in mask and sets the flags specified in flags. The previous
set of flags is returned. Some examples are (but see the next section (6.3.2.2) for a
more thorough discussion):
// left-adjust information in wide fields
cout.setf(ios::left, ios::adjustfield);
// display integral values as hexadecimal numbers
cout.setf(ios::hex, ios::basefield);
// display floating point values in scientific notation
cout.setf(ios::scientific, ios::floatfield);
• ios::fmtflags ios::unsetf(fmtflags flags):
the specified formatting flags are cleared (leaving the remaining flags unaltered)
and returns the previous set of flags. A request to unset an active default flag (e.g.,
cout.unsetf(ios::dec)) is ignored. Instead of this member function the manipulator
resetiosflags may also be used. Example:
cout << 12.24; // displays 12.24
98 CHAPTER 6. THE IO-STREAM LIBRARY
cout << setf(ios::fixed);
cout << 12.24; // displays 12.240000
cout.unsetf(ios::fixed); // undo a previous ios::fixed setting.
cout << 12.24; // displays 12.24
cout << resetiosflags(ios::fixed); // using manipulator rather
// than unsetf
• int ios::width() const:
the currently active output field width to use on the next insertion is returned. The
default value is 0, meaning ‘as many characters as needed to write the value’.
• int ios::width(int nchars):
the field width of the next insertion operation is set to nchars, returning the previously
used field width. This setting is not persistent. It is reset to 0 after every
insertion operation. Manipulator: std::setw(int). Example:
cout.width(5);
cout << 12; // using 5 chars field width
cout << setw(12) << "hello"; // using 12 chars field width
#endif
6.3.2.2 Formatting flags
Most formatting flags are related to outputting information. Information can be written to output
streams in basically two ways: using binary output information is written directly to an output
stream, without converting it first to some human-readable format and using formatted output by
which values stored in the computer’s memory are converted to human-readable text first. Formatting
flags are used to define the way this conversion takes place. In this section all formatting flags
are covered. Formatting flags may be (un)set using member functions, but often manipulators having
the same effect may also be used. For each of the flags it is shown how they can be controlled by
a member function or -if available- a manipulator.
To display information in wide fields:
• ios::internal:
to add fill characters (blanks by default) between the minus sign of negative numbers
and the value itself. Other values and data types are right-adjusted. Manipulator:
std::internal. Example:
cout.setf(ios::internal, ios::adjustfield);
cout << internal; // same, using the manipulator
cout << ’\’’ << setw(5) << -5 << "’\n"; // displays ’- 5’
• ios::left:
to left-adjust values in fields that are wider than needed to display the values. Manipulator:
std::left. Example:
cout.setf(ios::left, ios::adjustfield);
cout << left; // same, using the manipulator
cout << ’\’’ << setw(5) << "hi" << "’\n"; // displays ’hi ’
6.3. INTERFACING ‘STREAMBUF’ OBJECTS: THE CLASS ‘IOS’ 99
• ios::right:
to right-adjust values in fields that are wider than needed to display the values.
Manipulator: std::right. This is the default. Example:
cout.setf(ios::right, ios::adjustfield);
cout << right; // same, using the manipulator
cout << ’\’’ << setw(5) << "hi" << "’\n"; // displays ’ hi’
Using various number representations:
• ios::dec:
to display integral values as decimal numbers. Manipulator: std::dec. This is the
default. Example:
cout.setf(ios::dec, ios::basefield);
cout << dec; // same, using the manipulator
cout << 0x10; // displays 16
• ios::hex:
to display integral values as hexadecimal numbers. Manipulator: std::hex. Example:
cout.setf(ios::hex, ios::basefield);
cout << hex; // same, using the manipulator
cout << 16; // displays 10
• ios::oct:
to display integral values as octal numbers. Manipulator: std::oct. Example:
cout.setf(ios::oct, ios::basefield);
cout << oct; // same, using the manipulator
cout << 16; // displays 20
• std::setbase(int radix):
This is a manipulator that can be used to change the number representation to decimal,
hexadecimal or octal. Example:
cout << setbase(8); // octal numbers, use 10 for
// decimal, 16 for hexadecimal
cout << 16; // displays 20
Fine-tuning displaying values:
• ios::boolalpha:
logical values may be displayed as text using the text ‘true’ for the true logical
value, and ‘false’ for the false logical value using boolalpha. By default
this flag is not set. Complementary flag: ios::noboolalpha. Manipulators:
std::boolalpha and std::noboolalpha. Example:
cout.setf(ios::boolalpha);
cout << boolalpha; // same, using the manipulator
cout << (1 == 1); // displays true
100 CHAPTER 6. THE IO-STREAM LIBRARY
• ios::showbase:
to display the numeric base of integral values. With hexadecimal values the 0x
prefix is used, with octal values the prefix 0. For the (default) decimal value no
particular prefix is used. Complementary flag: ios::noshowbase. Manipulators:
std::showbase and std::noshowbase. Example:
cout.setf(ios::showbase);
cout << showbase; // same, using the manipulator
cout << hex << 16; // displays 0x10
• ios::showpos:
to display the + sign with positive decimal (only) values. Complementary flag:
ios::noshowpos. Manipulators: std::showpos and std::noshowpos. Example:
cout.setf(ios::showpos);
cout << showpos; // same, using the manipulator
cout << 16; // displays +16
cout.unsetf(ios::showpos); // Undo showpos
cout << 16; // displays 16
• ios::uppercase:
to display letters in hexadecimal values using capital letters. Complementary flag:
ios::nouppercase. Manipulators: std::uppercase and std::nouppercase.
By default lower case letters are used. Example:
cout.setf(ios::uppercase);
cout << uppercase; // same, using the manipulator
cout << hex << showbase <<
3735928559; // displays 0XDEADBEEF
Displaying floating point numbers
• ios::fixed:
to display real values using a fixed decimal point (e.g., 12.25 rather than 1.225e+01),
the fixed formatting flag is used. It can be used to set a fixed number of digits
behind the decimal point. Manipulator: fixed. Example:
cout.setf(ios::fixed, ios::floatfield);
cout.precision(3); // 3 digits behind the .
// Alternatively:
cout << setiosflags(ios::fixed) << setprecision(3);
cout << 3.0 << " " << 3.01 << " " << 3.001 << ’\n’;
<< 3.0004 << " " << 3.0005 << " " << 3.0006 << ’\n’
// Results in:
// 3.000 3.010 3.001
// 3.000 3.001 3.001
The example shows that 3.0005 is rounded away from zero, becoming 3.001 (likewise
-3.0005 becomes -3.001). First setting precision and then fixed has the same effect.
6.3. INTERFACING ‘STREAMBUF’ OBJECTS: THE CLASS ‘IOS’ 101
• ios::scientific:
to display real values in scientific notation (e.g., 1.24e+03). Manipulator:
std::scientific. Example:
cout.setf(ios::scientific, ios::floatfield);
cout << scientific; // same, using the manipulator
cout << 12.25; // displays 1.22500e+01
• ios::showpoint:
to display a trailing decimal point and trailing decimal zeros when real numbers
are displayed. Complementary flag: ios::noshowpoint. Manipulators:
std::showpoint, std::noshowpoint. Example:
cout << fixed << setprecision(3); // 3 digits behind .
cout.setf(ios::showpoint); // set the flag
cout << showpoint; // same, using the manipulator
cout << 16.0 << ", " << 16.1 << ", " << 16;
// displays: 16.000, 16.100, 16
Note that the final 16 is an integral rather than a floating point number, so it has
no decimal point. So showpoint has no effect. If ios::showpoint is not active
trailing zeros are discarded. If the fraction is zero the decimal point is discarded as
well. Example:
cout.unsetf(ios::fixed, ios::showpoint); // unset the flags
cout << 16.0 << ", " << 16.1;
// displays: 16, 16.1
Handling white space and flushing streams
• std::endl:
manipulator inserting a newline character and flushing the stream. Often flushing
the stream is not required and doing so would needlessly slow down I/O processing.
Consequently, using endl should be avoided (in favor of inserting ’\n’) unless flusing
the stream is explicitly intended. Note that streams are automatically flushed
when the program terminates or when a stream is ‘tied’ to another stream (cf. tie in
section 6.3). Example:
cout << "hello" << endl; // prefer: << ’\n’;
• std::ends:
manipulator inserting a 0-byte into a stream. It is usually used in combination with
memory-streams (cf. section 6.4.3).
• std::flush:
a streammay be flushed using this member. Often flushing the streamis not required
and doing so would needlessly slow down I/O processing. Consequently, using flush
should be avoided unless it is explicitly required to do so. Note that streams are
automatically flushed when the program terminates or when a stream is ‘tied’ to
another stream (cf. tie in section 6.3). Example:
cout << "hello" << flush; // avoid if possible.
102 CHAPTER 6. THE IO-STREAM LIBRARY
• ios::skipws:
leading white space characters (blanks, tabs, newlines, etc.) are skipped when a value
is extracted from a stream. This is the default. If the flag is not set, leading white
space characters are not skipped. Manipulator: std::skipws. Example:
cin.setf(ios::skipws); // to unset, use
// cin.unsetf(ios::skipws)
cin >> skipws; // same, using the manipulator
int value;
cin >> value; // skips initial blanks
• ios::unitbuf:
the stream for which this flag is set flushes its buffer after every output operation
Often flushing a stream is not required and doing so would needlessly slow down
I/O processing. Consequently, setting unitbuf should be avoided unless flusing the
stream is explicitly intended. Note that streams are automatically flushed when the
program terminates or when a stream is ‘tied’ to another stream (cf. tie in section
6.3). Complementary flag: ios::nounitbuf. Manipulators: std::unitbuf,
std::nounitbuf. Example:
cout.setf(ios::unitbuf);
cout << unitbuf; // same, using the manipulator
cout.write("xyz", 3); // flush follows write.
• std::ws:
manipulator removing all white space characters (blanks, tabs, newlines, etc.) at
the current file position. White space are removed if present even if the flag
ios::noskipws has been set. Example (assume the input contains 4 blank characters
followed by the character X):
cin >> ws; // skip white space
cin.get(); // returns ’X’
6.4 Output
In C++ output is primarily based on the std::ostream class. The ostream class defines the basic
operators and members inserting information into streams: the insertion operator (<<), and special
members like write writing unformatted information to streams.
The class ostream acts as base class for several other classes, all offering the functionality of the
ostream class, but adding their own specialties. In the upcoming sections the following classes are
discussed:
• The class ostream, offering the basic output facilities;
• The class ofstream, allowing us to write files (comparable to C’s fopen(filename, "w"));
• The class ostringstream, allowing us to write information to memory (comparable to C’s
sprintf function).
6.4. OUTPUT 103
6.4.1 Basic output: the class ‘ostream’
The class ostream defines basic output facilities. The cout, clog and cerr objects are all ostream
objects. All facilities related to output as defined by the ios class are also available in the ostream
class.
We may define ostream objects using the following ostream constructor:
• std::ostream object(std::streambuf _sb):
this constructor creates an ostream object which is a wrapper around an existing
std::streambuf object. It isn’t possible to define a plain ostream object (e.g., using
std::ostream out;) that can thereupon be used for insertions. When cout or
its friends are used, we are actually using a predefined ostream object that has
already been defined for us and interfaces to the standard output stream using a
(also predefined) streambuf object handling the actual interfacing.
It is, however, possible to define an ostream object passing it a 0-pointer. Such an
object cannot be used for insertions (i.e., it raises its ios::bad flag when something
is inserted into it), but it may be given a streambuf later. Thus it may be preliminary
constructed, suspending its use until an appropriate streambuf becomes available
(see also section 14.8.3).
To define the ostream class in C++ sources, the <ostream> header file must be included. To use
the predefined ostream objects (std::cin, std::cout etc.) the <iostream> header file must
be included.
6.4.1.1 Writing to ‘ostream’ objects
The class ostream supports both formatted and binary output.
The insertion operator (<<) is used to insert values in a type safe way into ostream objects. This is
called formatted output, as binary values which are stored in the computer’s memory are converted
to human-readable ASCII characters according to certain formatting rules.
The insertion operator points to the ostream object to receive the information. The normal associativity
of << remains unaltered, so when a statement like
cout << "hello " << "world";
is encountered, the leftmost two operands are evaluated first (cout << "hello "), and an ostream
& object, which is actually the same cout object, is returned. Now, the statement is reduced to
cout << "world";
and the second string is inserted into cout.
The << operator has a lot of (overloaded) variants, so many types of variables can be inserted into
ostream objects. There is an overloaded <<-operator expecting an int, a double, a pointer, etc.
etc.. Each operator returns the ostream object into which the information so far has been inserted,
and can thus immediately be followed by the next insertion.
Streams lack facilities for formatted output like C’s printf and vprintf functions. Although it is
not difficult to implement these facilities in the world of streams, printf-like functionality is hardly
104 CHAPTER 6. THE IO-STREAM LIBRARY
ever required in C++ programs. Furthermore, as it is potentially type-unsafe, it might be better to
avoid this functionality completely.
When binary files must be written, normally no text-formatting is used or required: an int value
should be written as a series of raw bytes, not as a series of ASCII numeric characters 0 to 9. The
following member functions of ostream objects may be used to write ‘binary files’:
• ostream& put(char c):
to write a single character to the output stream. Since a character is a byte, this
member function could also be used for writing a single character to a text-file.
• ostream& write(char const _buffer, int length):
to write at most length bytes, stored in the char const _buffer to the ostream
object. Bytes are written as they are stored in the buffer, no formatting is done
whatsoever. Note that the first argument is a char const _: a type cast is required
to write any other type. For example, to write an int as an unformatted series of
byte-values use:
int x;
out.write(reinterpret_cast<char const *>(&x), sizeof(int));
The bytes written by the above write call are written to the ostream in an order depending on
the endian-ness of the underlying hardware. Big-endian computers write the most significant
byte(s) ofmulti-byte values first, little-endian computers first write the least significant byte(s).
6.4.1.2 ‘ostream’ positioning
Although not every ostream object supports repositioning, they usually do. This means that it is
possible to rewrite a section of the stream which was written earlier. Repositioning is frequently
used in database applications where it must be possible to access the information in the database at
random.
The current position can be obtained and modified using the following members:
• ios::pos_type tellp():
the current (absolute) position in the file where the next write-operation to the stream
will take place is returned.
• ostream &seekp(ios::off_type step, ios::seekdir org):
modifies a stream’s actual position. The function expects an off_type step representing
the number of bytes the current stream position is moved with respect to
org. The step value may be negative, zero or positive.
The origin of the step, org is a value in the ios::seekdir enumeration. Its values
are:
– ios::beg:
the stepsize is computed relative to the beginning of the stream. This
value is used by default.
– ios::cur:
the stepsize is computed relative to the current position of the stream (as
returned by tellp).
6.4. OUTPUT 105
– ios::end:
the stepsize is interpreted relative to the current end position of the
stream.
It is OK to seek or write beyond the last file position. Writing bytes to a location
beyond EOF will pad the intermediate bytes with 0-valued bytes: null-bytes. Seeking
before ios::beg raises the ios::fail flag.
6.4.1.3 ‘ostream’ flushing
Unless the ios::unitbuf flag has been set, information written to an ostream object is not immediately
written to the physical stream. Rather, an internal buffer is filled during the writeoperations,
and when full it is flushed.
The stream’s internal buffer can be flushed under program control:
• ostream& flush():
any buffered information stored internally by the ostream object is flushed to the
device to which the ostream object interfaces. A stream is flushed automatically
when:
– the object ceases to exist;
– the endl or flush manipulators (see section 6.3.2.2) are inserted into an
ostream object;
– a stream supporting the close-operation is explicitly closed (e.g., a
std::ofstream object, cf. section 6.4.2).
6.4.2 Output to files: the class ‘ofstream’
The std::ofstream class is derived from the ostream class: it has the same capabilities as the
ostream class, but can be used to access files or create files for writing.
In order to use the ofstream class in C++ sources, the <fstream> header file must be included.
Including fstream does not automatically make available the standard streams cin, cout and
cerr. Include iostream to declare these standard streams.
The following constructors are available for ofstream objects:
• ofstream object:
this is the basic constructor. It defines an ofstream object which may be associated
with an actual file later, using its open() member (see below).
• ofstream object(char const _name, ios::openmode mode = ios::out):
this constructor defines an ofstream object and associates it immediately with the
file named name using output mode mode. Section 6.4.2.1 provides an overview of
available output modes. Example:
ofstream out("/tmp/scratch");
It is not possible to open an ofstream using a file descriptor. The reason for this is (apparently)
that file descriptors are not universally available over different operating systems. Fortunately, file
106 CHAPTER 6. THE IO-STREAM LIBRARY
descriptors can be used (indirectly) with a std::streambuf object (and in some implementations:
with a std::filebuf object, which is also a streambuf). Streambuf objects are discussed in
section 14.8, filebuf objects are discussed in section 14.8.2.
Instead of directly associating an ofstream object with a file, the object can be constructed first,
and opened later.
• void open(char const _name, ios::openmode mode = ios::out):
associates an ofstream object with an actual file. If the ios::fail flag was set
before calling open and opening succeeds the flag is cleared. Opening an already
open stream fails. To reassociate a stream with another file it must first be closed:
ofstream out("/tmp/out");
out << "hello\n";
out.close(); // flushes and closes out
out.open("/tmp/out2");
out << "world\n";
• void close():
closes the ofstream object. The function sets the ios::fail flag of the closed object.
Closing the file flushes any buffered information to the associated file. A file is
automatically closed when the associated ofstream object ceases to exist.
• bool is_open() const:
assume a stream was properly constructed, but it has not yet been attached to a
file. E.g., the statement ofstream ostr was executed. When we now check its
status through good(), a non-zero (i.e., OK) value is returned. The ‘good’ status
here indicates that the stream object has been constructed properly. It doesn’t mean
the file is also open. To test whether a stream is actually open, is_open should be
called. If it returns true, the stream is open. Example:
#include <fstream>
#include <iostream>
using namespace std;
int main()
{
ofstream of;
cout << "of’s open state: " << boolalpha << of.is_open() << ’\n’;
of.open("/dev/null"); // on Unix systems
cout << "of’s open state: " << of.is_open() << ’\n’;
}
/*
Generated output:
of’s open state: false
of’s open state: true
*/
6.4. OUTPUT 107
6.4.2.1 Modes for opening stream objects
The following file modes or file flags are available when constructing or opening ofstream (or
istream, see section 6.5.2) objects. The values are of type ios::openmode. Flags may be combined
using the bitor operator.
• ios::app:
reposition the stream to its end before every output command (see also ios::ate
below). The file is created if it doesn’t yet exist. When opening a stream in this mode
any existing contents of the file are kept.
• ios::ate:
start initially at the end of the file. Note that any existing contents are only kept
if some other flag tells the object to do so. For example ofstream out("gone",
ios::ate) rewrites the file gone, because the implied ios::out causes the rewriting.
If rewriting of an existing file should be prevented, the ios::in mode should
be specified too. However, when ios::in is specified the file must already exist. The
ate mode only initially positions the file at the end of file position. After that information
may be written in the middle of the file using seekp. When the app mode is
used information is only written at end of file (effectively ignoring seekp operations).
• ios::binary:
open a file in binary mode (used on systems distinguishing text- and binary files, like
MS-Windows).
• ios::in:
open the file for reading. The file must exist.
• ios::out:
open the file for writing. Create it if it doesn’t yet exist. If it exists, the file is rewritten.
• ios::trunc:
start initially with an empty file. Any existing contents of the file are lost.
The following combinations of file flags have special meanings:
in | out: The stream may be read and written. However, the
file must exist.
in | out | trunc: The stream may be read and written. It is
(re)created empty first.
An interesting subtlety is that the open members of the ifstream, ofstream and fstream
classes have a second parameter of type ios::openmode. In contrast to this, the bitor operator
returns an int when applied to two enum-values. The question why the bitor operator may
nevertheless be used here is answered in a later chapter (cf. section 11.11).
108 CHAPTER 6. THE IO-STREAM LIBRARY
6.4.3 Output to memory: the class ‘ostringstream’
To write information to memory using stream facilities, std::ostringstream objects should be
used. As the class ostringstream is derived from the class ostream all ostream’s facilities are
available to ostringstream objects as well. To use and define ostringstream objects the header
file <sstream> must be included. In addition the class ostringstream offers the following constructors
and members:
• ostringstream ostr(string const &init, ios::openmode mode = ios::out):
when specifying openmode as ios::ate, the ostringstream object is initialized
by the string init and remaining insertions are appended to the contents of the
ostringstream object.
• ostringstream ostr(ios::openmode mode = ios::out):
this constructor can also be used as default constructor. Alternatively it allows,
e.g., forced additions at the end of the information stored in the object so far (using
ios::app). Example:
std::ostringstream out;
• std::string str() const:
a copy of the string that is stored inside the ostringstream object is returned.
• void str(std::string const &str):
the current object is reinitialized with new initial contents.
The following example illustrates the use of the ostringstream class: several values are inserted
into the object. Then, the text contained by the ostringstream object is stored in a std::string,
whose length and contents are thereupon printed. Such ostringstream objects are most often
used for doing ‘type to string’ conversions, like converting int values to text. Formatting flags can
be used with ostringstreams as well, as they are part of the ostream class.
Here is an example showing an ostringstream object being used:
#include <iostream>
#include <sstream>
using namespace std;
int main()
{
ostringstream ostr("hello ", ios::ate);
cout << ostr.str() << ’\n’;
ostr.setf(ios::showbase);
ostr.setf(ios::hex, ios::basefield);
ostr << 12345;
cout << ostr.str() << ’\n’;
ostr << " -- ";
6.5. INPUT 109
ostr.unsetf(ios::hex);
ostr << 12;
cout << ostr.str() << ’\n’;
ostr.str("new text");
cout << ostr.str() << ’\n’;
ostr.seekp(4, ios::beg);
ostr << "world";
cout << ostr.str() << ’\n’;
}
/*
Output from this program:
hello
hello 0x3039
hello 0x3039 -- 12
new text
new world
*/
6.5 Input
In C++ input is primarily based on the std::istream class. The istream class defines the basic
operators and members extracting information from streams: the extraction operator (>>), and
special members like istream::read reading unformatted information from streams.
The class istream acts as base class for several other classes, all offering the functionality of the
istream class, but adding their own specialties. In the upcoming sections the following classes are
discussed:
• The class istream, offering the basic facilities for doing input;
• The class ifstream, allowing us to read files (comparable to C’s fopen(filename, "r"));
• The class istringstream, allowing us to read information from text that is not stored on files
(streams) but in memory (comparable to C’s sscanf function).
6.5.1 Basic input: the class ‘istream’
The class istream defines basic input facilities. The cin object, is an istream object. All facilities
related to input as defined by the ios class are also available in the istream class.
We may define istream objects using the following istream constructor:
• istream object(streambuf _sb):
this constructor can be used to construct a wrapper around an existing
std::streambuf object. Similarly to ostream objects, istream objects may be defined
by passing it initially a 0-pointer. See section 6.4.1 for a discussion, see also
section 14.8.3, and see chapter 24 for examples.
110 CHAPTER 6. THE IO-STREAM LIBRARY
To define the istream class in C++ sources, the <istream> header file must be included. To use
the predefined istream object cin, the <iostream> header file must be included.
6.5.1.1 Reading from ‘istream’ objects
The class istream supports both formatted and unformatted binary input. The extraction operator
(operator>>) is used to extract values in a type safe way from istream objects. This is called
formatted input, whereby human-readable ASCII characters are converted, according to certain
formatting rules, to binary values.
The extraction operator points to the objects or variables which receive new values. The normal
associativity of >> remains unaltered, so when a statement like
cin >> x >> y;
is encountered, the leftmost two operands are evaluated first (cin >> x), and an istream & object,
which is actually the same cin object, is returned. Now, the statement is reduced to
cin >> y
and the y variable is extracted from cin.
The >> operator has many (overloaded) variants and thus many types of variables can be extracted
fromistream objects. There is an overloaded>> available for the extraction of an int, of a double,
of a string, of an array of characters, possibly to a pointer, etc. etc.. String or character array
extraction by default first skips all white space characters, and then extracts all consecutive nonwhite
space characters. Once an extraction operator has been processed the istream object from
which the information was extracted is returned and it can immediately be used for additional
istream operations that appear in the same expression.
Streams lack facilities for formatted input (as used by, e.g., C’s scanf and vscanf functions). Although
it is not difficult to add these facilities to the world of streams, scanf-like functionality is
hardly ever required in C++ programs. Furthermore, as it is potentially type-unsafe, it might be
better to avoid formatted input completely.
When binary files must be read, the information should normally not be formatted: an int value
should be read as a series of unaltered bytes, not as a series of ASCII numeric characters 0 to 9. The
following member functions for reading information from istream objects are available:
• int gcount() const:
the number of characters read from the input stream by the last unformatted input
operation is returned.
• int get():
the next available single character is returned as an unsigned char value using an
int return type. EOF is returned if no more character are available.
• istream &get(char &ch):
the next single character read from the input stream is stored in ch. The member
function returns the stream itself which may be inspected to determine whether a
character was obtained or not.
6.5. INPUT 111
• istream& get(char _buffer, int len, char delim = ’\n’):
At most len - 1 characters are read from the input stream into the array starting
at buffer, which should be at least len bytes long. Reading also stops when the
delimiter delim is encountered. However, the delimiter itself is not removed from
the input stream.
Having stored the characters into buffer, an 0-valued character is written beyond
the last character stored into the buffer. The functions eof and fail (see section
6.3.1) return 0 (false) if the delimiter was encountered before reading len - 1
characters or if the delimiter was not encountered after reading len - 1 characters.
It is OK to specifiy an 0-valued character delimiter: this way NTB strings may be
read from a (binary) file.
• istream& getline(char _buffer, int len, char delim = ’\n’):
this member function operates analogously to the getmember function, but getline
removes delim from the stream if it is actually encountered. The delimiter itself, if
encountered, is not stored in the buffer. If delim was not found (before reading
len - 1 characters) the fail member function, and possibly also eof returns true.
Realize that the std::string class also offers a function std::getline which is
generally preferred over this getline member function that is described here (see
section 5.2.4).
• istream& ignore():
one character is skipped from the input stream.
• istream& ignore(int n):
n characters are skipped from the input stream.
• istream& ignore(int n, int delim):
at most n characters are skipped but skipping characters stops after having removed
delim from the input stream.
• int peek():
this function returns the next available input character, but does not actually remove
the character from the input stream. EOF is returned if no more characters are
available.
• istream& putback(char ch):
The character ch is ‘pushed back’ into the input stream, to be read again as the next
available character. EOF is returned if this is not allowed. Normally, it is OK to put
back one character. Example:
string value;
cin >> value;
cin.putback(’X’);
// displays: X
cout << static_cast<char>(cin.get());
• istream &read(char _buffer, int len):
At most len bytes are read from the input stream into the buffer. If EOF is encountered
first, fewer bytes are read, with the member function eof returning true. This
function is commonly used when reading binary files. Section 6.5.2 contains an example
in which this member function is used. The member function gcount() may
be used to determine the number of characters that were retrieved by read.
112 CHAPTER 6. THE IO-STREAM LIBRARY
• istream& readsome(char _buffer, int len):
atmost len bytes are read fromthe input streaminto the buffer. All available characters
are read into the buffer, but if EOF is encountered, fewer bytes are read, without
setting the ios::eofbit or ios::failbit.
• istream &unget():
the last character that was read from the stream is put back.
6.5.1.2 ‘istream’ positioning
Although not every istream object supports repositioning, some do. This means that it is possible
to read the same section of a stream repeatedly. Repositioning is frequently used in database
applications where it must be possible to access the information in the database randomly.
The current position can be obtained and modified using the following members:
• ios::pos_type tellg():
the stream’s current (absolute) position where the stream’s next read-operation will
take place is returned.
• istream &seekg(ios::off_type step, ios::seekdir org):
modifies a stream’s actual position. The function expects an off_type step representing
the number of bytes the current stream position is moved with respect to
org. The step value may be negative, zero or positive.
The origin of the step, org is a value in the ios::seekdir enumeration. Its values
are:
– ios::beg:
the stepsize is computed relative to the beginning of the stream. This
value is used by default.
– ios::cur:
the stepsize is computed relative to the current position of the stream (as
returned by tellp).
– ios::end:
the stepsize is interpreted relative to the current end position of the the
stream.
It is OK to seek beyond the last file position. Seeking before ios::beg raises the
ios::failbit flag.
6.5.2 Input from files: the class ‘ifstream’
The std::ifstream class is derived from the istream class: it has the same capabilities as the
istream class, but can be used to access files for reading.
In order to use the ifstream class in C++ sources, the <fstream> header file must be included.
Including fstream does not automatically make available the standard streams cin, cout and
cerr. Include iostream to declare these standard streams.
6.5. INPUT 113
The following constructors are available for ifstream objects:
• ifstream object:
this is the basic constructor. It defines an ifstream object which may be associated
with an actual file later, using its open() member (see below).
• ifstream object(char const _name, ios::openmode mode = ios::in):
this constructor can be used to define an ifstream object and associate it immediately
with the file named name using input mode mode. Section 6.4.2.1 provides an
overview of available input modes. Example:
ifstream in("/tmp/input");
Instead of directly associating an ifstream object with a file, the object can be constructed first,
and opened later.
• void open(char const _name, ios::openmode mode = ios::in):
associates an ifstream object with an actual file. If the ios::fail flag was set
before calling open and opening succeeds the flag is cleared. Opening an already
open stream fails. To reassociate a stream with another file it must first be closed:
ifstream in("/tmp/in");
in >> variable;
in.close(); // closes in
in.open("/tmp/in2");
in >> anotherVariable;
• void close():
closes the ifstream object. The function sets the ios::fail flag of the closed object.
Closing the file flushes any buffered information to the associated file. A file is
automatically closed when the associated ifstream object ceases to exist.
• bool is_open() const:
assume a stream was properly constructed, but it has not yet been attached to a
file. E.g., the statement ifstream ostr was executed. When we now check its
status through good(), a non-zero (i.e., OK) value is returned. The ‘good’ status
here indicates that the stream object has been constructed properly. It doesn’t mean
the file is also open. To test whether a stream is actually open, is_open should be
called. If it returns true, the stream is open. Also see the example in section 6.4.2.
The following example illustrates reading from a binary file (see also section 6.5.1.1):
#include <fstream>
using namespace std;
int main(int argc, char **argv)
{
ifstream in(argv[1]);
double value;
// reads double in raw, binary form from file.
in.read(reinterpret_cast<char *>(&value), sizeof(double));
}
114 CHAPTER 6. THE IO-STREAM LIBRARY
6.5.3 Input from memory: the class ‘istringstream’
To read information from memory using stream facilities, std::istringstream objects should
be used. As the class istringstream is derived from the class istream all istream’s facilities
are available to istringstream objects as well. To use and define istringstream objects the
header file <sstream> must be included. In addition the class istringstream offers the following
constructors and members:
• istringstream istr(string const &init, ios::openmode mode = ios::in):
the object is initialized with init’s contents
• istringstream istr(ios::openmode mode = ios::in) (this constructor is usually
used as the default constructor. Example:
std::istringstream in;
)
• void str(std::string const &str):
the current object is reinitialized with new initial contents.
The following example illustrates the use of the istringstream class: several values are extracted
from the object. Such istringstream objects are most often used for doing ‘string to type’ conversions,
like converting text to int values (cf. C’s atoi function). Formatting flags can be used with
istringstreams as well, as they are part of the istream class. In the example note especially the
use of the member seekg:
#include <iostream>
#include <sstream>
using namespace std;
int main()
{
istringstream istr("123 345"); // store some text.
int x;
istr.seekg(2); // skip "12"
istr >> x; // extract int
cout << x << ’\n’; // write it out
istr.seekg(0); // retry from the beginning
istr >> x; // extract int
cout << x << ’\n’; // write it out
istr.str("666"); // store another text
istr >> x; // extract it
cout << x << ’\n’; // write it out
}
/*
output of this program:
3
123
666
*/
6.5. INPUT 115
6.5.4 Copying streams
Usually, files are copied either by reading a source file character by character or line by line. The
basic mold to process streams is as follows:
• Continuous loop:
1. read from the stream
2. if reading did not succeed (i.e., fail returns true), break from the loop
3. process the information that was read
Note that reading must precede testing, as it is only possible to know after actually attempting
to read from a file whether the reading succeeded or not. Of course, variations are possible:
getline(istream &, string &) (see section 6.5.1.1) returns an istream &, so here reading
and testing may be contracted using one expression. Nevertheless, the above mold represents the
general case. So, the following program may be used to copy cin to cout:
#include <iostream>
using namespace::std;
int main()
{
while (true)
{
char c;
cin.get(c);
if (cin.fail())
break;
cout << c;
}
}
Contraction is possible here by combining get with the if-statement, resulting in:
if (!cin.get(c))
break;
Even so, this would still follow the basic rule: ‘read first, test later’.
Simply copying a file isn’t required very often. More often a situation is encountered where a file
is processed up to a certain point, followed by plain copying the file’s remaining information. The
next program illustrates this. Using ignore to skip the first line (for the sake of the example it is
assumed that the first line is at most 80 characters long), the second statement uses yet another
overloaded version of the <<-operator, in which a streambuf pointer is inserted into a stream. As
the member rdbuf returns a stream’s streambuf _, we have a simple means of inserting a stream’s
contents into an ostream:
#include <iostream>
using namespace std;
int main()
116 CHAPTER 6. THE IO-STREAM LIBRARY
{
cin.ignore(80, ’\n’); // skip the first line and...
cout << cin.rdbuf(); // copy the rest through the streambuf *
}
This way of copying streams only assumes the existence of a streambuf object. Consequently it can
be used with all specializations of the streambuf class.
6.5.5 Coupling streams
Ostream objects can be coupled to ios objects using the tie member function. Tying results in
flushing the ostream’s buffer whenever an input or output operation is performed on the ios object
to which the ostream object is tied. By default cout is tied to cin (using cin.tie(cout)). This
tie means that whenever an operation on cin is requested, cout is flushed first. To break the tie,
ios::tie(0) can be called. In the example: cin.tie(0).
Another useful coupling of streams is shown by the tie between cerr and cout. Because of the tie
standard output and error messages written to the screen are shown in sync with the time at which
they were generated:
#include <iostream>
using namespace std;
int main()
{
cerr.tie(0); // untie
cout << "first (buffered) line to cout ";
cerr << "first (unbuffered) line to cerr\n";
cout << "\n";
cerr.tie(&cout); // tie cout to cerr
cout << "second (buffered) line to cout ";
cerr << "second (unbuffered) line to cerr\n";
cout << "\n";
}
/*
Generated output:
first (unbuffered) line to cerr
first (buffered) line to cout
second (buffered) line to cout second (unbuffered) line to cerr
*/
An alternative way to couple streams is to make streams use a common streambuf object. This can
be implemented using the ios::rdbuf(streambuf _) member function. This way two streams
can use, e.g. their own formatting, one stream can be used for input, the other for output, and
redirection using the stream library rather than operating system calls can be implemented. See
the next sections for examples.
6.6. ADVANCED TOPICS 117
6.6 Advanced topics
6.6.1 Moving streams
Stream classes (e.g.„ all stream classes covered in this chapter) are movable and can be swapped.
This implies that factory functions can be designed for stream classes. Here is an example:
ofstream out(string const &name)
{
ofstream ret(name); // construct ofstream
return ret; // return value optimization, but
} // OK as moving is supported
int main()
{
ofstream mine(out("out")); // return value optimizations, but
// OK as moving is supported
ofstream base("base");
ofstream other;
base.swap(other); // swapping streams is OK
other = std::move(base); // moving streams is OK
// other = base; // this would ail: copy assignment
// is not available for streams
}
6.6.2 Redirecting streams
Using ios::rdbuf streams can be forced to share their streambuf objects. Thus information written
to one stream is actually written to another stream; a phenomenon normally called redirection.
Redirection is commonly implemented at the operating system level, and sometimes that is still
necessary (see section 24.2.3).
A common situation where redirection is useful is when error messages should be written to file
rather than to the standard error stream, usually indicated by its file descriptor number 2. In the
Unix operating system using the bash shell, this can be realized as follows:
program 2>/tmp/error.log
Following this command any error messages written by program are saved on the file
/tmp/error.log, instead of appearing on the screen.
Here is an example showing how this can be implemented using streambuf objects. Assume
program expects an argument defining the name of the file to write the error messages to. It could
be called as follows:
program /tmp/error.log
118 CHAPTER 6. THE IO-STREAM LIBRARY
The program looks like this, an explanation is provided below the program’s source text:
#include <iostream>
#include <fstream>
using namespace std;
int main(int argc, char **argv)
{
ofstream errlog; // 1
streambuf *cerr_buffer = 0; // 2
if (argc == 2)
{
errlog.open(argv[1]); // 3
cerr_buffer = cerr.rdbuf(errlog.rdbuf()); // 4
}
else
{
cerr << "Missing log filename\n";
return 1;
}
cerr << "Several messages to stderr, msg 1\n";
cerr << "Several messages to stderr, msg 2\n";
cout << "Now inspect the contents of " <<
argv[1] << "... [Enter] ";
cin.get(); // 5
cerr << "Several messages to stderr, msg 3\n";
cerr.rdbuf(cerr_buffer); // 6
cerr << "Done\n"; // 7
}
/*
Generated output on file argv[1]
at cin.get():
Several messages to stderr, msg 1
Several messages to stderr, msg 2
at the end of the program:
Several messages to stderr, msg 1
Several messages to stderr, msg 2
Several messages to stderr, msg 3
*/
• At lines 1-2 local variables are defined: errlog is the ofstream to write the error messages
too, and cerr_buffer is a pointer to a streambuf, to point to the original cerr buffer.
• At line 3 the alternate error stream is opened.
• At line 4 redirection takes place: cerr now writes to the streambuf defined by errlog. It is
6.6. ADVANCED TOPICS 119
important that the original buffer used by cerr is saved, as explained below.
• At line 5 we pause. At this point, two lines were written to the alternate error file. We get a
chance to take a look at its contents: there were indeed two lines written to the file.
• At line 6 the redirection is terminated. This is very important, as the errlog object is destroyed
at the end of main. If cerr’s buffer would not have been restored, then at that point
cerr would refer to a non-existing streambuf object, which might produce unexpected results.
It is the responsibility of the programmer to make sure that an original streambuf is
saved before redirection, and is restored when the redirection ends.
• Finally, at line 7, Done is again written to the screen, as the redirection has been terminated.
6.6.3 Reading AND Writing streams
In order to both read and write to a stream an std::fstream object must be created. As with
ifstream and ofstream objects, its constructor receives the name of the file to be opened:
fstream inout("iofile", ios::in | ios::out);
Note the use of the constants ios::in and ios::out, indicating that the file must be opened
for both reading and writing. Multiple mode indicators may be used, concatenated by the bitor
operator. Alternatively, instead of ios::out, ios::app could have been used and mere writing
would become appending (at the end of the file).
Reading and writing to the same file is always a bit awkward: what to do when the file may not yet
exist, but if it already exists it should not be rewritten? Having fought with this problem for some
time I now use the following approach:
#include <fstream>
#include <iostream>
#include <string>
using namespace std;
int main()
{
fstream rw("fname", ios::out | ios::in);
if (!rw) // file didn’t exist yet
{
rw.clear(); // try again, creating it using ios::trunc
rw.open("fname", ios::out | ios::trunc | ios::in);
}
if (!rw) // can’t even create it: bail out
{
cerr << "Opening ‘fname’ failed miserably" << ’\n’;
return 1;
}
cerr << "We’re at: " << rw.tellp() << ’\n’;
120 CHAPTER 6. THE IO-STREAM LIBRARY
// write something
rw << "Hello world" << ’\n’;
rw.seekg(0); // go back and read what’s written
string s;
getline(rw, s);
cout << "Read: " << s << ’\n’;
}
Under this approach if the first construction attempt fails fname doesn’t exist yet. But then open
can be attempted using the ios::trunc flag. If the file already existed, the construction would
have succeeded. By specifying ios::ate when defining rw, the initial read/write action would by
default have taken place at EOF.
Under DOS-like operating systems that use the multiple character sequence \r\n to separate lines
in text files the flag ios::binary is required to process binary files ensuring that \r\n combinations
are processed as two characters. In general, ios::binary should be specified when binary
(non-text) files are to be processed. By default files are opened as text files. Unix operating systems
do not distinguish text files from binary files.
With fstream objects, combinations of file flags are used to make sure that a stream is or is not
(re)created empty when opened. See section 6.4.2.1 for details.
Once a file has been opened in read and write mode, the << operator can be used to insert information
into the file, while the >> operator may be used to extract information from the file. These
operations may be performed in any order, but a seekg or seekp operation is required when switching
between insertions and extractions. The seek operation is used to activate the stream’s data
used for reading or those used for writing (and vice versa). The istream and ostream parts of
fstream objects share the stream’s data buffer and by performing the seek operation the stream
either activates its istream or its ostream part. If the seek is omitted, reading after writing and
writing after reading simply fails. The example shows a white space delimited word being read from
a file, writing another string to the file, just beyond the point where the just read word terminated.
Finally yet another string is read which is found just beyond the location where the just written
strings ended:
fstream f("filename", ios::in | ios::out);
string str;
f >> str; // read the first word
// write a well known text
f.seekg(0, ios::cur);
f << "hello world";
f.seekp(0, ios::cur);
f >> str; // and read again
Since a seek or clear operation is required when alternating between read and write (extraction and
insertion) operations on the same file it is not possible to execute a series of << and >> operations
in one expression statement.
Of course, random insertions and extractions are hardly ever used. Generally, insertions and extractions
occur at well-known locations in a file. In those cases, the position where insertions or
6.6. ADVANCED TOPICS 121
extractions are required can be controlled and monitored by the seekg, seekp, tellg and tellp
members (see sections 6.4.1.2 and 6.5.1.2).
Error conditions (see section 6.3.1) occurring due to, e.g., reading beyond end of file, reaching end
of file, or positioning before begin of file, can be cleared by the clear member function. Following
clear processing may continue. E.g.,
fstream f("filename", ios::in | ios::out);
string str;
f.seekg(-10); // this fails, but...
f.clear(); // processing f continues
f >> str; // read the first word
A situation where files are both read and written is seen in database applications, using files consisting
of records having fixed sizes, and where locations and sizes of pieces of information are known.
For example, the following program adds text lines to a (possibly existing) file. It can also be used to
retrieve a particular line, given its order-number in the file. A binary file index allows for the quick
retrieval of the location of lines.
#include <iostream>
#include <fstream>
#include <string>
#include <climits>
using namespace std;
void err(char const *msg)
{
cout << msg << ’\n’;
}
void err(char const *msg, long value)
{
cout << msg << value << ’\n’;
}
void read(fstream &index, fstream &strings)
{
int idx;
if (!(cin >> idx)) // read index
{
cin.clear(); // allow reading again
cin.ignore(INT_MAX, ’\n’); // skip the line
return err("line number expected");
}
index.seekg(idx * sizeof(long)); // go to index-offset
long offset;
if
(
122 CHAPTER 6. THE IO-STREAM LIBRARY
!index.read // read the line-offset
(
reinterpret_cast<char *>(&offset),
sizeof(long)
)
)
return err("no offset for line", idx);
if (!strings.seekg(offset)) // go to the line’s offset
return err("can’t get string offset ", offset);
string line;
if (!getline(strings, line)) // read the line
return err("no line at ", offset);
cout << "Got line: " << line << ’\n’; // show the line
}
void write(fstream &index, fstream &strings)
{
string line;
if (!getline(cin, line)) // read the line
return err("line missing");
strings.seekp(0, ios::end); // to strings
index.seekp(0, ios::end); // to index
long offset = strings.tellp();
if
(
!index.write // write the offset to index
(
reinterpret_cast<char *>(&offset),
sizeof(long)
)
)
return err("Writing failed to index: ", offset);
if (!(strings << line << ’\n’)) // write the line itself
return err("Writing to ‘strings’ failed");
// confirm writing the line
cout << "Write at offset " << offset << " line: " << line << ’\n’;
}
int main()
{
fstream index("index", ios::trunc | ios::in | ios::out);
fstream strings("strings", ios::trunc | ios::in | ios::out);
cout << "enter ‘r <number>’ to read line <number> or "
"w <line>’ to write a line\n"
6.6. ADVANCED TOPICS 123
"or enter ‘q’ to quit.\n";
while (true)
{
cout << "r <nr>, w <line>, q ? "; // show prompt
index.clear();
strings.clear();
string cmd;
cin >> cmd; // read cmd
if (cmd == "q") // process the cmd.
return 0;
if (cmd == "r")
read(index, strings);
else if (cmd == "w")
write(index, strings);
else if (cin.eof())
{
cout << "\n"
"Unexpected end-of-file\n";
return 1;
}
else
cout << "Unknown command: " << cmd << ’\n’;
}
}
Another example showing reading and writing of files is provided by the next program. It also
illustrates the processing of NTB strings:
#include <iostream>
#include <fstream>
using namespace std;
int main()
{ // r/w the file
fstream f("hello", ios::in | ios::out | ios::trunc);
f.write("hello", 6); // write 2 NTB strings
f.write("hello", 6);
f.seekg(0, ios::beg); // reset to begin of file
char buffer[100]; // or: char *buffer = new char[100]
char c;
// read the first ‘hello’
cout << f.get(buffer, sizeof(buffer), 0).tellg() << ’\n’;
f >> c; // read the NTB delim
// and read the second ‘hello’
cout << f.get(buffer + 6, sizeof(buffer) - 6, 0).tellg() << ’\n’;
124 CHAPTER 6. THE IO-STREAM LIBRARY
buffer[5] = ’ ’; // change asciiz to ’ ’
cout << buffer << ’\n’; // show 2 times ‘hello’
}
/*
Generated output:
5
11
hello hello
*/
A completely different way to read and write streams may be implemented using streambuf members.
All considerationsmentioned so far remain valid (e.g., before a read operation following a write
operation seekg must be used). When streambuf objects are used, either an istream is associated
with the streambuf object of another ostream object, or an ostream object is associated with
the streambuf object of another istream object. Here is the previous program again, now using
associated streams:
#include <iostream>
#include <fstream>
#include <string>
using namespace std;
void err(char const *msg); // see earlier example
void err(char const *msg, long value);
void read(istream &index, istream &strings)
{
index.clear();
strings.clear();
// insert the body of the read() function of the earlier example
}
void write(ostream &index, ostream &strings)
{
index.clear();
strings.clear();
// insert the body of the write() function of the earlier example
}
int main()
{
ifstream index_in("index", ios::trunc | ios::in | ios::out);
ifstream strings_in("strings", ios::trunc | ios::in | ios::out);
ostream index_out(index_in.rdbuf());
ostream strings_out(strings_in.rdbuf());
cout << "enter ‘r <number>’ to read line <number> or "
"w <line>’ to write a line\n"
"or enter ‘q’ to quit.\n";
6.6. ADVANCED TOPICS 125
while (true)
{
cout << "r <nr>, w <line>, q ? "; // show prompt
string cmd;
cin >> cmd; // read cmd
if (cmd == "q") // process the cmd.
return 0;
if (cmd == "r")
read(index_in, strings_in);
else if (cmd == "w")
write(index_out, strings_out);
else
cout << "Unknown command: " << cmd << ’\n’;
}
}
In this example
• the streams associated with the streambuf objects of existing streams are not ifstream or
ofstream objects but basic istream and ostream objects.
• The streambuf object is not defined by an ifstream or ofstream object. Instead it is defined
outside of the streams, using a filebuf (cf. section 14.8.2) and constructions like:
filebuf fb("index", ios::in | ios::out | ios::trunc);
istream index_in(&fb);
ostream index_out(&fb);
• An ifstream object can be constructed using stream modes normally used with ofstream
objects. Conversely, an ofstream objects can be constructed using stream modes normally
used with ifstream objects.
• If istream and ostreams share a streambuf, then their read and write pointers (should)
point to the shared buffer: they are tightly coupled.
• The advantage of using an external (separate) streambuf over a predefined fstream object
is (of course) that it opens the possibility of using stream objects with specialized streambuf
objects. These streambuf objects may specifically be constructed to control and interface particular
devices. Elaborating this (see also section 14.8) is left as an exercise to the reader.
126 CHAPTER 6. THE IO-STREAM LIBRARY

Chapter 7
Classes
The C programming language offers two methods for structuring data of different types. The C
struct holds data members of various types, and the C union also defines data members of various
types. However, a union’s data members all occupy the same location in memory and the
programmer may decide on which one to use.
In this chapter classes are introduced. A class is a kind of struct, but its contents are by default
inaccessible to the outside world, whereas the contents of a C++ struct are by default accessible to
the outside world. In C++ structs find little use: they are mainly used to aggregate data within the
context of classes or to define elaborate return values. Often a C++ struct merely contains plain
old data (POD, cf. section 9.9). In C++ the class is the main data structuring device, by default
enforcing two core concepts of current-day software engineering: data hiding and encapsulation (cf.
sections 3.2.1 and 7.1.1).
The union is another data structuring device the language offers. The traditional C union is still
available, but C++ also offers unrestricted unions. Unrestricted unions are unions whose data fields
may be of class types. The C++ Annotations covers these unrestricted unions in section 12.6, after
having introduced several other new concepts of C++,
C++ extends the C struct and union concepts by allowing the definition of member functions
(introduced in this chapter) within these data types. Member functions are functions that can only
be used with objects of these data types or within the scope of these data types. Some of these
member functions are special in that they are always, usually automatically, called when an object
starts its life (the so-called constructor) or ends its life (the so-called destructor). These and other
types of member functions, as well as the design and construction of, and philosophy behind, classes
are introduced in this chapter.
We step-by-step construct a class Person, which could be used in a database application to store a
person’s name, address and phone number.
Let’s start by creating a class Person right away. From the onset, it is important to make the
distinction between the class interface and its implementation. A class may loosely be defined as ‘a
set of data and all the functions operating on those data’. This definition is later refined but for now
it is sufficient to get us started.
A class interface is a definition, defining the organization of objects of that class. Normally a definition
results in memory reservation. E.g., when defining int variable the compiler ensures that
some memory is reserved in the final program storing variable’s values. Although it is a definition
no memory is set aside by the compiler once it has processed the class definition. But a class definition
follows the one definition rule: in C++ entities may be defined only once. As a class definition
127
128 CHAPTER 7. CLASSES
does not imply that memory is being reserved the term class interface is preferred instead.
Class interfaces are normally contained in a class header file, e.g., person.h. We’ll start our class
Person interface here (cf section 7.7 for an explanation of the const keywords behind some of the
class’s member functions):
#include <string>
class Person
{
std::string d_name; // name of person
std::string d_address; // address field
std::string d_phone; // telephone number
size_t d_mass; // the mass in kg.
public: // member functions
void setName(std::string const &name);
void setAddress(std::string const &address);
void setPhone(std::string const &phone);
void setMass(size_t mass);
std::string const &name() const;
std::string const &address() const;
std::string const &phone() const;
size_t mass() const;
};
The member functions that are declared in the interface must still be implemented. The implementation
of these members is properly called their definition.
In addition to the member function a class defines the data manipulated by the member functions.
These data are called the data memberdata members. In Person they are d_name, d_address,
d_phone and d_mass. Data members should be given private access rights. Since the class uses
private access rights by default they may simply be listed at the top of the interface.
All communication between the outer world and the class data is routed through the class’s member
functions. Data members may receive new values (e.g., using setName) or they may be retrieved
for inspection (e.g., using name). Functions merely returning values stored inside the object, not
allowing the caller to modify these internally stored values, are called accessors.
Syntactically there is only a marginal difference between a class and a struct. Classes by default
define private members, structs define public members. Conceptually, though, there are differences.
In C++ structs are used in the way they are used in C: to aggregate data, which are all freely
accessible. Classes, on the other hand, hide their data from access by the outside world (which is
aptly called data hiding) and offermember functions to define the communication between the outer
world and the class’s data members.
Following Lakos (Lakos, J., 2001) Large-Scale C++ Software Design (Addison-Wesley) I suggest
the following setup of class interfaces:
• All data members have private access rights, and are placed at the top of the interface.
• All data members start with d_, followed by a name suggesting their meaning (in chapter 8
we’ll also encounter data members starting with s_).
• Non-private data members do exist, but one should be hesitant to define non-private access
rights for data members (see also chapter 13).
7.1. THE CONSTRUCTOR 129
• Two broad categories ofmember functions are manipulators and accessors. Manipulators allow
the users of objects to modify the internal data of the objects. By convention, manipulators
start with set. E.g., setName.
• With accessors, a get-prefix is still frequently encountered, e.g., getName. However, following
the conventions promoted by the Qt (see http://www.trolltech.com) Graphical User
Interface Toolkit, the get-prefix is now deprecated. So, rather than defining the member
getAddress, it should simply be named address.
• Normally (exceptions exist) the public member functions of a class are listed first, immediately
following the class’s data members. They are the important elements of the interface as they
define the features the class is offering to its users. It’s a matter of convention to list them high
up in the interface. The keyword private is needed beyond the public members to switch back
from public members to private access rights which nicely separates the members that may be
used ‘by the general public’ from the class’s own support members.
Style conventions usually take a long time to develop. There is nothing obligatory about them,
though. I suggest that readers who have compelling reasons not to follow the above style conventions
use their own. All others are strongly advised to adopt the above style conventions.
Finally, referring back to section 3.1.2 that
using namespace std;
must be used in most (if not all) examples of source code. As explained in sections 7.11 and 7.11.1
the using directive should follow the preprocessor directive(s) including the header files, using a
setup like the following:
#include <iostream>
#include "person.h"
using namespace std;
int main()
{
...
}
7.1 The constructor
C++ classes may contain two special categories of member functions which are essential to the
proper working of the class. These categories are the constructors and the destructor. The destructor’s
primary task is to return memory allocated by an object to the common pool when an object
goes ‘out of scope’. Allocation of memory is discussed in chapter 9, and destructors are therefore be
discussed in depth in that chapter. In this chapter the emphasis is on the class’s organization and
its constructors.
Constructor are recognized by their names which is equal to the class name. Constructors do
not specify return values, not even void. E.g., the class Person may define a constructor
Person::Person(). The C++ run-time system ensures that the constructor of a class is called
when a variable of the class is defined. It is possible to define a class lacking any constructor. In that
case the compiler defines a default constructor that is called when an object of that class is defined.
130 CHAPTER 7. CLASSES
What actually happens in that case depends on the data members that are defined by that class (cf.
section 7.3.1).
Objects may be defined locally or globally. However, in C++ most objects are defined locally. Globally
defined objects are hardly ever required and are somewhat deprecated.
When a local object is defined its constructor is called every time the function is called. The object’s
constructor is activated at the point where the object is defined (a subtlety is that an object may be
defined implicitly as, e.g., a temporary variable in an expression).
When an object is defined as a static object it is constructed when the program starts. In this case
its constructor is called even before the function main starts. Example:
#include <iostream>
using namespace std;
class Demo
{
public:
Demo();
};
Demo::Demo()
{
cout << "Demo constructor called\n";
}
Demo d;
int main()
{}
/*
Generated output:
Demo constructor called
*/
The programcontains one global object of the class Demo with main having an empty body. Nonetheless,
the program produces some output generated by the constructor of the globally defined Demo
object.
Constructors have a very important and well-defined role. They must ensure that all the class’s
data members have sensible or at least well-defined values once the object has been constructed.
We’ll get back to this important task shortly. The default constructor has no argument. It is defined
by the compiler unless another constructor is defined and unless its definition is suppressed (cf.
section 7.6). If a default constructor is required in addition to another constructor then the default
constructor must explicitly be defined as well. C++ provides special syntax to do that as well, which
is also covered by section 7.6.
7.1.1 A first application
Our example class Person has three string data members and a size_t d_mass data member.
Access to these data members is controlled by interface functions.
7.1. THE CONSTRUCTOR 131
Whenever an object is defined the class’s constructor(s) ensure that its data members are given ‘sensible’
values. Thus, objects never suffer from uninitialized values. Data members may be given new
values, but that should never be directly allowed. It is a core principle (called data hiding) of good
class design that its data members are private. The modification of data members is therefore fully
controlled by member functions and thus, indirectly, by the class-designer. The class encapsulates all
actions performed on its data members and due to this encapsulation the class object may assume
the ‘responsibility’ for its own data-integrity. Here is a minimal definition of Person’s manipulating
members:
#include "person.h" // given earlier
using namespace std;
void Person::setName(string const &name)
{
d_name = name;
}
void Person::setAddress(string const &address)
{
d_address = address;
}
void Person::setPhone(string const &phone)
{
d_phone = phone;
}
void Person::setMass(size_t mass)
{
d_mass = mass;
}
It’s a minimal definition in that no checks are performed. But it should be clear that checks are easy
to implement. E.g., to ensure that a phone number only contains digits one could define:
void Person::setPhone(string const &phone)
{
if (phone.find_first_not_of("0123456789") == string::npos)
d_phone = phone;
else
cout << "A phone number may only contain digits\n";
}
Similarly, access to the data members is controlled by encapsulating accessor members. Accessors
ensure that data members cannot suffer from uncontrolled modifications. Since accessors conceptually
do not modify the object’s data (but only retrieve the data) these member functions are given
the predicate const. They are called const member functions, which, as they are guaranteed not to
modify their object’s data, are available to both modifiable and constant objects (cf. section 7.7).
To prevent backdoors we must also make sure that the data member is not modifiable through
an accessor’s return value. For values of built-in primitive types that’s easy, as they are usually
returned by value, which are copies of the values found in variables. But since objects may be fairly
large making copies are usually prevented by returning objects by reference. A backdoor is created
by returning a data member by reference, as in the following example, showing the allowed abuse
below the function definition:
string &Person::name() const
132 CHAPTER 7. CLASSES
{
return d_name;
}
Person somebody;
somebody.setName("Nemo");
somebody.name() = "Eve"; // Oops, backdoor changing the name
To prevent the backdoor objects are returned as const references from accessors. Here are the implementations
of Person’s accessors:
#include "person.h" // given earlier
using namespace std;
string const &Person::name() const
{
return d_name;
}
string const &Person::address() const
{
return d_address;
}
string const &Person::phone() const
{
return d_phone;
}
size_t Person::mass() const
{
return d_mass;
}
The Person class interface remains the starting point for the class design: its member functions
define what can be asked of a Person object. In the end the implementation of its members merely
is a technicality allowing Person objects to do their jobs.
The next example shows how the class Person may be used. An object is initialized and passed to a
function printperson(), printing the person’s data. Note the reference operator in the parameter
list of the function printperson. Only a reference to an existing Person object is passed to the
function, rather than a complete object. The fact that printperson does not modify its argument
is evident from the fact that the parameter is declared const.
#include <iostream>
#include "person.h" // given earlier
using namespace std;
void printperson(Person const &p)
{
cout << "Name : " << p.name() << "\n"
"Address : " << p.address() << "\n"
"Phone : " << p.phone() << "\n"
"Mass : " << p.mass() << ’\n’;
}
7.1. THE CONSTRUCTOR 133
int main()
{
Person p;
p.setName("Linus Torvalds");
p.setAddress("E-mail: [email protected]");
p.setPhone(" - not sure - ");
p.setMass(75); // kg.
printperson(p);
}
/*
Produced output:
Name : Linus Torvalds
Address : E-mail: [email protected]
Phone : - not sure -
Mass : 75
*/
7.1.2 Constructors: with and without arguments
The class Person’s constructor so far has no parameters. C++ allows constructors to be defined with
or without parameter lists. The arguments are supplied when an object is defined.
For the class Person a constructor expecting three strings and a size_t might be useful. Representing,
respectively, the person’s name, address, phone number and mass. This constructor is (but
see also section 7.3.1):
Person::Person(string const &name, string const &address,
string const &phone, size_t mass)
{
d_name = name;
d_address = address;
d_phone = phone;
d_mass = mass;
}
It must of course also be declared in the class interface:
class Person
{
// data members (not altered)
public:
Person(std::string const &name, std::string const &address,
std::string const &phone, size_t mass);
// rest of the class interface (not altered)
};
Now that this constructor has been declared, the default constructor must explicitly be declared as
134 CHAPTER 7. CLASSES
well if we still want to be able to construct a plain Person object without any specific initial values
for its data members. The class Person would thus support two constructors, and the part declaring
the constructors now becomes:
class Person
{
// data members
public:
Person();
Person(std::string const &name, std::string const &address,
std::string const &phone, size_t mass);
// additional members
};
In this case, the default constructor doesn’t have to do very much, as it doesn’t have to initialize the
string data members of the Person object. As these data members are objects themselves, they are
initialized to empty strings by their own default constructor. However, there is also a size_t data
member. That member is a variable of a built-in type and such variabes do not have constructors
and so are not initialized automatically. Therefore, unless the value of the d_mass data member is
explicitly initialized its value is:
• a random value for local Person objects;
• 0 for global and static Person objects.
The 0-value might not be too bad, but normally we don’t want a random value for our data members.
So, even the default constructor has a job to do: initializing the data members which are not
initialized to sensible values automatically. Its implementation can be:
Person::Person()
{
d_mass = 0;
}
Using constructors with and without arguments is illustrated next. The object karel is initialized
by the constructor defining a non-empty parameter list while the default constructor is used with
the anon object:
int main()
{
Person karel("Karel", "Rietveldlaan 37", "542 6044", 70);
Person anon;
}
The two Person objects are defined when main starts as they are local objects, living only for as
long as main is active.
If Person objects must be definable using other arguments, corresponding constructors must be
added to Person’s interface. Apart from overloading class constructors it is also possible to provide
constructors with default argument values. These default arguments must be specified with the
constructor declarations in the class interface, like so:
class Person
7.1. THE CONSTRUCTOR 135
{
public:
Person(std::string const &name,
std::string const &address = "--unknown--",
std::string const &phone = "--unknown--",
size_t mass = 0);
};
Often, constructors use highly similar implementions. This results from the fact that the constructor’s
parameters are often defined for convenience: a constructor not requiring a phone number but
requiring a mass cannot be defined using default arguments, since phone is not the constructor’s
last parameter. Consequently a special constructor is required not having phone in its parameter
list.
Before the C++11 standard this situation was commonly handled like this: all constructors must initialize
their reference and const data members, or the compiler (rightfully) complains. To initialize
the remaining members (non-const and non-reference members) we have two options:
• If the body of the construction process is sizeable but (parameterizable) identical to other constructors
bodies then factorize. Define a private member init which is called by the constructors
to provide the object’s data members with their appropriate values.
• If the constructors act fundamentally differently, then there’s nothing to factorize and each
constructor must be implemented by itself.
Currently, C++ allows constructors to call each other (called constructor delegation). This is illustrated
in section 7.4.1 below.
7.1.2.1 The order of construction
The possibility to pass arguments to constructors allows us to monitor the construction order of
objects during program execution. This is illustrated by the next program using a class Test. The
program defines a global Test object and two local Test objects. The order of construction is as
expected: first global, then main’s first local object, then func’s local object, and then, finally, main’s
second local object:
#include <iostream>
#include <string>
using namespace std;
class Test
{
public:
Test(string const &name); // constructor with an argument
};
Test::Test(string const &name)
{
cout << "Test object " << name << " created" << ’\n’;
}
Test globaltest("global");
136 CHAPTER 7. CLASSES
void func()
{
Test functest("func");
}
int main()
{
Test first("main first");
func();
Test second("main second");
}
/*
Generated output:
Test object global created
Test object main first created
Test object func created
Test object main second created
*/
7.2 Ambiguity resolution
Defining objects may result in some unexpected surprises. Assume the following class interface is
available:
class Data
{
public:
Data();
Data(int one);
Data(int one, int two);
void display();
};
The intention is to define two objects of the class Data, using, respectively, the first and second
constructors. Your code looks like this (and compiles correctly):
#include "data.h"
int main()
{
Data d1();
Data d2(argc);
}
Now it’s time to make some good use of the Data objects. You add two statements to main:
d1.display();
d2.display();
But, surprise, the compiler complains about the first of these two:
7.2. AMBIGUITY RESOLUTION 137
error: request for member ’display’ in ’d1’, which is of non-class type ’Data()’
What’s going on here? First of all, notice the data type the compiler refers to: Data(), rather than
Data. What are those () doing there?
Before answering that question, let’s broaden our story somewhat. We know that somewhere in
a library a factory function dataFactory exists. A factory function creates and returns an object
of a certain type. This dataFactory function returns a Data object, constructed using Data’s
default constructor. Hence, dataFactory needs no arguments. We want to use dataFactory in
our program, but must declare the function. So we add the declaration to main, as that’s the only
location where dataFactory will be used. It’s a function, not requiring arguments, returning a
Data object:
Data dataFactory();
This, however, looks remarkably similar to our d1 object definition:
Data d1();
We found the source of our problem: Data d1() apparently is not the definition of a d1 object, but
the declaration of a function, returning a Data object. So, what’s happening here and how should
we define a Data object using Data’s default constructor?
First: what’s happening here is that the compiler, when confronted with Data d1(), actually had a
choice. It could either define a Data object, or declare a function. It declares a function.
In fact, we’re encountering an ambiguity in C++’s syntax here, which is solved, according to the
language’s standard, by always letting a declaration prevail over a definition. We’ll encounter more
situations where this ambiguity occurs later on in this section.
Second: there are several ways we can solve this ambiguity the way we want it to be solved. To
define an object using its default constructor:
• merely mention it (like int x): Data d1;
• use the curly-brace initialization: Data d1{};
• use the assignment operator and an anonymous default constructed Data object: Data d1 =
Data().
7.2.1 Types ‘Data’ vs. ‘Data()’
Data(), which in the above context defines a default constructed anonymous Data object, takes us
back to the compiler error. According to the compiler, our original d1 apparently was not of type
Data, but of type Data(). So what’s that?
Let’s first have a look at our second constructor. It expects an int. We would like to define another
Data object, using the second constructor, but want to pass the default int value to the constructor,
using int(). We know this defines a default int value, as cout << int() << ’\n’ nicely
displays 0, and int x = int() also initialized x to 0. So we define ‘Data di(int())’ in main.
Not good: again the compiler complains when we try to use di. After ‘di.display()’ the compiler
tells us:
error: request for member ’display’ in ’di’, which is of non-class type ’Data(int (_)())’
138 CHAPTER 7. CLASSES
Oops, not as expected.... Didn’t we pass 0? Why the sudden pointer? It’s that same ‘use a declaration
when possible’ strategy again. The notation Type() not only represents the default value of type
Type, but it’s also a shorthand notation for an anonymous pointer to a function, not expecting arguments,
and returning a Type value, which you can verify by defining ‘int (_ip)() = nullptr’,
and passing ip as argument to di: di(ip) compiles fine.
So why doesn’t the error occur when inserting int() or assigning int() to int x? In these latter
cases nothing is declared. Rather, cout and int x = need expressions determining values, which
is provided by int()’s ‘natural’ interpretation. But with ‘Data di(int())’ the compiler again
has a choice, and (by design) it chooses a declaration because the declaration takes priority. Now
int()’s interpretation as an anonymous pointer is available and therefore used.
Likewise, if int x has been defined, ‘Data b1(int(x))’ declares b1 as a function, expecting an
int (as int(x) represents a type), while ‘Data b2((int)x)’ defines b2 as a Data object, using
the constructor expecting a single int value.
7.2.2 Superfluous parentheses
Let’s play some more. At some point in our program we defined int b. Then, in a compound statement
we need to construct an anonymous Data object, initialized using b, followed by displaying
b:
int b = 18;
{
Data(b);
cout << b;
}
About that cout statement the compiler tells us (Imodified the errormessage to reveal its meaning):
error: cannot bind ‘std::ostream & << Data const &’
Here we didn’t insert int b but Data b. Had we omitted the compound statement, the compiler
would have complained about a doubly defined b entity, as Data(b) simply means Data b, a Data
object constructed by default. The compiler may omit superfluous parentheses when parsing a definition
or declaration.
Of course, the question now becomes how a temporary object Data, initialized with int b can be
defined. Remember that the compiler may remove superfluous parentheses. So, what we need to do
is to pass an int to the anonymous Data object, without using the int’s name.
• We can use a cast: Data(static_cast<int>(b));
• We can use a curly-brace initialization: Data {b}.
Values and types make big differences. Consider the following definitions:
Data (*d4)(int); // 1
Data (*d5)(3); // 2
Definition 1 should cause no problems: it’s a pointer to a function, expecting an int, returning a
Data object. Hence, d4 is a pointer variable.
7.2. AMBIGUITY RESOLUTION 139
Definition 2 is slightly more complex. Yes, it’s a pointer. But it has nothing to do with a function.
So what’s that argument list containing 3 doing there? Well, it’s not an argument list. It’s an
initialization that looks like an argument list. Remember that variables can be initialized using the
assignment statement, by parentheses or by curly parentheses. So instead of ‘(3)’ we could have
written ‘= 3’ or ‘{3}’. Let’s pick the first alternative, resulting in:
Data (*d5) = 3;
Now we get to ‘play compiler’ again. Removing some superfluous parentheses we get:
Data *d5 = 3;
It’s a pointer to a Data object, initialized to 3 (semantically incorrect, but that’s only clear after the
syntactical analysis. If I had initially written
Data (*d5)(&d1); // 2
the fun resulting from contrasting int and 3 would most likely have been spoiled).
7.2.3 Existing types
Once a type name has been defined it also prevails over identifiers representing variables, if the
compiler is given a choice. This, too, can result in interesting constructions.
Assume a function process expecting an int exists in a library. We want to use this function to
process some int data values. So in main process is declared and called:
int process(int Data);
process(argc);
No problems here. But unfortunately we once decided to ‘beautify’ our code, by throwing in some
superfluous parentheses, like so:
int process(int (Data));
process(argc);
Now we’re in trouble. The compiler now generates an error, caused by its rule to let declarations
prevail over definitions. Data now becomes the name of the class Data, and analogous to int
(x) the parameter int (Data) is parsed as int (_)(Data): a pointer to a function, expecting a
Data object, returning an int.
Here is another example. When, instead of declaring
int process(int Data[10]);
we declare, e.g., to emphasize the fact that an array is passed to process:
int process(int (Data[10]));
140 CHAPTER 7. CLASSES
the process function does not expect a pointer to int values, but a pointer to a function expecting
a pointer to Data elements, returning an int.
To summarize the findings in the ‘Ambiguity Resolution’ section:
• The compiler will try to remove superfluous parentheses;
• But if the parenthesized construction represents a type, it will try to use the type;
• More in general: when possible the compiler will interpret a syntactic construction as a declaration,
rather than as a definition (of an object or variable).
7.3 Objects inside objects: composition
In the class Person objects are used as data members. This construction technique is called composition.
Composition is neither extraordinary nor C++ specific: in C a struct or union field is commonly
used in other compound types. In C++ it requires some special thought as their initialization sometimes
is subject to restrictions, as discussed in the next few sections.
7.3.1 Composition and const objects: const member initializers
Unless specified otherwise object data members of classes are initialized by their default constructors.
Using the default constructor might not always be the optimal way to intialize an object and it
might not even be possible: a class might simply not define a default constructor.
Earlier we’ve encountered the following constructor of the Person:
Person::Person(string const &name, string const &address,
string const &phone, size_t mass)
{
d_name = name;
d_address = address;
d_phone = phone;
d_mass = mass;
}
Think briefly about what is going on in this constructor. In the constructor’s body we encounter
assignments to string objects. Since assignments are used in the constructor’s body their left-hand
side objects must exist. But when objects are coming into existence constructors must have been
called. The initialization of those objects is thereupon immediately undone by the body of Person’s
constructor. That is not only inefficient but sometimes downright impossible. Assume that the class
interface mentions a string const data member: a data member whose value is not supposed
to change at all (like a birthday, which usually doesn’t change very much and is therefore a good
candidate for a string const data member). Constructing a birthday object and providing it with
an initial value is OK, but changing the initial value isn’t.
The body of a constructor allows assignments to data members. The initialization of data members
happens before that. C++ defines the member initializer syntax allowing us to specify the way
data members are initialized at construction time. Member initializers are specified as a list of
7.3. OBJECTS INSIDE OBJECTS: COMPOSITION 141
constructor specifications between a colon following a constructor’s parameter list and the opening
curly brace of a constructor’s body, as follows:
Person::Person(string const &name, string const &address,
string const &phone, size_t mass)
:
d_name(name),
d_address(address),
d_phone(phone),
d_mass(mass)
{}
Member initialization always occurs when objects are composed in classes: if no constructors are
mentioned in the member initializer list the default constructors of the objects are called. Note that
this only holds true for objects. Data members of primitive data types are not initialized automatically.
Member initialization can, however, also be used for primitive data members, like int and double.
The above example shows the initialization of the data member d_mass from the parameter mass.
When member initializers are used the data member could even have the same name as the constructor’s
parameter (although this is deprecated) as there is no ambiguity and the first (left) identifier
used in a member initializer is always a data member that is initialized whereas the identifier
between parentheses is interpreted as the parameter.
The order in which class type data members are initialized is defined by the order in which those
members are defined in the composing class interface. If the order of the initialization in the constructor
differs from the order in the class interface, the compiler complains, and reorders the initialization
so as to match the order of the class interface.
Member initializers should be used as often as possible. As shown it may be required to use them
(e.g., to initialize const data members, or to initialize objects of classes lacking default constructors)
but not using member initializers also results in inefficient code as the default constructor of a data
member is always automatically called unless an explicit member initializer is specified. Reassignment
in the constructor’s body following default construction is then clearly inefficient. Of course,
sometimes it is fine to use the default constructor, but in those cases the explicit member initializer
can be omitted.
As a rule of thumb: if a value is assigned to a data member in the constructor’s body then try to
avoid that assignment in favor of using a member initializer.
7.3.2 Composition and reference objects: reference member initializers
Apart from using member initializers to initialize composed objects (be they const objects or not),
there is another situation where member initializers must be used. Consider the following situation.
A program uses an object of the class Configfile, defined in main to access the information in a
configuration file. The configuration file contains parameters of the program which may be set by
changing the values in the configuration file, rather than by supplying command line arguments.
Assume another object used in main is an object of the class Process, doing ‘all the work’. What
possibilities do we have to tell the object of the class Process that an object of the class Configfile
exists?
• The objects could have been declared as global objects. This is a possibility, but not a very good
142 CHAPTER 7. CLASSES
one, since all the advantages of local objects are lost.
• The Configfile object may be passed to the Process object at construction time. Bluntly
passing an object (i.e., by value) might not be a very good idea, since the object must be copied
into the Configfile parameter, and then a data member of the Process class can be used to
make the Configfile object accessible throughout the Process class. This might involve yet
another object-copying task, as in the following situation:
Process::Process(Configfile conf) // a copy from the caller
{
d_conf = conf; // copying to d_conf member
}
• The copy-instructions can be avoided if pointers to the Configfile objects are used, as in:
Process::Process(Configfile *conf) // pointer to external object
{
d_conf = conf; // d_conf is a Configfile *
}
This construction as such is OK, but forces us to use the ‘->’ field selector operator, rather
than the ‘.’ operator, which is (disputably) awkward. Conceptually one tends to think of the
Configfile object as an object, and not as a pointer to an object. In C this would probably
have been the preferred method, but in C++ we can do better.
• Rather than using value or pointer parameters, the Configfile parameter could be defined
as a reference parameter of Process’s constructor. Next, use a Config reference data member
in the class Process.
But a reference variable cannot be initialized using an assignment, and so the following is incorrect:
Process::Process(Configfile &conf)
{
d_conf = conf; // wrong: no assignment
}
The statement d_conf = conf fails, because it is not an initialization, but an assignment of one
Configfile object (i.e., conf), to another (d_conf). An assignment to a reference variable is
actually an assignment to the variable the reference variable refers to. But which variable does
d_conf refer to? To no variable at all, since we haven’t initialized d_conf. After all, the whole
purpose of the statement d_conf = conf was to initialize d_conf....
How to initialize d_conf? We once again use the member initializer syntax. Here is the correct way
to initialize d_conf:
Process::Process(Configfile &conf)
:
d_conf(conf) // initializing reference member
{}
The above syntax must be used in all cases where reference data members are used. E.g., if d_ir
would have been an int reference data member, a construction like
Process::Process(int &ir)
7.4. DATA MEMBER INITIALIZERS 143
:
d_ir(ir)
{}
would have been required.
7.4 Data member initializers
Non-static data members of classes are usually initialized by the class’s constructors. Frequently
(but not always) the same initializations are used by different constructors, resulting in multiple
points where the initializations are performed, which in turn complicates class maintenance.
Consider a class defining several data members: a pointer to data, a data member storing the number
of data elements the pointer points at, a data member storing the sequence number of the object.
The class also offer a basic set of constructors, as shown in the following class interface:
class Container
{
Data *d_data;
size_t d_size;
size_t d_nr;
static size_t s_nObjects;
public:
Container();
Container(Container const &other);
Container(Data *data, size_t size);
Container(Container &&tmp);
};
The initial values of the data members are easy to describe, but somewhat hard to implement.
Consider the initial situation and assume the default constructor is used: all data members should
be set to 0, except for d_nr which must be given the value ++s_nObjects. Since these are nondefault
actions, we can’t declare the default constructor using = default, but we must provide an
actual implementation:
Container()
:
d_data(0),
d_size(0),
d_nr(++s_nObjects)
{}
In fact, all constructors require us to state the d_nr(++s_nObjects) initialization. So if d_data’s
type would have been a (move aware) class type, we would still have to provide implementations for
all of the above constructors.
C++, however, also supports data member initializers, simplifying the initialization of non-static
data members. Data member initializers allow us to assign initial values to data members. The
compiler must be able to compute these initial values from initialization expressions, but the initial
values do not have to be constant expressions. So ++s_nObjects can be an initial value.
144 CHAPTER 7. CLASSES
Using data member initializers for the class Container we get:
class Container
{
Data *d_data = 0;
size_t d_size = 0;
size_t d_nr = ++nObjects;
static size_t s_nObjects;
public:
Container() = default;
Container(Container const &other);
Container(Data *data, size_t size);
Container(Container &&tmp);
};
Note that the data member initializations are recognized by the compiler, and are applied to its
implementation of the default constructor. In fact, all constructors will apply the data member initializations,
unless explicitly initialized otherwise. E.g., the move-constructormay now be implented
like this:
Container(Container &&tmp)
:
d_data(tmp.d_data),
d_size(tmp.d_size)
{
tmp.d_data = 0;
}
Although d_nr’s intialization is left out of the implementation it is initialized due to the data member
initialization provided in the class’s interface.
An aggregate is an array or a class (usually a struct with no user-defined constructors, no private
or protected non-static data members, no base classes (cf. chapter 13), and no virtual functions (cf.
chapter 14)). E.g.,
struct POD // defining aggregate POD
{
int first = 5;
double second = 1.28;
std::string hello {"hello"};
};
The C++14 standard allows initialization of such aggregates using braced initializer lists. E.g.,
POD pod {4, 13.5, "hi there"};
When using braced-initializer lists not all data members need to be initialized. Specification may
stop at any data member, in which case the default (or explicitly defined initialization values) of the
remaining data members are used. E.g.,
POD pod {4}; // uses second: 1.28, hello: "hello"
7.4. DATA MEMBER INITIALIZERS 145
7.4.1 Delegating constructors
Often constructors are specializations of each other, allowing objects to be constructed specifying
only subsets of arguments for all of its data members, using default argument values for the remaining
data members.
Before the C++11 standard common practice was to define a member like init performing all initializations
common to constructors. Such an init function, however, cannot be used to initialize
const or reference data members, nor can it be used to perform so-called base class initializations
(cf. chapter 13).
Here is an example where such an init function might have been used. A class Stat is designed
as a wrapper class around C’s stat(2) function. The class might define three constructors: one
expecting no arguments and initializing all data members to appropriate values; a second one doing
the same, but it calls stat for the filename provided to the constructor; and a third one expecting a
filename and a search path for the provided file name. Instead of repeating the initialization code
in each constructor, the common code can be factorized into a member init which is called by the
constructors.
Currently, C++ offers an alternative by allowing constructors to call each other. This is called delegating
constructors The C++11 standard allows us to delegate constructors as illustrated by the next
example:
class Stat
{
public:
Stat()
:
State("", "") // no filename/searchpath
{}
Stat(std::string const &fileName)
:
Stat(fileName, "") // only a filename
{}
Stat(std::string const &fileName, std::string const &searchPath)
:
d_filename(fileName),
d_searchPath(searchPath)
{
// remaining actions to be performed by the constructor
}
};
C++ allows static const integral data members to be initialized within the class interfaces (cf. chapter
8). The C++11 standard adds to this the facility to define default initializations for plain data
members in class interfaces (these data members may or may not be const or of integral types, but
(of course) they cannot be reference data members).
These default initializations may be overruled by constructors. E.g., if the class Stat uses a data
member bool d_hasPath which is false by default but the third constructor (see above) should
initialize it to true then the following approach is possible:
class Stat
{
bool d_hasPath = false;
146 CHAPTER 7. CLASSES
public:
Stat(std::string const &fileName, std::string const &searchPath)
:
d_hasPath(true) // overrule the interface-specified
// value
{}
};
Here d_hasPath receives its value only once: it’s always initialized to false except when the shown
constructor is used in which case it is initialized to true.
7.5 Uniform initialization
When defining variables and objects theymay immediately be given initial values. Class type objects
are always initialized using one of their available constructors. C already supports the array and
struct initializer list consisting of a list of constant expressions surrounded by a pair of curly braces.
C++ supports a comparable initialization, called uniform initialization. It uses the following syntax:
Type object {value list};
When defining objects using a list of objects each individual object may use its own uniform initialization.
The advantage of uniform initialization over using constructors is that using constructor arguments
may sometimes result in an ambiguity as constructing an object may sometimes be confused with
using the object’s overloaded function call operator (cf. section 11.10). As initializer lists can only be
used with plain old data (POD) types (cf. section 9.9) and with classes that are ‘initializer list aware’
(like std::vector) the ambiguity does not arise when initializer lists are used.
Uniform initialization can be used to initialize an object or variable, but also to initialize data members
in a constructor or implicitly in the return statement of functions. Examples:
class Person
{
// data members
public:
Person(std::string const &name, size_t mass)
:
d_name {name},
d_mass {mass}
{}
Person copy() const
{
return {d_name, d_mass};
}
};
Object definitions may be encountered in unexpected places, easily resulting in (human) confusion.
Consider a function ‘func’ and a very simple class Fun (struct is used, as data hiding is not an
issue here; in-class implementatinos are used for brevity):
7.5. UNIFORM INITIALIZATION 147
void func();
struct Fun
{
Fun(void (*f)())
{
std::cout << "Constructor\n";
};
void process()
{
std::cout << "process\n";
}
};
In main a Fun object is defined: Fun fun(func). Running this program displays Constructor:
fun is constructed. Next we intend to call process for an anonymous Fun object:
Fun fun(func);
Fun(func).process();
Constructor appears twice, and then process is displayed.
What about just defining an anonymous Fun object? We do:
Fun(func);
Now we’re in for a surprise. The compiler complains that Fun’s default constructor is missing. Why’s
that? Insert some blanks immediately after Fun and you get Fun (func). Parentheses around an
identifier are OK, and are stripped off once the parenthesized expression has been parsed. In this
case: (func) equals func, and so we have Fun func: the definition of a Fun func object, using
Fun’s default constructor (which isn’t provided).
So why does Fun(func).process() compile? In this case we have a member selector operator,
whose left-hand operand must be an class-type object. The object must exist, and Fun(func) represents
that object. It’s not the name of an existing object, but a constructor expecting a function like
func exists. The compiler now creates an anonymous Fun, passing it func as its argument.
Clearly, in this example, parentheses cannot be used to create an anonymous Fun object. However,
the uniform initialization can be used. To define the anonymous Fun object use this syntax:
Fun {func};
(which can also be used to immediately call one of its members. E.g., Fun{func}.process()).
Although the uniform intialization syntax is slightly different from the syntax of an initializer list
(the latter using the assignment operator) the compiler nevertheless uses the initializer list if a
constructor supporting an initializer list is available. As an example consider:
class Vector
{
public:
Vector(size_t size);
148 CHAPTER 7. CLASSES
Vector(std::initializer_list<int> const &values);
};
Vector vi = {4};
When defining vi the constructor expecting the initializer list is called rather than the constructor
expecting a size_t argument. If the latter constructor is required the definition using the standard
constructor syntax must be used. I.e., Vector vi(4).
Initializer lists are themselves objects that may be constructed using another initializer list. However,
values stored in an initializer list are immutable. Once the initializer list has been defined
their values remain as-is.
Before using the initializer_list the initializer_list header file must be included.
Initializer lists support a basic set of member functions and constructors:
• initializer_list<Type> object:
defines object as an empty initializer list
• initializer_list<Type> object { list of Type values }:
defines object as an initializer list containing Type values
• initializer_list<Type> object(other):
initializes object using the values stored in other
• size_t size() const:
returns the number of elements in the initializer list
• Type const _begin() const:
returns a pointer to the first element of the initializer list
• Type const _end() const:
returns a pointer just beyond the location of the last element of the initializer list
7.6 Defaulted and deleted class members
In everyday class design two situations are frequently encountered:
• A class offering constructors explicitly has to define a default constructor;
• A class (e.g., a class implementing a stream) cannot initialize objects by copying the values
from an existing object of that class (called copy construction) and cannot assign objects to each
other.
Once a class defines at least one constructor its default constructor is not automatically defined by
the compiler. C++ relaxes that restriction somewhat by offering the ‘= default’ syntax. A class
specifying ‘= default’ with its default constructor declaration indicates that the trivial default
constructor should be provided by the compiler. A trivial default constructor performs the following
actions:
• Its data members of built-in or primitive types are not initialized;
7.7. CONST MEMBER FUNCTIONS AND CONST OBJECTS 149
• Its composed (class type) data members are initialized by their default constructors.
• If the class is derived froma base class (cf. chapter 13) the base class is initialized by its default
constructor.
Trivial implementations can also be provided for the copy constructor, the overloaded assignment
operator, and the destructor. Those members are introduced in chapter 9.
Conversely, situations exist where some (otherwise automatically provided) members should not be
made available. This is realized by specifying ‘= delete’. Using = default and = delete is
illustrated by the following example. The default constructor receives its trivial implementation,
copy-construction is prevented:
class Strings
{
public:
Strings() = default;
Strings(std::string const *sp, size_t size);
Strings(Strings const &other) = delete;
};
7.7 Const member functions and const objects
The keyword const is often used behind the parameter list of member functions. This keyword
indicates that a member function does not alter the data members of its object. Such member
functions are called const member functions. In the class Person, we see that the accessor functions
were declared const:
class Person
{
public:
std::string const &name() const;
std::string const &address() const;
std::string const &phone() const;
size_t mass() const;
};
The rule of thumb given in section 3.1.1 applies here too: whichever appears to the left of the keyword
const, is not altered. With member functions this should be interpreted as ‘doesn’t alter its own
data’.
When implementing a const member function the const attribute must be repeated:
string const &Person::name() const
{
return d_name;
}
The compiler prevents the data members of a class from being modified by one of its const member
functions. Therefore a statement like
d_name[0] = toupper(static_cast<unsigned char>(d_name[0]));
150 CHAPTER 7. CLASSES
results in a compiler error when added to the above function’s definition.
Const member functions are used to prevent inadvertent data modification. Except for constructors
and the destructor (cf. chapter 9) only const member functions can be used with (plain, references
or pointers to) const objects.
Const objects are frequently encounterd as const & parameters of functions. Inside such functions
only the object’s const members may be used. Here is an example:
void displayMass(ostream &out, Person const &person)
{
out << person.name() << " weighs " << person.mass() << " kg.\n";
}
Since person is defined as a Person const & the function displayMass cannot call, e.g.,
person.setMass(75).
The const member function attribute can be used to overload member functions. When functions
are overloaded by their const attribute the compiler uses the member function matching most
closely the const-qualification of the object:
• When the object is a const object, only const member functions can be used.
• When the object is not a const object, non-const member functions are used, unless only a
const member function is available. In that case, the const member function is used.
The next example illustrates how (non) const member functions are selected:
#include <iostream>
using namespace std;
class Members
{
public:
Members();
void member();
void member() const;
};
Members::Members()
{}
void Members::member()
{
cout << "non const member\n";
}
void Members::member() const
{
cout << "const member\n";
}
int main()
{
Members const constObject;
Members nonConstObject;
7.7. CONST MEMBER FUNCTIONS AND CONST OBJECTS 151
constObject.member();
nonConstObject.member();
}
/*
Generated output:
const member
non const member
*/
As a general principle of design: member functions should always be given the const attribute,
unless they actually modify the object’s data.
7.7.1 Anonymous objects
Sometimes objects are used because they offer a certain functionality. The objects only exist because
of their functionality, and nothing in the objects themselves is ever changed. The following
class Print offers a facility to print a string, using a configurable prefix and suffix. A partial class
interface could be:
class Print
{
public:
Print(ostream &out);
void print(std::string const &prefix, std::string const &text,
std::string const &suffix) const;
};
An interface like this would allow us to do things like:
Print print(cout);
for (int idx = 0; idx != argc; ++idx)
print.print("arg: ", argv[idx], "\n");
This works fine, but it could greatly be improved if we could pass print’s invariant arguments to
Print’s constructor. This would simplify print’s prototype (only one argument would need to be
passed rather than three) and we could wrap the above code in a function expecting a Print object:
void allArgs(Print const &print, int argc, char *argv[])
{
for (int idx = 0; idx != argc; ++idx)
print.print(argv[idx]);
}
The above is a fairly generic piece of code, at least it is with respect to Print. Since prefix and
suffix don’t change they can be passed to the constructor which could be given the prototype:
Print(ostream &out, string const &prefix = "", string const &suffix = "");
152 CHAPTER 7. CLASSES
Now allArgs may be used as follows:
Print p1(cout, "arg: ", "\n"); // prints to cout
Print p2(cerr, "err: --", "--\n"); // prints to cerr
allArgs(p1, argc, argv); // prints to cout
allArgs(p2, argc, argv); // prints to cerr
But now we note that p1 and p2 are only used inside the allArgs function. Furthermore, as we can
see from print’s prototype, print doesn’t modify the internal data of the Print object it is using.
In such situations it is actually not necessary to define objects before they are used. Instead anonymous
objects may be used. Anonymous objects can be used:
• to initialize a function parameter which is a const reference to an object;
• if the object is only used inside the function call.
These anonymous objects are considered constant as they merely exist for passing the information
of (class type) objects to functions. They are not considered ’variables’. Of course, a const_cast
could be used to cast away the const reference’s constness, but any change is lost once the function
returns. These anonymous objects used to initialize const references should not be confused with
rvalue references (section 3.3.2) which have a completely different purpose in life. Rvalue references
primarily exist to be ‘swallowed’ by functions receiving them. Thus, the information made available
by rvalue references outlives the rvalue reference objects which are also anonymous.
Anonymous objects are defined when a constructor is used without providing a name for the constructed
object. Here is the corresponding example:
allArgs(Print(cout, "arg: ", "\n"), argc, argv); // prints to cout
allArgs(Print(cerr, "err: --", "--\n"), argc, argv);// prints to cerr
In this situation the Print objects are constructed and immediately passed as first arguments to
the allArgs functions, where they are accessible as the function’s print parameter. While the
allArgs function is executing they can be used, but once the function has completed, the anonymous
Print objects are no longer accessible.
7.7.1.1 Subtleties with anonymous objects
Anonymous objects can be used to initialize function parameters that are const references to objects.
These objects are created just before such a function is called, and are destroyed once the
function has terminated. C++’s grammar allows us to use anonymous objects in other situations as
well. Consider the following snippet of code:
int main()
{
// initial statements
Print("hello", "world");
// later statements
}
7.7. CONST MEMBER FUNCTIONS AND CONST OBJECTS 153
In this example an anonymous Print object is constructed, and it is immediately destroyed thereafter.
So, following the ‘initial statements’ our Print object is constructed. Then it is destroyed
again followed by the execution of the ‘later statements’.
The example illustrates that the standard lifetime rules do not apply to anonymous objects. Their
lifetimes are limited to the statements, rather than to the end of the block in which they are defined.
Plain anonymous object are at least useful in one situation. Assume we want to put markers in
our code producing some output when the program’s execution reaches a certain point. An object’s
constructor could be implemented so as to provide that marker-functionality allowing us to put
markers in our code by defining anonymous, rather than named objects.
C++’s grammar contains another remarkable characteristic illustrated by the next example:
int main(int argc, char **argv)
{
Print p(cout, "", ""); // 1
allArgs(Print(p), argc, argv); // 2
}
In this example a non-anonymous object p is constructed in statement 1, which is then used in
statement 2 to initialize an anonymous object. The anonymous object, in turn, is then used to
initialize allArgs’s const reference parameter. This use of an existing object to initialize another
object is common practice, and is based on the existence of a so-called copy constructor. A copy
constructor creates an object (as it is a constructor) using an existing object’s characteristics to
initialize the data of the object that’s created. Copy constructors are discussed in depth in chapter
9, but presently only the concept of a copy constructor is used.
In the above example a copy constructor is used to initialize an anonymous object. The anonymous
object was then used to initialize a parameter of a function. However, when we try to apply the
same trick (i.e., using an existing object to initialize an anonymous object) to a plain statement, the
compiler generates an error: the object p can’t be redefined (in statement 3, below):
int main(int argc, char *argv[])
{
Print p("", ""); // 1
allArgs(Print(p), argc, argv); // 2
Print(p); // 3 error!
}
Does this mean that using an existing object to initialize an anonymous object that is used as function
argument is OK, while an existing object can’t be used to initialize an anonymous object in a
plain statement?
The compiler actually provides us with the answer to this apparent contradiction. About statement
3 the compiler reports something like:
error: redeclaration of ’Print p’
which solves the problem when realizing that within a compound statement objects and variables
may be defined. Inside a compound statement, a type name followed by a variable name is the
grammatical form of a variable definition. Parentheses can be used to break priorities, but if there
are no priorities to break, they have no effect, and are simply ignored by the compiler. In statement
3 the parentheses allowed us to get rid of the blank that’s required between a type name and the
variable name, but to the compiler we wrote
154 CHAPTER 7. CLASSES
Print (p);
which is, since the parentheses are superfluous, equal to
Print p;
thus producing p’s redeclaration.
As a further example: when we define a variable using a built-in type (e.g., double) using superfluous
parentheses the compiler quietly removes these parentheses for us:
double ((((a)))); // weird, but OK.
To summarize our findings about anonymous variables:
• Anonymous objects are great for initializing const reference parameters.
• The same syntaxis, however, can also be used in stand-alone statements, in which they are
interpreted as variable definitions if our intention actually was to initialize an anonymous
object using an existing object.
• Since this may cause confusion, it’s probably best to restrict the use of anonymous objects to
the first (and main) form: initializing function parameters.
7.8 The keyword ‘inline’
Let us take another look at the implementation of the function Person::name():
std::string const &Person::name() const
{
return d_name;
}
This function is used to retrieve the name field of an object of the class Person. Example:
void showName(Person const &person)
{
cout << person.name();
}
To insert person’s name the following actions are performed:
• The function Person::name() is called.
• This function returns person’s d_name as a reference.
• The referenced name is inserted into cout.
Especially the first part of these actions causes some time loss, since an extra function call is necessary
to retrieve the value of the name field. Sometimes a faster procedure immediately making
7.8. THE KEYWORD ‘INLINE’ 155
the d_name data member available is preferred without ever actually calling a function name. This
can be realized using inline functions. An inline function is a request to the compiler to insert the
function’s code at the location of the function’s call. This may speed up execution by avoiding a function
call, which typically comes with some (stack handling and parameter passing) overhead. Note
that inline is a request to the compiler: the compiler may decide to ignore it, and will probably
ignore it when the function’s body contains much code. Good programming discipline suggests to be
aware of this, and to avoid inline unless the function’s body is fairly small. More on this in section
7.8.2.
7.8.1 Defining members inline
Inline functions may be implemented in the class interface itself. For the class Person this results
in the following implementation of name:
class Person
{
public:
std::string const &name() const
{
return d_name;
}
};
Note that the inline code of the function name now literally occurs inline in the interface of the class
Person. The keyword const is again added to the function’s header.
Although members can be defined in-class (i.e., inside the class interface itself), it is considered bad
practice for the following reasons:
• Defining members inside the interface contaminates the interface with implementations. The
interface’s purpose is to document what functionality the class offers. Mixing member declarations
and implementation details complicates understanding the interface. Readers need to
skip implementation details which takes time and makes it hard to grab the ‘broad picture’,
and thus to understand at a glance what functionality the class’s objects are offering.
• In-class implementations of private member functions may usually be avoided altogether (as
they are private members). They should be moved to the internal header file (unless inline
public members use such inline private members).
• Although members that are eligible for inline-coding should remain inline, situations do exist
where such inline members migrate from an inline to a non-inline definition. In-class inline
definitions still need editing (sometimes considerable editing) before they can be compiled.
This additional editing is undesirable.
Because of the above considerations inline members should not be defined in-class. Rather, they
should be defined following the class interface. The Person::name member is therefore preferably
defined as follows:
class Person
{
public:
std::string const &name() const;
156 CHAPTER 7. CLASSES
};
inline std::string const &Person::name() const
{
return d_name;
}
If it is ever necessary to cancel Person::name’s inline implementation, then this becomes its noninline
implementation:
#include "person.ih"
std::string const &Person::name() const
{
return d_name;
}
Only the inline keyword needs to be removed to obtain the correct non-inline implementation.
Defining members inline has the following effect: whenever an inline-defined function is called, the
compilermay insert the function’s body at the location of the function call. It may be that the function
itself is never actually called.
This construction, where the function code itself is inserted rather than a call to the function, is
called an inline function. Note that using inline functions may result in multiple occurrences of the
code of those functions in a program: one copy for each invocation of the inline function. This is
probably OK if the function is a small one, and needs to be executed fast. It’s not so desirable if
the code of the function is extensive. The compiler knows this too, and handles the use of inline
functions as a request rather than a command. If the compiler considers the function too long, it will
not grant the request. Instead it will treat the function as a normal function.
7.8.2 When to use inline functions
When should inline functions be used, and when not? There are some rules of thumb which may be
followed:
• In general inline functions should not be used. Voilà; that’s simple, isn’t it?
• Consider defining a function inline once a fully developed and tested program runs too slowly
and shows ‘bottlenecks’ in certain functions, and the bottleneck is removed by defining inline
members. A profiler, which runs a program and determines where most of the time is spent, is
necessary to perform such optimizations.
• Defining inline functions may be considered when they consist of one very simple statement
(such as the return statement in the function Person::name).
• When a function is defined inline, its implementation is inserted in the code wherever the
function is used. As a consequence, when the implementation of the inline function changes, all
sources using the inline function must be recompiled. In practice that means that all functions
must be recompiled that include (either directly or indirectly) the header file of the class in
which the inline function is defined. Not a very attractive prospect.
• It is only useful to implement an inline function when the time spent during a function call is
long compared to the time spent by the function’s body. An example of an inline function which
hardly affects the program’s speed is:
7.9. LOCAL CLASSES: CLASSES INSIDE FUNCTIONS 157
inline void Person::printname() const
{
cout << d_name << ’\n’;
}
This function contains only one statement. However, the statement takes a relatively long time
to execute. In general, functions which performinput and output take lots of time. The effect of
the conversion of this function printname() to inline would therefore lead to an insignificant
gain in execution time.
All inline functions have one disadvantage: the actual code is inserted by the compiler and must
therefore be known at compile-time. Therefore, as mentioned earlier, an inline function can never
be located in a run-time library. Practically this means that an inline function is found near the
interface of a class, usually in the same header file. The result is a header file which not only
shows the declaration of a class, but also part of its implementation, thus always blurring the
distinction between interface and implementation.
7.8.2.1 A prelude: when NOT to use inline functions
As a prelude to chapter 14 (Polymorphism), there is one situation in which inline functions should
definitely be avoided. At this point in the C++ Annotations it’s a bit too early to expose the full
details, but since the keyword inline is the topic of this section this is considered the appropriate
location for the advice.
There are situations where the compiler is confronted with so-called vague linkage
(cf. http://gcc.gnu.org/onlinedocs/gcc-4.6.0/gcc/Vague-Linkage.html). These situations
occur when the compiler does not have a clear indication in what object file to put its compiled
code. This happens, e.g., with inline functions, which are usually encountered in multiple source
files. Since the compiler may insert the code of ordinary inline functions in places where these
functions are called, vague linking is usually no problem with these ordinary functions.
However, as explained in chapter 14, when using polymorphism the compiler must ignore the
inline keyword and define so-called virtual members as true (out-of-line functions). In this situation
the vague linkage may cause problems, as the compiler must decide in what object s to put
their code. Usually that’s not a big problemas long as the function is at least called once. But virtual
functions are special in the sense that they may very well never be explicitly called. On some architectures
(e.g., armel) the compiler may fail to compile such inline virtual functions. This may result
in missing symbols in programs using them. To make matters slightly more complex: the problem
may emerge when shared libraries are used, but not when static libraries are used.
To avoid all of these problems virtual functions should never be defined inline, but they should
always be defined out-of-line. I.e., they should be defined in source files.
7.9 Local classes: classes inside functions
Classes are usually defined at the global or namespace level. However, it is entirely possible to
define a local class, i.e., inside a function. Such classes are called local classes.
Local classes can be very useful in advanced applications involving inheritance or templates (cf.
section 13.8). At this point in the C++ Annotations they have limited use, although their main
features can be described. At the end of this section an example is provided.
158 CHAPTER 7. CLASSES
• Local classes may use almost all characteristics of normal classes. Theymay have constructors,
destructors, data members, and member functions;
• Local classes cannot define static data members. Static member functions, however, can be
defined.
• Since a local class may define static member functions, it is possible to define nested functions
in C++ somewhat comparable to the way programming languages like Pascal allow nested
functions to be defined.
• If a local class needs access to a constant integral value, a local enum can be used. The enum
may be anonymous, exposing only the enum values.
• Local classes cannot directly access the non-static variables of their surrounding context. For
example, in the example shown below the class Local cannot directly access main’s argc
parameter.
• Local classes may directly access global data and static variables defined by their surrounding
function. This includes variables defined in the anonymous namespace of the source file
containing the local class.
• Local class objects can be defined inside the function body, but they cannot leave the function
as objects of their own type. I.e., a local class name cannot be used for either the return type
or for the parameter types of its surrounding function.
• As a prelude to inheritance (chapter 13): a local class may be derived from an existing class
allowing the surrounding function to return a dynamically allocated locally constructed class
object, pointer or reference could be returned via a base class pointer or reference.
#include <iostream>
#include <string>
using namespace std;
int main(int argc, char *argv[])
{
static size_t staticValue = 0;
class Local
{
int d_argc; // non-static data members OK
public:
enum // enums OK
{
VALUE = 5
};
Local(int argc) // constructors and member functions OK
: // in-class implementation required
d_argc(argc)
{
// global data: accessible
cout << "Local constructor\n";
// static function variables: accessible
staticValue += 5;
}
7.10. THE KEYWORD ‘MUTABLE’ 159
static void hello() // static member functions: OK
{
cout << "hello world\n";
}
};
Local::hello(); // call Local static member
Local loc(argc); // define object of a local class.
}
7.10 The keyword ‘mutable’
Earlier, in section 7.7, the concepts of const member functions and const objects were introduced.
C++ also allows the declaration of data members whichmay be modified, even by constmember function.
The declaration of such data members in the class interface start with the keyword mutable.
Mutable should be used for those data members that may be modified without logically changing
the object, which might therefore still be considered a constant object.
An example of a situation where mutable is appropriately used is found in the implementation of a
string class. Consider the std::string’s c_str and data members. The actual data returned by
the two members are identical, but c_str must ensure that the returned string is terminated by an
0-byte. As a string object has both a length and a capacity an easy way to implement c_str is to
ensure that the string’s capacity exceeds its length by at least one character. This invariant allows
c_str to be implemented as follows:
char const *string::c_str() const
{
d_data[d_length] = 0;
return d_data;
}
This implementation logically does not modify the object’s data as the bytes beyond the object’s
initial (length) characters have undefined values. But in order to use this implementation d_data
must be declared mutable:
mutable char *d_data;
The keyword mutable is also useful in classes implementing, e.g., reference counting. Consider a
class implementing reference counting for textstrings. The object doing the reference countingmight
be a const object, but the class may define a copy constructor. Since const objects can’t be modified,
how would the copy constructor be able to increment the reference count? Here the mutable keyword
may profitably be used, as it can be incremented and decremented, even though its object is a
const object.
The keyword mutable should sparingly be used. Data modified by const member functions should
never logically modify the object, and it should be easy to demonstrate this. As a rule of thumb: do
not use mutable unless there is a very clear reason (the object is logically not altered) for violating
this rule.
160 CHAPTER 7. CLASSES
7.11 Header file organization
In section 2.5.10 the requirements for header files when a C++ program also uses C functions were
discussed. Header files containing class interfaces have additional requirements.
First, source files. With the exception of the occasional classless function, source files contain the
code of member functions of classes. here there are basically two approaches:
• All required header files for a member function are included in each individual source file.
• All required header files (for all member functions of a class) are included in a header file that
is included by each of the source files defining class members.
The first alternative has the advantage of economy for the compiler: it only needs to read the header
files that are necessary for a particular source file. It has the disadvantage that the program developer
must include multiple header files again and again in sourcefiles: it both takes time to type the
include-directives and to think about the header files which are needed in a particular source file.
The second alternative has the advantage of economy for the program developer: the header file of
the class accumulates header files, so it tends to become more and more generally useful. It has the
disadvantage that the compiler frequently has to process many header files which aren’t actually
used by the function to compile.
With computers running faster and faster (and compilers getting smarter and smarter) I think the
second alternative is to be preferred over the first alternative. So, as a starting point source files of
a particular class MyClass could be organized according to the following example:
#include <myclass.h>
int MyClass::aMemberFunction()
{}
There is only one include-directive. Note that the directive refers to a header file in a directory
mentioned in the INCLUDE-file environment variable. Local header files (using #include
"myclass.h") could be used too, but that tends to complicate the organization of the class header
file itself somewhat.
The organization of the header file itself requires some attention. Consider the following example,
in which two classes File and String are used.
Assume the File class has a member gets(String &destination), while the class String has
a member function getLine(File &file). The (partial) header file for the class String is
then:
#ifndef STRING_H_
#define STRING_H_
#include <project/file.h> // to know about a File
class String
{
public:
void getLine(File &file);
};
#endif
7.11. HEADER FILE ORGANIZATION 161
Unfortunately a similar setup is required for the class File:
#ifndef FILE_H_
#define FILE_H_
#include <project/string.h> // to know about a String
class File
{
public:
void gets(String &string);
};
#endif
Now we have created a problem. The compiler, trying to compile the source file of the function
File::gets proceeds as follows:
• The header file project/file.h is opened to be read;
• FILE_H_ is defined
• The header file project/string.h is opened to be read
• STRING_H_ is defined
• The header file project/file.h is (again) opened to be read
• Apparently, FILE_H_ is already defined, so the remainder of project/file.h is skipped.
• The interface of the class String is now parsed.
• In the class interface a reference to a File object is encountered.
• As the class File hasn’t been parsed yet, a File is still an undefined type, and the compiler
quits with an error.
The solution to this problem is to use a forward class reference before the class interface, and to
include the corresponding class header file beyond the class interface. So we get:
#ifndef STRING_H_
#define STRING_H_
class File; // forward reference
class String
{
public:
void getLine(File &file);
};
#include <project/file.h> // to know about a File
#endif
162 CHAPTER 7. CLASSES
A similar setup is required for the class File:
#ifndef FILE_H_
#define FILE_H_
class String; // forward reference
class File
{
public:
void gets(String &string);
};
#include <project/string.h> // to know about a String
#endif
This works well in all situations where either references or pointers to other classes are involved
and with (non-inline) member functions having class-type return values or parameters.
This setup doesn’t work with composition, nor with in-class inline member functions. Assume the
class File has a composed data member of the class String. In that case, the class interface of the
class File must include the header file of the class String before the class interface itself, because
otherwise the compiler can’t tell how big a File object is. A File object contains a String member,
but the compiler can’t determine the size of that String data member and thus, by implication, it
can’t determine the size of a File object.
In cases where classes contain composed objects (or are derived from other classes, see chapter 13)
the header files of the classes of the composed objects must have been read before the class interface
itself. In such a case the class File might be defined as follows:
#ifndef FILE_H_
#define FILE_H_
#include <project/string.h> // to know about a String
class File
{
String d_line; // composition !
public:
void gets(String &string);
};
#endif
The class String can’t declare a File object as a composed member: such a situation would again
result in an undefined class while compiling the sources of these classes.
All remaining header files (appearing below the class interface itself) are required only because they
are used by the class’s source files.
This approach allows us to introduce yet another refinement:
• Header files defining a class interface should declare what can be declared before defining the
7.11. HEADER FILE ORGANIZATION 163
class interface itself. So, classes that are mentioned in a class interface should be specified
using forward declarations unless
– They are a base class of the current class (see chapter 13);
– They are the class types of composed data members;
– They are used in inline member functions.
In particular: additional actual header files are not required for:
– class-type return values of functions;
– class-type value parameters of functions.
Class header files of objects that are either composed or inherited or that are used in inline
functions, must be known to the compiler before the interface of the current class starts. The
information in the header file itself is protected by the #ifndef ... #endif construction
introduced in section 2.5.10.
• Program sources in which the class is used only need to include this header file. Lakos, (2001)
refines this process even further. See his book Large-Scale C++ Software Design for further
details. This header file should be made available in a well-known location, such as a directory
or subdirectory of the standard INCLUDE path.
• To implement member functions the class’s header file is required and usually additional
header files (like the string header file) as well. The class header file itself as well as these
additional header files should be included in a separate internal header file (for which the
extension .ih (‘internal header’) is suggested).
The .ih file should be defined in the same directory as the source files of the class. It has the
following characteristics:
– There is no need for a protective #ifndef .. #endif shield, as the header file is never
included by other header files.
– The standard .h header file defining the class interface is included.
– The header files of all classes used as forward references in the standard .h header file
are included.
– Finally, all other header files that are required in the source files of the class are included.
An example of such a header file organization is:
– First part, e.g., /usr/local/include/myheaders/file.h:
#ifndef FILE_H_
#define FILE_H_
#include <fstream> // for composed ’ifstream’
class Buffer; // forward reference
class File // class interface
{
std::ifstream d_instream;
public:
void gets(Buffer &buffer);
};
#endif
164 CHAPTER 7. CLASSES
– Second part, e.g., ~/myproject/file/file.ih, where all sources of the class File are
stored:
#include <myheaders/file.h> // make the class File known
#include <buffer.h> // make Buffer known to File
#include <string> // used by members of the class
#include <sys/stat.h> // File.
7.11.1 Using namespaces in header files
When entities from namespaces are used in header files, no using directive should be specified in
those header files if they are to be used as general header files declaring classes or other entities
from a library. When the using directive is used in a header file then users of such a header file are
forced to accept and use the declarations in all code that includes the particular header file.
For example, if in a namespace special an object Inserter cout is declared, then
special::cout is of course a different object than std::cout. Now, if a class Flaw is constructed,
in which the constructor expects a reference to a special::Inserter, then the class should be
constructed as follows:
class special::Inserter;
class Flaw
{
public:
Flaw(special::Inserter &ins);
};
Now the person designing the class Flawmay be in a lazymood, andmight get bored by continuously
having to prefix special:: before every entity from that namespace. So, the following construction
is used:
using namespace special;
class Inserter;
class Flaw
{
public:
Flaw(Inserter &ins);
};
This works fine, up to the point where somebody wants to include flaw.h in other source files:
because of the using directive, this latter person is now by implication also using namespace
special, which could produce unwanted or unexpected effects:
#include <flaw.h>
#include <iostream>
using std::cout;
int main()
7.12. SIZEOF APPLIED TO CLASS DATA MEMBERS 165
{
cout << "starting\n"; // won’t compile
}
The compiler is confronted with two interpretations for cout: first, because of the using directive
in the flaw.h header file, it considers cout a special::Inserter, then, because of the using
directive in the user program, it considers cout a std::ostream. Consequently, the compiler
reports an error.
As a rule of thumb, header files intended for general use should not contain using declarations.
This rule does not hold true for header files which are only included by the sources of a class: here
the programmer is free to apply as many using declarations as desired, as these directives never
reach other sources.
7.12 Sizeof applied to class data members
In C++ the well-known sizeof operator can be applied to data members of classes without the need
to specify an object as well. Consider:
class Data
{
std::string d_name;
...
};
To obtain the size of Data’s d_name member the following expression can be used:
sizeof(Data::d_name);
However, note that the compiler observes data protection here as well. Sizeof(Data::d_name)
can only be used where d_name may be visible as well, i.e., by Data’s member functions and friends.
166 CHAPTER 7. CLASSES

Chapter 8
Static Data And Functions
In the previous chapters we provided examples of classes where each object had its own set of data
members data. Each of the class’s member functions could access any member of any object of its
class.
In some situations it may be desirable to define common data fields, that may be accessed by all
objects of the class. For example, the name of the startup directory, used by a program that recursively
scans the directory tree of a disk. A second example is a variable that indicates whether some
specific initialization has occurred. In that case the object that was constructed first would perform
the initialization and would set the flag to ‘done’.
Such situations are also encountered in C, where several functions need to access the same variable.
A common solution in C is to define all these functions in one source file and to define the variable
static: the variable name is invisible outside the scope of the source file. This approach is quite
valid, but violates our philosophy of using only one function per source file. Another C-solution is
to give the variable in question an unusual name, e.g., _6uldv8, hoping that other program parts
won’t use this name by accident. Neither the first, nor the second legacy C solution is elegant.
C++ solves the problem by defining static members: data and functions, common to all objects
of a class and (when defined in the private section) inaccessible outside of the class. These static
members are this chapter’s topic.
Static members cannot be defined as virtual functions. A virtual member function is an ordinary
member in that it has a this pointer. As static member functions have no this pointer, they cannot
be declared virtual.
8.1 Static data
Any data member of a class can be declared static; be it in the public or private section of the
class interface. Such a data member is created and initialized only once, in contrast to non-static
data members which are created again and again for each object of the class.
Static data members are created as soon as the program starts. Even though they’re created at the
very beginning of a program’s execution cycle they are nevertheless true members of their classes.
It is suggested to prefix the names of static member with s_ so they may easily be distinguished (in
class member functions) from the class’s data members (which should preferably start with d_).
167
168 CHAPTER 8. STATIC DATA AND FUNCTIONS
Public static data members are global variables. They may be accessed by all of the program’s code,
simply by using their class names, the scope resolution operator and their member names. Example:
class Test
{
static int s_private_int;
public:
static int s_public_int;
};
int main()
{
Test::s_public_int = 145; // OK
Test::s_private_int = 12; // wrong, don’t touch
// the private parts
}
The example does not present an executable program. It merely illustrates the interface, and not
the implementation of static data members, which is discussed next.
8.1.1 Private static data
To illustrate the use of a static data member which is a private variable in a class, consider the
following:
class Directory
{
static char s_path[];
public:
// constructors, destructors, etc.
};
The data member s_path[] is a private static data member. During the program’s execution only
one Directory::s_path[] exists, even though multiple objects of the class Directory may exist.
This data member could be inspected or altered by the constructor, destructor or by any other
member function of the class Directory.
Since constructors are called for each new object of a class, static data members are not initialized
by constructors. At most they are modified. The reason for this is that static data members exist
before any constructor of the class has been called. Static data members are initialized when they
are defined, outside of any member function, exactly like the initialization of ordinary (non-class)
global variables.
The definition and initialization of a static data member usually occurs in one of the source files
of the class functions, preferably in a source file dedicated to the definition of static data members,
called data.cc.
The data member s_path[], used above, could thus be defined and initialized as follows in a file
data.cc:
include "directory.ih"
8.1. STATIC DATA 169
char Directory::s_path[200] = "/usr/local";
In the class interface the static member is actually only declared. In its implementation (definition)
its type and class name are explicitly mentioned. Note also that the size specification can be left out
of the interface, as shown above. However, its size is (either explicitly or implicitly) required when
it is defined.
Note that any source file could contain the definition of the static datamembers of a class. A separate
data.cc source file is advised, but the source file containing, e.g., main() could be used as well. Of
course, any source file defining static data of a class must also include the header file of that class,
in order for the static data member to be known to the compiler.
A second example of a useful private static data member is given below. Assume that a class
Graphics defines the communication of a program with a graphics-capable device (e.g., a VGA
screen). The initialization of the device, which in this case would be to switch from text mode to
graphics mode, is an action of the constructor and depends on a static flag variable s_nobjects.
The variable s_nobjects simply counts the number of Graphics objects which are present at one
time. Similarly, the destructor of the class may switch back from graphics mode to text mode when
the last Graphics object ceases to exist. The class interface for this Graphics class might be:
class Graphics
{
static int s_nobjects; // counts # of objects
public:
Graphics();
~Graphics(); // other members not shown.
private:
void setgraphicsmode(); // switch to graphics mode
void settextmode(); // switch to text-mode
}
The purpose of the variable s_nobjects is to count the number of objects existing at a particular
moment in time. When the first object is created, the graphics device is initialized. At the destruction
of the last Graphics object, the switch from graphics mode to text mode is made:
int Graphics::s_nobjects = 0; // the static data member
Graphics::Graphics()
{
if (!s_nobjects++)
setgraphicsmode();
}
Graphics::~Graphics()
{
if (!--s_nobjects)
settextmode();
}
Obviously, when the class Graphics would definemore than one constructor, each constructor would
need to increase the variable s_nobjects and would possibly have to initialize the graphics mode.
170 CHAPTER 8. STATIC DATA AND FUNCTIONS
8.1.2 Public static data
Data members could also be declared in the public section of a class. This, however, is deprecated
(as it violates the principle of data hiding). The static data member s_path[] (cf. section 8.1) could
be declared in the public section of the class definition. This would allow all the program’s code to
access this variable directly:
int main()
{
getcwd(Directory::s_path, 199);
}
A declaration is not a definition. Consequently the variable s_path still has to be defined. This
implies that some source file still needs to contain s_path[] array’s definition.
8.1.3 Initializing static const data
Static const data members should be initialized like any other static data member: in source files
defining these data members.
Usually, if these data members are of integral or built-in primitive data types the compiler accepts
in-class initializations of such datamembers. However, there is no formal rule requiring the compiler
to do so. Compilations may or may not succeed depending on the optimizations used by the compiler
(e.g., using -O2 may result in a successful compilation, but -O0 (no-optimalizations) may fail to
compile, but then maybe only when shared libraries are used...).
In-class initializations of integer constant values (e.g., of types char, int, long, etc, maybe
unsigned) is nevertheless possible using (e.g., anonymous) enums. The following example illustrates
how this can be done:
class X
{
public:
enum { s_x = 34 };
enum: size_t { s_maxWidth = 100 };
};
To avoid confusion caused by different compiler options static data members should always explicitly
be defined and initialized in a source file, whether or not const.
8.1.4 Generalized constant expressions (constexpr)
In C macros are often used to let the preprocessor perform simple calculations. These macro functions
may have arguments, as illustrated in the next example:
#define xabs(x) ((x) < 0 ? -(x) : (x))
The disadvantages of macros are well-known. The main reason for avoiding macros is that they are
not parsed by the compiler, but are processed by the preprocessor resulting in mere text replacements
and thus avoid type-safety or syntactic checks of the macro definition by itself. Furthermore,
8.1. STATIC DATA 171
since macros are processed by the preprocessor their use is unconditional, without acknowledging
the context in which they are applied. NULL is an infamous example. Ever tried to define an enum
symbol NULL? or EOF? Chances are that, if you did, the compiler threw strange error messages at
you.
Generalized const expressions can be used as an alternative.
Generalized const expressions are recognized by the modifier constexpr (a keyword), that is applied
to the expression’s type.
There is a small syntactic difference between the use of the const modifier and the use of the
constexpr modifier. While the const modifier can be applied to definitions and declarations alike,
the constexpr modifier can only be applied to definitions:
extern int const externInt; // OK: declaration of const int
extern int constexpr error; // ERROR: not a definition
Variables defined with the constexpr modifier have constant (immutable) values. But generalized
const expressions are not just used to define constant variables; they have other applications as
well. The constexpr keyword is usually applied to functions, turning the function into a constantexpression
function.
A constant-expression function should not be confused with a function returning a const value
(although a constant-expression function does return a (const) value). A constant expression function
has the following characteristics:
• it returns a value;
• its return type is given the constexpr modifier;
• its body consists of one single return statement (but see also the notes about C++14 at end of
this section)
Such functions are also called named constant expressions with parameters.
These constant expression functions may or may not be called with arguments that have been evaluated
at compile-time (not just ‘const arguments’, as a const parameter value is not evaluated at
compile-time). If they are called with compile-time evaluated arguments then the returned value is
considered a const value as well.
This allows us to encapsulate expressions that can be evaluated at compile-time in functions, and
it allows us to use these functions in situations where previously the expressions themselves had to
be used. The encapsulation reduces the number of occurrences of the expressions to one, simplifying
maintenance and reduces the probability of errors.
If arguments that could not be compile-time evaluated are passed to constant-expression functions,
then these functions act like any other function, in that their return values are no longer considered
constant expressions.
Assume some two-dimensional arrays must be converted to one-dimensional arrays. The onedimensional
array must have nrows _ ncols + nrows + ncols + 1 elements, to store row, column,
and total marginals, as well as the elements of the source array itself. Furthermore assume
that nrows and ncols have been defined as globally available size_t const values (they could be
a class’s static data). The one-dimensional arrays are data members of a class or struct, or they are
also defined as global arrays.
172 CHAPTER 8. STATIC DATA AND FUNCTIONS
Now that constant-expression functions are available the expression returning the number of the
required elements can be encapsulated in such a function:
size_t const nRows = 45;
size_t const nCols = 10;
size_t constexpr nElements(size_t rows, size_t cols)
{
return rows * cols + rows + cols + 1;
}
....
int intLinear[ nElements(nRows, nCols) ];
struct Linear
{
double d_linear[ nElements(nRows, nCols) ];
};
If another part of the program needs to use a linear array for an array of different sizes then the
constant-expression function can also be used. E.g.,
string stringLinear[ nElements(10, 4) ];
Constant-expression functions can be used in other constant expression functions as well. The following
constant-expression function returns half the value, rounded upwards, that is returned by
nElements:
size_t constexpr halfNElements(size_t rows, size_t cols)
{
return (nElements(rows, cols) + 1) >> 1;
}
Classes should not expose their data members to external software, so as to reduce coupling between
classes and external software. But if a class defines a static const size_t data member then
that member’s value could very well be used to define entities living outside of the class’s scope, like
the number of elements of an array or to define the value of some enum. In situations like these
constant-expression functions are the perfect tool to maintain proper data hiding:
class Data
{
static size_t const s_size = 7;
public:
static size_t constexpr size();
size_t constexpr mSize();
};
size_t constexpr Data::size()
{
return s_size;
8.1. STATIC DATA 173
}
size_t constexpr Data::mSize()
{
return size();
}
double data[ Data::size() ]; // OK: 7 elements
short data2[ Data().mSize() ]; // also OK: see below
Please note the following:
• Constant-expression functions are implicitly declared inline;
• Non-static constant-expression member functions are implicitly const, and a const member
modifier for them is optional;
• Constant values (e.g., static constant data members) used by constant-expression functions
must be known by the time the compiler encounters the functions’ definitions. That’s why
s_size was initialized in Data’s class interface.
The C++14 standard relaxes the characteristics of constexpr functions. Using the C++14 standard,
constexpr functions may
• define any kind of variable except for static or thread_local variables;
• define variables without initializers;
• use conditional statements (if and switch);
• use repetition statements statements, including the range-based for statement;
• use expressions changing the values of objects that are local to the constexpr function;
In addition, C++14 allows constexpr member functions to be non-const. But note that non-const
constexpr member functions can only modify data members of objects that were defined local to
the constexpr function calling the non-const constexpr member function.
8.1.4.1 Constant expression data
As we’ve seen, (member) functions and variables of primitive data types can defined with the
constexpr modifier. What about class-type objects?
Objects of classes are values of class type, and like values of primitive types they can be defined with
the constexpr specifier. Constant expression class-type objects must be initialized with constant
expression arguments; the constructor that is actually used must itself have been declared with the
constexpr modifier. Note again that the constexpr constructor’s definition must have been seen
by the compiler before the constexpr object can be constructed:
class ConstExpr
{
public:
constexpr ConstExpr(int x);
};
174 CHAPTER 8. STATIC DATA AND FUNCTIONS
ConstExpr ok(7); // OK: not declared as constexpr
constexpr ConstExpr err(7); // ERROR: constructor’s definition
// not yet seen
constexpr ConstExpr::ConstExpr(int x)
{}
constexpr ConstExpr ok(7); // OK: definition seen
constexpr ConstExpr okToo = ConstExpr(7); // also OK
A constant-expression constructor has the following characteristics:
• it is declared with the constexpr modifier;
• its member initializers only use constant expressions;
• its body is empty.
An object constructed with a constant-expression constructor is called a user-defined literal. Destructors
and copy constructors of user-defined literals must be trivial.
The constexpr characteristic of user-defined literals may or may not be maintained by its class’s
members. If a member is not declared with a constexpr return value, then using that member
does not result in a constant-expression. If a member does declare a constexpr return value then
that member’s return value considered a constexpr if it is by itself a constant expression function.
To maintain its constexpr characteristics it can refer to its classes data members only if its object
has been defined with the constexpr modifier, as illustrated by the example:
class Data
{
int d_x;
public:
constexpr Data(int x)
:
d_x(x)
{}
int constexpr cMember()
{
return d_x;
}
int member() const
{
return d_x;
}
};
Data d1(0); // OK, but not a constant expression
enum e1 {
8.2. STATIC MEMBER FUNCTIONS 175
ERR = d1.cMember() // ERROR: cMember(): no constant
}; // expression anymore
constexpr Data d2(0); // OK, constant expression
enum e2 {
OK = d2.cMember(), // OK: cMember(): now a constant
// expression
ERR = d2.member(), // ERR: member(): not a constant
}; // expression
8.2 Static member functions
In addition to static data members, C++ allows us to define static member functions. Similar to
static data that are shared by all objects of the class, static member functions also exist without any
associated object of their class.
Static member functions can access all static members of their class, but also the members (private
or public) of objects of their class if they are informed about the existence of these objects (as in
the upcoming example). As static member functions are not associated with any object of their class
they do not have a this pointer. In fact, a static member function is completely comparable to a
global function, not associated with any class (i.e., in practice they are. See the next section (8.2.1)
for a subtle note). Since static member functions do not require an associated object, static member
functions declared in the public section of a class interface may be called without specifying an object
of its class. The following example illustrates this characteristic of static member functions:
class Directory
{
string d_currentPath;
static char s_path[];
public:
static void setpath(char const *newpath);
static void preset(Directory &dir, char const *newpath);
};
inline void Directory::preset(Directory &dir, char const *newpath)
{
// see the text below
dir.d_currentPath = newpath; // 1
}
char Directory::s_path[200] = "/usr/local"; // 2
void Directory::setpath(char const *newpath)
{
if (strlen(newpath) >= 200)
throw "newpath too long";
strcpy(s_path, newpath); // 3
}
int main()
176 CHAPTER 8. STATIC DATA AND FUNCTIONS
{
Directory dir;
Directory::setpath("/etc"); // 4
dir.setpath("/etc"); // 5
Directory::preset(dir, "/usr/local/bin"); // 6
dir.preset(dir, "/usr/local/bin"); // 7
}
• at 1 a static member function modifies a private data member of an object. However, the object
whose member must be modified is given to the member function as a reference parameter.
Note that static member functions can be defined as inline functions.
• at 2 a relatively long array is defined to be able to accomodate long paths. Alternatively, a
string or a pointer to dynamic memory could be used.
• at 3 a (possibly longer, but not too long) new pathname is stored in the static data member
s_path[]. Note that only static members are used.
• at 4, setpath() is called. It is a static member, so no object is required. But the compilermust
know to which class the function belongs, so the class is mentioned using the scope resolution
operator.
• at 5, the same is implemented as in 4. Here dir is used to tell the compiler that we’re talking
about a function in the Directory class. Static member functions can be called as normal
member functions, but this does not imply that the static member function receives the object’s
address as a this pointer. Here the member-call syntax is used as an alternative for the
classname plus scope resolution operator syntax.
• at 6, currentPath is altered. As in 4, the class and the scope resolution operator are used.
• at 7, the same is implemented as in 6. But here dir is used to tell the compiler that we’re
talking about a function in the Directory class. Here in particular note that this is not using
preset() as an ordinary member function of dir: the function still has no this-pointer, so
dir must be passed as argument to informthe static member function preset about the object
whose currentPath member it should modify.
In the example only public static member functions were used. C++ also allows the definition of
private static member functions. Such functions can only be called by member functions of their
class.
8.2.1 Calling conventions
As noted in the previous section, static (public) member functions are comparable to classless functions.
However, formally this statement is not true, as the C++ standard does not prescribe the same
calling conventions for static member functions as for classless global functions.
In practice the calling conventions are identical, implying that the address of a static member function
could be used as an argument of functions having parameters that are pointers to (global)
functions.
If unpleasant surprises must be avoided at all cost, it is suggested to create global classless wrapper
functions around static member functions that must be used as call back functions for other
functions.
8.2. STATIC MEMBER FUNCTIONS 177
Recognizing that the traditional situations in which call back functions are used in C are tackled in
C++ using template algorithms (cf. chapter 19), let’s assume that we have a class Person having
data members representing the person’s name, address, phone and mass. Furthermore, assume we
want to sort an array of pointers to Person objects, by comparing the Person objects these pointers
point to. Keeping things simple, we assume that the following public static member exists:
int Person::compare(Person const *const *p1, Person const *const *p2);
A useful characteristic of this member is that it may directly inspect the required data members of
the two Person objects passed to the member function using pointers to pointers (double pointers).
Most compilers allow us to pass this function’s address as the address of the comparison function for
the standard C qsort() function. E.g.,
qsort
(
personArray, nPersons, sizeof(Person *),
reinterpret_cast<int(*)(void const *, void const *)>(Person::compare)
);
However, if the compiler uses different calling conventions for static members and for classless
functions, this might not work. In such a case, a classless wrapper function like the following may
be used profitably:
int compareWrapper(void const *p1, void const *p2)
{
return
Person::compare
(
static_cast<Person const *const *>(p1),
static_cast<Person const *const *>(p2)
);
}
resulting in the following call of the qsort() function:
qsort(personArray, nPersons, sizeof(Person *), compareWrapper);
Note:
• The wrapper function takes care of any mismatch in the calling conventions of static member
functions and classless functions;
• The wrapper function handles the required type casts;
• The wrapper function might perform small additional services (like dereferencing pointers if
the static member function expects references to Person objects rather than double pointers);
• As an aside: in C++ programs functions like qsort(), requiring the specification of call back
functions are seldom used. Instead using existing generic template algorithms is preferred (cf.
chapter 19).
178 CHAPTER 8. STATIC DATA AND FUNCTIONS

Chapter 9
Classes And Memory Allocation
In contrast to the set of functions that handle memory allocation in C (i.e., malloc etc.), memory
allocation in C++ is handled by the operators new and delete. Important differences between
malloc and new are:
• The function malloc doesn’t ‘know’ what the allocated memory will be used for. E.g., when
memory for ints is allocated, the programmer must supply the correct expression using a
multiplication by sizeof(int). In contrast, new requires a type to be specified; the sizeof
expression is implicitly handled by the compiler. Using new is therefore type safe.
• Memory allocated by malloc is initialized by calloc, initializing the allocated characters to
a configurable initial value. This is not very useful when objects are available. As operator
new knows about the type of the allocated entity it may (and will) call the constructor of an
allocated class type object. This constructor may be also supplied with arguments.
• All C-allocation functions must be inspected for NULL-returns. This is not required anymore
when new is used. In fact, new’s behavior when confronted with failing memory allocation is
configurable through the use of a new_handler (cf. section 9.2.2).
A comparable relationship exists between free and delete: delete makes sure that when an
object is deallocated, its destructor is automatically called.
The automatic calling of constructors and destructors when objects are created and destroyed has
consequences which we shall discuss in this chapter. Many problems encountered during C program
development are caused by incorrect memory allocation or memory leaks: memory is not allocated,
not freed, not initialized, boundaries are overwritten, etc.. C++ does not ‘magically’ solve these
problems, but it does provide us with tools to prevent these kinds of problems.
As a consequence of malloc and friends becoming deprecated the very frequently used str...
functions, like strdup, that are all malloc based, should be avoided in C++ programs. Instead, the
facilities of the string class and operators new and delete should be used.
Memory allocation procedures influence the way classes dynamically allocating their own memory
should be designed. Therefore, in this chapter these topics are discussed in addition to discussions
about operators new and delete. We’ll first cover the peculiarities of operators new and delete,
followed by a discussion about:
• the destructor: the member function that’s called when an object ceases to exist;
• the assignment operator, allowing us to assign an object to another object of its own class;
179
180 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
• the this pointer, allowing explicit references to the object for which a member function was
called;
• the copy constructor: the constructor creating a copy of an object;
• the move constructor: a constructor creating an object from an anonymous temporary object.
9.1 Operators ‘new’ and ‘delete’
C++ defines two operators to allocate memory and to return it to the ‘common pool’. These operators
are, respectively new and delete.
Here is a simple example illustrating their use. An int pointer variable points to memory allocated
by operator new. This memory is later released by operator delete.
int *ip = new int;
delete ip;
Here are some characteristics of operators new and delete:
• new and delete are operators and therefore do not require parentheses, as required for functions
like malloc and free;
• new returns a pointer to the kind of memory that’s asked for by its operand (e.g., it returns a
pointer to an int);
• new uses a type as its operand, which has the important benefit that the correct amount of
memory, given the type of the object to be allocated, is made available;
• as a consequence, new is a type safe operator as it always returns a pointer to the type that
was mentioned as its operand. In addition, the type of the receving pointer must match the
type specified with operator new;
• new may fail, but this is normally of no concern to the programmer. In particular, the program
does not have to test the success of the memory allocation, as is required for malloc and
friends. Section 9.2.2 delves into this aspect of new;
• delete returns void;
• for each call to new a matching delete should eventually be executed, lest a memory leak
occurs;
• delete can safely operate on a 0-pointer (doing nothing);
• otherwise delete must only be used to return memory allocated by new. It should not be used
to return memory allocated by malloc and friends.
• in C++ malloc and friends are deprecated and should be avoided.
Operator new can be used to allocate primitive types but also to allocate objects. When a primitive
type or a struct type without a constructor is allocated the allocated memory is not guaranteed to
be initialized to 0, but an initialization expression may be provided:
int *v1 = new int; // not guaranteed to be initialized to 0
int *v1 = new int(); // initialized to 0
int *v2 = new int(3); // initialized to 3
int *v3 = new int(3 * *v2); // initialized to 9
9.1. OPERATORS ‘NEW’ AND ‘DELETE’ 181
When a class-type object is allocated, the arguments of its constructor (if any) are specified immediately
following the type specification in the new expression and the object is initialized by to the
thus specified constructor. For example, to allocate string objects the following statements could
be used:
string *s1 = new string; // uses the default constructor
string *s2 = new string(); // same
string *s3 = new string(4, ’ ’); // initializes to 4 blanks.
In addition to using new to allocate memory for a single entity or an array of entities there is also
a variant that allocates raw memory: operator new(sizeInBytes). Raw memory is returned as
a void _. Here new allocates a block of memory for unspecified purpose. Although raw memory
may consist of multiple characters it should not be interpreted as an array of characters. Since
raw memory returned by new is returned as a void _ its return value can be assigned to a void _
variable. More often it is assigned to a char _ variable, using a cast. Here is an example:
char *chPtr = static_cast<char *>(operator new(numberOfBytes));
The use of raw memory is frequently encountered in combination with the placement new operator,
discussed in section 9.1.5.
9.1.1 Allocating arrays
Operator new[] is used to allocate arrays. The generic notation new[] is used in the C++ Annotations.
Actually, the number of elements to be allocated must be specified between the square
brackets and it must, in turn, be prefixed by the type of the entities that must be allocated. Example:
int *intarr = new int[20]; // allocates 20 ints
string *stringarr = new string[10]; // allocates 10 strings.
Operator new is a different operator than operator new[]. A consequence of this difference is discussed
in the next section (9.1.2).
Arrays allocated by operator new[] are called dynamic arrays. They are constructed during the
execution of a program, and their lifetime may exceed the lifetime of the function in which they
were created. Dynamically allocated arrays may last for as long as the program runs.
When new[] is used to allocate an array of primitive values or an array of objects, new[] must
be specified with a type and an (unsigned) expression between its square brackets. The type and
expression together are used by the compiler to determine the required size of the block of memory
to make available. When new[] is used the array’s elements are stored consecutively in memory. An
array index expressionmay thereafter be used to access the array’s individual elements: intarr[0]
represents the first int value, immediately followed by intarr[1], and so on until the last element
(intarr[19]). With non-class types (primitive types, struct types without constructors) the block
of memory returned by operator new[] is not guaranteed to be initialized to 0.
When operator new[] is used to allocate arrays of objects their constructors are automatically used.
Consequently new string[20] results in a block of 20 initialized string objects. When allocating
arrays of objects the class’s default constructor is used to initialize each individual object in turn. A
non-default constructor cannot be called, but often it is possible to work around that as discussed in
section 13.8.
182 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
The expression between brackets of operator new[] represents the number of elements of the array
to allocate. The C++ standard allows allocation of 0-sized arrays. The statement new int[0] is
correct C++. However, it is also pointless and confusing and should be avoided. It is pointless as it
doesn’t refer to any element at all, it is confusing as the returned pointer has a useless non-0 value.
A pointer intending to point to an array of values should be initialized (like any pointer that isn’t
yet pointing to memory) to 0, allowing for expressions like if (ptr) ...
Without using operator new[], arrays of variable sizes can also be constructed as local arrays. Such
arrays are not dynamic arrays and their lifetimes are restricted to the lifetime of the block in which
they were defined.
Once allocated, all arrays have fixed sizes. There is no simple way to enlarge or shrink arrays. C++
has no operator ‘renew’. Section 9.1.3 illustrates how to enlarge arrays.
9.1.2 Deleting arrays
Dynamically allocated arrays are deleted using operator delete[]. It expects a pointer to a block
of memory, previously allocated by operator new[].
When operator delete[]’s operand is a pointer to an array of objects two actions are performed:
• First, the class’s destructor is called for each of the objects in the array. The destructor, as
explained later in this chapter, performs all kinds of cleanup operations that are required by
the time the object ceases to exist.
• Second, the memory pointed at by the pointer is returned to the common pool.
Here is an example showing how to allocate and delete an array of 10 string objects:
std::string *sp = new std::string[10];
delete[] sp;
No special action is performed if a dynamically allocated array of primitive typed values is deleted.
Following int _it = new int[10] the statement delete[] it simply returns the memory
pointed at by it. Realize that, as a pointer is a primitive type, deleting a dynamically allocated
array of pointers to objects does not result in the proper destruction of the objects the array’s elements
point at. So, the following example results in a memory leak:
string **sp = new string *[5];
for (size_t idx = 0; idx != 5; ++idx)
sp[idx] = new string;
delete[] sp; // MEMORY LEAK !
In this example the only action performed by delete[] is to return an area the size of five pointers
to strings to the common pool.
Here’s how the destruction in such cases should be performed:
• Call delete for each of the array’s elements;
• Delete the array itself
9.1. OPERATORS ‘NEW’ AND ‘DELETE’ 183
Example:
for (size_t idx = 0; idx != 5; ++idx)
delete sp[idx];
delete[] sp;
One of the consequences is of course that by the time the memory is going to be returned not only
the pointer must be available but also the number of elements it contains. This can easily be accomplished
by storing pointer and number of elements in a simple class and then using an object of that
class.
Operator delete[] is a different operator than operator delete. The rule of thumb is: if new[]
was used, also use delete[].
9.1.3 Enlarging arrays
Once allocated, all arrays have fixed sizes. There is no simple way to enlarge or shrink arrays. C++
has no renew operator. The basic steps to take when enlarging an array are the following:
• Allocate a new block of memory of larger size;
• Copy the old array contents to the new array;
• Delete the old array;
• Let the pointer to the array point to the newly allocated array.
Static and local arrays cannot be resized. Resizing is only possible for dynamically allocated arrays.
Example:
#include <string>
using namespace std;
string *enlarge(string *old, unsigned oldsize, unsigned newsize)
{
string *tmp = new string[newsize]; // allocate larger array
for (size_t idx = 0; idx != oldsize; ++idx)
tmp[idx] = old[idx]; // copy old to tmp
delete[] old; // delete the old array
return tmp; // return new array
}
int main()
{
string *arr = new string[4]; // initially: array of 4 strings
arr = enlarge(arr, 4, 6); // enlarge arr to 6 elements.
}
The procedure to enlarge shown in the example also has several drawbacks.
• The new array requires newsize constructors to be called;
184 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
• Having initialized the strings in the new array, oldsize of them are immediately reassigned
to the corresponding values in the original array;
• All the objects in the old arrays are destroyed.
Depending on the context various solutions exist to improve the efficiency of this rather inefficient
procedure. An array of pointers could be used (requiring only the pointers to be copied, no destruction,
no superfluous initialization) or raw memory in combination with the placement new operator
could be used (an array of objects remains available, no destruction, no superfluous construction).
9.1.4 Managing ‘raw’ memory
As we’ve seen operator new allocates the memory for an object and subsequently initializes that
object by calling one of its constructors. Likewise, operator delete calls an object’s destructor and
subsequently returns the memory allocated by operator new to the common pool.
In the next section we’ll encounter another use of new, allowing us to initialize objects in so-called
raw memory: memory merely consisting of bytes that have been made available by either static or
dynamic allocation.
Raw memory is made available by operator new(sizeInBytes). This should not be interpreted
as an array of any kind but just a series of memory locations that were dynamically made available.
operator new returns a void _ so a (static) cast is required to use it as memory of some type.
Here are two examples:
// room for 5 ints
int *ip = static_cast<int *>(operator new(5 * sizeof(int)));
// room for 5 strings
string *sp = static_cast<string *>(operator new(5 * sizeof(string)));
As operator new has no concept of data types the size of the intended data type must be specified
when allocating raw memory for a certain number of objects of an intended type. The use of
operator new therefore somewhat resembles the use of malloc.
The counterpart of operator new is operator delete. Operator delete expects a void _ (so
a pointer to any type can be passed to it). The pointer is interpreted as a pointer to raw memory
which is returned to the common pool without any further action. In particular, no destructors are
called by operator delete. The use of operator delete therefore resembles the use of free.
To return the memory pointed at by the abovementioned variables ip and sp operator delete
should be used:
// delete raw memory allocated by operator new
operator delete(ip);
operator delete(sp);
9.1.5 The ‘placement new’ operator
A remarkable form of operator new is called the placement new operator. Before using placement
new the <memory> header file must be included.
Placement new is passed an existing block of memory into which new initializes an object or value.
The block of memory should be large enough to contain the object, but apart from that there are
9.1. OPERATORS ‘NEW’ AND ‘DELETE’ 185
no further requirements. It is easy to determine how much memory is used by en entity (object or
variable) of type Type: the sizeof operator returns the number of bytes used by an Type entity.
Entities may of course dynamically allocate memory for their own use. Dynamically allocated memory,
however, is not part of the entity’s memory ‘footprint’ but it is always made available externally
to the entity itself. This is why sizeof returns the same value when applied to different string
objects that return different length and capacity values.
The placement new operator uses the following syntax (using Type to indicate the used data type):
Type *new(void *memory) Type(arguments);
Here, memory is a block of memory of at least sizeof(Type) bytes and Type(arguments) is any
constructor of the class Type.
The placement new operator is useful in situations where classes set aside memory to be used later.
This is used, e.g., by std::string to change its capacity. Calling string::reserve may enlarge
that capacity without making memory beyond the string’s length immediately available to the
string object’s users. But the object itself may use its additional memory. E.g, when information is
added to a string object it can drawmemory fromits capacity rather than performing a reallocation
for each single character that is added to its contents.
Let’s apply that philosophy to a class Strings storing std::string objects. The class defines a
string _d_memory accessing the memory holding its d_size string objects as well as d_capacity
- d_size reserved memory. Assuming that a default constructor initializes d_capacity to 1,
doubling d_capacity whenever an additional string must be stored, the class must support the
following essential operations:
• doubling its capacity when all its spare memory (e.g., made available by reserve) has been
consumed;
• adding another string object
• properly deleting the installed strings and memory when a Strings object ceases to exist.
The private member void Strings::reserve is called when the current capacity must be enlarged
to d_capacity. It operates as follows: First new, raw, memory is allocated (line 1). This
memory is in no way initialized with strings. Then the available strings in the old memory are
copied into the newly allocated raw memory using placement new (line 2). Next, the old memory is
deleted (line 3).
void Strings::reserve()
{
using std::string;
string *newMemory = static_cast<string *>( // 1
operator new(d_capacity * sizeof(string)));
for (size_t idx = 0; idx != d_size; ++idx) // 2
new (newMemory + idx) string(d_memory[idx]);
destroy(); // 3
d_memory = newMemory;
}
The member append adds another string object to a Strings object. A (public) member
reserve(request) (enlarging d_capacity if necessary and if enlarged calling reserve()) en186
CHAPTER 9. CLASSES AND MEMORY ALLOCATION
sures that the String object’s capacity is sufficient. Then placement new is used to install the latest
string into the raw memory’s appropriate location:
void Strings::append(std::string const &next)
{
reserve(d_size + 1);
new (d_memory + d_size) std::string(next);
++d_size;
}
At the end of the String object’s lifetime, and during enlarging operations all currently used dynamically
allocated memory must be returned. This is made the responsibility of the member destroy,
which is called by the class’s destructor and by reserve(). More about the destructor itself in the
next section, but the implementation of the support member destroy is discussed below.
With placement new an interesting situation is encountered. Objects, possibly themselves allocating
memory, are installed in memory that may or may not have been allocated dynamically, but that is
usually not completely filled with such objects. So a simple delete[] can’t be used. On the other
hand, a delete for each of the objects that are available can’t be used either, since those delete
operations would also try to delete the memory of the objects themselves, which wasn’t dynamically
allocated.
This peculiar situation is solved in a peculiar way, only encountered in cases where placement new
is used: memory allocated by objects initialized using placement new is returned by explicitly calling
the object’s destructor. The destructor is declared as a member having as its name the class name
preceded by a tilde, not using any arguments. So, std::string’s destructor is named ~string. An
object’s destructor only returns memory allocated by the object itself and, despite of its name, does
not destroy its object. Any memory allocated by the strings stored in our class Strings is therefore
properly destroyed by explicitly calling their destructors. Following this d_memory is back to its
initial status: it again points to raw memory. This raw memory is then returned to the common pool
by operator delete:
void Strings::destroy()
{
for (std::string *sp = d_memory + d_size; sp-- != d_memory; )
sp->~string();
operator delete(d_memory);
}
So far, so good. All is well as long as we’re using but one object. What about allocating an array of
objects? Initialization is performed as usual. But as with delete, delete[] cannot be called when
the buffer was allocated statically. Instead, when multiple objects were initialized using placement
new in combination with a statically allocated buffer all the objects’ destructors must be called explicitly,
as in the following example:
using std::string;
char buffer[3 * sizeof(string)];
string *sp = new(buffer) string [3];
for (size_t idx = 0; idx < 3; ++idx)
sp[idx].~string();
9.2. THE DESTRUCTOR 187
9.2 The destructor
Comparable to the constructor, classes may define a destructor. This function is the constructor’s
counterpart in the sense that it is invoked when an object ceases to exist. A destructor is usually
called automatically, but that’s not always true. The destructors of dynamically allocated objects are
not automatically activated, but in addition to that: when a program is interrupted by an exit call,
only the destructors of already initialized global objects are called. In that situation destructors of
objects defined locally by functions are also not called. This is one (good) reason for avoiding exit
in C++ programs.
Destructors obey the following syntactical requirements:
• a destructor’s name is equal to its class name prefixed by a tilde;
• a destructor has no arguments;
• a destructor has no return value.
Destructors are declared in their class interfaces. Example:
class Strings
{
public:
Strings();
~Strings(); // the destructor
};
By convention the constructors are declared first. The destructor is declared next, to be followed by
other member functions.
A destructor’s main task is to ensure that memory allocated by an object is properly returned when
the object ceases to exist. Consider the following interface of the class Strings:
class Strings
{
std::string *d_string;
size_t d_size;
public:
Strings();
Strings(char const *const *cStrings, size_t n);
~Strings();
std::string const &at(size_t idx) const;
size_t size() const;
};
The constructor’s task is to initialize the data fields of the object. E.g, its constructors are defined as
follows:
Strings::Strings()
:
d_string(0),
188 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
d_size(0)
{}
Strings::Strings(char const *const *cStrings, size_t size)
:
d_string(new string[size]),
d_size(size)
{
for (size_t idx = 0; idx != size; ++idx)
d_string[idx] = cStrings[idx];
}
As objects of the class Strings allocate memory a destructor is clearly required. Destructors may
or may not be called automatically, but note that destructors are only called (or, in the case of dynamically
allocated objects: should only be called) for fully constructed objects.
C++ considers objects ‘fully constructed’ once at least one of its constructors could normally complete.
It used to be the constructor, but as C++ supports constructor delegation, multiple constructors can
be activated for a single object; hence ‘at least one constructor’. The remaining rules apply to fully
constructed objects;
• Destructors of local non-static objects are called automatically when the execution flow leaves
the block in which they were defined; the destructors of objects defined somewhere in the outer
block of a function are called just before the function terminates.
• Destructors of static or global objects are called when the program itself terminates.
• The destructor of a dynamically allocated object is called by delete using the object’s address
as its operand;
• The destructors of a dynamically allocated array of objects are called by delete[] using the
address of the array’s first element as its operand;
• The destructor of an object initialized by placement new is activated by explicitly calling the
object’s destructor.
The destructor’s task is to ensure that all memory that is dynamically allocated and controlled only
by the object itself is returned. The task of the Strings’s destructor would therefore be to delete
the memory to which d_string points. Its implementation is:
Strings::~Strings()
{
delete[] d_string;
}
The next example shows Strings at work. In process a Strings store is created, and its data
are displayed. It returns a dynamically allocated Strings object to main. A Strings _ receives
the address of the allocated object and deletes the object again. Another Strings object is then
created in a block of memory made available locally in main, and an explicit call to ~Strings is
required to return the memory allocated by that object. In the example only once a Strings object
is automatically destroyed: the local Strings object defined by process. The other two Strings
objects require explicit actions to prevent memory leaks.
#include "strings.h"
9.2. THE DESTRUCTOR 189
#include <iostream>
using namespace std;;
void display(Strings const &store)
{
for (size_t idx = 0; idx != store.size(); ++idx)
cout << store.at(idx) << ’\n’;
}
Strings *process(char *argv[], int argc)
{
Strings store(argv, argc);
display(store);
return new Strings(argv, argc);
}
int main(int argc, char *argv[])
{
Strings *sp = process(argv, argc);
delete sp;
char buffer[sizeof(Strings)];
sp = new (buffer) Strings(argv, argc);
sp->~Strings();
}
9.2.1 Object pointers revisited
Operators new and delete are used when an object or variable is allocated. One of the advantages
of the operators new and delete over functions like malloc and free is that new and delete call
the corresponding object constructors and destructors.
The allocation of an object by operator new is a two-step process. First the memory for the object
itself is allocated. Then its constructor is called, initializing the object. Analogously to the construction
of an object, the destruction is also a two-step process: first, the destructor of the class is called
deleting the memory controlled by the object. Then the memory used by the object itself is freed.
Dynamically allocated arrays of objects can also be handled by new and delete. When allocating
an array of objects using operator new the default constructor is called for each object in the array.
In cases like this operator delete[] must be used to ensure that the destructor is called for each of
the objects in array.
However, the addresses returned by new Type and new Type[size] are of identical types, in both
cases a Type _. Consequently it cannot be determined by the type of the pointer whether a pointer
to dynamically allocated memory points to a single entity or to an array of entities.
What happens if delete rather than delete[] is used? Consider the following situation, in which
the destructor ~Strings is modified so that it tells us that it is called. In a main function an array
of two Strings objects is allocated by new, to be deleted by delete []. Next, the same actions are
repeated, albeit that the delete operator is called without []:
#include <iostream>
#include "strings.h"
190 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
using namespace std;
Strings::~Strings()
{
cout << "Strings destructor called" << ’\n’;
}
int main()
{
Strings *a = new Strings[2];
cout << "Destruction with []’s" << ’\n’;
delete[] a;
a = new Strings[2];
cout << "Destruction without []’s" << ’\n’;
delete a;
}
/*
Generated output:
Destruction with []’s
Strings destructor called
Strings destructor called
Destruction without []’s
Strings destructor called
*/
From the generated output, we see that the destructors of the individual Strings objects are called
when delete[] is used, while only the first object’s destructor is called if the [] is omitted.
Conversely, if delete[] is called in a situation where delete should have been called the results
are unpredictable, and the program will most likely crash. This problematic behavior is caused by
the way the run-time system stores information about the size of the allocated array (usually right
before the array’s first element). If a single object is allocated the array-specific information is not
available, but it is nevertheless assumed present by delete[]. Thus this latter operator encounters
bogus values in the memory locations just before the array’s first element. It then dutifully
interprets the value it encounters there as size information, usually causing the program to fail.
If no destructor is defined, a trivial destructor is defined by the compiler. The trivial destructor
ensures that the destructors of composed objects (as well as the destructors of base classes if a
class is a derived class, cf. chapter 13) are called. This has serious implications: objects allocating
memory create memory leaks unless precautionary measures are taken (by defining an appropriate
destructor). Consider the following program:
#include <iostream>
#include "strings.h"
using namespace std;
Strings::~Strings()
{
cout << "Strings destructor called" << ’\n’;
}
int main()
9.2. THE DESTRUCTOR 191
{
Strings **ptr = new Strings* [2];
ptr[0] = new Strings[2];
ptr[1] = new Strings[2];
delete[] ptr;
}
This program produces no output at all. Why is this? The variable ptr is defined as a pointer to
a pointer. The dynamically allocated array therefore consists of pointer variables and pointers are
of a primitive type. No destructors exist for primitive typed variables. Consequently only the array
itself is returned, and no Strings destructor is called.
Of course, we don’t want this, but require the Strings objects pointed to by the elements of ptr to
be deleted too. In this case we have two options:
• In a for-statement visit all the elements of the ptr array, calling delete for each of the array’s
elements. This procedure was demonstrated in the previous section.
• A wrapper class is designed around a pointer (to, e.g., an object of some class, like Strings).
Rather than using a pointer to a pointer to Strings objects a pointer to an array of wrapperclass
objects is used. As a result delete[] ptr calls the destructor of each of the wrapper
class objects, in turn calling the Strings destructor for their d_strings members. Example:
#include <iostream>
using namespace std;
class Strings // partially implemented
{
public:
~Strings();
};
inline Strings::~Strings()
{
cout << "destructor called\n";
}
class Wrapper
{
Strings *d_strings;
public:
Wrapper();
~Wrapper();
};
inline Wrapper::Wrapper()
:
d_strings(new Strings())
{}
inline Wrapper::~Wrapper()
{
delete d_strings;
192 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
}
int main()
{
auto ptr = new Strings *[4];
// ... code assigning ‘new Strings’ to ptr’s elements
delete[] ptr; // memory leak: ~Strings() not called
cout << "===========\n";
delete[] new Wrapper[4]; // OK: 4 x destructor called
}
/*
Generated output:
===========
destructor called
destructor called
destructor called
destructor called
*/
9.2.2 The function set_new_handler()
The C++ run-time system ensures that when memory allocation fails an error function is activated.
By default this function throws a bad_alloc exception (see section 10.8), terminating the program.
Therefore it is not necessary to check the return value of operator new. Operator new’s default
behavior may be modified in various ways. One way to modify its behavior is to redefine the function
that’s called when memory allocation fails. Such a function must comply with the following
requirements:
• it has no parameters;
• its return type is void.
A redefined error function might, e.g., print a message and terminate the program. The user-written
error function becomes part of the allocation system through the function set_new_handler.
Such an error function is illustrated below1:
#include <iostream>
#include <string>
#include <cstring>
using namespace std;
void outOfMemory()
{
cout << "Memory exhausted. Program terminates." << ’\n’;
exit(1);
}
1 Thisimplementation applies to the Gnu C/C++ requirements. Actually using the program given in the next example is
not advised, as it probably enormously slows down your computer due to the resulting use of the operating system’s swap
area.
9.3. THE ASSIGNMENT OPERATOR 193
int main()
{
long allocated = 0;
set_new_handler(outOfMemory); // install error function
while (true) // eat up all memory
{
memset(new int [100000], 0, 100000 * sizeof(int));
allocated += 100000 * sizeof(int);
cout << "Allocated " << allocated << " bytes\n";
}
}
Once the new error function has been installed it is automatically invoked when memory allocation
fails, and the program is terminated. Memory allocation may fail in indirectly called code as well,
e.g., when constructing or using streams or when strings are duplicated by low-level functions.
So far for the theory. On some systems the ‘out of memory’ condition may actually never be reached,
as the operating system may interfere before the run-time support system gets a chance to stop the
program (see also this link2).
The standard C functions allocating memory (like strdup, malloc, realloc etc.) do not trigger
the new handler when memory allocation fails and should be avoided in C++ programs.
9.3 The assignment operator
In C++ struct and class type objects can be directly assigned new values in the same way as this
is possible in C. The default action of such an assignment for non-class type data members is a
straight byte-by-byte copy from one data member to another. For now we’ll use the following simple
class Person:
class Person
{
char *d_name;
char *d_address;
char *d_phone;
public:
Person();
Person(char const *name, char const *addr, char const *phone);
~Person();
private:
char *strdupnew(char const *src); // returns a copy of src.
};
// strdupnew is easily implemented, here is its inline implementation:
inline char *Person::strdupnew(char const *src)
{
return strcpy(new char [strlen(src) + 1], src);
}
2http://www.linuxdevcenter.com/pub/a/linux/2006/11/30/linux-out-of-memory.html
194 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
Person’s data members are initialized to zeroes or to copies of the NTB strings passed to Person’s
constructor, using some variant of strdup. The allocated memory is eventually returned by
Person’s destructor.
Now consider the consequences of using Person objects in the following example:
void tmpPerson(Person const &person)
{
Person tmp;
tmp = person;
}
Here’s what happens when tmpPerson is called:
• it expects a reference to a Person as its parameter person.
• it defines a local object tmp, whose data members are initialized to zeroes.
• the object referenced by person is copied to tmp: sizeof(Person) number of bytes are copied
from person to tmp.
Now a potentially dangerous situation has been created. The actual values in person are pointers,
pointing to allocated memory. After the assignment this memory is addressed by two objects:
person and tmp.
• The potentially dangerous situation develops into an acutely dangerous situation once the
function tmpPerson terminates: tmp is destroyed. The destructor of the class Person releases
the memory pointed to by the fields d_name, d_address and d_phone: unfortunately, this
memory is also pointed at by person....
This problematic assignment is illustrated in Figure 9.1.
Having executed tmpPerson, the object referenced by person now contains pointers to deleted
memory.
This is undoubtedly not a desired effect of using a function like tmpPerson. The deleted memory is
likely to be reused by subsequent allocations. The pointer members of person have effectively become
wild pointers, as they don’t point to allocated memory anymore. In general it can be concluded
that
every class containing pointer data members is a potential candidate for trouble.
Fortunately, it is possible to prevent these troubles, as discussed next.
9.3.1 Overloading the assignment operator
Obviously, the right way to assign one Person object to another, is not to copy the contents of the
object bytewise. A better way is to make an equivalent object. One having its own allocated memory
containing copies of the original strings.
The way to assign a Person object to another is illustrated in Figure 9.2. There are several ways to
assign a Person object to another. One way would be to define a special member function to handle
9.3. THE ASSIGNMENT OPERATOR 195
Figure 9.1: Private data and public interface functions of the class Person, using byte-by-byte assignment
Figure 9.2: Private data and public interface functions of the class Person, using the ‘correct’ assignment.
196 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
the assignment. The purpose of this member function would be to create a copy of an object having
its own name, address and phone strings. Such a member function could be:
void Person::assign(Person const &other)
{
// delete our own previously used memory
delete[] d_name;
delete[] d_address;
delete[] d_phone;
// copy the other Person’s data
d_name = strdupnew(other.d_name);
d_address = strdupnew(other.d_address);
d_phone = strdupnew(other.d_phone);
}
Using assign we could rewrite the offending function tmpPerson:
void tmpPerson(Person const &person)
{
Person tmp;
// tmp (having its own memory) holds a copy of person
tmp.assign(person);
// now it doesn’t matter that tmp is destroyed..
}
This solution is valid, although it only tackles a symptom. It requires the programmer to use a
specific member function instead of the assignment operator. The original problem (assignment
produces wild pointers) is still not solved. Since it is hard to ‘strictly adhere to a rule’ a way to solve
the original problem is of course preferred.
Fortunately a solution exists using operator overloading: the possibility C++ offers to redefine the
actions of an operator in a given context. Operator overloading was briefly mentioned earlier, when
the operators << and >> were redefined to be used with streams (like cin, cout and cerr), see
section 3.1.4.
Overloading the assignment operator is probably the most common form of operator overloading in
C++. A word of warning is appropriate, though. The fact that C++ allows operator overloading does
not mean that this feature should indiscriminately be used. Here’s what you should keep in mind:
• operator overloading should be used in situations where an operator has a defined action, but
this default action has undesired side effects in a given context. A clear example is the above
assignment operator in the context of the class Person.
• operator overloading can be used in situations where the operator is commonly applied and no
surprise is introduced when it’s redefined. An example where operator overloading is appropriately
used is found in the class std::string: assiging one string object to another provides
the destination string with a copy of the contents of the source string. No surprises here.
• in all other cases a member function should be defined instead of redefining an operator.
An operator should simply do what it is designed to do. The phrase that’s often encountered in the
context of operator overloading is do as the ints do. The way operators behave when applied to ints
9.3. THE ASSIGNMENT OPERATOR 197
is what is expected, all other implementations probably cause surprises and confusion. Therefore,
overloading the insertion (<<) and extraction (>>) operators in the context of streams is probably
ill-chosen: the stream operations have nothing in common with bitwise shift operations.
9.3.1.1 The member ’operator=()’
To add operator overloading to a class, the class interface is simply provided with a (usually public)
member function naming the particular operator. That member function is thereupon implemented.
To overload the assignment operator =, a member operator=(Class const &rhs) is added to the
class interface. Note that the function name consists of two parts: the keyword operator, followed
by the operator itself. When we augment a class interface with a member function operator=, then
that operator is redefined for the class, which prevents the default operator from being used. In the
previous section the function assign was provided to solve the problems resulting from using the
default assignment operator. Rather than using an ordinary member function C++ commonly uses
a dedicated operator generalizing the operator’s default behavior to the class in which it is defined.
The assign member mentioned before may be redefined as follows (the member operator= presented
below is a first, rather unsophisticated, version of the overloaded assignment operator. It will
shortly be improved):
class Person
{
public: // extension of the class Person
// earlier members are assumed.
void operator=(Person const &other);
};
Its implementation could be
void Person::operator=(Person const &other)
{
delete[] d_name; // delete old data
delete[] d_address;
delete[] d_phone;
d_name = strdupnew(other.d_name); // duplicate other’s data
d_address = strdupnew(other.d_address);
d_phone = strdupnew(other.d_phone);
}
This member’s actions are similar to those of the previously mentioned member assign, but this
member is automatically called when the assignment operator = is used. Actually there are two
ways to call overloaded operators as shown in the next example:
void tmpPerson(Person const &person)
{
Person tmp;
tmp = person;
tmp.operator=(person); // the same thing
}
198 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
Overloaded operators are seldom called explicitly, but explicit calls must be used (rather than using
the plain operator syntax) when you explicitly want to call the overloaded operator from a pointer to
an object (it is also possible to dereference the pointer first and then use the plain operator syntax,
see the next example):
void tmpPerson(Person const &person)
{
Person *tmp = new Person;
tmp->operator=(person);
*tmp = person; // yes, also possible...
delete tmp;
}
9.4 The ‘this’ pointer
A member function of a given class is always called in combination with an object of its class. There
is always an implicit ‘substrate’ for the function to act on. C++ defines a keyword, this, to reach
this substrate.
The this keyword is a pointer variable that always contains the address of the object for which
the member function was called. The this pointer is implicitly declared by each member function
(whether public, protected, or private). The this ponter is a constant pointer to an object of
the member function’s class. For example, the members of the class Person implicitly declare:
extern Person *const this;
A member function like Person::name could be implemented in two ways: with or without using
the this pointer:
char const *Person::name() const // implicitly using ‘this’
{
return d_name;
}
char const *Person::name() const // explicitly using ‘this’
{
return this->d_name;
}
The this pointer is seldomexplicitly used, but situations do exist where the this pointer is actually
required (cf. chapter 16).
9.4.1 Sequential assignments and this
C++’s syntax allows for sequential assignments, with the assignment operator associating fromright
to left. In statements like:
a = b = c;
9.5. THE COPY CONSTRUCTOR: INITIALIZATION VS. ASSIGNMENT 199
the expression b = c is evaluated first, and its result in turn is assigned to a.
The implementation of the overloaded assignment operator we’ve encountered thus far does not
permit such constructions, as it returns void.
This imperfection can easily be remedied using the this pointer. The overloaded assignment operator
expects a reference to an object of its class. It can also return a reference to an object of its class.
This reference can then be used as an argument in sequential assignments.
The overloaded assignment operator commonly returns a reference to the current object (i.e., _this).
The next version of the overloaded assignment operator for the class Person thus becomes:
Person &Person::operator=(Person const &other)
{
delete[] d_address;
delete[] d_name;
delete[] d_phone;
d_address = strdupnew(other.d_address);
d_name = strdupnew(other.d_name);
d_phone = strdupnew(other.d_phone);
// return current object as a reference
return *this;
}
Overloaded operators may themselves be overloaded. Consider the string class, having
overloaded assignment operators operator=(std::string const &rhs), operator=(char
const _rhs), and several more overloaded versions. These additional overloaded versions are
there to handle different situations which are, as usual, recognized by their argument types. These
overloaded versions all follow the same mold: when necessary dynamically allocated memory controlled
by the object is deleted; new values are assigned using the overloaded operator’s parameter
values and _this is returned.
9.5 The copy constructor: initialization vs. assignment
Consider the class Strings, introduced in section 9.2, once again. As it contains several primitive
type data members as well as a pointer to dynamically allocated memory it needs a constructor,
a destructor, and an overloaded assignment operator. In fact the class offers two constructors: in
addition to the default constructor it offers a constructor expecting a char const _const _ and a
size_t.
Now consider the following code fragment. The statement references are discussed following the
example:
int main(int argc, char **argv)
{
Strings s1(argv, argc); // (1)
Strings s2; // (2)
Strings s3(s1); // (3)
s2 = s1; // (4)
}
200 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
• At 1 we see an initialization. The object s1 is initialized using main’s parameters: Strings’s
second constructor is used.
• At 2 Strings’s default constructor is used, initializing an empty Strings object.
• At 3 yet another Strings object is created, using a constructor accepting an existing Strings
object. This form of initializations has not yet been discussed. It is called a copy construction
and the constructor performing the initialization is called the copy constructor. Copy constructions
are also encountered in the following form:
Strings s3 = s1;
This is a construction and therefore an initialization. It is not an assignment as an assignment
needs a left-hand operand that has already been defined. C++ allows the assignment syntax
to be used for constructors having only one parameter. It is somewhat deprecated, though.
• At 4 we see a plain assignment.
In the above example three objects were defined, each using a different constructor. The actually
used constructor was deduced from the constructor’s argument list.
The copy constructor encountered here is new. It does not result in a compilation error even though
it hasn’t been declared in the class interface. This takes us to the following rule:
A copy constructor is (almost) always available, even if it isn’t declared in the class’s
interface.
The reason for the ‘(almost)’ is given in section 9.7.1.
The copy constructor made available by the compiler is also called the trivial copy constructor. Its
use can easily be suppressed (using the = delete idiom). The trivial copy constructor performs
a byte-wise copy operation of the existing object’s primitive data to the newly created object, calls
copy constructors to intialize the object’s class data members from their counterparts in the existing
object and, when inheritance is used, calls the copy constructors of the base class(es) to initialize the
new object’s base classes.
Consequently, in the above example the trivial copy constructor is used. As it performs a byte-bybyte
copy operation of the object’s primitive type data members that is exactly what happens at
statement 3. By the time s3 ceases to exist its destructor deletes its array of strings. Unfortunately
d_string is of a primitive data type and so it also deletes s1’s data. Once again we encounter wild
pointers as a result of an object going out of scope.
The remedy is easy: instead of using the trivial copy constructor a copy constructor must explicitly
be added to the class’s interface and its definition must prevent the wild pointers, comparably to
the way this was realized in the overloaded assignment operator. An object’s dynamically allocated
memory is duplicated, so that it contains its own allocated data. The copy constructor is simpler than
the overloaded assignment operator in that it doesn’t have to delete previously allocated memory.
Since the object is going to be created no previously allocated memory already exists.
Strings’s copy constructor can be implemented as follows:
Strings::Strings(Strings const &other)
:
d_string(new string[other.d_size]),
d_size(other.d_size)
{
9.6. REVISING THE ASSIGNMENT OPERATOR 201
for (size_t idx = 0; idx != d_size; ++idx)
d_string[idx] = other.d_string[idx];
}
The copy constructor is always called when an object is initialized using another object of its class.
Apart fromthe plain copy construction that we encountered thus far, here are other situations where
the copy constructor is used:
• it is used when a function defines a class type value parameter rather than a pointer or a reference.
The function’s argument initializes the function’s parameter using the copy constructor.
Example:
void process(Strings store) // no pointer, no reference
{
store.at(3) = "modified"; // doesn’t modify ‘outer’
}
int main(int argc, char **argv)
{
Strings outer(argv, argc);
process(outer);
}
• it is used when a function defines a class type value return type. Example:
Strings copy(Strings const &store)
{
return store;
}
Here store is used to initialize copy’s return value. The returned Strings object is a temporary,
anonymous object that may be immediately used by code calling copy but no assumptions can be
made about its lifetime thereafter.
9.6 Revising the assignment operator
The overloaded assignment operator has characteristics also encountered with the copy constructor
and the destructor:
• The copying of (private) data occurs (1) in the copy constructor and (2) in the overloaded assignment
function.
• Allocatedmemory is deleted (1) in the overloaded assignment function and (2) in the destructor.
The copy constructor and the destructor clearly are required. If the overloaded assignment operator
also needs to return allocated memory and to assign new values to its data members couldn’t the
destructor and copy constructor be used for that?
As we’ve seen in our discussion of the destructor (section 9.2) the destructor can explicitly be called,
but that doesn’t hold true for the (copy) constructor. But let’s briefly summarize what an overloaded
assignment operator is supposed to do:
• It should delete the dynamically allocated memory controlled by the current object;
202 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
• It should reassign the current object’s data members using a provided existing object of its
class.
The second part surely looks a lot like copy construction. Copy construction becomes even more
attractive after realizing that the copy constructor also initializes any reference data members the
class might have. Realizing the copy construction part is easy: just define a local object and initialize
it using the assignment operator’s const reference parameter, like this:
Strings &operator=(Strings const &other)
{
Strings tmp(other);
// more to follow
return *this;
}
You may think the optimization operator=(String tmp) is attractive, but let’s postpone that for
a little while (at least until section 9.7).
Now that we’ve done the copying part, what about the deleting part? And isn’t there another slight
problem as well? After all we copied all right, but not into our intended (current, _this) object.
At this point it’s time to introduce swapping. Swapping two variables means that the two variables
exchange their values. We’ll discuss swapping in detail in the next section, but let’s for now assume
that we’ve added a member swap(Strings &other) to our class Strings. This allows us to
complete String’s operator= implementation:
Strings &operator=(Strings const &other)
{
Strings tmp(other);
swap(tmp);
return *this;
}
This implementation of operator= is generic: it can be applied to every class whose objects are
swappable. How does it work?
• The information in the other object is used to initialize a local tmp object. This takes care of
the copying part of the assignment operator;
• Calling swap ensures that the current object receives its new values (with tmp receiving the
current object’s original values);
• When operator= terminates its local tmp object ceases to exist and its destructor is called.
As it by now contains the data previously owned by the current object, the current object’s
original data are now destroyed, effectively completing the destruction part of the assignment
operation.
Nice?
9.6.1 Swapping
Many classes (e.g., std::string) offer swap members allowing us to swap two of their objects.
The Standard Template Library (STL, cf. chapter 18) offers various functions related to swapping.
9.6. REVISING THE ASSIGNMENT OPERATOR 203
1234
Before Swapping 2 and 3
1324
After Swapping 2 and 3
Figure 9.3: Swapping a linked list
There is even a swap generic algorithm (cf. section 19.1.61), which is commonly implemented using
the assignment operator. When implementing a swap member for our class Strings it could be
used, provided that all of String’s data members can be swapped. As this is true (why this is true
is discussed shortly) we can augment class Strings with a swap member:
void Strings::swap(Strings &other)
{
swap(d_string, other.d_string);
swap(d_size, other.d_size);
}
Having added this member to Strings the copy-and-swap implementation of String::operator=
can now be used.
When two variables (e.g., double one and double two) are swapped, each one holds the other
one’s value after the swap. So, if one == 12.50 and two == -3.14 then after swap(one, two)
one == -3.14 and two == 12.50.
Variables of primitive data types (pointers and the built-in types) can be swapped, class-type objects
can be swapped if their classes offer a swap member.
So should we provide our classes with a swap member, and if so, how should it be implemented?
The above example (Strings::swap) shows the standard way to implement a swap member: each
of its data members are swapped in turn. But there are situations where a class cannot implement a
swap member this way, even if the class only defines data members of primitive data types. Consider
the situation depicted in figure 9.3.
In this figure there are four objects, each object has a pointer pointing to the next object. The basic
organization of such a class looks like this:
class List
{
List *d_next;
...
};
Initially four objects have their d_next pointer set to the next object: 1 to 2, 2 to 3, 3 to 4. This is
shown in the upper half of the figure. At the bottom half it is shown what happens if objects 2 and 3
204 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
&
a
b
&b
&
c
d
&d
&
a
b
&b
&
c
d
&d
Before:
After:
Figure 9.4: Swapping objects with self-referential data
are swapped: 3’s d_next point is now at object 2, which still points to 4; 2’s d_next pointer points
to 3’s address, but 2’s d_next is now at object 3, which is therefore pointing to itself. Bad news!
Another situation where swapping of objects goes wrong happens with classes having data members
pointing or referring to data members of the same object. Such a situation is shown in figure 9.4.
Here, objects have two data members, as in the following class setup:
class SelfRef
{
size_t *d_ownPtr; // initialized to &d_data
size_t d_data;
};
The top-half of figure 9.4 shows two objects; their upper data members pointing to their lower data
members. But if these objects are swapped then the situation shown in the figure’s bottom half is
encountered. Here the values at addresses a and c are swapped, and so, rather than pointing to
their bottom data members they suddenly point to other object’s data members. Again: bad news.
The common cause of these failing swapping operations is easily recognized: simple swapping operations
must be avoided when data members point or refer to data that is involved in the swapping.
If, in figure 9.4 the a and c data members would point to information outside of the two objects (e.g.,
if they would point to dynamically allocated memory) then the simple swapping would succeed.
However, the difficulty encountered with swapping SelfRef objects does not imply that two
SelfRef objects cannot be swapped; it only means that we must be careful when designing swap
members. Here is an implementation of SelfRef::swap:
void SelfRef::swap(SelfRef &other)
{
swap(d_data, other.d_data);
}
9.6. REVISING THE ASSIGNMENT OPERATOR 205
In this implementation swapping leaves the self-referential data member as-is, and merely swaps
the remaining data. A similar swap member could be designed for the linked list shown in figure
9.3.
9.6.1.1 Fast swapping
As we’ve seen with placement new objects can be constructed in blocks ofmemory of sizeof(Class)
bytes large. And so, two objects of the same class each occupy sizeof(Class) bytes.
If objects of our class can be swapped, and if our class’s data members do not refer to data actually
involved in the swapping operation then a very fast swapping method that is based on the fact that
we know how large our objects are can be implemented.
In this fast-swap method we merely swap the contents of the sizeof(Class) bytes. This procedure
may be applied to classes whose objects may be swapped using a member-by-member swapping
operation and can (in practice, although this probabaly overstretches the allowed operations as
described by the C++ ANSI/ISO standard) also be used in classes having reference data members.
It simply defines a buffer of sizeof(Class) bytes and performs a circular memcpy operation. Here
is its implementation for a hypothetical class Class. It results in very fast swapping:
#include <cstring>
void Class::swap(Class &other)
{
char buffer[sizeof(Class)];
memcpy(buffer, &other, sizeof(Class));
memcpy(&other, this, sizeof(Class));
memcpy(this, buffer, sizeof(Class));
}
Here is a simple example of a class defining a reference data member and offering a swap member
implemented like the one above. The reference data members are initialized to external streams.
After running the program one contains two hello to 1 lines, two contains two hello to 2 lines (for
brevity all members of Reference are defined inline):
#include <fstream>
#include <cstring>
class Reference
{
std::ostream &d_out;
public:
Reference(std::ostream &out)
:
d_out(out)
{}
void swap(Reference &other)
{
char buffer[sizeof(Reference)];
memcpy(buffer, this, sizeof(Reference));
memcpy(this, &other, sizeof(Reference));
memcpy(&other, buffer, sizeof(Reference));
206 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
}
std::ostream &out()
{
return d_out;
}
};
int main()
{
std::ofstream one("one");
std::ofstream two("two");
Reference ref1(one); // ref1/ref2 hold references to
Reference ref2(two); // the streams
ref1.out() << "hello to 1\n"; // generate some output
ref2.out() << "hello to 2\n";
ref1.swap(ref2);
ref2.out() << "hello to 1\n"; // more output
ref1.out() << "hello to 2\n";
}
Fast swapping should only be used for self-defined classes for which it can be proven that fastswapping
does not corrupt its objects, when swapped.
9.7 Moving data
Traditionally, C++ offered two ways to assign the information pointed to by a data member of a
temporary object to an lvalue object. Either a copy constructor or reference counting had to be used.
In addition to these two methods C++ now also supports move semantics, allowing transfer of the
data pointed to by a temporary object to its destination.
Moving information is based on the concept of anonymous (temporary) data. Temporary values
are returned by functions like operator-() and operator+(Type const &lhs, Type const
&rhs), and in general by functions returning their results ‘by value’ instead of returning references
or pointers.
Anonymous values are always short-lived. When the returned values are primitive types (int,
double, etc.) nothing special happens, but if a class-type object is returned by value then its destructor
can be called immediately following the function call that produced the value. In any case,
the value itself becomes inaccessible immediately after the call. Of course, a temporary return value
may be bound to a reference (lvalue or rvalue), but as far as the compiler is concerned the value now
has a name, which by itself ends its status as a temporary value.
In this section we concentrate on anonymous temporary values and show how they can be used
to improve the efficiency of object construction and assignment. These special construction and
assignment methods are known as move construction and move assignment. Classes supporting
move operations are called move-aware.
Classes allocating their own memory usually benefit from becoming move-aware. But a class does
not have to use dynamic memory allocation before it can benefit from move operations. Most classes
9.7. MOVING DATA 207
using composition (or inheritance where the base class uses composition) can benefit from move
operations as well.
Movable parameters for class Class take the form Class &&tmp. The parameter is a rvalue reference,
and a rvalue reference only binds to an anonymous temporary value. The compiler is required
to call functions offering movable parameters whenever possible. This happens when the class defines
functions supporting Class && parameters and an anonymous temporary value is passed
to such functions. Once a temporary value has a name (which already happens inside functions
defining Class const & or Class &&tmp parameters as within such functions the names of these
parameters are available) it is no longer an anonymous temporary value, and within such functions
the compiler no longer calls functions expecting anonymous temporary values when the parameters
are used as arguments.
The next example (using inline member implementations for brevity) illustrates what happens if a
non-const object, a temporary object and a const object are passed to functions fun for which these
kinds of parameters were defined. Each of these functions call a function gun for which these kinds of
parameters were also defined. The first time fun is called it (as expected) calls gun(Class &). Then
fun(Class &&) is called as its argument is an anonymous (temporary) object. However, inside
fun the anonymous value has received a name, and so it isn’t anonymous anymore. Consequently,
gun(Class &) is called once again. Finally fun(Class const &) is called, and (as expected)
gun(Class const &) is now called.
#include <iostream>
using namespace std;
class Class
{
public:
Class()
{};
void fun(Class const &other)
{
cout << "fun: Class const &\n";
gun(other);
}
void fun(Class &other)
{
cout << "fun: Class &\n";
gun(other);
}
void fun(Class &&tmp)
{
cout << "fun: Class &&\n";
gun(tmp);
}
void gun(Class const &other)
{
cout << "gun: Class const &\n";
}
void gun(Class &other)
{
cout << "gun: Class &\n";
}
void gun(Class &&tmp)
208 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
{
cout << "gun: Class &&\n";
}
};
int main()
{
Class c1;
c1.fun(c1);
c1.fun(Class());
Class const c0;
c1.fun(c0);
}
Generally it is pointless to define a function having an rvalue reference return type. The compiler
decides whether or not to use an overloaded member expecting an rvalue reference on the basis of
the provided argument. If it is an anonymous temporary it calls the function defining the rvalue
reference parameter, if such a function is available. A rvalue reference return type is used, e.g.,
with the std::move call, to keep the rvalue reference nature of its argument, which is known to
be a temporary anonymous object. Such a situation can be exploited also in a situation where a
temporary object is passed to (and returned from) a function which must be able to modify the
temporary object. The alternative, passing a const &, is less attractive as it requires a const_cast
before the object can be modified. Here is an example:
std::string &&doubleString(std::string &&tmp)
{
tmp += tmp;
return std::move(tmp);
}
This allows us to do something like
std::cout << doubleString(std::string("hello "));
to insert hello hello into cout.
The compiler, when selecting a function to call applies a fairly simple algorithm, and also considers
copy elision. This is covered shortly (section 9.8).
9.7.1 The move constructor (dynamic data)
Our class Strings has, among other members a data member string _d_string. Clearly,
Strings should define a copy constructor, a destructor and an overloaded assignment operator.
Now consider the following function loadStrings(std::istream &in) extracting the strings for
a Strings object from in. Next, the Strings object filled by loadStrings is returned by value.
The function loadStrings returns a temporary object, which can then used to initialize an external
Strings object:
Strings loadStrings(std::istream &in)
9.7. MOVING DATA 209
{
Strings ret;
// load the strings into ’ret’
return ret;
}
// usage:
Strings store(loadStrings(cin));
In this example two full copies of a Strings object are required:
• initializing loadString’s value return type from its local Strings ret object;
• initializing store from loadString’s return value
We can improve the above procedure by defining a move constructor. Here is the declaration of the
Strings class move constructor:
Strings(Strings &&tmp);
Move constructors of classes using dynamic memory allocation are allowed to assign the values of
pointer data members to their own pointer data members without requiring them to make a copy of
the source’s data. Next, the temporary’s pointer value is set to zero to prevent its destructor from
destroying data now owned by the just constructed object. The move constructor has grabbed or
stolen the data from the temporary object. This is OK as the temporary object cannot be referred to
again (as it is anonymous, it cannot be accessed by other code) and the temporary objects cease to
exist shortly after the constructor’s call. Here is the implementation of Strings move constructor:
Strings::Strings(Strings &&tmp)
:
d_memory(tmp.d_memory),
d_size(tmp.d_size),
d_capacity(tmp.d_capacity)
{
tmp.d_memory = 0;
}
In section 9.5 it was stated that the copy constructor is almost always available. Almost always
as the declaration of a move constructor suppresses the default availability of the copy constructor.
The default copy constructor is also suppressed if a move assignment operator is declared (cf. section
9.7.3).
The following example shows a simple class Class, declaring a move constructor. In the main function
following the class interface a Class object is defined which is then passed to the constructor of
a second Class object. Compilation fails with the compiler reporting:
error: cannot bind ’Class’ lvalue to ’Class&&’
error: initializing argument 1 of ’Class::Class(Class&&)’
class Class
{
public:
Class() = default;
210 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
Class(Class &&tmp)
{}
};
int main()
{
Class one;
Class two(one);
}
The cure is easy: after declaring a (possibly default) copy constructor the error disappears:
class Class
{
public:
Class() = default;
Class(Class const &other) = default;
Class(Class &&tmp)
{}
};
int main()
{
Class one;
Class two(one);
}
9.7.2 The move constructor (composition)
Classes not using pointer members pointing to memory controlled by its objects (and not having
base classes doing so, see chapter 13) may also benefit from overloaded members expecting rvalue
references. The class benefits frommove operations when one ormore of the composed datamembers
themselves support move operations.
Move operations cannot be implemented if the class type of a composed data member does not support
moving or copying. Currently, stream classes fall into this category.
An example of amove-aware class is the class std:string. A class Person could use composition by
defining std::string d_name and std::string d_address. Its move constructor would then
have the following prototype:
Person(Person &&tmp);
However, the following implementation of this move constructor is incorrect:
Person::Person(Person &&tmp)
:
d_name(tmp.d_name),
d_address(tmp.d_address)
{}
It is incorrect as it string’s copy constructors rather than string’s move constructors are called.
If you’re wondering why this happens then remember that move operations are only performed for
9.7. MOVING DATA 211
anonymous objects. To the compiler anything having a name isn’t anonymous. And so, by implication,
having available a rvalue reference does not mean that we’re referring to an anonymous object.
But we know that the move constructor is only called for anonymous arguments. To use the corresponding
string move operations we have to inform the compiler that we’re talking about anonymous
data members as well. For this a cast could be used (e.g., static_cast<Person &&>(tmp)),
but the C++-0x standard provides the function std::move to anonymize a named object. The correct
implementation of Person’s move construction is, therefore:
Person::Person(Person &&tmp)
:
d_name( std::move(tmp.d_name) ),
d_address( std::move(tmp.d_address) )
{}
The function std::move is (indirectly) declared by many header files. If no header is already declaring
std::move then include utility.
When a class using composition not only contains class type data members but also other types of
data (pointers, references, primitive data types), then these other data types can be initialized as
usual. Primitive data type members can simply be copied; references can be initialized as usual en
pointers may use move operations as discussed in the previous section.
The compiler never calls move operations for variables having names. Let’s consider the implications
of this by looking at the next example, assuming Class offers a move constructor and a copy
constructor:
Class factory();
void fun(Class const &other); // a
void fun(Class &&tmp); // b
void callee(Class &&tmp);
{
fun(tmp); // 1
}
int main()
{
callee(factory());
}
• At 1 function a is called. At first sight this might be surprising, but fun’s argument is not an
anonymous temporary object but a named temporary object.
Realizing that fun(tmp) might be called twice the compiler’s choice is understandable. If tmp’s
data would have been grabbed at the first call, the second call would receive tmp without any data.
But at the last call we might know that tmp is never used again and so we might like to ensure that
fun(Class &&) is called. For this, once again, std::move is used:
fun(std::move(tmp)); // last call!
212 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
9.7.3 Move-assignment
In addition to the overloaded assignment operator a move assignment operator may be implemented
for classes supporting move operations. In this case, if the class supports swapping the implementation
is surprisingly simple. No copy construction is required and the move assignment operator can
simply be implemented like this:
Class &operator=(Class &&tmp)
{
swap(tmp);
return *this;
}
If swapping is not supported then the assignment can be performed for each of the data members in
turn, using std::move as shown in the previous section with a class Person. Here is an example
showing how to do this with that class Person:
Person &operator=(Person &&tmp)
{
d_name = std::move(tmp.d_name);
d_address = std::move(tmp.d_address);
return *this;
}
As noted previously (section 9.7.1) declaring a move assignment operator suppresses the default
availability of the copy constructor. It is made available again by declaring the copy constructor
in the class’s interface (and of course by providing an explicit implementation or by using the =
default default implementation).
9.7.4 Revising the assignment operator (part II)
Now that we’ve familiarized ourselves with the overloaded assignment operator and the moveassignment,
let’s once again have a look at their implementations for a class Class, supporting
swapping through its swap member. Here is the generic implementation of the overloaded assignment
operator:
Class &operator=(Class const &other)
{
Class tmp(other);
swap(tmp);
return *this;
}
and this is the move-assignment operator:
Class &operator=(Class &&tmp)
{
swap(tmp);
return *this;
}
9.7. MOVING DATA 213
They look remarkably similar in the sense that the overloaded assignment operator’s code is identical
to the move-assignment operator’s code once a copy of the other object is available. Since the
overloaded assignment operator’s tmp object really is nothing but a temporary Class object we can
use this fact by implementing the overloaded assignment operator in terms of the move-assignment.
Here is a second revision of the overloaded assignment operator:
Class &operator=(Class const &other)
{
Class tmp(other);
return *this = std::move(tmp);
}
9.7.5 Moving and the destructor
Once a class becomes a move-aware class one should realize that its destructor still performs its job
as implemented. Consequently, when moving pointer values from a temporary source to a destination
the move constructor should make sure that the temporary’s pointer value is set to zero, to
prevent doubly freeing memory.
If a class defines pointers to pointer data members there usually is not only a pointer that is moved,
but also a size_t defining the number of elements in the array of pointers.
Once again, consider the class Strings. Its destructor is implemented like this:
Strings::~Strings()
{
for (string **end = d_string + d_size; end-- != d_string; )
delete *end;
delete[] d_string;
}
The move constructor (and other move operations!) must realize that the destructor not only deletes
d_string, but also considers d_size. A member implementing move operations should therefore
not only set d_string to zero but also d_size. The previously shownmove constructor for Strings
is therefore incorrect. Its improved implementation is:
Strings::Strings(Strings &&tmp)
:
d_memory(tmp.d_memory),
d_size(tmp.d_size),
d_capacity(tmp.d_capacity)
{
tmp.d_memory = 0;
tmp.d_size = 0;
}
If operations by the destructor all depend on d_string having a non-zero value then variations of
the above approach are of course possible. The move operationsmerely could decide to set d_memory
to 0, and then test whether d_memory == 0 in the destructor (and if so, end the destructor’s actions),
saving some d_size assignments.
214 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
9.7.6 Move-only classes
Classes may very well allow move semantics without offering copy semantics. Most stream classes
belong to this category. Extending their definition with move semantics greatly enhances their
usability. Once move semantics becomes available for such classes, so called factory functions (functions
returning an object constructed by the function) can easily be implemented. E.g.,
// assume char *filename
ifstream inStream(openIstream(filename));
For this example to work an ifstream constructor must offer a move constructor. This ensures that
only one object refers to the open istream.
Once classes offer move semantics their objects can also safely be stored in standard containers (cf.
chapter 12). When such containers perform reallocations (e.g., when their sizes are enlarged) they
use the object’s move constructors rather than their copy constructors. As move-only classes suppress
copy semantics containers storing objects of move-only classes implement the correct behavior
in that it is impossible to assign such containers to each other.
9.7.7 Default move constructors and assignment operators
As we’ve seen, classes by default offer a copy constructor and assignment operator. These class
members are implemented so as to provide basic support: data members of primitive data types
are copied byte-by-byte, but for class type data members their corresponding coy constructors c.q.
assignment operators are called.
The compiler can provide default implementations for move constructors and move assignment operators.
However, except for the copy constructor, default implementations for constructors (c.q. assignment
operators) are no longer provided once a class declares at least one constructor (c.q. assignment operator),
while the default copy constructor is suppressed by declarations of either the move constructor
or the move assignment operator.
If default implementations should be available in these cases, it’s easy to add them to the class by
adding = default to the appropriate constructor and assignment operator declarations.
Here is an example of a class offering all defaults: constructor, copy constructor, move constructor,
assignment operator and move assignment operator:
class Defaults
{
int d_x;
Mov d_mov;
};
Assuming that Mov is a class offering move operations in addition to the standard deep copy operations,
then the following actions are performed on the destination’s d_mov and d_x:
Defaults factory();
int main()
{ Mov operation: d_x:
9.7. MOVING DATA 215
---------------------------
Defaults one; Mov(), undefined
Defaults two(one); Mov(Mov const &), one.d_x
Defaults three(factory()); Mov(Mov &&tmp), tmp.d_x
one = two; Mov::operator=( two.d_x
Mov const &),
one = factory(); Mov::operator=( tmp.d_x
Mov &&tmp)
}
If, however, Defaults declares at least one constructor (it could be the copy constructor) and one
assignment operator, then only those members and the copy constructor remain available. E.g.:
class Defaults
{
int d_x;
Mov d_mov;
public:
Defaults(int x);
Defaults operator=(Defaults &&tmp);
};
Defaults factory();
int main()
{ Mov operation: resulting d_x:
--------------------------------
Defaults one; ERROR: not available
Defaults two(one); Mov(Mov const &), one.d_x
Defaults three(factory()); ERROR: not available
one = two; ERROR: not available
one = factory(); Mov::operator=( tmp.d_x
Mov &&tmp)
}
To reestablish the defaults, append = default to the appropriate declarations:
class Defaults
{
int d_x;
Mov d_mov;
public:
Defaults() = default;
Defaults(Defaults &&tmp) = default;
Defaults(int x);
// Default(Default const &) remains available
Defaults operator=(Defaults const &rhs) = default;
216 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
Defaults operator=(Defaults &&tmp);
};
Be cautious, declaring defaults, as default implementations copy data members of primitive types
byte-by-byte from the source object to the destination object. This is likely to cause problems with
pointer type data members.
The = default suffix can only be used when declaring constructors or assignment operators in the
class’s public section.
9.7.8 Moving: implications for class design
Here are some general rules to apply when designing classes offering value semantics (i.e., classes
whose objects can be used to initialize other objectes of their class and that can be asssigned to other
objects of their class):
• Classes using pointers to dynamically allocated memory, owned by the class’s objects must be
provided with a copy constructor, an overloaded copy assignment operator and a destructor;
• Classes using pointers to dynamically allocated memory, owned by the class’s objects, should
be provided with a move constructor and a move assignment operator;
• Classes using compositionmay benefit frommove constructors and move assignment operators
as well. Some classes support neithermove nor copy construction and assignment (for example:
stream classes don’t). If your class contains data members of such class types then defining
move operations is pointless.
In the previous sections we’ve also encountered an important design principle that can be applied to
move-aware classes:
Whenever a member of a class receives a const & to an object of its own class and creates
a copy of that object to perform its actual actions on, then that function’s implementation
can be implemented by an overloaded function expecting an rvalue reference.
The former function can now call the latter by passing std::move(tmp) to it. The advantages of
this design principle should be clear: there is only one implementation of the actual actions, and the
class automatically becomes move-aware with respect to the involved function.
We’ve seen an initial example of the use of this principle in section 9.7.4. Of course, the principle
cannot be applied to the copy constructor itself, as you need a copy constructor to make a copy. The
copy- and move constructors must always be implemented independently from each other.
9.8 Copy Elision and Return Value Optimization
When the compiler selects a member function (or constructor) it applies a simple set of rules, matching
arguments with parameter types.
Below two tables are shown. The first table should be used in cases where a function argument has
a name, the second table should be used in cases where the argument is anonymous. In each table
select the const or non-const column and then use the topmost overloaded function that is available
having the specified parameter type.
9.8. COPY ELISION AND RETURN VALUE OPTIMIZATION 217
The tables do not handle functions defining value parameters. If a function has overloads expecting,
respectively, a value parameter and some form of reference parameter the compiler reports an ambiguity
when such a function is called. In the following selection procedure we may assume, without
loss of generality, that this ambiguity does not occur and that all parameter types are reference
parameters.
Parameter types matching a function’s argument of type T if the argument is:
• a named argument (an lvalue or a named rvalue)
the argument is:
non-const const
Use the topmost (T &)
available function (T const &) (T const &)
Example: for an int x argument a function fun(int &) is selected rather than a function
fun(int const &). If no fun(int &) is available the fun(int const &) function is used.
If neither is available (and fun int hasn’t been defined instead) the compiler reports an error.
• an anonymous argument (an anonymous temporary or a literal value)
the argument is:
non-const const
Use the topmost (T &&)
available function (T const &&) (T const &&)
available function (T const &) (T const &)
Example: when the return value of an int arg() function is passed to a function fun for
which various overloaded versions are available fun(int &&) is selected. If this function is
unavailable but fun(int const &) is, then the latter function is used. If none of these two
functions is available the compiler reports an error.
The tables show that eventually all arguments can be used with a function specifying a T const
& parameter. For anonymous arguments a similar catch all is available having a higher priority:
T const && matches all anonymous arguments. Functions having this signature are normally not
defined as their implementations are (should be) identical to the implementations of the functions
expecting a T const & parameter. Since the temporary can apparently not be modified a function
defining a T const && parameter has no alternative but to copy the temporary’s resources. As
this task is already performed by functions expecting a T const &, there is no need for implenting
functions expecting T const && parameters.
As we’ve seen the move constructor grabs the information from a temporary for its own use. That is
OK as the temporary is going to be destroyed after that anyway. It also means that the temporary’s
data members are modified.
Having defined appropriate copy and/or move constructors it may be somewhat surprising to learn
that the compiler may decide to stay clear of a copy or move operation. After all making no copy and
not moving is more efficient than copying or moving.
The option the compiler has to avoid making copies (or perform move operations) is called copy
elision or return value optimization. In all situations where copy or move constructions are appropriate
the compiler may apply copy elision. Here are the rules. In sequence the compiler considers
the following options, stopping once an option can be selected:
• if a copy or move constructor exists, try copy elision
218 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
• if a move constructor exists, move.
• if a copy constructor exists, copy.
• report an error
All modern compilers apply copy elision. Here are some examples where it may be encountered:
class Elide;
Elide fun() // 1
{
Elide ret;
return ret;
}
void gun(Elide par);
Elide elide(fun()); // 2
gun(fun()); // 3
• At 1 ret may never exist. Instead of using ret and copying ret eventually to fun’s return
value it may directly use the area used to contain fun’s return value.
• At 2 fun’s return value may never exist. Instead of defining an area containing fun’s return
value and copying that return value to elide the compiler may decide to use elide to create
fun’s return value in.
• At 3 the compiler may decide to do the same for gun’s par parameter: fun’s return value is
directly created in par’s area, thus eliding the copy operation from fun’s return value to par.
9.9 Plain Old Data
C++ inherited the struct concept fromC and extended it with the class concept. Structs are still used
in C++, mainly to store and pass around aggregates of different data types. A commonly term for
these structs is plain old data (pod). Plain old data is commonly used in C++ programs to aggregate
data. E.g., when a function needs to return a double, bool and std::string these three different
data types may be aggregated using a struct that merely exists to pass along values. Data
protection and functionality is hardly ever an issue. For such cases C and C++ use structs. But
as a C++ struct is just a class with special access rights some members (constructors, destructor,
overloaded assignment operator) may implicitly be defined. The plain old data capitalizes on this
concept by requiring that its definition remains as simple as possible. Pod is considered any class or
struct having the following characteristics:
• it has a trivial default constructor.
If a type has some trivial member then the type (or its base class(es), cf. chapter 13) does
not explicitly define that member. Rather, it is supplied by the compiler. A trivial default
constructor leaves all its non-class data members unitialized and calls the default constructors
of all its class data members. A class having a trivial default constructor does not define any
constructor at all (nor does/do its base class/classes). It may also define the default constructor
using the default constructor syntax introduced in section 7.6;
9.10. CONCLUSION 219
• it has a trivial copy constructor.
A trivial copy constructor byte-wise copies the non-class data members from the provided existing
class object and uses copy constructors to initialize its base class(es) and class data
members with the information found in the provided existing class object;
• it has a trivial overloaded assignment operator.
A trivial assignment operator performs a byte-wise copy of the non-class data members of
the provided right-hand class object and uses overloaded assignment operators to assign new
values to its class data members using the corresponding members of the provided right-hand
class object;
• it has a trivial destructor.
A trivial destructor calls the destructors of its base class(es) and class-type data members;
• it has a standard layout.
A standard-layout class or struct
• has only non-static data members that are themselves showing the standard-layout;
• has identical access control (public, private, protected) for all its non-static members;
Furthermore, in the context of class derivation (cf. chapters 14 and 13), a standard-layout class or
struct:
• has only base classes that themselves show the standard-layout;
• has at most one (in)direct base class having non-static members;
• has no base classes of the same type as its first non-static data member;
• has no virtual base classes;
• has no virtual members.
9.10 Conclusion
Four important extensions to classes were introduced in this chapter: the destructor, the copy constructor,
the move constructor and the overloaded assignment operator. In addition the importance
of swapping, especially in combination with the overloaded assignment operator, was stressed.
Classes having pointer data members, pointing to dynamically allocated memory controlled by the
objects of those classes, are potential sources of memory leaks. The extensions introduced in this
chapter implement the standard defense against such memory leaks.
Encapsulation (data hiding) allows us to ensure that the object’s data integrity is maintained. The
automatic activation of constructors and destructors greatly enhance our capabilities to ensure the
data integrity of objects doing dynamic memory allocation.
A simple conclusion is therefore that classes whose objects allocate memory controlled by themselves
must at least implement a destructor, an overloaded assignment operator and a copy constructor.
Implementing a move constructor remains optional, but it allows us to use factory functions with
classes not allowing copy construction and/or assignment.
In the end, assuming the availability of at least a copy or move constructor, the compiler might
avoid them using copy elision. The compiler is free to use copy elision wherever possible; it is,
220 CHAPTER 9. CLASSES AND MEMORY ALLOCATION
however, never a requirement. The compiler may therefore always decide not to use copy elision. In
all situations where otherwise a copy or move constructor would have been used the compiler may
consider to use copy elision.

Chapter 10
Exceptions
C supports several ways for a program to react to situations breaking the normal unhampered flow
of a program:
• The function may notice the abnormality and issue a message. This is probably the least
disastrous reaction a program may show.
• The function in which the abnormality is observed may decide to stop its intended task, returning
an error code to its caller. This is a great example of postponing decisions: now the
calling function is faced with a problem. Of course the calling function may act similarly, by
passing the error code up to its caller.
• The function may decide that things are going out of hand, and may call exit to terminate the
program completely. A tough way to handle a problem if only because the destructors of local
objects aren’t activated.
• The function may use a combination of the functions setjmp and longjmp to enforce non-local
exits. This mechanism implements a kind of goto jump, allowing the program to continue at
an outer level, skipping the intermediate levels which would have to be visited if a series of
returns from nested functions would have been used.
In C++ all these flow-breaking methods are still available. However, of the mentioned alternatives,
setjmp and longjmp isn’t frequently encountered in C++ (or even in C) programs, due to the fact
that the program flow is completely disrupted.
C++ offers exceptions as the preferred alternative to, e.g., setjmp and longjmp. Exceptions allow
C++ programs to perform a controlled non-local return, without the disadvantages of longjmp and
setjmp.
Exceptions are the proper way to bail out of a situation which cannot be handled easily by a function
itself, but which is not disastrous enough for a program to terminate completely. Also, exceptions
provide a flexible layer of control between the short-range return and the crude exit.
In this chapter exceptions are covered. First an example is given of the different impact exceptions
and the setjmp/longjmp combination have on programs. This example is followed by a discussion
of the formal aspects of exceptions. In this part the guarantees our software should be able to offer
when confronted with exceptions are presented. Exceptions and their guarantees have consequences
for constructors and destructors. We’ll encounter these consequences at the end of this chapter.
221
222 CHAPTER 10. EXCEPTIONS
10.1 Exception syntax
Before contrasting the traditional C way of handling non-local gotos with exceptions let’s introduce
the syntactic elements that are involved when using exceptions.
• Exceptions are generated by a throw statement. The keyword throw, followed by an expression
of a certain type, throws the expression value as an exception. In C++ anything having
value semantics may be thrown as an exception: an int, a bool, a string, etc. However,
there also exists a standard exception type (cf. section 10.8) that may be used as base class (cf.
chapter 13) when defining new exception types.
• Exceptions are generated within a well-defined local environment, called a try-block. The
run-time support system ensures that all of the program’s code is itself surrounded by a global
try block. Thus, every exception generated by our code will always reach the boundary of at
least one try-block. A program terminates when an exception reaches the boundary of the
global try block, and when this happens destructors of local and global objects that were alive
at the point where the exception was generated are not called. This is not a desirable situation
and therefore all exceptions should be generated within a try-block explicitly defined by the
program. Here is an example of a string exception thrown from within a try-block:
try
{
// any code can be defined here
if (someConditionIsTrue)
throw string("this is the std::string exception");
// any code can be defined here
}
• catch: Immediately following the try-block, one or more catch-clauses must be defined. A
catch-clause consists of a catch-header defining the type of the exception it can catch followed
by a compound statement defining what to do with the caught exception:
catch (string const &msg)
{
// statements in which the caught string object are handled
}
Multiple catch clauses may appear underneath each other, one for each exception type that
has to be caught. In general the catch clauses may appear in any order, but there are exceptions
requiring a specific order. To avoid confusion it’s best to put a catch clause for the most
general exception last. At most one exception clause will be activated. C++ does not support a
Java-style finally-clause activated after completing a catch clause.
10.2 An example using exceptions
In the following examples the same basic program is used. The program uses two classes, Outer
and Inner.
First, an Outer object is defined in main, and its member Outer::fun is called. Then, in
Outer::fun an Inner object is defined. Having defined the Inner object, its member Inner::fun
is called.
10.2. AN EXAMPLE USING EXCEPTIONS 223
That’s about it. The function Outer::fun terminates calling inner’s destructor. Then the program
terminates, activating outer’s destructor. Here is the basic program:
#include <iostream>
using namespace std;
class Inner
{
public:
Inner();
~Inner();
void fun();
};
Inner::Inner()
{
cout << "Inner constructor\n";
}
Inner::~Inner()
{
cout << "Inner destructor\n";
}
void Inner::fun()
{
cout << "Inner fun\n";
}
class Outer
{
public:
Outer();
~Outer();
void fun();
};
Outer::Outer()
{
cout << "Outer constructor\n";
}
Outer::~Outer()
{
cout << "Outer destructor\n";
}
void Outer::fun()
{
Inner in;
cout << "Outer fun\n";
in.fun();
}
int main()
{
Outer out;
out.fun();
}
224 CHAPTER 10. EXCEPTIONS
/*
Generated output:
Outer constructor
Inner constructor
Outer fun
Inner fun
Inner destructor
Outer destructor
*/
After compiling and running, the program’s output is entirely as expected: the destructors are called
in their correct order (reversing the calling sequence of the constructors).
Now let’s focus our attention on two variants in which we simulate a non-fatal disastrous event in
the Inner::fun function. This event must supposedly be handled near main’s end.
We’ll consider two variants. In the first variant the event is handled by setjmp and longjmp; in
the second variant the event is handled using C++’s exception mechanism.
10.2.1 Anachronisms: ‘setjmp’ and ‘longjmp’
The basic program from the previous section is slightly modified to contain a variable jmp_buf
jmpBuf used by setjmp and longjmp.
The function Inner::fun calls longjmp, simulating a disastrous event, to be handled near main’s
end. In main a target location for the long jump is defined through the function setjmp. Setjmp’s
zero return indicates the initialization of the jmp_buf variable, in which case Outer::fun is called.
This situation represents the ‘normal flow’.
The program’s return value is zero only if Outer::fun terminates normally. The program, however,
is designed in such a way that this won’t happen: Inner::fun calls longjmp. As a result the
execution flow returns to the setjmp function. In this case it does not return a zero return value.
Consequently, after calling Inner::fun from Outer::fun main’s if-statement is entered and the
program terminates with return value 1. Try to follow these steps when studying the following
program source, which is a direct modification of the basic program given in section 10.2:
#include <iostream>
#include <setjmp.h>
#include <cstdlib>
using namespace std;
jmp_buf jmpBuf;
class Inner
{
public:
Inner();
~Inner();
void fun();
};
Inner::Inner()
{
10.2. AN EXAMPLE USING EXCEPTIONS 225
cout << "Inner constructor\n";
}
void Inner::fun()
{
cout << "Inner fun\n";
longjmp(jmpBuf, 0);
}
Inner::~Inner()
{
cout << "Inner destructor\n";
}
class Outer
{
public:
Outer();
~Outer();
void fun();
};
Outer::Outer()
{
cout << "Outer constructor\n";
}
Outer::~Outer()
{
cout << "Outer destructor\n";
}
void Outer::fun()
{
Inner in;
cout << "Outer fun\n";
in.fun();
}
int main()
{
Outer out;
if (setjmp(jmpBuf) != 0)
return 1;
out.fun();
}
/*
Generated output:
Outer constructor
Inner constructor
Outer fun
Inner fun
Outer destructor
*/
This program’s output clearly shows that inner’s destructor is not called. This is a direct conse226
CHAPTER 10. EXCEPTIONS
quence of the non-local jump performed by longjmp. Processing proceeds immediately from the
longjmp call inside Inner::fun to setjmp in main. There, its return value is unequal zero, and
the program terminates with return value 1. Because of the non-local jump Inner::~Inner is
never executed: upon return to main’s setjmp the existing stack is simply broken down disregarding
any destructors waiting to be called.
This example illustrates that the destructors of objects can easily be skipped when longjmp and
setjmp are used and C++ programs should therefore avoid those functions like the plague.
10.2.2 Exceptions: the preferred alternative
Exceptions are C++’s answer to the problems caused by setjmp and longjmp. Here is an example
using exceptions. The program is once again derived from the basic program of section 10.2:
#include <iostream>
using namespace std;
class Inner
{
public:
Inner();
~Inner();
void fun();
};
Inner::Inner()
{
cout << "Inner constructor\n";
}
Inner::~Inner()
{
cout << "Inner destructor\n";
}
void Inner::fun()
{
cout << "Inner fun\n";
throw 1;
cout << "This statement is not executed\n";
}
class Outer
{
public:
Outer();
~Outer();
void fun();
};
Outer::Outer()
{
cout << "Outer constructor\n";
}
Outer::~Outer()
{
10.3. THROWING EXCEPTIONS 227
cout << "Outer destructor\n";
}
void Outer::fun()
{
Inner in;
cout << "Outer fun\n";
in.fun();
}
int main()
{
Outer out;
try
{
out.fun();
}
catch (int x)
{}
}
/*
Generated output:
Outer constructor
Inner constructor
Outer fun
Inner fun
Inner destructor
Outer destructor
*/
Inner::fun now throws an int exception where a longjmp was previously used. Since in.fun is
called by out.fun, the exception is generated within the try block surrounding the out.fun call.
As an int value was thrown this value reappears in the catch clause beyond the try block.
Now Inner::fun terminates by throwing an exception instead of calling longjmp. The exception is
caught in main, and the program terminates. Now we see that inner’s destructor is properly called.
It is interesting to note that Inner::fun’s execution really terminates at the throw statement: The
cout statement, placed just beyond the throw statement, isn’t executed.
What did this example teach us?
• Exceptions provide a means to break a function’s (and program’s) normal flow without having
to use a cascade of return-statements, and without the need to terminate the program using
blunt tools like the function exit.
• Exceptions do not disrupt the proper activation of destructors. Since setjmp and longjmp do
distrupt the proper activation of destructors their use is strongly deprecated in C++.
10.3 Throwing exceptions
Exceptions are generated by throw statements. The throw keyword is followed by an expression,
defining the thrown exception value. Example:
throw "Hello world"; // throws a char *
228 CHAPTER 10. EXCEPTIONS
throw 18; // throws an int
throw string("hello"); // throws a string
Local objects cease to exist when a function terminates. This is no different for exceptions.
Objects defined locally in functions are automatically destroyed once exceptions thrown by these
functions leave these functions. This also happens to objects thrown as exceptions. However, just
before leaving the function context the object is copied and it is this copy that eventually reaches the
appropriate catch clause.
The following examples illustrates this process. Object::fun defines a local Object toThrow,
that is thrown as an exception. The exception is caught in main. But by then the object originally
thrown doesn’t exist anymore, and main received a copy:
#include <iostream>
#include <string>
using namespace std;
class Object
{
string d_name;
public:
Object(string name)
:
d_name(name)
{
cout << "Constructor of " << d_name << "\n";
}
Object(Object const &other)
:
d_name(other.d_name + " (copy)")
{
cout << "Copy constructor for " << d_name << "\n";
}
~Object()
{
cout << "Destructor of " << d_name << "\n";
}
void fun()
{
Object toThrow("’local object’");
cout << "Calling fun of " << d_name << "\n";
throw toThrow;
}
void hello()
{
cout << "Hello by " << d_name << "\n";
}
};
int main()
{
Object out("’main object’");
try
10.3. THROWING EXCEPTIONS 229
{
out.fun();
}
catch (Object o)
{
cout << "Caught exception\n";
o.hello();
}
}
Object’s copy constructor is special in that it defines its name as the other object’s name to which
the string " (copy)" is appended. This allow us to monitor the construction and destruction of
objects more closely. Object::fun generates an exception, and throws its locally defined object.
Just before throwing the exception the program has produced the following output:
Constructor of ’main object’
Constructor of ’local object’
Calling fun of ’main object’
When the exception is generated the next line of output is produced:
Copy constructor for ’local object’ (copy)
The local object is passed to throw where it is treated as a value argument, creating a copy of
toThrow. This copy is thrown as the exception, and the local toThrow object ceases to exist. The
thrown exception is now caught by the catch clause, defining an Object value parameter. Since
this is a value parameter yet another copy is created. Thus, the program writes the following text:
Destructor of ’local object’
Copy constructor for ’local object’ (copy) (copy)
The catch block now displays:
Caught exception
Following this o’s hello member is called, showing us that we indeed received a copy of the copy of
the original toThrow object:
Hello by ’local object’ (copy) (copy)
Then the program terminates and its remaining objects are now destroyed, reversing their order of
creation:
Destructor of ’local object’ (copy) (copy)
Destructor of ’local object’ (copy)
Destructor of ’main object’
The copy created by the catch clause clearly is superfluous. It can be avoided by defining object
reference parameters in catch clauses: ‘catch (Object &o)’. The program now produces the
following output:
Constructor of ’main object’
230 CHAPTER 10. EXCEPTIONS
Constructor of ’local object’
Calling fun of ’main object’
Copy constructor for ’local object’ (copy)
Destructor of ’local object’
Caught exception
Hello by ’local object’ (copy)
Destructor of ’local object’ (copy)
Destructor of ’main object’
Only a single copy of toThrow was created.
It’s a bad idea to throw a pointer to a locally defined object. The pointer is thrown, but the object
to which the pointer refers ceases to exist once the exception is thrown. The catcher receives a wild
pointer. Bad news....
Let’s summarize the above findings:
• Local objects are thrown as copied objects;
• Don’t throw pointers to local objects;
• It is possible to throw pointers to dynamically generated objects. In this case one must take
care that the generated object is properly deleted by the exception handler to prevent amemory
leak.
Exceptions are thrown in situations where a function can’t complete its assigned task, but the program
is still able to continue. Imagine a program offering an interactive calculator. The program
expects numeric expressions, which are evaluated. Expressions may show syntactic errors or it may
be mathematically impossible to evaluate them. Maybe the calculator allows us to define and use
variables and the user might refer to non-existing variables: plenty of reasons for the expression
evaluation to fail, and so many reasons for exceptions to be thrown. None of those should terminate
the program. Instead, the program’s user is informed about the nature of the problem and is invited
to enter another expression. Example:
if (!parse(expressionBuffer)) // parsing failed
throw "Syntax error in expression";
if (!lookup(variableName)) // variable not found
throw "Variable not defined";
if (divisionByZero()) // unable to do division
throw "Division by zero is not defined";
Where these throw statements are located is irrelevant: they may be found deeply nested inside the
program, or at a more superficial level. Furthermore, functions may be used to generate the exception
to be thrown. An Exception object might support stream-like insertion operations allowing us
to do, e.g.,
if (!lookup(variableName))
throw Exception() << "Undefined variable ’" << variableName << "’;
10.3. THROWING EXCEPTIONS 231
10.3.1 The empty ‘throw’ statement
Sometimes it is required to inspect a thrown exception. An exception catcher may decide to ignore
the exception, to process the exception, to rethrow it after inspection or to change it into another
kind of exception. For example, in a server-client application the client may submit requests to the
server by entering them into a queue. Normally every request is eventually answered by the server.
The server may reply that the request was successfully processed, or that some sort of error has
occurred. On the other hand, the server may have died, and the client should be able to discover this
calamity, by not waiting indefinitely for the server to reply.
In this situation an intermediate exception handler is called for. A thrown exception is first inspected
at the middle level. If possible it is processed there. If it is not possible to process the exception at the
middle level, it is passed on, unaltered, to a more superficial level, where the really tough exceptions
are handled.
By placing an empty throw statement in the exception handler’s code the received exception is
passed on to the next level that might be able to process that particular type of exception. The
rethrown exception is never handled by one of its neighboring exception handlers; it is always transferred
to an exception handler at a more superficial level.
In our server-client situation a function
initialExceptionHandler(string &exception)
could be designed to handle the string exception. The received message is inspected. If it’s
a simple message it’s processed, otherwise the exception is passed on to an outer level. In
initialExceptionHandler’s implementation the empty throw statement is used:
void initialExceptionHandler(string &exception)
{
if (!plainMessage(exception))
throw;
handleTheMessage(exception);
}
Below (section 10.5), the empty throw statement is used to pass on the exception received by a
catch-block. Therefore, a function like initialExceptionHandler can be used for a variety of
thrown exceptions, as long as their types match initialExceptionHandler’s parameter, which is
a string.
The next example jumps slightly ahead, using some of the topics covered in chapter 14. The example
may be skipped, though, without loss of continuity.
A basic exception handling class can be constructed from which specific exception types are
derived. Suppose we have a class Exception, having a member function ExceptionType
Exception::severity. This member function tells us (little wonder!) the severity of a thrown
exception. It might be Info, Notice, Warning, Error or Fatal. The information contained in
the exception depends on its severity and is processed by a function handle. In addition, all exceptions
support a member function like textMsg, returning textual information about the exception
in a string.
By defining a polymorphic function handle it can be made to behave differently, depending on the
nature of a thrown exception, when called from a basic Exception pointer or reference.
232 CHAPTER 10. EXCEPTIONS
In this case, a program may throw any of these five exception types. Assuming that the classes
Message and Warning were derived from the class Exception, then the handle function matching
the exception type will automatically be called by the following exception catcher:
//
catch(Exception &ex)
{
cout << e.textMsg() << ’\n’;
if
(
ex.severity() != ExceptionType::Warning
&&
ex.severity() != ExceptionType::Message
)
throw; // Pass on other types of Exceptions
ex.handle(); // Process a message or a warning
}
Now anywhere in the try block preceding the exception handler Exception objects or objects of
one of its derived classes may be thrown. All those exceptions will be caught by the above handler.
E.g.,
throw Info();
throw Warning();
throw Notice();
throw Error();
throw Fatal();
10.4 The try block
The try-block surrounds throw statements. Remember that a program is always surrounded by
a global try block, so throw statements may appear anywhere in your code. More often, though,
throw statements are used in function bodies and such functions may be called from within try
blocks.
A try block is defined by the keyword try followed by a compound statement. This block, in turn,
must be followed by at least one catch handler:
try
{
// any statements here
}
catch(...) // at least one catch clause here
{}
Try-blocks are commonly nested, creating exception levels. For example, main’s code is surrounded
by a try-block, forming an outer level handling exceptions. Within main’s try-block functions are
called which may also contain try-blocks, forming the next exception level. As we have seen (section
10.3.1), exceptions thrown in inner level try-blocks may or may not be processed at that level. By
10.5. CATCHING EXCEPTIONS 233
placing an empty throw statement in an exception handler, the thrown exception is passed on to
the next (outer) level.
10.5 Catching exceptions
A catch clause consists of the keyword catch followed by a parameter list defining one parameter
specifying type and (parameter) name of the exception caught by that particular catch handler.
This name may then be used as a variable in the compound statement following the catch clause.
Example:
catch (string &message)
{
// code to handle the message
}
Primitive types and objects may be thrown as exceptions. It’s a bad idea to throw a pointer or reference
to a local object, but a pointer to a dynamically allocated object may be thrown if the exception
handler deletes the allocated memory to prevent a memory leak. Nevertheless, throwing such a
pointer is dangerous as the exception handler won’t be able to distinguish dynamically allocated
memory from non-dynamically allocated memory, as illustrated by the next example:
try
{
static int x;
int *xp = &x;
if (condition1)
throw xp;
xp = new int(0);
if (condition2)
throw xp;
}
catch (int *ptr)
{
// delete ptr or not?
}
Close attention should be paid to the nature of the parameter of the exception handler, to make
sure that when pointers to dynamically allocated memory are thrown the memory is returned once
the handler has processed the pointer. In general pointers should not be thrown as exceptions. If
dynamically allocated memory must be passed to an exception handler then the pointer should be
wrapped in a smart pointer, like unique_ptr or shared_ptr (cf. sections 18.3 and 18.4).
Multiple catch handlers may follow a try block, each handler defining its own exception type.
The order of the exception handlers is important. When an exception is thrown, the first exception
handler matching the type of the thrown exception is used and remaining exception handlers are
ignored. Eventually at most one exception handler following a try-block is activated. Normally this
is of no concern as each exception has its own unique type.
Example: if exception handlers are defined for char _s and void _s then NTB strings are caught
by the former handler. Note that a char _ can also be considered a void _, but the exception type
234 CHAPTER 10. EXCEPTIONS
matching procedure is smart enough to use the char _ handler with the thrown NTBS. Handlers
should be designed very type specific to catch the correspondingly typed exception. For example,
int-exceptions are not caught by double-catchers, char-exceptions are not caught by int-catchers.
Here is a little example illustrating that the order of the catchers is not important for types not
having any hierarchal relationship to each other (i.e., int is not derived from double; string is
not derived from an NTBS):
#include <iostream>
using namespace std;
int main()
{
while (true)
{
try
{
string s;
cout << "Enter a,c,i,s for ascii-z, char, int, string "
"exception\n";
getline(cin, s);
switch (s[0])
{
case ’a’:
throw "ascii-z";
case ’c’:
throw ’c’;
case ’i’:
throw 12;
case ’s’:
throw string();
}
}
catch (string const &)
{
cout << "string caught\n";
}
catch (char const *)
{
cout << "ASCII-Z string caught\n";
}
catch (double)
{
cout << "isn’t caught at all\n";
}
catch (int)
{
cout << "int caught\n";
}
catch (char)
{
cout << "char caught\n";
}
}
}
10.5. CATCHING EXCEPTIONS 235
Rather than defining specific exception handlers a specific class can be designed whose objects contain
information about the exception. Such an approach was mentioned earlier, in section 10.3.1.
Using this approach, there’s only one handler required, since we know we don’t throw other types of
exceptions:
try
{
// code throws only Exception pointers
}
catch (Exception &ex)
{
ex.handle();
}
When the code of an exception handler has been processed, execution continues beyond the last
exception handler directly following the matching try-block (assuming the handler doesn’t itself
use flow control statements (like return or throw) to break the default flow of execution). The
following cases can be distinguished:
• If no exception was thrown within the try-block no exception handler is activated, and execution
continues from the last statement in the try-block to the first statement beyond the last
catch-block.
• If an exception was thrown within the try-block but neither the current level nor another level
contains an appropriate exception handler, the program’s default exception handler is called,
aborting the program.
• If an exception was thrown from the try-block and an appropriate exception handler is available,
then the code of that exception handler is executed. Following that, the program’s execution
continues at the first statement beyond the last catch-block.
All statements in a try block following an executed throw-statement are ignored. However, objects
that were successfully constructed within the try block before executing the throw statement are
destroyed before any exception handler’s code is executed.
10.5.1 The default catcher
At a certain level of the program only a limited set of handlers may actually be required. Exceptions
whose types belong to that limited set are processed, all other exceptions are passed on to exception
handlers of an outer level try block.
An intermediate type of exception handling may be implemented using the default exception handler,
which must be (due to the hierarchal nature of exception catchers, discussed in section 10.5)
placed beyond all other, more specific exception handlers.
This default exception handler cannot determine the actual type of the thrown exception and cannot
determine the exception’s value but it may execute some statements, and thus do some default
processing. Moreover, the caught exception is not lost, and the default exception handler may use
the empty throw statement (see section 10.3.1) to pass the exception on to an outer level, where it’s
actually processed. Here is an example showing this use of a default exception handler:
#include <iostream>
using namespace std;
236 CHAPTER 10. EXCEPTIONS
int main()
{
try
{
try
{
throw 12.25; // no specific handler for doubles
}
catch (int value)
{
cout << "Inner level: caught int\n";
}
catch (...)
{
cout << "Inner level: generic handling of exceptions\n";
throw;
}
}
catch(double d)
{
cout << "Outer level may use the thrown double: " << d << ’\n’;
}
}
/*
Generated output:
Inner level: generic handling of exceptions
Outer level may use the thrown double: 12.25
*/
The program’s output illustrates that an empty throw statement in a default exception handler
throws the received exception to the next (outer) level of exception catchers, keeping type and value
of the thrown exception.
Thus, basic or generic exception handling can be accomplished at an inner level, while specific handling,
based on the type of the thrown expression, can be provided at an outer level. Additionally,
particularly in multi-threaded programs (cf. chapter 20), thrown exceptions can be transferred between
threads after converting std::exception objects to std::exception_ptr objects. This
proceduce can even be used from inside the default catcher. Refer to section 20.13.1 for further
coverage of the class std::exception_ptr.
10.6 Declaring exception throwers (deprecated)
Functions defined elsewhere may be linked to code that uses these functions. Such functions are
normally declared in header files, either as standalone functions or as class member functions.
Those functions may of course throw exceptions. Declarations of such functions may contain a (now
deprecated, see also section 23.7) function throw list or exception specification list specifying the
types of the exceptions that can be thrown by the function. For example, a function that may throw
‘char _’ and ‘int’ exceptions can be declared as
void exceptionThrower() throw(char *, int);
10.6. DECLARING EXCEPTION THROWERS (DEPRECATED) 237
A function throw list immediately follows the function header (and it also follows a possible const
specifier). Throw lists may be empty. It has the following general form:
throw([type1 [, type2, type3, ...]])
If a function is guaranteed not to throw exceptions an empty function throw list may be used. E.g.,
void noExceptions() throw ();
In all cases, the function header used in the function definition must exactly match the function
header used in the declaration, including a possibly empty function throw list.
A function for which a function throw list is specified may only throw exceptions of the types mentioned
in its throw list. A run-time error occurs if it throws other types of exceptions than those
mentioned in the function throw list. Example: the function charPintThrower shown below clearly
throws a char const _ exception. Since intThrower may throw an int exception, the function
throw list of charPintThrower must also contain int.
#include <iostream>
using namespace std;
void charPintThrower() throw(char const *, int);
class Thrower
{
public:
void intThrower(int) const throw(int);
};
void Thrower::intThrower(int x) const throw(int)
{
if (x)
throw x;
}
void charPintThrower() throw(char const *, int)
{
int x;
cerr << "Enter an int: ";
cin >> x;
Thrower().intThrower(x);
throw "this text is thrown if 0 was entered";
}
void runTimeError() throw(int)
{
throw 12.5;
}
int main()
{
238 CHAPTER 10. EXCEPTIONS
try
{
charPintThrower();
}
catch (char const *message)
{
cerr << "Text exception: " << message << ’\n’;
}
catch (int value)
{
cerr << "Int exception: " << value << ’\n’;
}
try
{
cerr << "Generating a run-time error\n";
runTimeError();
}
catch(...)
{
cerr << "not reached\n";
}
}
A function without a throw list may throw any kind of exception. Without a function throw list the
program’s designer is responsible for providing the correct handlers.
For various reason declaring exception throwers is now deprecated. Declaring exception throwers
does not imply that the compiler checks whether an improper exception is thrown. Rather, the
function will be surrounded by additional code in which the actual exception that is thrown is processed.
Instead of compile time checks one gets run-time overhead, resulting in additional code (and
execution time) thay is added to the function’s code. One could write, e.g.,
void fun() throw (int)
{
// code of this function, throwing exceptions
}
but the function would be compiled to something like the following (cf. section 10.11 for the
use of try immediately following the function’s header and section 10.8 for a description of
bad_exception):
void fun()
try // this code resulting from throw(int)
{
// the function’s code, throwing all kinds of exceptions
}
catch (int) // remaining code resulting from throw(int)
{
throw; // rethrow the exception, so it can be caught by the
// ‘intended’ handler
}
catch (...) // catch any other exception
{
throw bad_exception{};
10.7. IOSTREAMS AND EXCEPTIONS 239
}
Run-time overhead is caused by doubling the number of thrown and caught exceptions. Without a
throw list a thrown int is simply caught by its intended handler; with a throw list the int is first
caught by the ‘safeguarding’ handler added to the function. In there it is rethrown to be caught by
its intended handler next.
10.7 Iostreams and exceptions
The C++ I/O library was used well before exceptions were available in C++. Hence, normally the
classes of the iostream library do not throw exceptions. However, it is possible to modify that behavior
using the ios::exceptions member function. This function has two overloaded versions:
• ios::iostate exceptions():
this member returns the state flags for which the stream will throw exceptions;
• void exceptions(ios::iostate state)
this member causes the stream to throw an exception when state state is observed.
In the I/O library, exceptions are objects of the class ios::failure, derived from
ios::exception. A std::string const &message may be specified when defining a failure
object. Its message may then be retrieved using its virtual char const _what() const member.
Exceptions should be used in exceptional circumstances. Therefore, we think it is questionable
to have stream objects throw exceptions for fairly normal situations like EOF. Using exceptions to
handle input errors might be defensible (e.g., in situations where input errors should not occur and
imply a corrupted file) but often aborting the program with an appropriate error message would
probably be the more appropriate action. As an example consider the following interactive program
using exceptions to catch incorrect input:
#include <iostream>
#include <climits>
using namespace::std;
int main()
{
cin.exceptions(ios::failbit); // throw exception on fail
while (true)
{
try
{
cout << "enter a number: ";
int value;
cin >> value;
cout << "you entered " << value << ’\n’;
}
catch (ios::failure const &problem)
{
cout << problem.what() << ’\n’;
240 CHAPTER 10. EXCEPTIONS
cin.clear();
cin.ignore(INT_MAX, ’\n’); // ignore the faulty line
}
}
}
By default, exceptions raised from within ostream objects are caught by these objects, which set
their ios::badbit as a result. See also the paragraph on this issue in section 14.8.
10.8 Standard Exceptions
All data types may be thrown as exceptions. Several additional exception classes are now defined
by the C++ standard. Before using those additional exception classes the <stdexcept> header file
must be included. All of these standard exceptions are class types by themselves, but also offer all
facilities of the std::exception class and objects of the standard exception classes may also be
considered objects of the std::exception class.
The std::exception class offers the member
char const *what() const;
describing in a short textual message the nature of the exception.
C++ defines the following standard exception classes:
• std::bad_alloc (this requires the <new> header file): thrown when operator new fails;
• std::bad_exception (this requires the header file <exception> header file): thrown when
a function tries to generate another type of exception than declared in its function throw list;
• std::bad_cast (this requires the <typeinfo> header file): thrown in the context of polymorphism
(see section 14.6.1);
• std::bad_typeid (this requires the <typeinfo> header file): also thrown in the context of
polymorphism (see section 14.6.2);
All additional exception classes were derived from std::exception. The constructors of all these
additional classes accept std::string const & arguments summarizing the reason for the exception
(retrieved by the exception::what member). The additionally defined exception classes
are:
• std::domain_error: a (mathematical) domain error is detected;
• std::invalid_argument: the argument of a function has an invalid value;
• std::length_error: thrown when an object would have exceeded its maximum permitted
length;
• std::logic_error: a logic error should be thrown when a problemis detected in the internal
logic of the program. Example: a function like C’s printf is called with more arguments than
there are format specifiers in its format string;
• std::out_of_range: thrown when an argument exceeds its permitted range. Example:
thrown by at members when their arguments exceed the range of admissible index values;
10.9. SYSTEM ERROR, ERROR CODE AND ERROR CATEGORY 241
• std::overflow_error: an overflow error should be thrown when an arithmetic overflow is
detected. Example: dividing a value by a very small value;
• std::range_error: a range error should be thrown when an internal computation results in
a value exceeding a permissible range;
• std::runtime_error: a runtime error should be thrown when a problem is encountered that
can only be detected while the program is being executed. Example: a non-integral is entered
when the program’s input expects an integral value.
• std::underflow_error: an underflow error should be thrown when an arithmetic underflow
is detected. Example: dividing a very small value by a very large value.
10.9 System error, error code and error category
A std::system_error can be thrown when an error occurs that has an associated error code. Such
errors are typically encountered when calling low-level (like operating system) functions.
Before using system_error the <system_error> header file must be included.
A system_error object can be constructed using the standard textual description of the nature of
the encountered error, but in addition accepts an error_code or error_category object (see the next
two sections), further specifying the nature of the error. The error_code and error_category
classes are also declared in the system_error header file.
The header file system_error also defines an enum class errc whose values are equal to and
describe in a less cryptic way the traditional error code values as offered by C macros, e.g.,
enum class errc
{
address_family_not_supported, // EAFNOSUPPORT
address_in_use, // EADDRINUSE
address_not_available, // EADDRNOTAVAIL
already_connected, // EISCONN
argument_list_too_long, // E2BIG
argument_out_of_domain, // EDOM
bad_address, // EFAULT
...
};
In addition to the standard what member, the system_error class also offers a member code
returning a const reference to the exception’s error code. Here is the class’s public interface:
class system_error: public runtime_error
{
public:
system_error(error_code ec, string const &what_arg);
system_error(error_code ec, char const *what_arg);
system_error(error_code ec);
system_error(int ev, error_category const &ecat,
string const &what_arg);
system_error(int ev, error_category const &ecat,
char const *what_arg);
242 CHAPTER 10. EXCEPTIONS
system_error(int ev, error_category const &ecat);
error_code const &code() const noexcept;
char const *what() const noexcept;
}
The NTBS returned by its what member may be formatted by a system_error object like this:
what_arg + ": " + code().message()
Note that, although system_error was derived fromruntime_error, you’ll lose the codemember
when catching a std::exception object. Of course, downcasting is always possible, but that’s a
stopgap. Therefore, if a system_error is thrown, a matching catch(system_error const &)
clause should be provided (for a flexible alternative, see the class FBB::Exception in the author’s
Bobcat library1.)
10.9.1 The class ‘std::error_code’
Objects of the class std:error_code hold error code values, which may be defined by the operating
system or comparable low-level functions.
Before using error_code the <system_error> header file must be included.
The class offers the following constructors, members, and free functions:
Constructors:
• error_code() noexcept:
the default construction initializes the error code with an error value 0 and an error
category set to &system_category();
• error_code(ErrorCodeEnum e) noexcept:
this is a member template (cf. section 22.1.3), defining template <class
ErrorCodeEnum>. It initializes the object with the return value of
make_error_code(e).
The copy constructor is also available.
Members:
• void assign(int val, const error_category& cat):
assigns new values to the current object’s value and category data members;
• error_category const &category() const noexcept:
returns a reference to the object’s error category;
• void clear() noexcept:
after calling this member value is set to 0 and the object’s error category set to
&system_category();
1http://bobcat.sourceforge.net
10.9. SYSTEM ERROR, ERROR CODE AND ERROR CATEGORY 243
• error_condition default_error_condition() const noexcept:
returns category().default_error_condition(value());
• string message() const:
returns category().message(value());
• errorcode& operator=(ErrorCodeEnum e) noexcept:
a member template defining template <class ErrorCodeEnum>. It assigns the
return value of make_error_code(e) to the current object;
• explicit operator bool() const noexcept:
returns value() != 0;
• int value() const noexcept:
returns the object’s error value.
Free functions:
• error_code make_error_code(errc e) noexcept:
returns error_code(static_cast<int>(e), generic_category());
• bool operator<(error_code const &lhs, error_code const &rhs) noexcept:
returns
lhs.category() < rhs.category()
||
lhs.category() == rhs.category() && lhs.value() < rhs.value();
• std::ostream &operator<<(std::ostream & os, error_code const &ec):
inserts the following text into os:
os << ec.category().name() << ’:’ << ec.value().
10.9.2 The class ‘std::error_category’
The class std::error_category serves as a base class for types that identify the source and
encoding of a particular categories of error codes.
Before using error_category the <system_error> header file must be included.
Classes that are derived from error_category should merely support categories of errors in addition
to those that are already available in C++, and the behavior of such derived classes should
not differ from the be behavior of the error_category class itself. Moreover, such derived classes
should not alter errno’s value, or error states provided by other libraries.
The equality of error_category objects is deducted from the equality of their addresses. As
error_category objects are passed by reference, programs using objects of classes derived from
error_category should ensure that only a single object of each such type is actually used: the class
is designed as a Singleton (cf. Singleton Design Pattern (cf. Gamma et al. (1995) Design Patterns,
Addison-Wesley)): looking at the class’s public interface it becomes clear that no error_category
object can immediately be constructed. There is no public constructor. Nor is it possible to copy
244 CHAPTER 10. EXCEPTIONS
an existing error_category object, as the copy constructor and overloaded assignment operators
have been deleted. Derived classes should enforce these singleton characteristics as well. Here is
the error_category’s non-private class interface:
class error_category
{
public:
error_category(error_category const &) = delete;
virtual ~error_category() noexcept;
error_category& operator=(error_category const &) = delete;
virtual char const *name() const noexcept = 0;
virtual string message(int ev) const = 0;
virtual error_condition
default_error_condition(int ev) const noexcept;
virtual bool equivalent(int code,
error_condition const &condition
) const noexcept;
virtual bool equivalent(error_code const &code,
int condition
) const noexcept;
bool operator==(error_category const &rhs) const noexcept;
bool operator!=(error_category const &rhs) const noexcept;
bool operator<(error_category const &rhs) const noexcept;
protected:
error_category() noexcept;
};
error_category const &generic_category() noexcept;
error_category const &system_category() noexcept;
Members:
• char const _name() const noexcept:
must be overridden, and should return a textual name of the error category;
• string message(int ev) const:
must be overridden, and should return a string describing the error condition denoted
by ev;
• error_condition default_error_condition(int ev) const noexcept:
returns error_condition(ev, _this) (An object of type error_condition that
corresponds to ev);
• bool equivalent(int code, error_condition const &condition) const
noexcept:
returns default_error_condition(code) == condition (true if, for the category
of error represented by _this, code is considered equivalent to condition;
otherwise false);
10.10. EXCEPTION GUARANTEES 245
• bool equivalent(error_code const &code, int condition) const noexcept:
returns _this == code.category() && code.value() == condition (true
if, for the category of error represented by _this, code is considered equivalent to
condition; otherwise false);
• bool operator<(error_category const &rhs) const noexcept:
returns less<const error_category_>()(this, &rhs).
Free functions:
• error_category const &generic_category() noexcept:
returns a reference to an object of a type derived from the class error_category.
Since error_category and its derived classes should be singleton classes, calls to
this function must return references to the same object. The returned object’s name
member shall return a pointer to the string "generic";
• error_category const &system_category() noexcept:
returns a reference to an object of a type derived from the class error_category.
Since error_category and its derived classes should be singleton classes, calls to
this function must return references to the same object. The object’s name member
shall return a pointer to the string "system". If the argument ev corresponds to
a POSIX errno value ‘posv’, then the object’s default_error_condition member
should return error-condition(posv, generic_category()). Otherwise,
error_condition(ev, system_category()) shall be returned.
10.10 Exception guarantees
Software should be exception safe: the program should continue to work according to its specifications
in the face of exceptions. It is not always easy to realize exception safety. In this section some
guidelines and terminology is introduced when discussing exception safety.
Since exceptions may be generated from within all C++ functions, exceptions may be generated in
many situations. Not all of these situations are immediately and intuitively recognized as situations
where exceptions can be thrown. Consider the following function and ask yourself at which points
exceptions may be thrown:
void fun()
{
X x;
cout << x;
X *xp = new X(x);
cout << (x + *xp);
delete xp;
}
If it can be assumed that cout as used above does not throw an exception there are at least 13
opportunities for exceptions to be thrown:
• X x: the default constructor could throw an exception (#1)
246 CHAPTER 10. EXCEPTIONS
• cout << x: the overloaded insertion operator could throw an exception (#2), but its rvalue
argument might not be an X but, e.g., an int, and so X::operator int() const could be
called which offers yet another opportunity for an exception (#3).
• _xp = new X(x): the copy constructor may throw an exception (#4) and operator new (#5a)
too. But did you realize that this latter exception might not be thrown from ::new, but from,
e.g., X’s own overload of operator new? (#5b)
• cout << (x + _xp): we might be seduced into thinking that two X objects are added. But
it doesn’t have to be that way. A separate class Y might exist and X may have a conversion
operator operator Y() const, and operator+(Y const &lhs, X const &rhs),
operator+(X const &lhs, Y const &rhs), and operator+(X const &lhs, X const
&rhs) might all exist. So, if the conversion operator exists, then depending on the kind of overload
of operator+ that is defined either the addition’s left-hand side operand (#6), right-hand
side operand (#7), or operator+ itself (#8) may throw an exception. The resulting value may
again be of any type and so the overloaded cout << return-type-of-operator+ operator
may throw an exception (#9). Since operator+ returns a temporary object it is destroyed
shortly after its use. X’s destructor could throw an exception (#10).
• delete xp: whenever operator new is overloaded operator delete should be overloaded
as well and may throw an exception (#11). And of course, X’s destructor might again throw an
exception (#12).
• }: when the function terminates the local x object is destroyed: again an exception could be
thrown (#13).
It is stressed here (and further discussed in section 10.12) that although it is possible for exceptions
to leave destructors this would violate the C++ standard and so it must be prevented in wellbehaving
C++ programs.
How can we expect to create working programs when exceptions might be thrown at this many
situations?
Exceptions may be generated in a great many situations, but serious problems are prevented when
we’re able to provide at least one of the following exception guarantees:
• The basic guarantee: no resources are leaked. In practice this means: all allocated memory is
properly returned when exceptions are thrown.
• The strong guarantee: the program’s state remains unaltered when an exception is thrown (as
an example: the canonical formof the overloaded assignment operator provides this guarantee)
• The nothrow guarantee: this applies to code for which it can be proven that no exception can
be thrown from it.
10.10.1 The basic guarantee
The basic guarantee dictates that functions that fail to complete their assigned tasks must return
all allocated resources, usually memory, before terminating. Since practically all functions and operators
may throw exceptions and since a function may repeatedly allocate resources the blueprint of
a function allocating resources shown below defines a try block to catch all exceptions that might be
thrown. The catch handler’s task is to return all allocated resources and then rethrow the exception.
void allocator(X **xDest, Y **yDest)
{
10.10. EXCEPTION GUARANTEES 247
X *xp = 0; // non-throwing preamble
Y *yp = 0;
try // this part might throw
{
xp = new X[nX]; // alternatively: allocate one object
yp = new Y[nY];
}
catch(...)
{
delete xp;
throw;
}
delete[] *xDest; // non-throwing postamble
*xDest = xp;
delete[] *yDest;
*yDest = yp;
}
In the pre-try code the pointers to receive the addresses returned by the operator new calls are initialized
to 0. Since the catch handlermust be able to return allocatedmemory theymust be available
outside of the try block. If the allocation succeeds the memory pointed to by the destination pointers
is returned and then the pointers are given new values.
Allocation and or initialization might fail. If allocation fails new throws a std::bad_alloc exception
and the catch handler simply deletes 0 pointers which is OK.
If allocation succeeds but the construction of (some) of the objects fails by throwing an exception
then the following is guaranteed to happen:
• The destructors of all successfully allocated objects are called;
• The dynamically allocated memory to contain the objects is returned
Consequently, there is no memory leak when new fails. Inside the above try block new X may fail:
this does not affect the 0-pointers and so the catch handler merely deletes 0 pointers. When new
Y fails xp points to allocated memory and so it must be returned. This happens inside the catch
handler. The final pointer (here: yp) will only be unequal zero when new Y properly completes, so
there’s no need for the catch handler to return the memory pointed at by yp.
10.10.2 The strong guarantee
The strong guarantee dictates that an object’s state should not change in the face of exceptions. This
is realized by performing all operations that might throw on a separate copy of the data. If all this
succeeds then the current object and its (now successfully modified) copy are swapped. An example
of this approach can be observed in the canonical overloaded assignment operator:
Class &operator=(Class const &other)
{
Class tmp(other);
swap(tmp);
return *this;
248 CHAPTER 10. EXCEPTIONS
}
The copy construction might throw an exception, but this keeps the current object’s state intact. If
the copy construction succeeds swap swaps the current object’s contents with tmp’s contents and
returns a reference to the current object. For this to succeed it must be guaranteed that swap won’t
throw an exception. Returning a reference (or a value of a primitive data type) is also guaranteed
not to throw exceptions. The canonical form of the overloaded assignment operator therefore meets
the requirements of the strong guarantee.
Some rules of thumb were formulated that relate to the strong guarantee (cf. Sutter, H., Exceptional
C++, Addison-Wesley, 2000). E.g.,
• All the code that might throw an exception affecting the current state of an object should perform
its tasks separately from the data controlled by the object. Once this code has performed
its tasks without throwing an exception replace the object’s data by the new data.
• Member functions modifying their object’s data should not return original (contained) objects
by value.
The canonical assignment operator is a good example of the first rule of thumb. Another example is
found in classes storing objects. Consider a class PersonDb storing multiple Person objects. Such
a class might offer a member void add(Person const &next). A plain implementation of this
function (merely intended to show the application of the first rule of thumb, but otherwise completely
disregarding efficiency considerations) might be:
void PersonDb::newAppend(Person const &next)
{
Person *tmp = 0;
try
{
tmp = new Person[d_size + 1];
for (size_t idx = 0; idx < d_size; ++idx)
tmp[idx] = d_data[idx];
tmp[d_size] = next;
}
catch (...)
{
delete[] tmp;
throw;
}
}
void PersonDb::add(Person const &next)
{
Person *tmp = newAppend(next);
delete[] d_data;
d_data = tmp;
++d_size;
}
The (private) newAppendmember’s task is to create a copy of the currently allocated Person objects,
including the data of the next Person object. Its catch handler catches any exception that might
be thrown during the allocation or copy process and returns all memory allocated so far, rethrowing
the exception at the end. The function is exception neutral as it propagates all its exceptions to its
10.10. EXCEPTION GUARANTEES 249
caller. The function also doesn’t modify the PersonDb object’s data, so it meets the strong exception
guarantee. Returning from newAppend the member add may now modify its data. Its existing data
are returned and its d_data pointer is made to point to the newly created array of Person objects.
Finally its d_size is incremented. As these three steps don’t throw exceptions add too meets the
strong guarantee.
The second rule of thumb (member functions modifying their object’s data should not return original
(contained) objects by value) may be illustrated using a member PersonDb::erase(size_t idx).
Here is an implementation attempting to return the original d_data[idx] object:
Person PersonData::erase(size_t idx)
{
if (idx >= d_size)
throw string("Array bounds exceeded");
Person ret(d_data[idx]);
Person *tmp = copyAllBut(idx);
delete[] d_data;
d_data = tmp;
--d_size;
return ret;
}
Although copy elision usually prevents the use of the copy constructor when returning ret, this is
not guaranteed to happen. Furthermore, a copy constructormay throw an exception. If that happens
the function has irrevocably mutated the PersonDb’s data, thus losing the strong guarantee.
Rather than returning d_data[idx] by value it might be assigned to an external Person object
before mutating PersonDb’s data:
void PersonData::erase(Person *dest, size_t idx)
{
if (idx >= d_size)
throw string("Array bounds exceeded");
*dest = d_data[idx];
Person *tmp = copyAllBut(idx);
delete[] d_data;
d_data = tmp;
--d_size;
}
This modification works, but changes the original assignment of creating a member returning the
original object. However, both functions suffer from a task overload as they modify PersonDb’s data
and also return an original object. In situations like these the one-function-one-responsibility rule of
thumb should be kept in mind: a function should have a single, well defined responsibility.
The preferred approach is to retrieve PersonDb’s objects using a member like Person
const &at(size_t idx) const and to erase an object using a member like void
PersonData::erase(size_t idx).
10.10.3 The nothrow guarantee
Exception safety can only be realized if some functions and operations are guaranteed not to throw
exceptions. This is called the nothrow guarantee. An example of a function that must offer the
250 CHAPTER 10. EXCEPTIONS
nothrow guarantee is the swap function. Consider once again the canonical overloaded assignment
operator:
Class &operator=(Class const &other)
{
Class tmp(other);
swap(tmp);
return *this;
}
If swap were allowed to throw exceptions then it would most likely leave the current object in a
partially swapped state. As a result the current object’s state would most likely have been changed.
As tmp has been destroyed by the time a catch handler receives the thrown exception it becomes
very difficult (as in: impossible) to retrieve the object’s original state. Losing the strong guarantee
as a consequence.
The swap function must therefore offer the nothrow guarantee. It must have been designed as if
using the following prototype (see also section 23.7):
void Class::swap(Class &other) noexcept;
Likewise, operator delete and operator delete[] offer the nothrow guarantee, and according
to the C++ standard destructors may themselves not throw exceptions (if they do their behavior is
formally undefined, see also section 10.12 below).
Since the C programming language does not define the exception concept functions from the standard
C library offer the nothrow guarantee by implication. This allowed us to define the generic
swap function in section 9.6 using memcpy.
Operations on primitive types offer the nothrow guarantee. Pointers may be reassigned, references
may be returned etc. etc. without having to worry about exceptions that might be thrown.
10.11 Function try blocks
Exceptions may be generated while a constructor is initializing its members. How can exceptions
generated in such situations be caught by the constructor itself, rather than outside the constructor?
The intuitive solution, nesting the object construction in a try block does not solve the problem.
The exception by then has left the constructor and the object we intended to construct isn’t visible
anymore.
Using a nested try block is illustrated in the next example, where main defines an object of class
PersonDb. Assuming that PersonDb’s constructor throws an exception, there is no way we can access
the resources that might have been allocated by PersonDb’s constructor from the catch handler
as the pdb object is out of scope:
int main(int argc, char **argv)
{
try
{
PersonDb pdb(argc, argv); // may throw exceptions
... // main()’s other code
}
10.11. FUNCTION TRY BLOCKS 251
catch(...) // and/or other handlers
{
... // pdb is inaccessible from here
}
}
Although all objects and variables defined inside a try block are inaccessible from its associated
catch handlers, object data members were available before starting the try block and so they may be
accessed froma catch handler. In the following example the catch handler in PersonDb’s constructor
is able to access its d_data member:
PersonDb::PersonDb(int argc, char **argv)
:
d_data(0),
d_size(0)
{
try
{
initialize(argc, argv);
}
catch(...)
{
// d_data, d_size: accessible
}
}
Unfortunately, this does not help us much. The initialize member is unable to reassign d_data
and d_size if PersonDb const pdb was defined; the initialize member should at least offer
the basic exception guarantee and return any resources it has acquired before terminating due to
a thrown exception; and although d_data and d_size offer the nothrow guarantee as they are
of primitive data types a class type data member might throw an exception, possibly resulting in
violation of the basic guarantee.
In the next implementation of PersonDb assume that constructor receives a pointer to an already
allocated block of Person objects. The PersonDb object takes ownership of the allocated memory
and it is therefore responsible for the allocated memory’s eventual destruction. Moreover, d_data
and d_size are also used by a composed object PersonDbSupport, having a constructor expecting
a Person const _ and size_t argument. Our next implementation may then look something like
this:
PersonDb::PersonDb(Person *pData, size_t size)
:
d_data(pData),
d_size(size),
d_support(d_data, d_size)
{
// no further actions
}
This setup allows us to define a PersonDb const &pdb. Unfortunately, PersonDb cannot offer the
basic guarantee. If PersonDbSupport’s constructor throws an exception it isn’t caught although
d_data already points to allocated memory.
The function try block offers a solution for this problem. A function try block consists of a try
block and its associated handlers. The function try block starts immediately after the function
252 CHAPTER 10. EXCEPTIONS
header, and its block defines the function body. With constructors base class and data member
initializers may be placed between the try keyword and the opening curly brace. Here is our final
implementation of PersonDb, now offering the basic guarantee:
PersonDb::PersonDb(Person *pData, size_t size)
try
:
d_data(pData),
d_size(size),
d_support(d_data, d_size)
{}
catch (...)
{
delete[] d_data;
}
Let’s have a look at a stripped-down example. A constructor defines a function try block. The
exception thrown by the Throw object is initially caught by the object itself. Then it is rethrown. The
surrounding Composer’s constructor also defines a function try block, Throw’s rethrown exception
is properly caught by Composer’s exception handler, even though the exception was generated from
within its member initializer list:
#include <iostream>
class Throw
{
public:
Throw(int value)
try
{
throw value;
}
catch(...)
{
std::cout << "Throw’s exception handled locally by Throw()\n";
throw;
}
};
class Composer
{
Throw d_t;
public:
Composer()
try // NOTE: try precedes initializer list
:
d_t(5)
{}
catch(...)
{
std::cout << "Composer() caught exception as well\n";
}
};
10.12. EXCEPTIONS IN CONSTRUCTORS AND DESTRUCTORS 253
int main()
{
Composer c;
}
When running this example, we’re in for a nasty surprise: the program runs and then breaks with
an abort exception. Here is the output it produces, the last two lines being added by the system’s
final catch-all handler, catching all remaining uncaught exceptions:
Throw’s exception handled locally by Throw()
Composer() caught exception as well
terminate called after throwing an instance of ’int’
Abort
The reason for this is documented in the C++ standard: at the end of a catch-handler belonging to a
constructor or destructor function try block, the original exception is automatically rethrown.
The exception is not rethrown if the handler itself throws another exception, offering the constructor
or destructor a way to replace a thrown exception by another one. The exception is only rethrown if
it reaches the end of the catch handler of a constructor or destructor function try block. Exceptions
caught by nested catch handlers are not automatically rethrown.
As only constructors and destructors rethrow exceptions caught by their function try block catch
handlers the run-time error encountered in the above example may simply be repaired by providing
main with its own function try block:
int main()
try
{
Composer c;
}
catch (...)
{}
Now the program runs as planned, producing the following output:
Throw’s exception handled locally by Throw()
Composer() caught exception as well
A final note: if a function defining a function try block also declares an exception throw list then
only the types of rethrown exceptions must match the types mentioned in the throw list.
10.12 Exceptions in constructors and destructors
Object destructors are only activated for completely constructed objects. Although this may sound
like a truism, there is a subtlety here. If the construction of an object fails for some reason, the
object’s destructor is not called when the object goes out of scope. This could happen if an exception
that is generated by the constructor is not caught by the constructor. If the exception is thrown when
the object has already allocated some memory, then that memory is not returned: its destructor isn’t
called as the object’s construction wasn’t successfully completed.
254 CHAPTER 10. EXCEPTIONS
The following example illustrates this situation in its prototypical form. The constructor of the class
Incomplete first displays a message and then throws an exception. Its destructor also displays a
message:
class Incomplete
{
public:
Incomplete()
{
cerr << "Allocated some memory\n";
throw 0;
}
~Incomplete()
{
cerr << "Destroying the allocated memory\n";
}
};
Next, main() creates an Incomplete object inside a try block. Any exception that may be generated
is subsequently caught:
int main()
{
try
{
cerr << "Creating ‘Incomplete’ object\n";
Incomplete();
cerr << "Object constructed\n";
}
catch(...)
{
cerr << "Caught exception\n";
}
}
When this program is run, it produces the following output:
Creating ‘Incomplete’ object
Allocated some memory
Caught exception
Thus, if Incomplete’s constructor would actually have allocated some memory, the program would
suffer from a memory leak. To prevent this from happening, the following counter measures are
available:
• Prevent the exceptions from leaving the constructor.
If part of the constructor’s body may generate exceptions, then this part may be surrounded
by a try block, allowing the exception to be caught by the constructor itself. This approach is
defensible when the constructor is able to repair the cause of the exception and to complete its
construction as a valid object.
• If an exception is generated by a base class constructor or by a member initializing constructor
then a try block within the constructor’s body won’t be able to catch the thrown exception.
10.12. EXCEPTIONS IN CONSTRUCTORS AND DESTRUCTORS 255
This always results in the exception leaving the constructor and the object is not considered to
have been properly constructed. A try block may include the member initializers, and the try
block’s compound statement becomes the constructor’s body as in the following example:
class Incomplete2
{
Composed d_composed;
public:
Incomplete2()
try
:
d_composed(/* arguments */)
{
// body
}
catch (...)
{}
};
An exception thrown by either the member initializers or the body results in the execution
never reaching the body’s closing curly brace. Instead the catch clause is reached. Since the
constructor’s body isn’t properly completed the object is not considered properly constructed
and eventually the object’s destructor won’t be called.
The catch clause of a constructor’s function try block behaves slightly different than a catch clause
of an ordinary function try block. An exception reaching a constructor’s function try block may be
transformed into another exception (which is thrown from the catch clause) but if no exception is
explicitly thrown from the catch clause the exception originally reaching the catch clause is always
rethrown. Consequently, there’s no way to confine an exception thrown from a base class constructor
or from a member initializer to the constructor: such an exception always propagates to a more
shallow block and in that case the object’s construction is always considered incomplete.
Consequently, if incompletely constructed objects throw exceptions then the constructor’s catch
clause is responsible for preventing memory (generally: resource) leaks. There are several ways
to realize this:
• When multiple inheritance is used: if initial base classes have properly been constructed and a
later base class throws, then the initial base class objects are automatically destroyed (as they
are themselves fully constructed objects)
• When composition is used: already constructed composed objects are automatically destroyed
(as they are fully constructed objects)
• Instead of using plain pointers smart pointers (cf. section 18.4) should be used to manage
dynamically allocated memory. In this case, if the constructor throws either before or after the
allocation of the dynamic memory, then allocated memory is properly returned as shared_ptr
objects are, after all, objects.
• If plain pointer data members must be used then the constructor’s body should first, in its
member initialization section, initialize its plain pointer data members. Then, in its body it
can dynamically allocate memory, reassigning the plain pointer datamembers. The constructor
must be provided with a function try block whose generic catch clause deletes the memory
pointed at by the class’s plain pointer data members. Example:
class Incomplete2
256 CHAPTER 10. EXCEPTIONS
{
Composed d_composed;
char *d_cp; // plain pointers
int *d_ip;
public:
Incomplete2(size_t nChars, size_t nInts)
try
:
d_composed(/* arguments */), // might throw
d_cp(0),
d_ip(0)
{
preamble(); // might throw
d_cp = new char[nChars]; // might throw
d_ip = new int[nChars]; // might throw
postamble(); // might throw
}
catch (...)
{
delete[] d_cp; // clean up
delete[] d_ip;
}
};
On the other hand, since C++ supports constructor delegation an object may have been completely
constructed according to the C++ run-time system, but yet its constructor may have thrown an
exception. This happens if a delegated constructor successfully completes (after which the object is
considered ‘completely constructed’), but the constructor itself throws an exception, as illustrated by
the next example:
class Delegate
{
public:
Delegate()
:
Delegate(0)
{
throw 12; // throws but completely constructed
}
Delegate(int x) // completes OK
{}
};
int main()
try
{
Delegate del; // throws
} // del’s destructor is called here
catch (...)
{}
In this example it is the responsibility of Delegate’s designer to ensure that the throwing default
constructor does not invalidate the actions performed by Delegate’s destructor. E.g., if the del10.12.
EXCEPTIONS IN CONSTRUCTORS AND DESTRUCTORS 257
egated constructor allocates memory to be deleted by the destructor, then the default constructor
should either leave the memory as-is, or it can delete the memory and set the corresponding pointer
to zero thereafter. In any case, it is Delegate’s responsibility to ensure that the object remains in a
valid state, even though it throws an exception.
According to the C++ standard exceptions thrown by destructors may not leave their bodies. Providing
a destructor with a function try block is therefore a violation of the standard: exceptions caught
by a function try block’s catch clause have already left the destructor’s body. If –in violation of the
standard– the destructor is provided with a function try block and an exception is caught by the
try block then that exception is rethrown, similar to what happens in catch clauses of constructor
functions’ try blocks.
The consequences of an exception leaving the destructor’s body is not defined, and may result in
unexpected behavior. Consider the following example:
Assume a carpenter builds a cupboard having a single drawer. The cupboard is finished, and a
customer, buying the cupboard, finds that the cupboard can be used as expected. Satisfied with the
cupboard, the customer asks the carpenter to build another cupboard, this time having two drawers.
When the second cupboard is finished, the customer takes it home and is utterly amazed when the
second cupboard completely collapses immediately after it is used for the first time.
Weird story? Then consider the following program:
int main()
{
try
{
cerr << "Creating Cupboard1\n";
Cupboard1();
cerr << "Beyond Cupboard1 object\n";
}
catch (...)
{
cerr << "Cupboard1 behaves as expected\n";
}
try
{
cerr << "Creating Cupboard2\n";
Cupboard2();
cerr << "Beyond Cupboard2 object\n";
}
catch (...)
{
cerr << "Cupboard2 behaves as expected\n";
}
}
When this program is run it produces the following output:
Creating Cupboard1
Drawer 1 used
Cupboard1 behaves as expected
Creating Cupboard2
Drawer 2 used
Drawer 1 used
258 CHAPTER 10. EXCEPTIONS
terminate called after throwing an instance of ’int’
Abort
The final Abort indicates that the program has aborted instead of displaying a message like
Cupboard2 behaves as expected.
Let’s have a look at the three classes involved. The class Drawer has no particular characteristics,
except that its destructor throws an exception:
class Drawer
{
size_t d_nr;
public:
Drawer(size_t nr)
:
d_nr(nr)
{}
~Drawer()
{
cerr << "Drawer " << d_nr << " used\n";
throw 0;
}
};
The class Cupboard1 has no special characteristics at all. It merely has a single composed Drawer
object:
class Cupboard1
{
Drawer left;
public:
Cupboard1()
:
left(1)
{}
};
The class Cupboard2 is constructed comparably, but it has two composed Drawer objects:
class Cupboard2
{
Drawer left;
Drawer right;
public:
Cupboard2()
:
left(1),
right(2)
{}
};
When Cupboard1’s destructor is called Drawer’s destructor is eventually called to destroy its composed
object. This destructor throws an exception, which is caught beyond the program’s first try
block. This behavior is completely as expected.
10.12. EXCEPTIONS IN CONSTRUCTORS AND DESTRUCTORS 259
A subtlety here is that Cupboard1’s destructor (and hence Drawer’s destructor) is activated immediately
subsequent to its construction. Its destructor is called immediately subsequent to its
construction as Cupboard1() defines an anonymous object. As a result the Beyond Cupboard1
object text is never inserted into std::cerr.
Because of Drawer’s destructor throwing an exception a problem occurs when Cupboard2’s destructor
is called. Of its two composed objects, the second Drawer’s destructor is called first. This destructor
throws an exception, which ought to be caught beyond the program’s second try block. However,
although the flow of control by then has left the context of Cupboard2’s destructor, that object hasn’t
completely been destroyed yet as the destructor of its other (left) Drawer still has to be called.
Normally that would not be a big problem: once an exception is thrown from Cupboard2’s destructor
any remaining actions would simply be ignored, albeit that (as both drawers are properly constructed
objects) left’s destructor would still have to be called.
This happens here too and left’s destructor also needs to throw an exception. But as we’ve already
left the context of the second try block, the current flow control is now thoroughly mixed up, and
the program has no other option but to abort. It does so by calling terminate(), which in turn calls
abort(). Here we have our collapsing cupboard having two drawers, even though the cupboard
having one drawer behaves perfectly.
The program aborts since there are multiple composed objects whose destructors throw exceptions
leaving the destructors. In this situation one of the composed objects would throw an exception by
the time the program’s flow control has already left its proper context causing the program to abort.
The C++ standard therefore understandably stipulates that exceptions may never leave destructors.
Here is the skeleton of a destructor whose code might throw exceptions. No function try block but
all the destructor’s actions are encapsulated in a try block nested under the destructor’s body.
Class::~Class()
{
try
{
maybe_throw_exceptions();
}
catch (...)
{}
}
260 CHAPTER 10. EXCEPTIONS