\typeout{Original Yodl file: preamble}
















  
    \makeindex 
























  
    

\typeout{Original Yodl file: abstract}


    
    \documentclass[a4paper,twoside]{report}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\usepackage{newcent}
\usepackage{epsf}
\usepackage{upquote}
\usepackage{cplusplusus}
\usepackage[nottoc]{tocbibind}
\usepackage{etoolbox}

\usepackage[T1]{fontenc}
\usepackage{makecell}
\hfuzz=50pt % don't fuss when less than 50pt

\setlength{\parskip}{3mm} % height between par
\setlength{\parindent}{0mm} % no par indent
\setcounter{secnumdepth}{3}
\pagestyle{empty}
\renewcommand*{\ttdefault}{lmtt}
\appto\ttfamily{\fontsize{10pt}{10pt}\selectfont}

\title{C++ Annotations
            Version 13.04.01}
            
\author{Frank B. Brokken\ \\ 
University of Groningen,\ \\ The Netherlands \ \\ 
        Published at the University of Groningen \ \\ 
        ISBN 90 367 0470 7}
\date{1994-2026}
\begin{document}
            \maketitle\cleardoublepage

\abstract{
    This document is intended for knowledgeable users of \textbf{C} (or any other
language using a \textbf{C}-like grammar, like \textbf{Python}, \textbf{Perl} or \textbf{Java})
who would like to know more about, or make the transition to, \textbf{C++}. This
document is the main textbook for Frank's \textbf{C++} programming courses. Feel
free to contact \texttt{Frank B. Brokken}\footnote{mailto:f.b.brokken@rug.nl} if you're interested in
organizing a local, on-site \textbf{C++} course anywhere in the world.

    The \textbf{C++} Annotations do not cover all aspects of \textbf{C++}, though. In
particular, \textbf{C++}'s basic grammar is not covered when equal to \textbf{C}'s
grammar. Any basic book on \textbf{C} may be consulted to refresh that part of
\textbf{C++}'s grammar.

If you want a \textbf{hard-copy version of the C++ Annotations}: printable versions
are available in zip-archives containing files in postscript, pdf and other
formats at
    \index{https://gitlab.com/fbb-git/cppannotations-zip}
        \begin{center}    \texttt{https://gitlab.com/fbb-git/cppannotations-zip}
        \end{center}
    Pages of files having names starting with \texttt{cplusplus} are in A4 paper
size, pages of files having names starting with \texttt{cplusplusus} are in the US
\emph{legal} paper size. The \textbf{C++} Annotations are also available as a Kindle book.

The latest version of the \textbf{C++} Annotations in html-format can be
browsed at:
        \begin{center}
    \texttt{https://fbb-git.gitlab.io/cppannotations/}

        \end{center}


    }


\pagestyle{plain}
\pagenumbering{roman}
\tableofcontents



\cleardoublepage
\pagestyle{headings}
\pagenumbering{arabic}


\cleardoublepage\chapter{Overview Of The Chapters}\label{Overview}
\typeout{Original Yodl file: overview}The chapters of the \textbf{C++} Annotations cover the following topics:
    \begin{itemize}
    \item Chapter \ref{Overview}: This overview of the chapters.
    \item Chapter \ref{IntroC}: A general introduction to \textbf{C++}.
    \item Chapter \ref{FirstImpression}: A first impression: differences between \textbf{C}
        and \textbf{C++}.
    \item Chapter \ref{NAMESPACE}: Name Spaces: how to avoid name collisions.
    \item Chapter \ref{String}: The `string' data type.
    \item Chapter \ref{IOStreams}: The \textbf{C++} I/O library.
    \item Chapter \ref{Classes}: The `class' concept: structs having functions. The
        `object' concept: variables of a \texttt{class}.
    \item Chapter \ref{StaticDataFun}: Static data and functions: members of a class
        not bound to objects.
    \item Chapter \ref{MEMORY}: Allocation and returning unused memory: \texttt{new},
        \texttt{delete}, and the function \linebreak  \texttt{set\_new\_handler()}.
    \item Chapter \ref{EXCEPTIONS}: Exceptions: handle errors where appropriate, rather
        than where they occur.
    \item Chapter \ref{OVERLOADING}: Give your own meaning to operators.
    \item Chapter \ref{CONTAINERS}: Abstract Containers to put stuff into.
    \item Chapter \ref{INHERITANCE}: Building classes upon classes: setting up class
        hierarchies.
    \item Chapter \ref{POLYMORPHISM}: Changing the behavior of member functions
        accessed through base class pointers.
    \item Chapter \ref{Friends}: Gaining access to private parts: friend functions and
        classes.
    \item Chapter \ref{PointMembers}: Classes having pointers to members: pointing to
        locations inside objects.
    \item Chapter \ref{NESTEDCLASSES}: Constructing classes and enums within classes.
    \item Chapter \ref{STL}: The Standard Template Library.
    \item Chapter \ref{GENERIC}: The STL generic algorithms.
    \item Chapter \ref{THREADING}: Multi Threading.
    \item Chapter \ref{TEMPLATES}: Function templates: using \emph{molds} for type independent
        functions.
    \item Chapter \ref{TEMPCLASS}: Class templates: using \emph{molds} for type independent
        classes.
    \item Chapter \ref{ADVANCEDTEMPL}: Advanced Template Use: programming the compiler.
    \item Chapter \ref{COROUTINES}: Coroutines.
    \item Chapter \ref{CONCRETE}: Several examples of programs written in \textbf{C++}.
    \end{itemize}


\cleardoublepage\chapter{Introduction}\label{IntroC}
\typeout{Original Yodl file: intro}\typeout{Original Yodl file: intro/intro}This document offers an introduction to the \textbf{C++} programming language. It
is a guide for \textbf{C/C++} programming courses, yearly presented by Frank at the
University of Groningen. This document is not a complete \textbf{C/C++} handbook,
as much of the \textbf{C}-background of \textbf{C++} is not covered. Other sources
should be referred to for that (e.g., the
\index{http://publications.gbdirect.co.uk/c\_book/}
 \texttt{on-line book}\footnote{http://publications.gbdirect.co.uk/c\_book/} suggested to
me by George Danchev (danchev at spnet dot net)).

The reader should be forewarned that extensive knowledge of the \textbf{C}
programming language is actually assumed. The \textbf{C++} Annotations continue where
topics of the \textbf{C} programming language end, such as pointers, basic flow
control and the construction of functions.

Some elements of the language, like specific lexical tokens (like
\index{digraphs}\emph{digraphs} (e.g., \texttt{$<$:} for \texttt{{[}}, and \texttt{$>$:} for \texttt{{]}})) are not covered
by the \textbf{C++} Annotations, as these tokens occur extremely seldom in \textbf{C++} source
code. In addition, \index{trigraphs}\emph{trigraphs} (using \texttt{??$<$} for \texttt{\{}, and \texttt{??$>$} for
\texttt{\}}) have been removed from \textbf{C++}.

The working draft of the \textbf{C++} standard is freely available, and can be
cloned from the git-repository at \texttt{https://gitlab.com/cplusplus/draft.git}

The version number of the \textbf{C++} Annotations (currently 13.04.01) is updated when
the content of the document change. The first number is the major number, and
is probably not going to change for some time: it indicates a major
rewriting. The middle number is increased when new information is added to the
document. The last number only indicates small changes; it is increased when,
e.g., series of typos are corrected.

This document is published by the Center of Information Technology,
University of Groningen,
the Netherlands under the \index{http://www.gnu.org/licenses/}
 \texttt{GNU General Public License}\footnote{http://www.gnu.org/licenses/}.

The \textbf{C++ Annotations} were typeset using the \index{Yodl}
    \index{https://fbb-git.gitlab.io/yodl/}
    \texttt{yodl}\footnote{https://fbb-git.gitlab.io/yodl/}
formatting system.

\begin{quote}
    \textbf{
        All correspondence concerning suggestions, additions, improvements or
        changes to this document should be directed to the author:
    }

\textbf{
        \begin{center}Frank B. Brokken \ \\ 
        University of Groningen,\ \\ The Netherlands \ \\ 
        (email: f.b.brokken@rug.nl)
        \end{center}
   }
\end{quote}

In this chapter an overview of \textbf{C++}'s defining features is presented. A few
extensions to \textbf{C} are reviewed and the concepts of object based and object
oriented programming (OOP) are briefly introduced.

\section{What's new in the C++ Annotations}\label{WHATSNEW}
    \typeout{Original Yodl file: whatsnew}This section is modified when the first or second part of the version number
changes (and occasionally also for the third field of the version number). At
a major version upgrade the entries of the previous major version are kept,
and entries referring to older releases are removed.
    \begin{itemize}
    \item  Version 13.04.00: added new sections: the \texttt{std::quoted} manipulator
        (\ref{QUOTED}), and \emph{Intermezzo: hashing and unordered containers}
        (\ref{HASH}). The \texttt{unordered\_set} (\ref{USET}) is now covered before
        covering the \texttt{unordered\_map} (\ref{UMAP}).

\item  Version 13.03.00: 13.03.00 updated description of lambda expression
        syntax; new section 22.1.9: Template parameter initialization.

\item  Version 13.02.00's chapter \emph{Modules} was rewritten, and adds
        a section to chapter \texttt{POLYMORPHISM} about deriving a
        \texttt{std::streambuf} class that can be used by \texttt{std::iostream} objects
        (cf. section \ref{IOSTREAMBUF}).

\item  Version 13.01.00 reorganized section 4.3 (note: changing
        \texttt{\_\_file\_clock} to \texttt{file\_clock}); removed section 12.3 (allocators,
        removed in the \texttt{C++20} standard); included missing examples; and
        repaired typos.

\item  Version 13.0.0 adds a new chapter (\ref{MODULES}) about \textbf{C++}
        \texttt{Modules}, covers the \texttt{\_} \emph{name-independent declaration},
        upgraded the \textbf{C++} standard to \texttt{C++26}, clarified and repaired
        typos in several sections.

\item  Version 12.5.0 adds a subsection about constructors of polymorphic
        classes (cf. section \ref{CONSPOLY}) and adds a section about reading
        and writing devices using the \texttt{std::iostream} class (replaced by
        section \ref{IOSTREAMBUF} in version 13.02.00).
        

\item  Version 12.4.0 adds a section about the \texttt{std::byte} type
        (cf. chapter \ref{FirstImpression}), offers an alternative
        implementation (cf. section \ref{BYTE}), and covers the definition of
        multi-argument index operators (chapter \ref{OVERLOADING}). The
        description of how to implement class constructors that may throw
        exceptions was updated (cf. section \ref{CONSEXCEPTIONS}).

\item  Version 12.3.0 updates and reorganizes the coverage of the generic
        algorithms, fixes many typos and unclarities in the Annotations' text,
        removed superfluous sections since C++20, and adds an overview of
        facilities to handle objects constructed in raw memory.

\item  Version 12.2.0 takes into account that \texttt{std::iterator} is
        deprecated. Section \ref{ITERATORCONS} was rewritten; section
        \ref{OPERATORINDEX} was updated (\texttt{operator{[}{]} const} should return
        \texttt{Type const \&} instead of \texttt{Type} values); added section
        \ref{STRINGVIEW} covering \texttt{std::string\_view}; added section
        \ref{OSYNC} covering synchronization of output to streams in
        multi-threaded programs; added sections \ref{FREEBOUND} and
        \ref{BOUNDCONCEPT} about bound-friends; 'typedef' definitions were
        replaced by 'using' declarations.

\item  Version 12.1.0 adds a description of the \texttt{\_\_file\_clock::to\_sys}
        static member,
         repaired the descriptions
        of \texttt{pop$*$()} members of various abstract containers, and reorganized
        the description of the facilities of the \texttt{filesystem::path} class.

\item  Version 12.0.0 adds a new chapter about coroutines (chapter
        \ref{COROUTINES}) and a new section (\ref{JTHREAD}) to chapter
        \ref{THREADING}.
    \end{itemize}

\section{C++'s history}
    \typeout{Original Yodl file: intro/history}The first implementation of \textbf{C++} was developed in the 1980s at
the AT\&T Bell Labs, where the Unix operating system was created.

\textbf{C++} was originally a `pre-compiler', similar to the preprocessor of \textbf{C},
converting special constructions in its source code to plain \textbf{C}. Back then
this code was compiled by a standard \textbf{C} compiler. The `pre-code', which was
read by the \textbf{C++} pre-compiler, was usually located in a file with the
extension \texttt{.cc}, \texttt{.C} or \texttt{.cpp}. This file would then be converted to a
\textbf{C} source file with the extension \texttt{.c}, which was thereupon compiled and
linked.

The nomenclature of \textbf{C++} source files remains: the extensions \texttt{.cc} and
\texttt{.cpp} are still used. However, the preliminary work of a \textbf{C++}
pre-compiler is nowadays usually performed during the actual compilation
process. Often compilers determine the language used in a source file from its
extension. This holds true for Borland's and Microsoft's \textbf{C++} compilers,
which assume a \textbf{C++} source for an extension \texttt{.cpp}. The \index{GNU}GNU
\index{compiler}compiler \index{g++}\texttt{g++}, which is available on many Unix platforms, assumes for
\textbf{C++} the extension \texttt{.cc}.

The fact that \textbf{C++} used to be compiled into \textbf{C} code is also visible
from the fact that \textbf{C++} is a superset of \textbf{C}: \textbf{C++} offers the full
\textbf{C} grammar and supports all \textbf{C}-library functions, and adds to this
features of its own. This makes the transition from \textbf{C} to
\textbf{C++} quite easy. Programmers familiar with \textbf{C} may start
`programming in \textbf{C++}' by using source files having extensions \texttt{.cc} or
\texttt{.cpp} instead of \texttt{.c}, and may then comfortably slip into all the
possibilities offered by \textbf{C++}. No abrupt change of habits is required.

\subsection{History of the C++ Annotations}
        \typeout{Original Yodl file: intro/annohistory}The original version of the \textbf{C++} Annotations was written by Frank Brokken
and Karel Kubat in Dutch using \texttt{LaTeX}. After some time, Karel rewrote the
text and converted the guide to a more suitable format and (of course) to
English in September 1994.

The first version of the guide appeared on the net in October 1994. By then it
was converted to \texttt{SGML}.

Gradually new chapters were added, and the content was modified and further
improved (thanks to countless readers who sent us their comments).

In major version four Frank added new chapters and converted the document from
SGML to \texttt{yodl}\footnote{https://fbb-git.gitlab.io/yodl/}.
    \begin{quote}
    The \textbf{C++} Annotations are freely distributable. Be sure to read
    the \texttt{legal notes}\footnote{legal.shtml}.

\textbf{Reading the annotations beyond this point implies that you are aware of
    these notes and that you agree with them.}
    \end{quote}
    If you like this document, tell your friends about it. Even better, let us
know by sending email to \texttt{Frank}\footnote{mailto:f.b.brokken@rug.nl}.

\subsection{Compiling a C program using a C++ compiler}\label{CppComp}
        \typeout{Original Yodl file: intro/cascpp}Prospective \textbf{C++} programmers should realize that \textbf{C++} is not a perfect
superset of \textbf{C}. There are some differences you might encounter when you
simply rename a file to a file having the extension \texttt{.cc} and run it through
a \textbf{C++} compiler:
    \begin{itemize}
    \item  In \textbf{C}, \index{sizeof}\texttt{sizeof}\texttt{('c')} equals \texttt{sizeof(int)}, \texttt{'c'} being
any ASCII character.  The underlying philosophy is probably that \texttt{char}s,
when passed as arguments to functions, are passed as integers
anyway. Furthermore, the \textbf{C} compiler handles a character constant like
\texttt{'c'} as an integer constant. Hence, in \textbf{C}, the function calls
        \begin{verbatim}
    putchar(10);
\end{verbatim}
and
        \begin{verbatim}
    putchar('\n');
\end{verbatim}
are synonymous.

By contrast, in \textbf{C++}, \texttt{sizeof('c')} is always 1 (but see also section
\ref{WCHAR}). An \texttt{int} is still an \texttt{int}, though. As we shall see later
(section \ref{FunctionOverloading}), the two function calls
        \begin{verbatim}
    somefunc(10);
\end{verbatim}
and
        \begin{verbatim}
    somefunc('\n');
\end{verbatim}
may be handled by different functions: \textbf{C++} distinguishes functions not
only by their names, but also by their argument types, which are different in
these two calls. The former using an \texttt{int} argument, the latter a \texttt{char}.
    \item  \textbf{C++} requires very strict \index{prototyping}prototyping of external
functions. E.g., in \textbf{C} a prototype like
        \begin{verbatim}
    void func();
\end{verbatim}
means that a function \texttt{func()} exists, returning no value. The
declaration doesn't specify which arguments (if any) are accepted by the
function.

However, in \textbf{C++} the above declaration means that the function \texttt{func()}
does \emph{not} accept any arguments at all. Any arguments passed to it
result in a compile-time error.

Note that the keyword \index{extern}\texttt{extern} is not required when declaring functions. A
function definition becomes a function declaration simply by replacing a
function's body by a semicolon. The keyword \texttt{extern} \emph{is} required,
though, when declaring variables.
    \end{itemize}

\subsection{Compiling a C++ program}\label{COMPILATION}
        \typeout{Original Yodl file: intro/compiling}To compile a \textbf{C++} program, a \textbf{C++} \index{compiler}compiler is required. Considering
the free nature of this document, it won't come as a surprise that a
 \index{free compiler}\emph{free compiler} is suggested here. The
 \index{Free Software Foundation}Free Software Foundation (\index{FSF}FSF) provides at \index{http://www.gnu.org}
 \texttt{http://www.gnu.org} a free \textbf{C++}
compiler which is, among other places, also part of the \index{Debian}Debian
 \index{http://www.debian.org}
 (\texttt{http://www.debian.org}) distribution of \index{Linux}Linux
 (\index{http://www.linux.org} \texttt{http://www.linux.org}).

Always use the latest \textbf{C++} standard supported by your compiler. When the
latest standard isn't used by default, but is already partially implemented it
can usually be selected by specifying the appropriate flag. E.g., to use the
C++26 standard specify the flag \index{-{}-{}std=c++26}\texttt{-}\texttt{-std=c++26}. 

Note: in the \textbf{C++} Annotations it is assumed that the lastest available standard
is specified using the \texttt{+NOTRANS(-\{\}-\{\})std} flag, even if no \texttt{+NOTRANS(-\{\}-\{\})std} flag has been
specified.

\subsubsection{C++ under MS-Windows}
            \typeout{Original Yodl file: intro/mswindows}For \index{MS-Windows}MS-Windows \index{Cygwin}Cygwin \index{http://cygwin.com}
(\texttt{http://cygwin.com}) or \index{MinGW}MinGW \index{http://mingw-w64.org/doku.php}
(\texttt{http://mingw-w64.org/doku.php}) provide the foundation
for installing the \emph{Windows port} of the \index{GNU}GNU \index{g++}\texttt{g++} \index{compiler}compiler
(see also \texttt{https://docs.microsoft.com/en-us/windows/wsl/about}).

The GNU \texttt{g++} compiler's official home page is 
    \index{http://gcc.gnu.org} \texttt{http://gcc.gnu.org}, also containing
information about how to install the compiler in an MS-Windows system.

\subsubsection{Compiling a C++ source text}\label{COMPSRC}
            \typeout{Original Yodl file: intro/compilesources}Generally the following command can be used to compile a \textbf{C++} source file
`\texttt{source.cc}':
        \begin{verbatim}
        g++ source.cc
\end{verbatim}
This produces a binary program (\texttt{a.out} or \texttt{a.exe}). If the default
name is inappropriate, the name of the executable can be specified using the
\texttt{-o} flag (here producing the program \texttt{source}):
        \begin{verbatim}
        g++ -o source source.cc
\end{verbatim}
If a mere compilation is required, the compiled module can be produced using
the \texttt{-c} flag:
        \begin{verbatim}
        g++ -c source.cc
\end{verbatim}
This generates the file \texttt{source.o}, which can later on be linked to
other modules. 

\textbf{C++} programs quickly become too complex to maintain `by hand'. With all
serious programming projects program maintenance tools are used. Usually the
standard \index{make}\texttt{make} program is used to maintain \textbf{C++} programs, but good
alternatives exist, like  the \index{icmake}
        \texttt{icmake}\footnote{https://fbb-git.gitlab.io/icmake/}
    or \index{ccbuild} \texttt{ccbuild}\footnote{https://gitlab.com/bneijt/ccbuild/} program
maintenance utilities.

It is strongly advised to start using maintenance utilities early in the study
of \textbf{C++}.

\section{C++: advantages and claims}\label{Pretensions}
    \typeout{Original Yodl file: intro/advantage}Often it is said that programming in \textbf{C++} leads to `better' programs. Some
of the claimed advantages of \textbf{C++} are:
    \begin{itemize}
    \item  New programs would be developed in less time because old code can be
reused.
    \item  Creating and using new data types would be easier than in \textbf{C}.
    \item  The memory management under \textbf{C++} would be easier and more
transparent.
    \item  Programs would be less bug-prone, as \textbf{C++} uses a stricter syntax
and type checking.
    \item  \index{data hiding}`Data hiding', the usage of data by one program part
while other program parts cannot access the data, would be easier to implement
with \textbf{C++}.
    \end{itemize}
    Which of these allegations are true? Originally, our impression was that
the \textbf{C++} language was somewhat overrated; the same holding true for the
entire object-oriented programming (OOP) approach. The enthusiasm for the
\textbf{C++} language resembles the once uttered allegations about
Artificial-Intelligence (AI) languages like \index{Lisp}Lisp and \index{Prolog}Prolog: these
languages were supposed to solve the most difficult AI-problems `almost
without effort'. New languages are often oversold: in the end, each problem
can be coded in any programming language (say \index{BASIC}BASIC or
    \index{assembly language}assembly language).  The advantages and disadvantages of a given
programming language aren't in `what you can do with them', but rather in
`which tools the language offers to implement an efficient and understandable
solution to a programming problem'. Often these tools take the form of
syntactic \index{restrictions}\emph{restrictions}, enforcing or promoting certain constructions or
simply suggesting intentions by applying or `embracing' such syntactic
forms. Rather than a long list of plain assembly instructions we now use flow
control statements, functions, objects or even (with \textbf{C++}) so-called
\emph{templates} to structure and organize code and to express
oneself `eloquently' in the language of one's choice.

Concerning the above allegations of \textbf{C++}, we support the following, however.
    \begin{itemize}
    \item  The development of new programs while existing code is reused can
also be implemented in \textbf{C} by, e.g., using function libraries.  Functions
can be collected in a library and need not be re-invented with each new
program. \textbf{C++}, however, offers specific syntax possibilities for code
reuse, apart from function libraries (see chapters \ref{INHERITANCE} and
\ref{TEMPLATES}).
    \item  Creating and using new data types is certainly possible in \textbf{C};
e.g., by using \texttt{struct}s, \texttt{typedef}s etc.. From these types other types
can be derived, thus leading to \texttt{struct}s containing \texttt{struct}s and so
on. In \textbf{C++} these facilities are augmented by defining data types which are
completely `self supporting', taking care of, e.g., their memory management
automatically (without having to resort to an independently operating memory
management system as used in, e.g., \textbf{Java}).
    \item  In \textbf{C++} memory management can in principle be either as easy or as
difficult as it is in C.  Especially when dedicated \textbf{C} functions such as
\texttt{xmalloc} and \texttt{xrealloc} are used (allocating the memory or aborting
the program when the memory pool is exhausted). However, with functions like
\texttt{malloc} it is easy to err. Frequently errors in \textbf{C} programs can be
traced back to  miscalculations when using \texttt{malloc}. Instead, \textbf{C++}
offers facilities to allocate memory in a somewhat safer way, using its
\texttt{operator new}.
    \item  Concerning `bug proneness' we can say that \textbf{C++} indeed uses
stricter type checking than \textbf{C}. However, most modern \textbf{C} compilers
implement `warning levels'; it is then the programmer's choice to disregard or
get rid of the warnings. In \textbf{C++} many of such warnings become fatal errors
(the compilation stops).
    \item  As far as `data hiding' is concerned, \textbf{C} does offer some tools.
E.g., where possible, local or \index{static}\texttt{static} variables can be used and special
data types such as \texttt{struct}s can be manipulated by dedicated functions.
Using such techniques, data hiding can be implemented even in \textbf{C}; though it
must be admitted that \textbf{C++} offers special syntactic constructions, making
it far easier to implement `data hiding' (and more in general:
`encapsulation') in \textbf{C++} than in \textbf{C}.
    \end{itemize}
    \textbf{C++} in particular (and OOP in general) is of course not \emph{the}
solution to all programming problems. However, the language \emph{does} offer
various new and elegant facilities which are worth investigating. At the
downside, the level of grammatical complexity of \textbf{C++} has increased
significantly as compared to \textbf{C}. This may be considered a serious drawback
of the language. Although we got used to this increased level of complexity
over time, the transition was neither fast nor painless.

With the \textbf{C++} Annotations we hope to help the reader when transiting from \textbf{C}
to \textbf{C++} by focusing on the additions of \textbf{C++} as compared to \textbf{C} and by
leaving out plain \textbf{C}. It is our hope that you like this document and
may benefit from it.

Enjoy and good luck on your journey into \textbf{C++}!

\section{What is Object-Oriented Programming?}\label{OOP}
    \typeout{Original Yodl file: intro/object}Object-oriented (and object-based) programming propagates a slightly different
approach to programming problems than the strategy usually used in \textbf{C}
programs. In \textbf{C} programming problems are usually solved using a
`\index{procedural approach}procedural approach': a problem is decomposed into subproblems and this
process is repeated until the subtasks can be coded. Thus a conglomerate of
functions is created, communicating through arguments and variables, global or
local (or \texttt{static}).

In contrast (or maybe better: in addition) to this, an object-based approach
identifies the \textbf{keywords} used in a problem statement. These keywords are
then depicted in a diagram where arrows are drawn between those keywords to
depict an internal hierarchy. The keywords become the objects in the
implementation and the hierarchy defines the relationship between these
objects. The term object is used here to describe a limited, well-defined
structure, containing all information about an entity: data types and
functions to manipulate the data. As an example of an
  \index{object oriented approach}object oriented approach, an illustration follows:
    \begin{quote}
    The employees and owner of a car dealer and auto garage company are paid
    as follows. First, mechanics who work in the garage are paid a certain sum
    each month. Second, the owner of the company receives a fixed amount each
    month. Third, there are car salesmen who work in the showroom and receive
    their salary each month plus a bonus per sold car. Finally, the company
    employs second-hand car purchasers who travel around; these employees
    receive their monthly salary, a bonus per bought car, and a restitution of
    their travel expenses.
    \end{quote}
    When representing the above salary administration, the keywords could be
mechanics, owner, salesmen and purchasers. The properties of such units are: a
monthly salary, sometimes a bonus per purchase or sale, and sometimes
restitution of travel expenses. When analyzing the problem in this manner we
arrive at the following representation:
    \begin{itemize}
    \item  The owner and the mechanics can be represented by identical types,
receiving a given salary per month. The relevant information for such a type
would be the monthly amount. In addition this object could contain data as the
name, address and social security number.
    \item  Car salesmen who work in the showroom can be represented as the same
type as above but with some \emph{extra} functionality: the number of
transactions (sales) and the bonus per transaction.

In the hierarchy of objects we would define the dependency between the
first two objects by letting the car salesmen be `derived' from
the owner and mechanics.
    \item  Finally, there are the second-hand car purchasers. These share the
functionality of the salesmen except for travel expenses. The additional
functionality would therefore consist of the expenses made and this type would
be derived from the salesmen.
    \end{itemize}
    The hierarchy of the identified objects are further illustrated in
Figure \ref{objects}.
    \begin{figure}[tbp]
\centerline{\epsffile{intro/objects.eps}}
\caption{\label{objects}Hierarchy of objects in the salary administration.}
\end{figure}

The overall process in the definition of a hierarchy such as the above starts
with the description of the most simple type. Traditionally (and still
encountered with some popular object oriented languages) more complex types
are thereupon derived from the basic type, with each derived type adding some
new functionality. From these derived types, more complex types can again be
derived \emph{ad infinitum}, until a representation of the entire problem can be
made. 

Over the years this approach has become less popular in \textbf{C++} as it
typically results in very tight \index{coupling}\emph{coupling} among those types, which in
turns \emph{reduces} rather than enhances the understanding, maintainability and
testability of complex programs. The term \emph{coupling} refers to the degree of
independence between software components: tight coupling means a strong
dependency, which is frowned upon in \textbf{C++}. In \textbf{C++} object oriented
programs more and more favor small, easy to understand hierarchies, limited
coupling and a developmental process where \index{design pattern}\emph{design
patterns} (cf. \emph{Gamma et al.}  (1995)) play a central role.

In \textbf{C++} \index{class} \emph{classes} are frequently used to define the
characteristics of \emph{objects}. Classes contain the necessary functionality to
do useful things. Classes generally do not offer all their functionality (and
typically \emph{none} of their data) to objects of other classes. As we will see,
classes tend to \emph{hide} their properties in such a way that they are not
directly modifiable by the outside world. Instead, dedicated functions are
used to reach or modify the properties of objects. Thus class-type objects are
able to uphold their own integrity. The core concept here is \emph{encapsulation}
of which \emph{data hiding} is just an example. These concepts are further
elaborated in chapter \ref{Classes}.

\section{Differences between C and C++}
    \typeout{Original Yodl file: intro/differences}In this section some examples of \textbf{C++} code are shown. Some differences
between \textbf{C} and \textbf{C++} are highlighted.

\subsection{The function `main'}
        \typeout{Original Yodl file: intro/main}In \textbf{C++} there are only two variants of the function \index{main}\texttt{main}:
\texttt{int main()} and \texttt{int main(int argc, char $*$$*$argv)}. 

Notes:
    \begin{itemize}
    \item  The return type of \texttt{main} is \texttt{int}, and \emph{not} \texttt{void};
    \item  The function \texttt{main} cannot be overloaded (for other than the
abovementioned signatures);
    \item  It is \emph{not} required to use an explicit \texttt{return} statement at the
end of  \texttt{main}. If omitted \texttt{main} returns 0;
    \item  The value of \texttt{argv{[}argc{]}} equals 0;
    \item  The `third \texttt{char $*$$*$envp} parameter' is not defined by the \textbf{C++}
standard and should be avoided.  Instead, the global variable \index{environ}
\texttt{extern char $*$$*$environ} should be declared providing access to the program's
environment variables. Its final element has the value 0;
    \item  A \textbf{C++} program ends normally when the \texttt{main} function
returns. Using a \emph{function try block} (cf. section \ref{FUNTRY}) for \texttt{main}
is also considered a normal end of a \textbf{C++} program. When a \textbf{C++} ends
normally, destructors (cf. section \ref{DESTRUCTOR}) of globally defined
objects are activated. A function like \textbf{exit}(3) does not normally end
a \textbf{C++} program and using such functions is therefore deprecated.
    \end{itemize}

\subsection{End-of-line comment}
        \typeout{Original Yodl file: intro/eoln}According to the \index{ANSI/ISO}ANSI/ISO definition, `\index{end of line comment}end of line comment' is
implemented in the syntax of \textbf{C++}. This comment starts with \index{//}\texttt{//} and ends
at the end-of-line marker. The standard \textbf{C} comment, delimited by \texttt{/$*$} and
\texttt{$*$/} can still be used in \textbf{C++}:
        \begin{verbatim}
    int main()
    {
        // this is end-of-line comment
        // one comment per line

        /*
            this is standard-C comment, covering
            multiple lines
        */
    }
\end{verbatim}
Despite the example, it is advised \emph{not} to use \textbf{C} type comment
inside the body of \textbf{C++} functions. Sometimes existing code must temporarily
be suppressed, e.g., for testing purposes. In those cases it's very practical
to be able to use standard \textbf{C} comment. If such suppressed code itself
contains such comment, it would result in nested comment-lines, resulting in
compiler errors. Therefore, the \index{rule of thumb}rule of thumb is not to use \textbf{C} type
comment inside the body of \textbf{C++} functions (alternatively, \texttt{\#if 0} until
\texttt{\#endif} pair of preprocessor directives could of course also be used).

\subsection{Strict type checking}
        \typeout{Original Yodl file: intro/type}\textbf{C++} uses very strict \index{type checking}type checking. A prototype must be known for each
function before it is called, and the call must match the prototype.
The program
        \begin{verbatim}
    int main()
    {
        printf("Hello World\n");
    }
\end{verbatim}
often compiles under \textbf{C}, albeit with a warning that \index{printf}\texttt{printf()}
is an unknown function. But \textbf{C++} compilers (should) fail to produce code in
such cases. The error is of course caused by the missing \index{stdio.h}
 \texttt{\#include $<$stdio.h$>$} (which in \textbf{C++} is more commonly included as
 \index{cstdio} \texttt{\#include $<$cstdio$>$} directive).

And while we're at it: as we've seen in \textbf{C++} \index{main}\texttt{main} \emph{always} uses
the \texttt{int} \index{return value}return value. Although it is possible to define \index{main}\texttt{int
main()} without explicitly defining a return statement, within \texttt{main} it is
not possible to use a \texttt{return} statement without an explicit
\texttt{int}-expression.  For example:
        \begin{verbatim}
    int main()
    {
        return;     // won't compile: expects int expression, e.g.
                    // return 1;
    }
\end{verbatim}
Implicit conversions from \texttt{void $*$} to non-void pointers are not
allowed. E.g., the following isn't accepted in \textbf{C++}:
        \begin{verbatim}
    void *none()
    {
        return 0;
    }
    
    int main()
    {
        int *empty = none();
    }
\end{verbatim}
\subsection{Function Overloading}\label{FunctionOverloading}
        \typeout{Original Yodl file: intro/overload}In \textbf{C++} it is possible to define
    \index{functions having identical names}functions having identical names but performing different actions. The
functions must differ in their \index{parameter list} parameter lists (and/or in
their \index{const function attribute} \texttt{const} attribute). An example is given
below:
        \begin{verbatim}
    #include <stdio.h>

    void show(int val)
    {
        printf("Integer: %d\n", val);
    }

    void show(double val)
    {
        printf("Double: %lf\n", val);
    }

    void show(char const *val)
    {
        printf("String: %s\n", val);
    }

    int main()
    {
        show(12);
        show(3.1415);
        show("Hello World!\n");
    }
\end{verbatim}
    In the above program three functions \texttt{show} are defined, only differing
in their parameter lists, expecting an \texttt{int}, \texttt{double} and \texttt{char $*$},
respectively. The functions have identical names. Functions having identical
names but different parameter lists are called \emph{overloaded}. The act of
defining such functions is called `\index{function overloading}function overloading'.

The \textbf{C++} compiler implements function overloading in a rather simple
way. Although the functions share their names (in this example \texttt{show}), the
compiler (and hence the linker) use quite different names. The conversion of a
name in the source file to an internally used name is called
 `\index{name mangling}name mangling'. E.g., the \textbf{C++} compiler might convert the prototype
\texttt{void} \texttt{show} \texttt{(int)} to the internal name \texttt{VshowI}, while an
analogous function having a \texttt{char $*$} argument might be called
\texttt{VshowCP}. The actual names that are used internally depend on the compiler
and are not relevant for the programmer, except where these names show up in
e.g., a listing of the content of a library.

Some additional remarks with respect to  function overloading:
    \begin{itemize}
    \item  Do not use function overloading for functions doing conceptually
different tasks.  In the example above, the functions \texttt{show} are still
somewhat related (they print information to the screen).

However, it is also quite possible to define two functions \texttt{lookup},
one of which would find a name in a list while the other would determine the
video mode. In this case the behavior of those two functions have nothing in
common. It would therefore be more practical to use names which suggest their
actions; say, \texttt{findname} and \texttt{videoMode}.
    \item  \textbf{C++} does not allow identically named functions to differ only in
their return values, as it is always the programmer's choice to either use or
ignore a function's  return value. E.g., the fragment
    \begin{verbatim}
printf("Hello World!\n");
\end{verbatim}
provides no information about the return value of the function
\texttt{printf}. Two functions \texttt{printf} which only differ in their
return types would therefore not be distinguishable to the compiler.
    \item  In chapter \ref{Classes} the notion of \texttt{const} member functions is
introduced (cf. section \ref{ConstFunctions}). Here it is merely mentioned
that classes normally have so-called member functions associated with them
(see, e.g., chapter \ref{String} for an informal introduction to the
concept). Apart from
    \index{member function: overloading}
    overloading member functions using different parameter lists, it
is then also possible to
    \index{overloading: by const attribute}
    overload member functions by their \texttt{const} attributes. In those cases,
classes may have pairs of identically named member functions, having identical
parameter lists. Then, these functions are overloaded by their \texttt{const}
attribute. In such cases only one of these functions must have the \texttt{const}
attribute.
    \end{itemize}

\subsection{Default function arguments}
        \typeout{Original Yodl file: intro/default}In \textbf{C++} it is possible to provide `\index{default arguments}default arguments' when defining a
function. These arguments are supplied by the compiler when they are not
specified by the programmer. For example:
        \begin{verbatim}
    #include <stdio.h>

    void showstring(char *str = "Hello World!\n");

    int main()
    {
        showstring("Here's an explicit argument.\n");

        showstring();           // in fact this says:
                                // showstring("Hello World!\n");
    }
\end{verbatim}
The possibility to omit arguments in situations where default arguments
are defined is just a nice touch: it is the compiler who supplies the lacking
argument unless it is explicitly specified at the call. The code of the
program will neither be shorter nor more efficient when default arguments are
used.

Functions may be defined with more than one default argument:
        \begin{verbatim}
    void two_ints(int a = 1, int b = 4);

    int main()
    {
        two_ints();            // arguments:  1, 4
        two_ints(20);          // arguments: 20, 4
        two_ints(20, 5);       // arguments: 20, 5
    }
\end{verbatim}
When the function \texttt{two\_ints} is called, the compiler supplies one or two
arguments whenever necessary. A statement like \texttt{two\_ints(,6)} is, however,
not allowed: when arguments are omitted they must be on the right-hand side.

Default arguments must be known at \index{compile-time}compile-time since at that moment
arguments are supplied to functions. Therefore, the default arguments must be
mentioned at the function's \emph{declaration}, rather than at its
\emph{implementation}:
        \begin{verbatim}
    // sample header file
    void two_ints(int a = 1, int b = 4);

    // code of function in, say, two.cc
    void two_ints(int a, int b)
    {
        ...
    }
\end{verbatim}
It is an error to supply default arguments in both function definitions and
function declarations. When applicable default arguments should be provided in
function declarations: when the function is used by other sources the compiler
commonly reads the header file rather than the function definition
itself. Consequently the compiler has no way to determine the values of
default arguments if they are provided in the function definition.

\subsection{NULL-pointers vs. 0-pointers and nullptr}
        \typeout{Original Yodl file: intro/null}In \textbf{C++} all zero values are coded as \texttt{0}. In \textbf{C} \index{NULL}\texttt{NULL} is often used
in the context of pointers. This difference is purely stylistic, though one
that is widely adopted. In \textbf{C++} \texttt{NULL} should be avoided (as it is a
\index{macro}macro, and macros can -{}-{}and therefore should-{}-{} easily be avoided in
\textbf{C++}, see also section \ref{GENCONST}). Instead \texttt{0} can almost always be
used.

Almost always, but not always. As \textbf{C++} allows function overloading
(cf. section \ref{FunctionOverloading}) the programmer might be confronted with
an unexpected function selection in the situation shown in section
\ref{FunctionOverloading}:
        \begin{verbatim}
    #include <stdio.h>

    void show(int val)
    {
        printf("Integer: %d\n", val);
    }

    void show(double val)
    {
        printf("Double: %lf\n", val);
    }

    void show(char const *val)
    {
        printf("String: %s\n", val);
    }

    int main()
    {
        show(12);
        show(3.1415);
        show("Hello World!\n");
    }
\end{verbatim}
In this situation a programmer intending to call \texttt{show(char const $*$)} might
call \texttt{show(0)}. But this doesn't work, as 0 is interpreted as \texttt{int} and so
\texttt{show(int)} is called. But calling \texttt{show(NULL)} doesn't work either, as
\textbf{C++} usually defines \index{NULL}\texttt{NULL} as 0, rather than \texttt{((void $*$)0)}. So,
\texttt{show(int)} is called once again. To solve these kinds of problems the new
\textbf{C++} standard introduces the keyword \index{nullptr}\texttt{nullptr} representing the 0
pointer. In the current example the programmer should call \texttt{show(nullptr)}
to avoid the selection of the wrong function. The \texttt{nullptr} value can also
be used to initialize pointer variables. E.g.,
        \begin{verbatim}
    int *ip = nullptr;      // OK
    int value = nullptr;    // error: value is no pointer
\end{verbatim}
\subsection{The `void' parameter list}
        \typeout{Original Yodl file: intro/void}In \textbf{C}, a function prototype with an \index{empty parameter list}empty parameter list, such as
        \begin{verbatim}
    void func();
\end{verbatim}
means that the argument list of the declared function is not prototyped: for
functions using this prototype the compiler does not warn against calling
\texttt{func} with any set of arguments. In \textbf{C} the keyword \index{void}\texttt{void} is used when
it is the explicit intent to declare a function with no arguments at all, as
in:
        \begin{verbatim}
    void func(void);
\end{verbatim}
As \textbf{C++} enforces strict type checking, in \textbf{C++} an empty parameter
list indicates the \emph{total absence} of parameters. The keyword \texttt{void} is
thus omitted.

\subsection{The `\#define \_\_cplusplus'}
        \typeout{Original Yodl file: intro/cplus}Each \textbf{C++} compiler which conforms to the \index{ANSI/ISO}ANSI/ISO standard defines the
symbol \index{\_\_cplusplus}\texttt{\_\_cplusplus}: it is as if each source file were prefixed with the
\index{preprocessor directive}preprocessor directive \index{\#define \_\_cplusplus}\texttt{\#define \_\_cplusplus}.

We shall see examples of the usage of this symbol in the following sections.

\subsection{Using standard C functions}
        \typeout{Original Yodl file: intro/cfunc}Normal \textbf{C} functions, e.g., which are compiled and collected in a run-time
library, can also be used in \textbf{C++} programs. Such functions, however, must be
declared as \textbf{C} functions.

As an example, the following code fragment declares a function \texttt{xmalloc}
as a \textbf{C} function:
        \begin{verbatim}
    extern "C" void *xmalloc(int size);
\end{verbatim}
This declaration is analogous to a declaration in \textbf{C}, except that the
prototype is prefixed with \index{extern "C"}\texttt{extern "C"}.

A slightly different way to declare \textbf{C} functions is the following:
        \begin{verbatim}
    extern "C"
    {
        // C-declarations go in here
    }
\end{verbatim}
It is also possible to place preprocessor directives at the location of
the declarations. E.g., a \textbf{C} header file \texttt{myheader.h} which declares
\textbf{C} functions can be included in a \textbf{C++} source file as follows:
        \begin{verbatim}
    extern "C"
    {
        #include <myheader.h>
    }
\end{verbatim}
Although these two approaches may be used, they are actually seldom
encountered in \textbf{C++} sources. A more frequently used method to declare
external \textbf{C} functions is encountered in the next section.

\subsection{Header files for both C and C++}\label{CHeaders}
        \typeout{Original Yodl file: intro/header}The combination of the predefined symbol \index{\_\_cplusplus}\texttt{\_\_cplusplus} and the
possibility to define \index{extern "C"}\texttt{extern "C"} functions offers the ability to
create header files for both \textbf{C} and \textbf{C++}. Such a header file might,
e.g., declare a group of functions which are to be used in both \textbf{C} and
\textbf{C++} programs.

The setup of such a header file is as follows:
        \begin{verbatim}
    #ifdef __cplusplus
    extern "C"
    {
    #endif

        /* declaration of C-data and functions are inserted here. E.g., */
        void *xmalloc(int size);

    #ifdef __cplusplus
    }
    #endif
\end{verbatim}
Using this setup, a normal \textbf{C} header file is enclosed by \texttt{extern "C"}
\texttt{\{} which occurs near the top of the file and by \texttt{\}}, which occurs near
the bottom of the file. The \index{\#ifdef}\texttt{\#ifdef} directives test for the type of the
compilation: \textbf{C} or \textbf{C++}. The `standard' \textbf{C} header files, such as
\index{stdio.h}\texttt{stdio.h}, are built in this manner and are therefore usable for both \textbf{C}
and \textbf{C++}.

In addition \textbf{C++} headers should support \index{include guard}\emph{include guard}\emph{s}.
In \textbf{C++} it is usually undesirable to include the same header file twice in
the same source file. Such multiple inclusions can easily be avoided by
including an \index{\#ifndef}\texttt{\#ifndef} directive in the header file.  For example:
        \begin{verbatim}
    #ifndef MYHEADER_H_
    #define MYHEADER_H_
        // declarations of the header file is inserted here,
        // using #ifdef __cplusplus etc. directives
    #endif
\end{verbatim}
When this file is initially scanned by the preprocessor, the symbol
\texttt{MYHEADER\_H\_} is not yet defined. The \texttt{\#ifndef} condition succeeds and all
declarations are scanned. In addition, the symbol \texttt{MYHEADER\_H\_} is defined.

When this file is scanned next while compiling the same source file,
the symbol \texttt{MYHEADER\_H\_} has been defined and consequently all information
between the \texttt{\#ifndef} and \texttt{\#endif} directives is skipped by the compiler.

In this context the symbol name \texttt{MYHEADER\_H\_} serves only for
recognition purposes. E.g., the name of the header file can be used for this
purpose, in capitals, with an underscore character instead of a dot.

Apart from all this, the custom has evolved to give \textbf{C} header files the
extension \index{.h}\texttt{.h}, and to give \texttt{C++} header files \emph{no} extension. For
example, the standard \emph{iostreams} \texttt{cin, cout} and \texttt{cerr} are available
after including the header file \index{iostream}\texttt{iostream}, rather
than \index{iostream.h}\texttt{iostream.h}. In the Annotations this convention is used
with the standard \textbf{C++} header files, but not necessarily everywhere else.

There is more to be said about header files. Section \ref{CLASSHEADER} provides
an in-depth discussion of the preferred organization of \textbf{C++} header files.
In addition, starting with the \texttt{C++26} standard \emph{modules} are available
resulting in a somewhat more efficient way of handling declarations than
offered by the traditional header files. 

Currently, the \textbf{C++} Annotations very briefly covers \emph{modules} (cf. section
\ref{MODULES}).

\subsection{Defining local variables}\label{LOCALVARS}
        \typeout{Original Yodl file: intro/local}Although already available in the \textbf{C} programming language,
    \index{local variables}local variables should only be defined once they're needed.  Although
doing so requires a little getting used to, eventually it tends to produce
more readable, maintainable and often more efficient code than defining
variables at the beginning of compound statements. We suggest to apply the
following rules \index{rule of thumb} of thumb when defining local variables:
    \begin{itemize}
    \item  Local variables should be created at `intuitively right' places, such
as in the example below. This does not only entail the \texttt{for}-statement, but
also all situations where a variable is only needed, say, half-way through the
function.
    \item  More in general, variables should be defined in such a way that their
scope is as \emph{limited} and \emph{localized} as possible.  When avoidable local
variables are not defined at the beginning of functions but rather where
they're first used.
    \item  It is considered good practice to \index{global variable: avoid}
    \index{avoid global variables}\emph{avoid global variables}. It is fairly easy to lose track of which
global variable is used for what purpose. In \textbf{C++} global variables are
seldom required, and by localizing variables the risk of using the same
variable for multiple purposes (thereby invalidating the separate purposes of
the variable), can easily be avoided.
    \end{itemize}

If considered appropriate, \index{nested blocks}\emph{nested blocks} can be used to localize
auxiliary variables. However, situations exist where local variables are
considered appropriate inside nested statements. The just mentioned \texttt{for}
statement is of course a case in point, but local variables can also be
defined within the condition clauses of \texttt{if-else} statements, within
selection clauses of \texttt{switch} statements and condition clauses of \texttt{while}
statements. Variables thus defined are available to the full
statement, including its nested statements. For example, consider the
following \texttt{switch} statement:
        \begin{verbatim}
    #include <stdio.h>

    int main()
    {
        switch (int c = getchar())
        {
            case 'a':
            case 'e':
            case 'i':
            case 'o':
            case 'u':
                printf("Saw vowel %c\n", c);
            break;

            case EOF:
                printf("Saw EOF\n");
            break;

            case '0' ... '9':
                printf("Saw number character %c\n", c);
            break;

            default:
                printf("Saw other character, hex value 0x%2x\n", c);
        }
    }
\end{verbatim}
    Note the location of the definition of the character `\texttt{c}': it is
defined in the expression part of the \texttt{switch} statement. This implies
that `\texttt{c}' is available \emph{only} to the \texttt{switch} statement itself,
including its nested (sub)statements, but not outside the scope of the
\texttt{switch}.

The same approach can be used with \texttt{if} and \texttt{while} statements: a
variable that is defined in the condition clause of an \texttt{if} and \texttt{while}
statement is available in their nested statements. There are some caveats,
though:
    \begin{itemize}
    \item  The variable that is defined in the condition clause must be a
variable which is initialized to a numeric or logical value;
    \item  The variable definition cannot be nested (e.g., using parentheses)
within a more complex expression.
    \end{itemize}
    The former point of attention should come as no big surprise: in order to
be able to evaluate the logical condition of an \texttt{if} or \texttt{while} statement,
the value of the variable must be interpretable as either zero (false) or
non-zero (true). Usually this is no problem, but in \textbf{C++} \emph{objects} (like
objects of the type \texttt{std::string} (cf. chapter \ref{String})) are often
returned by functions. Such objects may or may not be interpretable as numeric
values. If not (as is the case with \texttt{std::string} objects), then such
variables can \emph{not} be defined at the condition or expression clauses of
condition- or repetition statements. The following example will therefore
\emph{not} compile:
        \begin{verbatim}
    if (std::string myString = getString())     // assume getString returns
    {                                           // a std::string value
        // process myString
    }
\end{verbatim}
The above example requires additional clarification. Often a variable can
profitably be given local scope, but an extra check is required immediately
following its initialization. The initialization \emph{and} the test cannot
\emph{both} be combined in one expression. Instead \emph{two} nested statements are
required. Consequently, the following example won't compile either:
        \begin{verbatim}
    if ((int c = getchar()) && strchr("aeiou", c))
        printf("Saw a vowel\n");
\end{verbatim}
If such a situation occurs, either use two nested \texttt{if} statements, or
localize the definition of \texttt{int c} using a nested compound statement:
        \begin{verbatim}
    if (int c = getchar())             // nested if-statements
        if (strchr("aeiou", c))
            printf("Saw a vowel\n");

    {                                  // nested compound statement
        int c = getchar();
        if (c && strchr("aeiou", c))
           printf("Saw a vowel\n");
    }
\end{verbatim}
The \textbf{C++26} standard introduced \index{name-independent declarations}\emph{name-independent declarations}. They're
covered in section \ref{INDEP}.

\subsection{The keyword `typedef'}
        \typeout{Original Yodl file: intro/typedef}The keyword \index{typedef}\texttt{typedef} is still used in \textbf{C++}, but is not required
anymore when defining  \index{union}\texttt{union}, \index{struct}\texttt{struct} or \index{enum}\texttt{enum} definitions.
This is illustrated in the following example:
        \begin{verbatim}
    struct SomeStruct
    {
        int     a;
        double  d;
        char    string[80];
    };
\end{verbatim}
When a \texttt{struct, union} or other compound type is defined, the tag of
this type can be used as type name (this is \texttt{SomeStruct} in the above
example):
        \begin{verbatim}
    SomeStruct what;

    what.d = 3.1415;
\end{verbatim}
\subsection{Functions as part of a struct}\label{FunctionInStruct}
        \typeout{Original Yodl file: intro/struct}In \textbf{C++} we may define \index{functions as members of structs}functions as members of structs. Here we
encounter the first concrete example of an object: as previously described
(see section \ref{OOP}), an \index{object}object is a structure containing data while
specialized functions exist to manipulate those data.

A definition of a \texttt{struct Point} is provided by the code fragment below.
In this structure, two \texttt{int} data fields and one function \texttt{draw} are
declared.
        \begin{verbatim}
    struct Point            // definition of a screen-dot
    {
        int x;              // coordinates
        int y;              // x/y
        void draw();        // drawing function
    };
\end{verbatim}
A similar structure could be part of a painting program and could, e.g.,
represent a pixel. With respect to this \texttt{struct} it should be noted that:
    \begin{itemize}
    \item  The function \texttt{draw} mentioned in the \texttt{struct} definition is a
mere \emph{declaration}. The actual code of the function defining the actions
performed by the function is found elsewhere (the concept of functions inside
\texttt{struct}s is further discussed in section \ref{FunctionsInStructs}).
    \item  The size of the \texttt{struct} \texttt{Point} is equal to the size of its
two \texttt{int}s.  A function declared inside the structure does not affect its
size. The compiler implements this behavior by allowing the function
\texttt{draw} to be available only in the context of a \texttt{Point}.
    \end{itemize}
    The \texttt{Point} structure could be used as follows:
        \begin{verbatim}
    Point a;                // two points on
    Point b;                // the screen

    a.x = 0;                // define first dot
    a.y = 10;               // and draw it
    a.draw();

    b = a;                  // copy a to b
    b.y = 20;               // redefine y-coord
    b.draw();               // and draw it
\end{verbatim}
As shown in the above example a function that is part of the structure may
be selected using the dot (.) (the arrow (\texttt{-$>$}) operator is used when
pointers to objects are available). This is therefore identical to the way
data fields of structures are selected.

The idea behind this syntactic construction is that several types may
contain \index{functions having identical names}functions having identical names. E.g., a structure representing a
circle might contain three \texttt{int} values: two values for the coordinates of
the center of the circle and one value for the radius. Analogously to the
\texttt{Point} structure, a \texttt{Circle} may now have a function \texttt{draw} to draw the
circle.

\subsection{Evaluation order of operands}
        \typeout{Original Yodl file: intro/evaluation}    Traditionally, the evaluation order of expressions of operands of binary
operators is, except for the boolean operators \texttt{and} and \texttt{or}, not
defined. C++ changed this for postfix expressions, assignment expressions
(including compound assignments), and shift operators:
    \begin{itemize}
    \item  Expressions using postfix operators (like index operators and member
        selectors) are evaluated from left to right (do not confuse this with
        postfix increment or decrement operators, which cannot be concatenated
        (e.g., \texttt{variable++++} does not compile)).
    \item  Assignment expressions are evaluated from right to left;
    \item  Operands of shift operators are evaluated from left to right.
    \end{itemize}

In the following examples \texttt{first} is evaluated before \texttt{second}, before
\texttt{third}, before \texttt{fourth}, whether they are single variables, parenthesized
expressions, or function calls:
        \begin{verbatim}
    first.second
    fourth += third = second += first
    first << second << third << fourth
    first >> second >> third >> fourth
\end{verbatim}
In addition, when overloading an operator, the function implementing the
overloaded operator is evaluated like the built-in operator it overloads, and
not in the way function calls are generally ordered.


\cleardoublepage\chapter{A First Impression Of C++}\label{FirstImpression}
\typeout{Original Yodl file: first}\typeout{Original Yodl file: first/first}In this chapter \textbf{C++} is further explored. The possibility to
declare functions in \texttt{struct}s is illustrated in various examples; the
concept of a \texttt{class} is introduced; casting is covered in detail; many new
types are introduced and several important notational extensions to \textbf{C} are
discussed.

\section{Notable differences with C}
\typeout{Original Yodl file: first/extensions}Before we continue with the `real' object-approach to programming, we first
introduce some notable differences with the \textbf{C} programming language: not
mere differences between \textbf{C} and \textbf{C++}, but important syntactic constructs
and keywords not found or differently used in \textbf{C}.

\subsection{Using the keyword `const'}\label{ConstRule}
    \typeout{Original Yodl file: first/const}Even though the keyword \index{const}\texttt{const} is part of the \textbf{C} grammar, its use is
more important and much more common and strictly used in \textbf{C++} than it is in
\textbf{C}.

The \texttt{const} keyword is a modifier stating that the value of a variable
or of an argument may not be modified. In the following example the intent is
to  change the value of a variable \texttt{ival}, which fails:
        \begin{verbatim}
    int main()
    {
        int const ival = 3;     // a constant int
                                // initialized to 3

        ival = 4;               // assignment produces
                                // an error message
    }
\end{verbatim}
This example shows how \texttt{ival} may be initialized to a given value in its
definition; attempts to change the value later (in an assignment) are not
permitted.

Variables that are declared \texttt{const} can, in contrast to \textbf{C}, be used to
specify the size of an array, as in the following example:
        \begin{verbatim}
    int const size = 20;
    char buf[size];             // 20 chars big
\end{verbatim}
Another use of the keyword \texttt{const} is seen in the declaration of
pointers, e.g., in pointer-arguments. In the declaration
        \begin{verbatim}
    char const *buf;
\end{verbatim}
\texttt{buf} is a pointer variable pointing to \texttt{char}s. Whatever is pointed
to by \texttt{buf} may not be changed through \texttt{buf}: the \texttt{char}s are declared
as \texttt{const}. The pointer \texttt{buf} itself however may be changed. A statement
like \texttt{$*$buf = 'a';} is therefore not allowed, while \texttt{++buf} is.

In the declaration
        \begin{verbatim}
    char *const buf;
\end{verbatim}
\texttt{buf} itself is a \texttt{const} pointer which may not be changed. Whatever
\texttt{char}s are pointed to by \texttt{buf} may be changed at will.

Finally, the declaration
        \begin{verbatim}
    char const *const buf;
\end{verbatim}
is also possible; here, neither the pointer nor what it points to may be
changed.

The \index{rule of thumb}rule of thumb for the placement of the keyword \texttt{const} is the
following: what's written to the \emph{left} of \texttt{const} may not be changed.

Although simple, this rule of thumb is, unfortunately, not often used. For
example,
    \index{Stroustrup}
    Bjarne Stroustrup states (in
    \index{http://www.stroustrup.com/...}
    \texttt{https://www.stroustrup.com/bs\_faq2.html\#constplacement}):
    \begin{quote}
    \emph{Should I put "const" before or after the type?}

\emph{I put it before, but that's a matter of taste. "const T" and "T const"
were always (both) allowed and equivalent. For example:}
        \begin{verbatim}
    const int a = 1;        // OK
    int const b = 2;        // also OK
\end{verbatim}
\emph{My guess is that using the first version will confuse fewer programmers
(``is more idiomatic'').}
    \end{quote}
    But we've already seen an example where applying this simple `before'
placement rule for the keyword \texttt{const} produces unexpected (i.e., unwanted)
results as we will shortly see (below). Furthermore, the `idiomatic'
before-placement also conflicts with the notion of \index{const functions}\emph{const functions}, which
we will encounter in section \ref{ConstFunctions}. With const functions the
keyword \texttt{const} is also placed behind rather than before the name of the
function.

The definition or declaration (either or not containing \texttt{const}) should
always be read from the variable or function identifier back to the type
identifier:
        \begin{quote}
    ``Buf is a const pointer to const characters''
        \end{quote}
    This rule of thumb is especially useful in cases where confusion may
occur.  In examples of \textbf{C++} code published in other places one often
encounters the reverse: \texttt{const} \emph{preceding} what should not be
altered. That this may result in sloppy code is indicated by our second
example above:
        \begin{verbatim}
    char const *buf;
\end{verbatim}
What must remain constant here? According to the sloppy interpretation,
the pointer cannot be altered (as \texttt{const} precedes the pointer). In fact,
the char values are the constant entities here, as becomes clear when we try
to compile the following program:
        \begin{verbatim}
    int main()
    {
        char const *buf = "hello";

        ++buf;                  // accepted by the compiler
        *buf = 'u';             // rejected by the compiler
    }
\end{verbatim}
Compilation fails on the statement \texttt{$*$buf = 'u';} and \emph{not} on the
statement \texttt{++buf}.

\index{Cline, M.}
    \index{http://www/parashift.com/c++-faq-lite/}
    \index{Marshall Cline}Marshall Cline's
    \texttt{C++ FAQ}\footnote{http://www.parashift.com/c++-faq-lite/const-correctness.html} gives the
same rule (paragraph 18.5) , in a similar context:
    \begin{quote}\emph{
    {[}18.5{]} What's the difference between "const Fred$*$ p", "Fred$*$ const p" and
"const Fred$*$ const p"?}

\emph{You have to read pointer declarations right-to-left.}
    \end{quote}
    Marshall Cline's advice can be improved, though. Here's a recipe that will
effortlessly dissect even the most complex declaration:
    \begin{enumerate}
    \item  start reading at the variable's name
    \item  read as far as possible until you reach the end of the declaration or
an (as yet unmatched) closing parenthesis.
    \item  return to the point where you started reading, and read backwards
until you reach the beginning of the declaration or a matching opening
parenthesis.
    \item  If you reached an opening parenthesis, continue at step 2 beyond the
parenthesis where you previously stopped.
    \end{enumerate}
    Let's apply this recipe to the following (by itself irrelevant) complex
declaration. Little arrows indicate how far we should read at each step and
the direction of the arrow indicates the reading direction:
            \begin{verbatim}
    char const *(* const (*(*ip)())[])[]

                             ip          Start at the variable's name:
                                             'ip' is

                             ip)         Hitting a closing paren: revert
                             -->

                           (*ip)         Find the matching open paren:
                           <-                'a pointer to'

                           (*ip)())      The next unmatched closing par:
                                -->          'a function (not expecting
                                              arguments)'

                         (*(*ip)())      Find the matching open paren:
                         <-                  'returning a pointer to'

                         (*(*ip)())[])   The next closing par:
                                   -->       'an array of'

                (* const (*(*ip)())[])   Find the matching open paren:
                <--------                    'const pointers to'

                (* const (*(*ip)())[])[] Read until the end:
                                      ->     'an array of'

    char const *(* const (*(*ip)())[])[] Read backwards what's left:
    <-----------                             'pointers to const chars'
\end{verbatim}
Collecting all the parts, we get for \texttt{char const $*$($*$ const
($*$($*$ip)()){[}{]}){[}{]}}: \emph{ip is a pointer to a function (not expecting arguments),
returning a pointer to an array of const pointers to an array of pointers to
const chars}. This is what \texttt{ip} represents; the recipe can be used to parse
any declaration you ever encounter.

\subsection{Namespaces}\label{INTRONAME}
    \typeout{Original Yodl file: first/namespaces}\textbf{C++} introduces the notion of a \index{namespace}\emph{namespace}: all symbols are defined
in a larger context, called a \emph{namespace}. Namespaces are used to avoid
    \index{name conflicts}name conflicts that could arise when a programmer would like to define
a function like \texttt{sin} operating on \emph{degrees}, but does not want to lose
the capability of using the standard \texttt{sin} function, operating on
\emph{radians}.

Namespaces are covered extensively in chapter \ref{NAMESPACE}. For now it
should be noted that most compilers require the explicit declaration of a
\index{standard namespace}\emph{standard namespace}: \texttt{std}. So, unless otherwise indicated, it is
stressed that all examples in the Annotations now implicitly use the
    \index{using namespace std}
        \begin{verbatim}
        using namespace std;
\end{verbatim}
declaration. So, if you actually intend to compile examples given in
the \textbf{C++} Annotations, make sure that the sources start with the above \texttt{using}
declaration.

\subsection{The scope resolution operator ::}
    \typeout{Original Yodl file: first/scope}\textbf{C++} introduces several new operators, among which the
\index{scope resolution operator}scope resolution operator (\index{::}\texttt{::}). This operator can be
used in situations where a global variable exists having the same name as a
local variable:
        \begin{verbatim}
    #include <stdio.h>

    double counter = 50;                // global variable

    int main()
    {
        for (int counter = 1;           // this refers to the
             counter != 10;             // local variable
             ++counter)
        {
            printf("%d\n",
                    ::counter           // global variable
                    /                   // divided by
                    counter);           // local variable
        }
    }
\end{verbatim}
In the above program the scope operator is used to address a global
variable instead of the local variable having the same name. In \textbf{C++} the
scope operator is used extensively, but it is seldom used to reach a global
variable shadowed by an identically named local variable. Its main purpose
is encountered in chapter \ref{Classes}.

\subsection{`cout', `cin', and `cerr'}\label{CoutCinCerr}
    \typeout{Original Yodl file: first/cout}Analogous to \textbf{C}, \textbf{C++} defines standard input- and output streams
which are available when a program is executed. The streams are:
    \begin{itemize}
    \item  \index{cout}\texttt{cout}, analogous to \index{stdout}\texttt{stdout},
    \item  \index{cin}\texttt{cin}, analogous to \index{stdin}\texttt{stdin},
    \item  \index{cerr}\texttt{cerr}, analogous to \index{stderr}\texttt{stderr}.
    \end{itemize}
    Syntactically these streams are not used as functions: instead, data are
written to streams or read from them using the operators $<<$, called
the \index{insertion operator}\emph{insertion operator} and $>>$, called the
\index{extraction operator}\emph{extraction operator}.  This is illustrated in the next example:
        \begin{verbatim}
    #include <iostream>

    using namespace std;

    int main()
    {
        int     ival;
        char    sval[30];

        cout << "Enter a number:\n";
        cin >> ival;
        cout << "And now a string:\n";
        cin >> sval;

        cout << "The number is: " << ival << "\n"
                "And the string is: " << sval << '\n';
    }
\end{verbatim}
This program reads a number and a string from the \texttt{cin} stream (usually
the keyboard) and prints these data to \texttt{cout}. With respect to streams,
please note:
    \begin{itemize}
    \item  The standard streams are declared in the header file
        \index{iostream}\texttt{iostream}. In the examples in the
\textbf{C++} Annotations this header file is often not mentioned explicitly. Nonetheless,
it \emph{must} be included (either directly or indirectly) when these streams are
used. Comparable to the use of the \texttt{using namespace std;} clause, the reader
is expected to \texttt{\#include $<$iostream$>$} with all the examples in which the
standard streams are used.
    \item  The streams \texttt{cout}, \texttt{cin} and \texttt{cerr} are variables of so-called
\index{class}\emph{class}-types. Such variables are commonly called \emph{objects}. Classes
are discussed in detail in chapter \ref{Classes} and are used extensively in
\textbf{C++}.
    \item  The stream \texttt{cin} extracts data from a stream and copies the
extracted information to variables (e.g., \texttt{ival} in the above example) using
the extraction operator (two consecutive \texttt{$>$} characters: $>>$). Later in
the Annotations we will describe how operators in \textbf{C++} can perform quite
different actions than what they are defined to do by the language, as is the
case here. Function overloading has already been mentioned.  In \textbf{C++}
\emph{operators} can also have multiple definitions, which is called \emph{operator
overloading}.
    \item  The operators which manipulate \texttt{cin}, \texttt{cout} and \texttt{cerr} (i.e.,
$>>$ and $<<$) also manipulate variables of different types. In the
above example \texttt{cout} $<<$ \texttt{ival} results in the printing of an integer
value, whereas \texttt{cout} $<<$ \texttt{"Enter a number"} results in the printing
of a string. The actions of the operators therefore depend on the types of
supplied variables.
    \item  The \index{extraction operator}\emph{extraction operator} ($>>$) performs a so called
        \index{type safe}\emph{type safe} assignment to a variable by `extracting' its value from
a text stream. Normally, the extraction operator skips all
        \index{whitespace}\emph{whitespace} \index{skipping leading blanks} characters preceding
the values to be extracted.
    \item  Special \index{symbolic constants}symbolic constants are used for special
situations. Normally a line is terminated by inserting \texttt{"\textbackslash{}n"} or
\texttt{'\textbackslash{}n'}. But when inserting the \index{endl}\texttt{endl} symbol the line is terminated
followed by the flushing of the stream's internal buffer. Thus, \texttt{endl} can
usually be avoided in favor of \texttt{'\textbackslash{}n'} resulting in somewhat more efficient
code.
    \end{itemize}
    The stream objects \texttt{cin}, \texttt{cout} and \texttt{cerr} are not part of the
\textbf{C++} grammar proper. The streams are part of the definitions in the header
file \texttt{iostream}. This is comparable to functions like \texttt{printf} that are
not part of the \textbf{C} grammar, but were originally written by people who
considered such functions important and collected them in a run-time library.

A program may still use the old-style functions like \texttt{printf} and \texttt{scanf}
rather than the new-style streams.  The two styles can even be mixed. But
streams offer several clear advantages and in many \textbf{C++} programs have
completely replaced the old-style \textbf{C} functions. Some advantages of using
streams are:
    \begin{itemize}
    \item  Using insertion and extraction operators is
\index{type-safe}\emph{type-safe}.  The format strings which are used with \texttt{printf} and
\texttt{scanf} can define wrong format specifiers for their arguments, for which
the compiler sometimes can't warn. In contrast, argument checking with
\texttt{cin}, \texttt{cout} and \texttt{cerr} is performed by the compiler. Consequently it
isn't possible to err by providing an \texttt{int} argument in places where,
according to the format string, a string argument should appear. With streams
there are no format strings.
    \item  The functions \texttt{printf} and \texttt{scanf} (and other functions using
format strings) in fact implement a \emph{mini-language} which is interpreted at
run-time. In contrast, with streams the \textbf{C++} compiler knows exactly which
in- or output action to perform given the arguments used. No mini-language
here.
    \item  In addition the possibilities of the insertion and extraction
operators may be \emph{extended} allowing objects of classes that didn't exist
when the streams were originally designed to be inserted into or extracted
from streams. Mini languages as used with \texttt{printf} cannot be extended.
    \item  The usage of the left-shift and right-shift operators in the context
of the streams illustrates yet another capability of \textbf{C++}: operator
overloading allowing us to redefine the actions an operator performs in
certain contexts. Coming from \textbf{C} operator overloading requires some getting
used to, but after a short little while these overloaded operators feel rather
comfortable.
    \item  Streams are independent of the media they operate upon. This (at this
point somewhat abstract) notion means that the same code can be used without
\emph{any} modification at all to interface your code to \emph{any} kind of
device. The code using streams can be used when the device is a file on disk;
an Internet connection; a digital camera; a DVD device; a satellite link; and
much more: you name it. Streams allow your code to be decoupled (independent)
of the devices your code is supposed to operate on, which eases maintenance
and allows reuse of the same code in new situations.
    \end{itemize}
    The \emph{iostream library} has a lot more to offer than just \texttt{cin, cout}
and \texttt{cerr}. In chapter \ref{IOStreams} \emph{iostreams} are covered in
greater detail. Even though \index{printf}\texttt{printf} and friends can still be used in
\textbf{C++} programs, streams have practically replaced the old-style \textbf{C}
\texttt{I/O} functions like \texttt{printf}. If you \emph{think} you still need to use
\texttt{printf} and related functions, think again: in that case you've probably
not yet completely grasped the possibilities of stream objects.

\section{Functions as part of structs}\label{FunctionsInStructs}
\typeout{Original Yodl file: first/structs}Earlier we noted that functions can be part of \texttt{struct}s (see
section \ref{FunctionInStruct}).  Such functions are called
    \index{member function}\emph{member functions}.
This section briefly discusses how to define such functions.

The code fragment below shows a \texttt{struct} having data fields for a person's
name and address. A function \texttt{print} is included in the
\texttt{struct}'s definition:
        \begin{verbatim}
    struct Person
    {
        char name[80];
        char address[80];

        void print();
    };
\end{verbatim}
When defining the member function \texttt{print} the structure's name
(\texttt{Person}) and the scope resolution operator (\texttt{::}) are used:
        \begin{verbatim}
    void Person::print()
    {
        cout << "Name:      " << name << "\n"
                "Address:   " << address << '\n';
    }
\end{verbatim}
The implementation of \texttt{Person::print} shows how the fields of the
\texttt{struct} can be accessed without using the structure's type name. Here the
function \texttt{Person::print} prints a variable \texttt{name}. Since \texttt{Person::print}
is itself a part of \texttt{struct} \texttt{person}, the variable \texttt{name} implicitly
refers to the same type.

This \texttt{struct Person} could be used as follows:
        \begin{verbatim}
    Person person;

    strcpy(person.name, "Karel");
    strcpy(person.address, "Marskramerstraat 33");
    person.print();
\end{verbatim}
The advantage of member functions is that the called function
automatically accesses the data fields of the structure for which it was
invoked. In the statement \texttt{person.print()} the object \texttt{person} is the
`substrate': the variables \texttt{name} and \texttt{address} that are used in the code
of \texttt{print} refer to the data stored in the \texttt{person} object.

\subsection{Data hiding: public, private and class}\label{HIDING}
    \typeout{Original Yodl file: first/public}As mentioned before (see section \ref{Pretensions}), \textbf{C++} contains
specialized syntactic possibilities to implement \index{data hiding}data hiding. Data hiding
is the capability of sections of a program to hide its data from other
sections. This results in very clean data definitions. It also allows these
sections to enforce the integrity of their data.

\textbf{C++} has three keywords that are related to data hiding: \index{private}\texttt{private},
\index{protected}\texttt{protected} and \index{public}\texttt{public}. These keywords can be used in the definition of
\texttt{struct}s. The keyword \texttt{public} allows all subsequent fields of a
structure to be accessed by all code; the keyword \texttt{private} only allows code
that is part of the \texttt{struct} itself to access subsequent fields. The keyword
\texttt{protected} is discussed in chapter \ref{INHERITANCE}, and is somewhat
outside of the scope of the current discussion.

In a \texttt{struct} all fields are \texttt{public}, unless explicitly stated otherwise.
Using this knowledge we can expand the \texttt{struct} \texttt{Person}:
        \begin{verbatim}
    struct Person
    {
        private:
            char d_name[80];
            char d_address[80];
        public:
            void setName(char const *n);
            void setAddress(char const *a);
            void print();
            char const *name();
            char const *address();
    };
\end{verbatim}
As the data fields \texttt{d\_name} and \texttt{d\_address} are in a \texttt{private}
section they are only accessible to the member functions which are defined in
the \texttt{struct}: these are the functions \texttt{setName}, \texttt{setAddress} etc.. As
an illustration consider the following code:
        \begin{verbatim}
    Person fbb;

    fbb.setName("Frank");         // OK, setName is public
    strcpy(fbb.d_name, "Knarf");  // error, x.d_name is private
\end{verbatim}
Data integrity is implemented as follows: the actual data of a \texttt{struct}
\texttt{Person} are mentioned in the structure definition. The data are accessed by
the outside world using special functions that are also part of the
definition. These member functions control all traffic between the data fields
and other parts of the program and are therefore also called `interface'
functions.  The thus implemented data hiding is illustrated in
Figure \ref{datahiding}.
        \begin{figure}[tbp]
\centerline{\epsffile{first/datahiding.eps}}
\caption{\label{datahiding}Private data and public interface functions of the class Person.}
\end{figure}
    The members \texttt{setName} and \texttt{setAddress} are declared with \texttt{char const
$*$} parameters. This indicates that the functions will not alter the strings
which are supplied as their arguments.  Analogously, the members \texttt{name}
and \texttt{address} return \texttt{char const $*$}s: the compiler prevents callers of
those members from modifying  the information made accessible through the
return values of those members.

Two examples of member functions of the \texttt{struct} \texttt{Person} are shown
below:
        \begin{verbatim}
    void Person::setName(char const *n)
    {
        strncpy(d_name, n, 79);
        d_name[79] = 0;
    }

    char const *Person::name()
    {
        return d_name;
    }
\end{verbatim}
The power of member functions and of the concept of data hiding results
from the abilities of member functions to perform special tasks, e.g.,
checking the validity of the data. In the above example \texttt{setName} copies
only up to 79 characters from its argument to the data member \texttt{name},
thereby avoiding a \index{buffer overflow}buffer overflow.

Another illustration of the concept of data hiding is the following. As an
alternative to member functions that keep their data in memory a library could
be developed featuring member functions storing data on file. To convert a
program storing \texttt{Person} structures in memory to one that stores the
data on disk no special modifications are required. After recompilation
and linking the program to a new library it is converted from storage
in memory to storage on disk. This example illustrates a broader concept than
data hiding; it illustrates \index{encapsulation}\emph{encapsulation}. Data hiding is a kind of
encapsulation. Encapsulation in general results in reduced coupling of
different sections of a program. This in turn greatly enhances reusability and
maintainability of the resulting software. By having the structure encapsulate
the actual storage medium the program using the structure becomes independent
of the actual storage medium that is used.

Though data hiding can be implemented using \texttt{struct}s, more often (almost
always) \emph{classes} are used instead. A class is a kind of struct, except that
a class uses private access by default, whereas structs use public access by
default. The definition of a \texttt{class} \texttt{Person} is therefore identical to
the one shown above, except that the keyword \texttt{class} has
replaced \texttt{struct} while the initial \texttt{private:} clause can be omitted.  Our
typographic suggestion for class names (and other type names defined by the
programmer) is to start with a capital character to be followed by the
remainder of the type name using lower case letters (e.g., \texttt{Person}).

\subsection{Structs in C vs. structs in C++}
    \typeout{Original Yodl file: first/cvscpp}In this section we'll discuss an important difference between \textbf{C} and
\textbf{C++} structs and (member) functions. In \textbf{C} it is common to define
several functions to process a \texttt{struct}, which then require a pointer to the
\texttt{struct} as one of their arguments. An imaginary \textbf{C} header file showing
this concept is:
        \begin{verbatim}
    /* definition of a struct PERSON    This is C   */
    typedef struct
    {
        char name[80];
        char address[80];
    } PERSON;

    /* some functions to manipulate PERSON structs */

    /* initialize fields with a name and address    */
    void initialize(PERSON *p, char const *nm,
                       char const *adr);

    /* print information    */
    void print(PERSON const *p);

    /* etc..    */
\end{verbatim}
In \textbf{C++}, the declarations of the involved functions are put inside
the definition of the \texttt{struct} or \texttt{class}. The argument denoting
which \texttt{struct} is involved is no longer needed.
        \begin{verbatim}
    class Person
    {
        char d_name[80];
        char d_address[80];

        public:
            void initialize(char const *nm, char const *adr);
            void print();
            // etc..
    };
\end{verbatim}
In \textbf{C++} the \texttt{struct} parameter is not used. A \textbf{C} function call
such as:
        \begin{verbatim}
    PERSON x;

    initialize(&x, "some name", "some address");
\end{verbatim}
becomes in \textbf{C++}:
        \begin{verbatim}
    Person x;

    x.initialize("some name", "some address");
\end{verbatim}
\section{Several additions to C's grammar}

\subsection{References}
    \typeout{Original Yodl file: first/references}In addition to the common ways to define variables (plain variables or
pointers) \textbf{C++} introduces \index{reference}\emph{references} defining synonyms
for variables. A reference to a variable is like an \emph{alias}; the variable
and the reference can both be used in statements involving the variable:
        \begin{verbatim}
    int int_value;
    int &ref = int_value;
\end{verbatim}
In the above example a variable \texttt{int\_value} is defined. Subsequently a
reference \texttt{ref} is defined, which (due to its initialization) refers to the
same memory location as \texttt{int\_value}. In the definition of \texttt{ref}, the
\index{reference operator}reference operator \index{operator\&} \texttt{\&} indicates that \texttt{ref} is not
itself an \texttt{int} but a reference to one. The two statements
        \begin{verbatim}
    ++int_value;
    ++ref;
\end{verbatim}
have the same effect: they increment \texttt{int\_value}'s value.  Whether that
location is called \texttt{int\_value} or \texttt{ref} does not matter.

References serve an important function in \textbf{C++} as a means to pass
modifiable arguments to functions. E.g., in standard \textbf{C}, a function that
increases the value of its argument by five and returning nothing needs a
pointer parameter:
        \begin{verbatim}
    void increase(int *valp)    // expects a pointer
    {                           // to an int
        *valp += 5;
    }

    int main()
    {
        int x;

        increase(&x);           // pass x's address
    }
\end{verbatim}
This construction can \emph{also} be used in \textbf{C++} but the same effect
is also achieved using a reference:
        \begin{verbatim}
    void increase(int &valr)    // expects a reference
    {                           // to an int
        valr += 5;
    }

    int main()
    {
        int x;

        increase(x);            // passed as reference
    }
\end{verbatim}
It is arguable whether code such as the above should be preferred over
\textbf{C}'s method, though. The statement \texttt{increase} \texttt{(x)} suggests that not
\texttt{x} itself but a \emph{copy} is passed. Yet the value of \texttt{x} changes because
of the way \texttt{increase()} is defined. However, references can also be used to
pass objects that are only inspected (without the need for a copy or a const
$*$) or to pass objects whose modification is an accepted side-effect of their
use. In those cases using references are strongly preferred over existing
alternatives like copy by value or passing pointers.

Behind the scenes references are implemented using pointers. So, as far as
the compiler is concerned references in \textbf{C++} are just const pointers.  With
references, however, the programmer does not need to know or to bother about
levels of indirection. An important distinction between plain pointers and
references is of course that with references no indirection takes place. For
example:
        \begin{verbatim}
    extern int *ip;
    extern int &ir;

    ip = 0;     // reassigns ip, now a 0-pointer
    ir = 0;     // ir unchanged, the int variable it refers to
                // is now 0.
\end{verbatim}
In order to prevent confusion, we suggest to adhere to the following:
    \begin{itemize}
    \item  In those situations where a function does not alter its
parameters of a built-in or pointer type, value parameters can be used:
        \begin{verbatim}
void some_func(int val)
{
    cout << val << '\n';
}

int main()
{
    int x;

    some_func(x);       // a copy is passed
}
\end{verbatim}
\item  When a function explicitly must change the values of its arguments, a
pointer parameter is preferred. These pointer parameters should preferably be
the function's initial parameters. This is called \index{return by argument}\emph{return by argument}.
        \begin{verbatim}
void by_pointer(int *valp)
{
    *valp += 5;
}
\end{verbatim}
\item  When a function doesn't change the value of its class- or struct-type
arguments, or if the modification of the argument is a trivial side-effect
(e.g., the argument is a stream) references can be used. Const-references
should be used if the function does not modify the argument:
        \begin{verbatim}
void by_reference(string const &str)
{
    cout << str;    // no modification of str
}

int main ()
{
    int x = 7;
    by_pointer(&x);         // a pointer is passed
                            // x might be changed
    string str("hello");
    by_reference(str);      // str is not altered
}
\end{verbatim}
References play an important role in cases where the argument is not
changed by the function but where it is undesirable to copy the argument to
initialize the parameter. Such a situation occurs when a large object is
passed as argument, or is returned by the function.  In these cases the
copying operation tends to become a significant factor, as the entire
object must be copied. In these cases references are preferred.

If the argument isn't modified by the function, or if the caller shouldn't
modify the returned information, the \texttt{const} keyword should be
used. Consider the following example:
        \begin{verbatim}
struct Person                   // some large structure
{
    char    name[80];
    char    address[90];
    double  salary;
};

Person person[50];          // database of persons

                            // printperson expects a
                            // reference to a structure
                            // but won't change it
void printperson (Person const &subject)
{
    cout << "Name: " << subject.name << '\n' <<
            "Address: " << subject.address << '\n';

}
                            // get a person by index value
Person const &personIdx(int index)
{
    return person[index];   // a reference is returned,
}                           // not a copy of person[index]

int main()
{
    Person boss;

    printperson(boss);      // no pointer is passed,
                            // so `boss' won't be
                            // altered by the function
    printperson(personIdx(5));
                            // references, not copies
                            // are passed here
}
\end{verbatim}
\item  Furthermore, note that there is yet another reason for using
references when passing objects as function arguments. When passing a
reference to an object, the activation of a so called \emph{copy constructor}
is avoided. Copy constructors are covered in chapter \ref{MEMORY}.
    \end{itemize}

References \emph{could} result in extremely `ugly' code. A function may
return a reference to a variable, as in the following example:
        \begin{verbatim}
    int &func()
    {
        static int value;
        return value;
    }
\end{verbatim}
This allows the use of the following constructions:
        \begin{verbatim}
    func() = 20;
    func() += func();
\end{verbatim}
It is probably superfluous to note that such constructions should normally
not be used. Nonetheless, there are situations where it is useful to return a
reference.  We have actually already seen an example of this phenomenon in our
previous discussion of streams. In a statement like \texttt{cout} $<<$
\texttt{"Hello"} $<<$ \texttt{'\textbackslash{}n';} the insertion operator returns a reference to
\texttt{cout}. So, in this statement first the \texttt{"Hello"} is inserted into
\texttt{cout}, producing a reference to \texttt{cout}. Through this reference the
\texttt{'\textbackslash{}n'} is then inserted in the \texttt{cout} object, again producing a reference
to \texttt{cout}, which is then ignored.

Several differences between pointers and references are pointed out in the
next list below:
    \begin{itemize}
    \item  A reference cannot exist by itself, i.e., without something to
refer to. A declaration of a reference like
        \begin{center}\texttt{int \&ref;}\end{center}
    is not allowed; what would \texttt{ref} refer to?
    \item  References can be declared as \texttt{external}.  These references were
initialized elsewhere.
    \item  References may exist as parameters of functions: they are initialized
when the function is called.
    \item  References may be used in the return types of functions. In those
cases the function determines what the return value refers to.
    \item  References may be used as data members of classes. We return
to this usage later.
    \item  Pointers are variables by themselves. They point at
something concrete or just ``at nothing''.
    \item  References are aliases for other variables and cannot be re-aliased
to another variable. Once a reference is defined, it refers to its particular
variable.
    \item  Pointers (except for const pointers) can be reassigned to point to
different variables.
    \item  When an \index{address-of operator}address-of operator \index{operator\&} \index{\&}\texttt{\&} is used with a
reference, the expression yields the address of the variable to which the
reference applies. In contrast, ordinary pointers are variables themselves, so
the address of a pointer variable has nothing to do with the address of the
variable pointed to.
    \end{itemize}

\subsection{Rvalue References}\label{RREF}
    \typeout{Original Yodl file: first/rvalueref}In \textbf{C++}, temporary (rvalue) values are indistinguishable from \texttt{const \&}
types. \textbf{C++} introduces a new reference type called an
    \index{rvalue reference}\emph{rvalue reference}, which is defined as \index{typename \&\&}\texttt{typename \&\&}.

The name \emph{rvalue} reference is derived from assignment statements, where the
variable to the left of the assignment operator is called an \index{lvalue}\emph{lvalue} and
the expression to the right of the assignment operator is called an
\index{rvalue}\emph{rvalue}. Rvalues are often temporary, anonymous values, like values
returned by functions.

In this parlance the \textbf{C++} reference should be considered an
 \index{lvalue reference}\emph{lvalue reference} (using the notation \texttt{typename \&}). They can be
contrasted to \emph{rvalue references} (using the notation \texttt{typename \&\&}).

The key to understanding rvalue references is the concept of an
 \index{anonymous variable}\emph{anonymous variable}. An anonymous variable has no name and this is the
distinguishing feature for the compiler to associate it automatically with an
rvalue reference if it has a choice. Before introducing some interesting
constructions let's first have a look at some standard situations where
\emph{lvalue} references are used. The following function returns a temporary
(anonymous) value:
        \begin{verbatim}
    int intVal()
    {
        return 5;
    }
\end{verbatim}
Although \texttt{intVal}'s return value  can be assigned to an \texttt{int}
variable it requires copying, which might become prohibitive when
a function does not return an \texttt{int} but instead some large object. A
\emph{reference} or \emph{pointer} cannot be used either to collect the anonymous
return value as the return value won't survive beyond that. So the following
is illegal (as noted by the compiler):
        \begin{verbatim}
    int &ir = intVal();         // fails: refers to a temporary
    int const &ic = intVal();   // OK: immutable temporary
    int *ip = &intVal();        // fails: no lvalue available
\end{verbatim}
Apparently it is not possible to modify the temporary returned by
\texttt{intVal}. But now consider these functions:
        \begin{verbatim}
    void receive(int &value)            // note: lvalue reference
    {
        cout << "int value parameter\n";
    }
    void receive(int &&value)           // note: rvalue reference
    {
        cout << "int R-value parameter\n";
    }
\end{verbatim}
and let's call this function from \texttt{main}:
        \begin{verbatim}
    int main()
    {
        receive(18);
        int value = 5;
        receive(value);
        receive(intVal());
    }
\end{verbatim}
This program produces the following output:
        \begin{verbatim}
    int R-value parameter
    int value parameter
    int R-value parameter
\end{verbatim}
The program's output shows the compiler selecting \texttt{receive(int \&\&value)}
in all cases where it receives an anonymous \texttt{int} as its argument. Note that
this includes \texttt{receive(18)}: a value 18 has no name and thus \texttt{receive(int
\&\&value)} is called. Internally, it actually uses a temporary variable to
store the 18, as is shown by the following example which modifies \texttt{receive}:
        \begin{verbatim}
    void receive(int &&value)
    {
        ++value;
        cout << "int R-value parameter, now: " << value << '\n';
            // displays 19 and 6, respectively.
    }
\end{verbatim}
Contrasting \texttt{receive(int \&value)} with \texttt{receive(int \&\&value)} has
nothing to do with \texttt{int \&value} not being a const reference. If
\texttt{receive(int const \&value)} is used the same results are obtained. Bottom
line: the compiler selects the overloaded function using the rvalue reference
if the function is passed an anonymous value.

The compiler runs into problems if \texttt{void receive(int \&value)} is
replaced by \texttt{void receive(int value)}, though. When confronted with the
choice between a value parameter and a reference parameter (either lvalue or
rvalue) it cannot make a decision and reports an ambiguity. In practical
contexts this is not a problem. Rvalue references were added to the language in
order to be able to distinguish the two forms of references: named values
(for which lvalue references are used) and anonymous values (for which
rvalue references are used).

It is this distinction that allows the implementation of
 \index{move semantics}\emph{move semantics} and \index{perfect forwarding}\emph{perfect forwarding}. At this point the concept of
\index{move semantics}\emph{move semantics} cannot yet fully be discussed (but see section \ref{MOVE}
for a more thorough discussion) but it is very well possible to illustrate
the underlying ideas.

Consider the situation where a function returns a \texttt{struct Data} containing a
pointer to a dynamically allocated NTBS. We agree that \texttt{Data} objects
are only used after initialization, for which two \texttt{init} functions
are available. As an aside: when \texttt{Data} objects are no longer required the
memory pointed at by \texttt{text} must again be returned to the operating
system; assume that that task is properly performed.
        \begin{verbatim}
    struct Data
    {
        char *text;

        void init(char const *txt);     // initialize text from txt

        void init(Data const &other)
        {
            text = strdup(other.text);
        }
    };
\end{verbatim}
There's also this interesting function:
        \begin{verbatim}
    Data dataFactory(char const *text);
\end{verbatim}
Its implementation is irrelevant, but it returns a (temporary) \texttt{Data}
object initialized with \texttt{text}. Such temporary objects cease to exist once
the statement in which they are created end.

Now we'll use \texttt{Data}:
        \begin{verbatim}
    int main()
    {
        Data d1;
        d1.init(dataFactory("object"));
    }
\end{verbatim}
Here the \texttt{init} function duplicates the NTBS stored in the temporary
object. Immediately thereafter the temporary object ceases to exist. If you
think about it, then you realize that that's a bit over the top:
    \begin{itemize}
    \item  the \texttt{dataFactory} function uses \texttt{init} to initialize the \texttt{text}
        variable of its temporary \texttt{Data} object. For that it uses
        \texttt{strdup}; 
    \item  the \texttt{d1.init} function then \emph{also} uses \texttt{strdup} to initialize
        \texttt{d1.text}; 
    \item  the statement ends, and the temporary object ceases to exist.
    \end{itemize}
    That's two \texttt{strdup} calls, but the temporary \texttt{Data} object thereafter
is never used again.

To handle cases like these \emph{rvalue reference} were introduced. We add
the following function to the \texttt{struct Data}:
        \begin{verbatim}
    void init(Data &&tmp)
    {
        text = tmp.text;      // (1)
        tmp.text = 0;         // (2)
    }
\end{verbatim}
Now, when the compiler translates \texttt{d1.init(dataFactory("object"))} it
notices that \texttt{dataFactory} returns a (temporary) object, and because of that
it uses the \texttt{init(Data \&\&tmp)} function. As we know that the \texttt{tmp} object
ceases to exist after executing the statement in which it is used, the \texttt{d1}
object (at (1)) \emph{grabs} the temporary object's \texttt{text} value, and then (at
(2)) assigns 0 to \texttt{other.text} so that the temporary object's \texttt{free(text)}
action does no harm.

Thus, \texttt{struct Data} suddenly has become \index{move-aware}\emph{move-aware} and implements
\emph{move semantics}, removing the (extra copy) drawback of the previous
approach, and instead of making an extra copy of the temporary object's NTBS
the pointer value is simply transferred to its new owner.

\subsection{Lvalues, rvalues and more}
    \typeout{Original Yodl file: first/lvalues}Although this section contains forward references to chapters \ref{String},
\ref{Classes}, and \ref{PointMembers}, its topic best fits the current
chapter. This section can be skipped without loss of continuity, and you might
consider returning to it once you're familiar with the content of these
future chapters.

Historically, the \textbf{C} programming language distinguished between \emph{lvalues}
and \emph{rvalues}. The terminology was based on assignment expressions, where
the expression to the left of the assignment operator receives a value (e.g.,
it referred to a location in memory where a value could be written into, like
a variable), while the expression to the right of the assignment operator only
had to represent a value (it could be a temporary variable, a constant value
or the value stored in a variable):
        \begin{verbatim}
    lvalue = rvalue;
\end{verbatim}
\textbf{C++} adds to this basic distinction several new ways of referring to
expressions: 
    \begin{itemize}
    \item \texttt{lvalue}: an \index{lvalue}\emph{lvalue} in \textbf{C++} has the same meaning as in
        \textbf{C}. It refers to a location where a value can be stored, like a
        variable, a reference to a variable, or a dereferenced pointer.
    \item \texttt{xvalue}: an \index{xvalue}\emph{xvalue} indicates an \index{expiring value}\emph{expiring value}. An expiring
        value refers to an \emph{object} (cf. chapter \ref{Classes}) just before
        its lifetime ends. Such objects normally have to make sure that
        resources they own (like dynamically allocated memory) also cease to
        exist, but such resources may, just before the object's lifetime ends,
        be moved to another location, thus preventing their destruction.
    \item \texttt{glvalue}: a \index{glvalue}\emph{glvalue} is a \index{generalized lvalue}\emph{generalized lvalue}. A generalized
        lvalue refers to anything that may receive a value. It is either an
        lvalue or an xvalue.
    \item \texttt{prvalue}: a \index{prvalue}\emph{prvalue} is a \index{pure rvalue}\emph{pure rvalue}: a literal value (like
        \texttt{1.2e3}) or an immutable object (e.g., the value returned from a
        function returning a constant \texttt{std::string} (cf. chapter
        \ref{String})).
    \end{itemize}

An expression's value is an xvalue if it is:
    \begin{itemize}
    \item  the value returned by a function returning an rvalue reference to an
            object;
    \item  an object that is cast to an rvalue reference;
    \item  an expression accessing a non-static class data member whose object
            is 
        \begin{itemize}
        \item  an xvalue, or
        \item  a \texttt{.$*$} (pointer-to-member) expression (cf. chapter
            \ref{PointMembers}) in which the left-hand side operand is an
            xvalue and the right-hand side operand is a pointer to a data
            member.
        \end{itemize}
        The effect of this rule is that named rvalue references are treated as
            lvalues and anonymous rvalue references to objects are treated as
            xvalues.\ \\ 
        Rvalue references to functions are treated as lvalues whether
            anonymous or not.
    \end{itemize}

Here is a small example. Consider this simple struct:
        \begin{verbatim}
    struct Demo 
    {
        int d_value;
    };
\end{verbatim}
In addition we have these function declarations and definitions:
    \begin{verbatim}
    Demo &&operator+(Demo const &lhs, Demo const &rhs);
    Demo &&factory();

    Demo demo;
    Demo &&rref = static_cast<Demo &&>(demo);
\end{verbatim}
Expressions like
        \begin{verbatim}
    factory();
    factory().d_value;
    static_cast<Demo &&>(demo);
    demo + demo
\end{verbatim}
are xvalues. However, the expression
        \begin{verbatim}
    rref;
\end{verbatim}
is an lvalue.

In many situations it's not particularly important to know what kind of lvalue
or what kind of rvalue is actually used. In the \textbf{C++} Annotations the term
\index{lhs}\emph{lhs} (\index{left hand side}left hand side) is frequently used to indicate an operand that's
written to the left of a binary operator, while the term \index{rhs}\emph{rhs} 
    (\index{right hand side}right hand side) is frequently used to indicate an operand that's
written to the right of a binary operator. Lhs and rhs operands could actually
be gvalues (e.g., when representing ordinary variables), but they could also
be prvalues (e.g., numeric values added together using the addition
operator). Whether or not lhs and rhs operands are gvalues or lvalues can
always be determined from the context in which they are used.

\subsection{Strongly typed enumerations}
    \typeout{Original Yodl file: first/stronglytyped}Enumeration values in \textbf{C++} are in fact \texttt{int} values, thereby bypassing
type safety. E.g., values of different enumeration types may  be
compared for (in)equality, albeit through a (static) type cast.

Another problem with the current \texttt{enum} type is that their values are not
restricted to the enum type name itself, but to the scope where the
enumeration is defined. As a consequence, two enumerations having the same
scope cannot have identical names.

Such problems are solved by defining
    \emph{enum classes}. An \index{enum class}\emph{enum class} can be defined as in the following
example:
        \begin{verbatim}
    enum class SafeEnum
    {
        NOT_OK,     // 0, by implication
        OK          = 10,
        MAYBE_OK    // 11, by implication
    };
\end{verbatim}
Enum classes use \texttt{int} values by default, but the used value type can
easily be changed using the \texttt{: type} notation, as in:
        \begin{verbatim}
    enum class CharEnum: unsigned char
    {
        NOT_OK,
        OK
    };
\end{verbatim}
To use a value defined in an enum class its enumeration name must be
provided as well. E.g., \texttt{OK} is not defined, \texttt{CharEnum::OK} is.

Using the data type specification (noting that it defaults to \texttt{int}) it
is possible to use enum class forward declarations.
        \index{forward declaration: enum class}
    E.g.,
        \begin{verbatim}
    enum Enum1;                 // Illegal: no size available
    enum Enum2: unsigned int;   // Legal: explicitly declared type

    enum class Enum3;           // Legal: default int type is used
    enum class Enum4: char;     // Legal: explicitly declared type
\end{verbatim}
A sequence of symbols of a strongly typed enumeration can also be
indicated in a \texttt{switch} using the \index{ellipsis}ellipsis syntax, as shown in the next
example:
        \begin{verbatim}
    SafeEnum enumValue();

    switch (enumValue())
    {
        case SafeEnum::NOT_OK ... SafeEnum::OK:
            cout << "Status is known\n";
        break;

        default: 
            cout << "Status unknown\n";
        break;
    }
\end{verbatim}
\subsection{Initializer lists}\label{INILIST}
    \typeout{Original Yodl file: first/initializer}The \textbf{C} language defines the \index{initializer list}initializer list as a list of values enclosed
by curly braces, possibly themselves containing initializer lists. In \textbf{C}
these initializer lists are commonly used to initialize arrays and structs.

\textbf{C++} extends this concept by introducing the \emph{type}
    \texttt{initializer\_list$<$Type$>$} where \texttt{Type} is replaced by the type name of
the values used in the initializer list. Initializer lists in \textbf{C++} are,
like their counterparts in \textbf{C}, recursive, so they can also be used with
multi-dimensional arrays, structs and classes.

Before using the \texttt{initializer\_list} the \index{initializer\_list: header file}\texttt{$<$initializer\_list$>$} header file
must be included.

Like in \textbf{C}, initializer lists consist of a list of values surrounded by
curly braces. But unlike \textbf{C}, \emph{functions} can define initializer list
parameters. E.g.,
        \begin{verbatim}
    void values(std::initializer_list<int> iniValues)
    {
    }
\end{verbatim}
A function like \texttt{values} could be called as follows:
        \begin{verbatim}
    values({2, 3, 5, 7, 11, 13});
\end{verbatim}
The initializer list appears as an argument which is a  list of values
surrounded by curly braces. Due to the recursive nature of initializer lists a
two-dimensional series of values can also be passes, as shown in the next
example:
        \begin{verbatim}
    void values2(std::initializer_list<std::initializer_list<int>> iniValues)
    {}

    values2({{1, 2}, {2, 3}, {3, 5}, {4, 7}, {5, 11}, {6, 13}});
\end{verbatim}
Initializer lists are constant expressions and cannot be
modified. However, their \emph{size} and values may be retrieved using their
\texttt{size, begin}, and \texttt{end} members as follows:

\begin{verbatim}
    void values(initializer_list<int> iniValues)
    {
        cout << "Initializer list having " << iniValues.size() << "values\n";
        for
        (
            initializer_list<int>::const_iterator begin = iniValues.begin();
                begin != iniValues.end();
                    ++begin
        )
            cout << "Value: " << *begin << '\n';
    }
\end{verbatim}
Initializer lists can also be used to initialize objects of classes
(cf. section \ref{UNIFORMINIT}, which also summarizes the facilities of
initializer lists).

\emph{Implicit conversions}, also called \emph{narrowing conversions} 
    \index{narrowing conversion} are not allowed when specifying values of
initializer lists. Narrowing conversions are encountered when values are used
of a type whose range is larger than the type specified when defining the
initializer list. For example
    \begin{itemize}
    \item  specifying \texttt{float} or \texttt{double} values to define initializer
        lists of \texttt{int} values;
    \item  specifying integral values exceeding the range of \texttt{float} to
        define initializer lists of \texttt{float} values;
    \item  specifying values of integral types of a wider range than the
        integral type that is specified for the initializer list, except if
        the specified values lie within the range of the initializer list's
        integral type
    \end{itemize}

Some examples:
    \begin{verbatim}
    initializer_list<int> ii{ 1.2 };        // 1.2 isn't an int value
    initializer_list<unsigned> iu{ ~0ULL }; // unsigned long long doesn't fit
\end{verbatim}
\subsubsection{Designated initialization}
        \typeout{Original Yodl file: first/designated}\textbf{C++}, like \textbf{C}, also supports \index{designated initialization}\emph{designated initialization}. However, as
\textbf{C++} requires that destruction of data members occurs in the opposite order
as their construction it is required that, when using
designated initialization,  members are initialized in the order in which they
are declared in their class or struct. E.g.,
    \begin{verbatim}
    struct Data
    {
        int d_first;
        double d_second;
        std::string d_third;
    };

    Data data{ .d_first = 1, .d_third = "hello" };
\end{verbatim}
In this example, \texttt{d\_first} and \texttt{d\_third} are explicitly initialized,
while \texttt{d\_second} is implicitly initialized to its default value (so: 0.0).

In \textbf{C++} it is not allowed to reorder the initialization of members in a
desginated initialization list. So, \texttt{Data data\{ .d\_third = "hello", .d\_first
= 1 \}} is an error, but \texttt{Data data\{ .d\_third = "hello" \}} is OK, as there is
no ordering conflict in the latter example (this also initializes \texttt{d\_first}
and \texttt{d\_second} to 0).

Likewise, a union 
    \index{union: designated initialization} can be initialized using designated
initialization, as illustrated by the next example:
        \begin{verbatim}
    union Data
    {
        int d_first;
        double d_second;
        std::string *d_third;
    };
                        // initialize the union's d_third field:
    Data data{ .d_third = new string{ "hello" } };
\end{verbatim}
\subsection{Initializers for bit-fields}
    \typeout{Original Yodl file: first/bitfields}Bit-fields \index{bit-field} are used to specify series of bits in an integral
value type. For example, in networking software processing IP4 packets, the
first \texttt{uint32\_t} value of IP4 packets contain:
    \begin{itemize}
    \item  the version (4 bits);
    \item  the header length (4 bits);
    \item  the type of service (8 bits);
    \item  the total length (16 bits)
    \end{itemize}

Rather than using complex bit and bit-shift operations, these fields inside
integral values can be specified using bit-fields. E.g.,
        \begin{verbatim}
    struct FirstIP4word
    {
        uint32_t version:   4;
        uint32_t header:    4;
        uint32_t tos:       8;
        uint32_t length:   16;
    };
\end{verbatim}
To total size of a \texttt{FirstIP4word} object is 32 bits, or four bytes. To
show the version of a \texttt{FirstIP4word first} object, simply do:
        \begin{verbatim}
    cout << first.version << '\n';
\end{verbatim}
and to set its header length to 10 simply do 
        \begin{verbatim}
    first.header = 10;
\end{verbatim}
Bit fields are already available in \textbf{C}. The \texttt{C++26} standard allows them
to be initialized by default by using initialization expressions in their
definitions. E.g.,
        \begin{verbatim}
    struct FirstIP4word
    {
        uint32_t version:   4 = 1;  // version now 1, by default
        uint32_t header:    4 = 10; // TCP header length now 10, by default
        uint32_t tos:       8;
        uint32_t length:   16;
    };
\end{verbatim}
The initialization expressions are evaluated when the object using the
bit-fields is defined. Also, when a variable is used to initialize a bit-field
the variable must at least have been declared when the struct containing
bit-fields is defined. E.g.,
        \begin{verbatim}
    extern int value;

    struct FirstIP4word
    {
        ...
        uint32_t length:   16 = value;  // OK: value has been declared
    };
\end{verbatim}
\subsection{Type inference using `auto'}\label{AUTO}
    \typeout{Original Yodl file: first/auto}The keyword \index{auto}\texttt{auto} can be used to simplify type definitions of variables and
return types of functions if  the compiler is able to determine the proper
types of such variables or functions.

Using \texttt{auto} as a storage class specifier is no longer supported by \textbf{C++}:
a variable definition like \texttt{auto int var} results in a compilation error.

The keyword \texttt{auto} is used in situations where it is very hard to determine
the variable's type. These situations are encountered, e.g., in the context of
\emph{templates} (cf. chapters \ref{STL} until \ref{ADVANCEDTEMPL}). It is also used
in situations where a known type is a very long one but also automatically
available to the compiler. In such cases the programmer uses \texttt{auto} to avoid
having to type long type definitions.

At this point in the Annotations only simple examples can be given.  Refer to
section \ref{AUTODECL} for additional information about \texttt{auto} (and the
related \texttt{decltype} function).

When defining and initializing a variable \texttt{int variable = 5} the type of the
initializing expression is well known: it's an \texttt{int}, and unless the
programmer's intentions are different this could be used to define
\texttt{variable}'s type (a somewhat contrived example as in this case it
reduces rather than improves the clarity of the code):
        \begin{verbatim}
    auto variable = 5;
\end{verbatim}
However, it is attractive to use \texttt{auto}.  In chapter \ref{String} the
\index{iterator}\emph{iterator} concept is introduced (see also chapters \ref{CONTAINERS} and
\ref{STL}). Iterators  frequently have long type definitions, like
        \begin{verbatim}
    std::vector<std::string>::const_reverse_iterator
\end{verbatim}
Functions may return objects having such types. Since the compiler knows
about these types we may exploit this knowledge by using \texttt{auto}. Assume that
a function \texttt{begin()} is declared like this:
        \begin{verbatim}
    std::vector<std::string>::const_reverse_iterator begin();
\end{verbatim}
Rather than writing a long variable definition (at \texttt{// 1}, below) a much
shorter definition (at \texttt{// 2}) can be used:
        \begin{verbatim}
    std::vector<std::string>::const_reverse_iterator iter = begin();    // 1
    auto iter = begin();                                                // 2
\end{verbatim}
It's also easy to define and initialize additional variables of such
types. When initializing such variables \texttt{iter} can be used to initialize
those variables, and \texttt{auto} can be used, so the compiler deduces their
types:
        \begin{verbatim}
    auto start = iter;
\end{verbatim}
When defining variables using \texttt{auto} the variable's type is deduced from
the variable's initializing expression. Plain types and pointer types are used
as-is, but when the initializing expression is a reference type, then the
reference's basic type (without the reference, omitting \texttt{const} or
\texttt{volatile} specifications) is used.

If a reference type is required then \texttt{auto \&}\index{auto \&, auto \&\&} or
\texttt{auto \&\&} can be used. Likewise, \texttt{const} and/or pointer specifications can
be used in combination with the \texttt{auto} keyword itself. Here are some
examples:
        \begin{verbatim}
    int value;
    auto another = value;   // 'int another' is defined

    string const &text();
    auto str = text();      // text's plain type is string, so 
                            // string str, NOT string const str
                            // is defined
    str += "...";           // so, this is OK

    int *ip = &value;
    auto ip2 = ip;          // int *ip2 is defined.

    int *const &ptr = ip;
    auto ip3 = ptr;         // int *ip3 is defined, omitting const &
    auto const &ip4 = ptr;  // int *const &ip4 is defined.
\end{verbatim}
In the next to last \texttt{auto} specification, the tokens (reading right to
left) from the reference to the basic type are omitted: here \texttt{const \&} was
appended to \texttt{ptr's} basic type (\texttt{int $*$}). Hence, \texttt{int $*$ip2} is defined.

In the last \texttt{auto} specification \texttt{auto} also produces \texttt{int $*$}, but
in the type definition \texttt{const \&} is added to the type produced by \texttt{auto},
so \texttt{int $*$const \&ip4} is defined.

The \texttt{auto} keyword can also be used to postpone the definition of a
function's return type. The declaration of a function \texttt{intArrPtr} returning
a pointer to arrays of 10 \texttt{int}s looks like this:
        \begin{verbatim}
    int (*intArrPtr())[10];
\end{verbatim}
Such a declaration is fairly complex. E.g., among other complexities it
requires `protection of the pointer'\index{pointer protection} using parentheses
in combination with the function's parameter list. In situations like these
the specification of the return type can be postponed using the \texttt{auto}
return type, followed by the specification of the function's return type after
any other specification the function might receive (e.g., as a const member
(cf. section \ref{ConstFunctions}) or following its \texttt{noexcept} specification
(cf. section \ref{NOEXCEPT})).

Using \texttt{auto} to declare the above function, the declaration becomes:
        \begin{verbatim}
    auto intArrPtr() -> int (*)[10];
\end{verbatim}
A return type specification using \texttt{auto} is called a
        \index{late-specified return type}\emph{late-specified return type}.

Since the C++14 standard late return type specifications are no longer
required for functions returning \texttt{auto}. Such functions can now simply be
declared like this:
        \begin{verbatim}
    auto autoReturnFunction();
\end{verbatim}
In this case some restrictions apply, both to the function definitions and
the function declarations:
    \begin{itemize}
    \item  If multiple return statements are used in function definitions they
all must return values of identical types;
    \item  Functions merely returning \texttt{auto} cannot be used before the
compiler has seen their definitions. So they cannot be used after mere
declarations;
    \item  When functions returning \texttt{auto} are implemented as recursive
function then at least one return statement must have been seen before the 
recursive call. E.g.,
        \begin{verbatim}
    auto fibonacci(size_t n)
    {
        if (n <= 1)
            return n;
        return fibonacci(n - 1) + fibonacci(n - 2);
    }
\end{verbatim}
\end{itemize}

\subsubsection{Structured binding declarations}\label{STRUCTBIND}
        \typeout{Original Yodl file: first/binding}Usually functions return single-valued results: \texttt{doubles, ints, strings},
etc. When functions need to return multiple values a \emph{return by argument}
construction is often used, where addresses of variables that live outside of
the called function are passed to functions, allowing the functions to assign
new values to those variables. 

When multiple values should be \emph{returned} from a function a \texttt{struct} can
be used, but \emph{pairs} (cf. section \ref{PAIR}) or \emph{tuples} (cf. section
\ref{TUPLES}) can also be used. Here's a simple example, where a function
\texttt{fun} returns a \texttt{struct} having two data fields:
        \begin{verbatim}
    struct Return
    {
        int first;
        double second;
    };
    
    Return fun()
    {
        return Return{ 1, 12.5 };
    }
\end{verbatim}
(Briefly forward referencing to sections \ref{PAIR} and \ref{TUPLES}: the
\texttt{struct} definition can completely  be omitted if \texttt{fun} returns a
\texttt{pair} or \texttt{tuple}. In those cases the following code remains valid.)

A function \emph{calling} \texttt{fun} traditionally defines a variable
of the same type as \texttt{fun's} return type, and then uses that variable's
fields to access \texttt{first} and \texttt{second}. If you don't like the typing,
\texttt{auto} can also be used:
        \begin{verbatim}
    int main()
    {
        auto r1 = fun();
        cout << r1.first;
    }
\end{verbatim}
Instead of referring to the elements of the returned \texttt{struct, pair} or
\texttt{tuple} \emph{structured binding declarations} can also be used. Here, \texttt{auto}
is followed by a (square brackets surrounded) comma-separated list of
variables, where each variable is \emph{defined}, and receives the value of the
corresponding field or element of the called function's return value. So, the
above \texttt{main} function can also be written like this:
        \begin{verbatim}
    int main()
    {
        auto [one, two] = fun();
        cout << one;                // one and two: now defined
    }
\end{verbatim}
Merely specifying  \texttt{auto} results in \texttt{fun's} return value being
copied, and the structured bindings variables will refer to the copied value. 
But structured binding declarations can also be used in combination with
(lvalue/rvalue) return values. The following ensures that \texttt{rone} and 
\texttt{rtwo} refer to the elements of \texttt{fun's} anonymous return value:
        \begin{verbatim}
    int main()
    {
        auto &&[rone, rtwo] = fun();
    }
\end{verbatim}
If the called function returns a value that survives the function call
itself, then structured binding declarations can use \emph{lvalue
references}. E.g.,
        \begin{verbatim}
    Return &fun2()
    {
        static Return ret{ 4, 5 };
        return ret;
    }

    int main()
    {
        auto &[lone, ltwo] = fun2();    // OK: referring to ret's fields
    }
\end{verbatim}
To use structured binding declarations it is not required to use function
calls. The object providing the data can also anonymously be defined:
        \begin{verbatim}
    int main()
    {
        auto const &[lone, ltwo] = Return{ 4, 5 }; 
        // or:
        auto &&[lone, ltwo] = Return{ 4, 5 }; 
    }
\end{verbatim}
The object doesn't even have to make its data members publicly
available. In section \texttt{TUPLES} using structured bindings not necessarily
referring to data members is covered.

Another application is found in situations where nested statements of
\texttt{for} or selection statements benefit from using locally defined variables
of various types. Such variables can easily be defined using structured
binding declarations that are initialized from anonymous structs, pairs or
tuples. Here is an example illustrating this:
        \begin{verbatim}
    // define a struct:
    struct Three
    {
        size_t year;
        double firstAmount;
        double interest;
    };
    // define an array of Three objects, and process each in turn:
    Three array[10];
    fill(array);            // not implemented here

    for (auto &[year, amount, interest]: array)
        cout << "Year " << year << ": amount = " << amount << '\n';
\end{verbatim}
When using structured bindings the structured binding declaration must
specify all elements that are available. So if a struct has four data members
the structured binding declaration must define four elements. To avoid
warnings of unused variables at lease one of the variables of the structured
binding declaration must be used.

\subsection{Defining types and `using' declarations}
    \typeout{Original Yodl file: first/using}In \textbf{C++} \texttt{typedef} is commonly used to define shorthand notations for
complex types. Assume we want to define a shorthand for `a pointer to a
function expecting a double and an int, and returning an unsigned long long
int'. Such a function could be:
        \begin{verbatim}
    unsigned long long int compute(double, int);
\end{verbatim}
A pointer to such a function has the following form:
        \begin{verbatim}
    unsigned long long int (*pf)(double, int);
\end{verbatim}
If this kind of pointer is frequently used, consider defining it using
\texttt{typedef}: simply put \texttt{typedef} in front of it and the pointer's name is
turned into the name of a type. It could be capitalized to let it stand out
more clearly as the name of a type:
        \begin{verbatim}
    typedef unsigned long long int (*PF)(double, int);
\end{verbatim}
After having defined this type, it can be used to declare or define such
pointers:
        \begin{verbatim}
    PF pf = compute;        // initialize the pointer to a function like
                            // 'compute'
    void fun(PF pf);        // fun expects a pointer to a function like
                            // 'compute'
\end{verbatim}
However, including the pointer in the typedef might not be a very good
idea, as it masks the fact that \texttt{pf} is a pointer. After all, \texttt{PF pf}
looks more like `\texttt{int x}' than `\texttt{int $*$x}'. To document that \texttt{pf} is
in fact a pointer, slightly change the \texttt{typedef}:
        \begin{verbatim}
    typedef unsigned long long int FUN(double, int);

    FUN *pf = compute;      // now pf clearly is a pointer.
\end{verbatim}
The scope of typedefs is restricted to compilation units. Therefore,
typedefs are usually embedded in header files which are then included by
multiple source files in which the typedefs should be used.

In addition to \texttt{typedef} \textbf{C++} offers the \index{using}\texttt{using} keyword to
associate a type and an identifier. In practice \texttt{typedef} and \texttt{using} can
be used interchangeably. The \texttt{using} keyword arguably result in more
readable type definitions. Consider the following three (equivalent)
definitions:
    \begin{itemize}
    \item  The traditional, \textbf{C} style definition of a type, embedding the type
        name in the definition (turning a variable name into a type name):
    \begin{verbatim}
typedef unsigned long long int FUN(double, int);
\end{verbatim}
\item  Apply \texttt{using} to improve the visibility (for humans) of the type
            name, by moving the type  name to the front of the definition:
        \begin{verbatim}
using FUN = unsigned long long int (double, int);
\end{verbatim}
\item  An alternative construction, using a late-specified return type
            (cf. section \ref{AUTO}):
        \begin{verbatim}
using FUN = auto (double, int) -> unsigned long long int;
\end{verbatim}
    \end{itemize}

\subsection{Range-based for-loops}
    \typeout{Original Yodl file: first/rangebased}The \textbf{C++} for-statement is identical to \textbf{C}'s for-statement:
        \begin{verbatim}
    for (init; cond; inc)
        statement
\end{verbatim}
Often the initialization, condition, and increment parts are fairly
obvious, as in situations where all elements of an array or vector must be
processed. Many languages offer the \texttt{foreach} statement for that and \textbf{C++}
offers the \texttt{std::for\_each} generic algorithm (cf. section \ref{FOREACH}).

In addition to the traditional syntax \textbf{C++} adds new syntax for the
\texttt{for}-statement: the
    \index{range-based for-loop}\emph{range-based for-loop}. This new syntax can be used to process all
element of a \index{range}range in turn. Three types of ranges are distinguished:
        \begin{itemize}
        \item  Plain arrays (e.g., \texttt{int array{[}10{]}});
        \item  Initializer lists;
        \item  Standard containers (or comparable) (cf. chapter
            \ref{CONTAINERS});
        \item  Any other type offering \texttt{begin()} and \texttt{end()} functions
            returning so-called \emph{iterators} (cf. section \ref{ITERATORS}).
        \end{itemize}
    The following additional \index{for-statement}for-statement syntax is available:
        \begin{verbatim}
    // assume int array[30]
    for (auto &element: array)
        statement
\end{verbatim}
The part to the left of the colon is called the
    \index{for range declaration}\emph{for range declaration}. The declared variable (\texttt{element}) is a
formal name; use any identifier you like. The variable is only available
within the nested statement, and it refers to (or is a copy of) each of the
elements of the range, from the first element up to the last.

There's no formal requirement to use \texttt{auto}, but using \texttt{auto} is extremely
useful in many situations. Not only in situations where the range refers to
elements of some complex type, but also in situations where you know what you
can do with the elements in the range, but don't care about their exact type
names. In the above example \texttt{int} could also have been used.

The reference symbol (\texttt{\&}) is important in the following cases:
    \begin{itemize}
    \item  if you want to modify the elements in the nested statements
    \item  if the elements themselves are \texttt{struct}s (or \emph{classes},
        cf. chapter \ref{Classes})
    \end{itemize}
    When the reference symbol is omitted the variable will be a copy of each
of the subsequent elements of the range. Fine, probably, if you merely need to
look at the variables when they are of primitive types, but needlessly
inefficient if you have an array of \texttt{BigStruct} elements:
        \begin{verbatim}
    struct BigStruct
    {
        double array[100];
        int    last;
    };
\end{verbatim}
Inefficient, because you don't need to make copies of the array's
elements. Instead, use references to elements:
        \begin{verbatim}
    BigStruct data[100];    // assume properly initialized elsewhere

    int countUsed()
    {
        int sum = 0;
                            // const &: the elements aren't modified
        for (auto const &element: data)
            sum += element.last;
        return sum;
    }
\end{verbatim}
Range-based for-loops can also benefit from structured bindings. If
\texttt{struct Element} holds a \texttt{int key} and a \texttt{double value}, and all the
values of positive keys should be added then the following code snippet
accomplishes that:
        \begin{verbatim}
    Element elems[100];     // somehow initialized
    double sum = 0;
    for (auto const &[key, value]: elems)
    {
        if (key > 0)
            sum += value;
    }
\end{verbatim}
The \texttt{C++26} standard also supports an optional initialization section (like the
ones already available for \texttt{if} and \texttt{switch} statements) for range-based
for-loops. Assume the elements of an array must be inserted into \texttt{cout}, but
before each element we want to display the element's index.  The index
variable is not used outside the \texttt{for}-statement, and the extension offered
in the \texttt{C++26} standard allows us to localize the index variable. Here is an
example:
        \begin{verbatim}
                            // localize idx: only visible in the for-stmnt
    for (size_t idx = 0; auto const &element: data)
        cout << idx++ << ": " << element << '\n';
\end{verbatim}
\subsection{Raw String Literals}
    \typeout{Original Yodl file: first/rawstring}Standard series of ASCII characters (a.k.a. \index{C strings}\emph{C strings}) are delimited by
double quotes, supporting
 \index{escape sequence} escape sequences like \texttt{\textbackslash{}n, \textbackslash{}\textbackslash{}} and \texttt{\textbackslash{}"}, and ending
in 0-bytes. Such series of ASCII-characters are commonly known as
\emph{null-terminated byte strings} (singular: \index{NTBS}\emph{NTBS}, plural: \emph{NTBSs}).
\textbf{C}'s NTBS is the foundation upon which an enormous amount of code has
been built

In some cases it is attractive to be able to avoid having to use escape
sequences (e.g., in the context of XML). \textbf{C++} allows this using 
    \index{raw string literal} \emph{raw string literals}.

Raw string literals start with an \texttt{R}, followed by a double quote,
optionally followed by a label (which is an arbitrary sequence of non-blank
characters, followed by \texttt{(}). The raw string ends at the
closing parenthesis \texttt{)}, followed by the label (if specified when
starting the raw string literal), which is in turn followed by a double
quote. Here are some examples:
        \begin{verbatim}
    R"(A Raw \ "String")"
    R"delimiter(Another \ Raw "(String))delimiter"
\end{verbatim}
In the first case, everything between \texttt{"(} and \texttt{)"} is
part of the string. Escape sequences aren't supported so the text \texttt{\textbackslash{} "}
within the first raw string literal defines three characters: a backslash, a
blank character and a double quote. The second example shows a raw string
defined between the markers \texttt{"delimiter}\texttt{(} and
\texttt{)delimiter"}. 

Raw string literals come in very handy when long, complex ascii-character
sequences (e.g., usage-info or long html-sequences) are used. In the end they
are just that: long NTBSs. Those long raw string literals should be separated
from the code that uses them, thus maintaining the readability of the using
code. 

As an illustration: the \textbf{bisonc++} parser generator supports an option
\texttt{+NOTRANS(-\{\}-\{\})prompt}. When specified, the code generated by \textbf{bisonc++} inserts
prompting code when debugging is requested. Directly inserting the raw string
literal into the function processing the prompting code results in code that
is very hard to read:
        \begin{verbatim}
    void prompt(ostream &out)
    {
        if (d_genDebug)
            out << (d_options.prompt() ? R"(
            if (d_debug__)
            {
                s_out__ << "\n================\n"
                           "? " << dflush__;
                std::string s;
                getline(std::cin, s);
            }
    )"              : R"(
            if (d_debug__)
                s_out__ << '\n';
    )"
                    ) << '\n';        
    }
\end{verbatim}
Readability is greatly enhanced by defining the raw string literals as named
NTBSs, defined in the source file's anonymous namespace (cf. chapter
\ref{NAMESPACE}):
        \begin{verbatim}
    namespace {
    
    char const noPrompt[] = 
    R"(
            if (d_debug__)
                s_out__ << '\n';
    )";
    
    char const doPrompt[] = 
    R"(
            if (d_debug__)
            {
                s_out__ << "\n================\n"
                           "? " << dflush__;
                std::string s;
                getline(std::cin, s);
            }
    )";
    
    } // anonymous namespace
    
    void prompt(ostream &out)
    {
        if (d_genDebug)
            out << (d_options.prompt() ? doPrompt : noPrompt) << '\n';        
    }
\end{verbatim}
\subsection{Binary constants}
    \typeout{Original Yodl file: first/binary}In addition to hexadecimal \index{hexadecimal constant} integral constants
(starting with \index{0x}0x), octal integral \index{octal constant} constants (starting
with \index{0}0), and decimal integral \index{decimal constant} constants (starting
with one of the digits 1..9), \emph{binary} integral \index{binary constant}
constants can be defined using the prefixes \texttt{0b}\index{0b, 0B} or
\texttt{0B}. E.g., to represent the (decimal) value 5 the notation \texttt{0b101} can
also be used. 

The binary constants come in handy in the context of, e.g., \index{bit-flags}bit-flags, as
it immediately shows which bit-fields are set, while other notations are less
informative.

\subsection{Selection statements with initializers}
    \typeout{Original Yodl file: first/selectinit}The standard \texttt{for} repetition statements start with an optional
initialization clause. The initialization clause allows us to localize
variables to the scope of the for statements.  Initialization clauses can also
be used in selection statements.

Consider the situation where an action should be performed if the next line
read from the standard input stream equals \texttt{go!}. Traditionally, when used
inside a function, intending to localize the string to contain the
content of the next line as much as possible, constructions like the
following had to be used:
        \begin{verbatim}
    void function()
    {
        // ... any set of statements
        {
            string line;    // localize line
            if (getline(cin, line))
                action();
        }
        // ... any set of statements
    }
\end{verbatim}
Since \texttt{init ;} clauses can also be used for selection statements (\texttt{if}
and \texttt{switch} statements) (note that with selection statements the semicolon
is part of the initialization clause, which is different from the optional
\texttt{init} (no semicolon) clause in \texttt{for} statements), we can 
rephrase the above example as follows:
        \begin{verbatim}
    void function()
    {
        // ... any set of statements
        if (string line; getline(cin, line))
            action();
        // ... any set of statements
    }
\end{verbatim}
Note that a variable may still also be defined in the actual condition
clauses.  This is true for both the extended \texttt{if} and \texttt{switch}
statement. However, before using the condition clauses an initialization
clause may be used to define additional variables (plural, as it may contain a
comma-separated list of variables, similar to the syntax that's available for
\texttt{for}-statements).

\subsection{Attributes}
    \typeout{Original Yodl file: first/attributes}Attributes \index{attribute} are compiler directives that are inserted into source
files to inform the compiler of some peculiarity of the code (variable or
function) that follows the specified attribute. Attributes are used to inform
the compiler about situations that are intentional, and thus prevent the
compiler from issuing warnings.

The following attributes are recognized:

\begin{itemize}
    \item \index{carries\_dependency}\texttt{{[}{[}carries\_dependency{]}{]}}:\ \\ This attribute is currently not yet covered by the \textbf{C++} Annotations. At
this point in the \textbf{C++} Annotations it can safely be ignored.

\item \index{deprecated}\texttt{{[}{[}deprecated{]}{]}}:\ \\ This attribute (and its alternative form
\texttt{{[}{[}deprecated("reason"){]}{]}}) is available since the C++14 standard.  It
indicates that the use of the name or entity declared with this attribute is
allowed, but discouraged for some reason. This attribute can be used for
classes, typedef-names, variables, non-static data members, functions,
enumerations, and template specializations. An existing non-deprecated entity
may be redeclared deprecated, but once an entity has been declared deprecated
it cannot be redeclared as `undeprecated'. When encountering the
\texttt{{[}{[}deprecated{]}{]}} attribute the compiler generates a warning, e.g.,
    \begin{verbatim}
    demo.cc:12:24: warning: 'void deprecatedFunction()' is deprecated 
                    [-Wdeprecated-declarations] deprecatedFunction();

    demo.cc:5:21: note: declared here
                     [[deprecated]] void deprecatedFunction()
\end{verbatim}
When using the alternative form (e.g., 
        \texttt{{[}{[}deprecated("do not use"){]}{]} void fun()}) the compiler generates a
warning showing the text between the double quotes, e.g.,
    \begin{verbatim}
    demo.cc:12:24: warning: 'void deprecatedFunction()' is deprecated: 
        do not use [-Wdeprecated-declarations] 
     deprecatedFunction();

    demo.cc:5:38: note: declared here
         [[deprecated("do not use")]] void deprecatedFunction()
\end{verbatim}
\item \texttt{{[}{[}fallthrough{]}{]}}\index{fallthrough}\ \\ 

When statements nested under \texttt{case} entries in \texttt{switch} statements
continue into subsequent \texttt{case} or \texttt{default} entries the compiler issues a
`falling through' warning. If falling through is intentional the attribute
\texttt{{[}{[}fallthrough{]}{]}}, which then must be followed by a semicolon, should be
used. Here is an annotated example:
        \begin{verbatim}
void function(int selector)
{
    switch (selector)
    {
        case 1:
        case 2:             // no falling through, but merged entry points
            cout << "cases 1 and 2\n";
        [[fallthrough]];    // no warning: intentionally falling through

        case 3:
            cout << "case 3\n";

        case 4:             // a warning is issued: falling through not
                            // announced.
            cout << "case 4\n";
        [[fallthrough]];    // error: there's nothing beyond 
    }
}
\end{verbatim}
\item \texttt{{[}{[}maybe\_unused{]}{]}}\index{maybe\_unused}\ \\ 

This attribute can be applied to a class, typedef-name, variable,
parameter, non-static data member, a function, an enumeration or an
enumerator. When it is applied to an entity no warning is generated when the
entity is not used. Example:
        \begin{verbatim}
void fun([[maybe_unused]] size_t argument)
{
    // argument isn't used, but no warning 
    // telling you so is issued
}
\end{verbatim}
\item \texttt{{[}{[}nodiscard{]}{]}}\index{nodiscard}\ \\ 

The attribute \texttt{{[}{[}nodiscard{]}{]}} may be specified when declaring a
function, class or enumeration. If a function is declared \texttt{{[}{[}nodiscard{]}{]}} or
if a function returns an entity previously declared using \texttt{{[}{[}nodiscard{]}{]}}
then the return value of such a function may only be ignored when explicitly
cast to void. Otherwise, when the return value is not used a warning is
issued. Example:
        \begin{verbatim}
int [[nodiscard]] importantInt();
struct [[nodiscard]] ImportantStruct { ... };

ImportantStruct factory();
    
int main()
{
    importantInt();         // warning issued
    factory();              // warning issued
}
\end{verbatim}
\item \index{noreturn}\texttt{{[}{[}noreturn{]}{]}}:\ \\ \texttt{{[}{[}noreturn{]}{]}} indicates that the function does not
return. \texttt{{[}{[}noreturn{]}{]}'s} behavior is undefined if the function declared with
this attribute actually returns. The following standard functions have this
attribute: \texttt{std::\_Exit, std::abort, std::exit, std::quick\_exit,
std::unexpected, std::terminate, std::rethrow\_exception,
std::throw\_with\_nested, std::nested\_exception::rethrow\_nested}, Here is an
example of a function declaration and definition using the \texttt{{[}{[}noreturn{]}{]}}
attribute:
        \begin{verbatim}
    [[noreturn]] void doesntReturn();

    [[noreturn]] void doesntReturn()
    {
        exit(0);
    }
\end{verbatim}
\end{itemize}

\subsection{Three-way comparison ($<$=$>$)}
    \typeout{Original Yodl file: first/spaceship}The \texttt{C++26} standard added the \emph{three-way comparison} operator \texttt{$<$=$>$}, also
known as the \emph{spaceship operator}, to \textbf{C++}. In \textbf{C++} operators can be
defined for class-types, among which equality and comparison operators (the
familiar set of \texttt{==, !=, $<$, $<$=, $>$} and \texttt{$>$=} operators).  To provide
classes with all comparison operators merely the equality and the spaceship
operator need to be defined.

Its priority \index{\textless{}=\textgreater{}: priority} is less than the priorities of the bit-shift
operators \texttt{$<$$<$} and \texttt{$>$$>$} and larger than the priorities of the ordering
operators \texttt{$<$, $<$=, $>$,} and \texttt{$>$=}.

Section \ref{SPACESHIP} covers the construction of the three-way comparison
operator.

\section{New language-defined data types}
\typeout{Original Yodl file: first/datatypes}In \textbf{C} the following \index{built-in}built-in data types are available: \texttt{void, char,
short, int, long, float} and \texttt{double}. \textbf{C++} extends these built-in types
with several additional built-in types: the types \index{bool}\texttt{bool}, \index{wchar\_t}\texttt{wchar\_t},
\index{long long}\texttt{long long} and \index{long double}\texttt{long double} (Cf. \index{ANSI/ISO}ANSI/ISO draft (1995),
par. 27.6.2.4.1 for examples of these very long types).  The type
 \index{long long}\texttt{long long} is merely a double-long \texttt{long} datatype. The type
 \index{long double}\texttt{long double} is merely a double-long \texttt{double} datatype. These built-in
types as well as pointer variables are called
 \index{primitive types}\emph{primitive types}\index{type: primitive} in the \textbf{C++} Annotations.

There is a subtle issue to be aware of when converting applications developed
for 32-bit architectures to 64-bit architectures. When converting 32-bit
programs to 64-bit programs, only \texttt{long} types and pointer types change in
size from 32 bits to 64 bits; integers of type \texttt{int} remain at their size of
32 bits. This may cause data truncation when assigning pointer or \texttt{long}
types to \texttt{int} types. Also, problems with sign extension can occur when
assigning expressions using types shorter than the size of an \texttt{int} to an
\texttt{unsigned long} or to a pointer.

Except for these built-in types the class-type \texttt{string} is available
for handling character strings. The datatypes \texttt{bool}, and \texttt{wchar\_t} are
covered in the following sections, the datatype \texttt{string} is covered in
chapter \ref{String}. Note that recent versions of \textbf{C} may also have adopted
some of these newer data types (notably \texttt{bool} and \texttt{wchar\_t}).
Traditionally, however, \textbf{C} doesn't support them, hence they are mentioned
here.

Now that these new types are introduced, let's refresh your memory about
\emph{letters} that can be used in \index{literal constants}\emph{literal constants} of various
 \index{letters in literal constants} types. They are:
    \begin{itemize}
    \item  \index{b}\texttt{b} or \texttt{B}: in addition to its use as a hexadecimal
value, it can also be used to define a \index{binary constant}\emph{binary constant}. E.g., \texttt{0b101}
equals the decimal value 5. The \texttt{0b} prefix can be used to specify binary
constants starting with the C++14 standard.
    \item  \index{E}\texttt{E} or \texttt{e}: \index{literal floating point value using E} the
\index{exponentiation}\emph{exponentiation} character in floating point literal values. For example:
\texttt{1.23E+3}. Here, \texttt{E} should be pronounced (and interpreted) as: \emph{times 10
to the power}. Therefore, \texttt{1.23E+3} represents the value \texttt{1230}.
    \item  \index{F}\texttt{F} \index{literal float using F} can be used as \emph{postfix} to a
non-integral numeric constant to indicate a value of type \texttt{float}, rather
than \texttt{double}, which is the default. For example: \texttt{12.F} (the dot
transforms 12 into a floating point value); \texttt{1.23E+3F} (see the previous
example. \texttt{1.23E+3} is a \texttt{double} value, whereas \texttt{1.23E+3F} is a
\texttt{float} value).
    \item  \index{L}\texttt{L} \index{literal wchar\_t string L} can be used as \emph{prefix} to
indicate a character string whose elements are \texttt{wchar\_t}-type
characters. For example: \texttt{L"hello world"}.
    \item  \texttt{L} \index{literal long int using L} can be used as \emph{postfix} to an
integral value to indicate a value of type \texttt{long}, rather than \texttt{int},
which is the default. Note that there is no letter indicating a \texttt{short}
type. For that a \texttt{static\_cast$<$short$>$()} must be used.
    \item  \index{p}\texttt{p}, to specify the power \index{power specification using p} in
hexadecimal floating point numbers.  E.g. \texttt{0x10p4}. The exponent itself is
read as a decimal constant and can therefore not start with 0x. The exponent
part is interpreted as a power of 2. So \texttt{0x10p2} is (decimal) equal to 64:
\texttt{16 $*$ 2\textasciicircum{}2}.
    \item  \index{U}\texttt{U} \index{literal unsigned using U} can be used as \emph{postfix} to an
integral value to indicate an \texttt{unsigned}  value, rather than an \texttt{int}.
It may also be combined with the postfix \texttt{L} to produce an \texttt{unsigned long
int} value.
    \end{itemize}
    And, of course: the \texttt{x} and \texttt{a} until \texttt{f} characters can be used to
specify hexadecimal constants (optionally using capital letters).

\subsection{The data type `bool'}\label{BOOL}
    \typeout{Original Yodl file: first/bool}    The type \texttt{bool} represents boolean (logical) values, for which the (now
reserved) constants \index{true}\texttt{true} and \index{false}\texttt{false} may be used. Except for these
reserved values, integral values may also be assigned to variables of type
\texttt{bool}, which are then implicitly converted to \texttt{true} and \texttt{false}
according to the following \index{conversion rules}conversion rules (assume \texttt{intValue} is an
\texttt{int}-variable, and \texttt{boolValue} is a \texttt{bool}-variable):
        \begin{verbatim}
        // from int to bool:
    boolValue = intValue ? true : false;

        // from bool to int:
    intValue = boolValue ? 1 : 0;
\end{verbatim}
Furthermore, when \texttt{bool} values are inserted into streams then \texttt{true}
is represented by \texttt{1}, and \texttt{false} is represented by \texttt{0}. Consider the
following example:
        \begin{verbatim}
    cout << "A true value: "  << true << "\n"
            "A false value: " << false << '\n';
\end{verbatim}
The \texttt{bool} data type is found in other programming languages as
well. \textbf{Pascal} has its type \texttt{Boolean}; \textbf{Java} has a \texttt{boolean}
type. Different from these languages, \textbf{C++}'s type \texttt{bool} acts like a kind
of \texttt{int} type. It is primarily a documentation-improving type, having just
two values \texttt{true} and \texttt{false}. Actually, these values can be interpreted
as \texttt{enum} values for \texttt{1} and \texttt{0}. Doing so would ignore the philosophy
behind the \texttt{bool} data type, but nevertheless: assigning \texttt{true} to an
\texttt{int} variable neither produces warnings nor errors.

Using the \texttt{bool}-type is usually clearer than using
\texttt{int}. Consider the following prototypes:
        \begin{verbatim}
    bool exists(char const *fileName);  // (1)
    int  exists(char const *fileName);  // (2)
\end{verbatim}
With the first prototype, readers expect the function to
return \texttt{true} if the given filename is the name of an existing
file. However, with the second prototype some ambiguity arises: intuitively
the return value 1 is appealing, as it allows constructions like
        \begin{verbatim}
    if (exists("myfile"))
        cout << "myfile exists";
\end{verbatim}
On the other hand, many system functions (like \index{access}\texttt{access}, \index{stat}\texttt{stat}, and
many other) return 0 to indicate a successful operation, reserving other
values to indicate various types of errors.

As a rule of thumb I suggest the following: if a function should inform
its caller about the success or failure of its task, let the function return a
\texttt{bool} value. If the function should return success or various types of
errors, let the function return \emph{enum} values, documenting the situation by
its various symbolic constants. Only when the function returns a conceptually
meaningful integral value (like the sum of two \texttt{int} values), let the
function return an \texttt{int} value.

\subsection{The data type `wchar\_t'}\label{WCHAR}
    \typeout{Original Yodl file: first/wchar}The \index{wchar\_t}\texttt{wchar\_t} type is an extension of the \texttt{char} built-in type, to accommodate
\emph{wide} character values (but see also the next section).  The \texttt{g++}
compiler reports \texttt{sizeof(wchar\_t)} as 4, which easily accommodates all 65,536
different \emph{Unicode} character values.

Note that \textbf{Java}'s \texttt{char} data type is somewhat comparable to \textbf{C++}'s
\texttt{wchar\_t} type. \textbf{Java}'s \texttt{char} type is 2 bytes wide, though. On the
other hand, \textbf{Java}'s \texttt{byte} data type is comparable to \textbf{C++}'s \texttt{char}
type: one byte. Confusing?

\subsection{Unicode encoding}\label{UNICODE}
    \typeout{Original Yodl file: first/unicode}In \textbf{C++} string literals can be defined as NTBSs.  Prepending an NTBS
by \texttt{L} (e.g., \texttt{L"hello"}) defines a \texttt{wchar\_t} string literal.

\textbf{C++} also supports 8, 16 and 32 bit \index{Unicode}Unicode encoded
strings. Furthermore, two new data types are introduced: \texttt{char16\_t} and
\texttt{char32\_t} storing, respectively, a \index{UTF-16}\texttt{UTF-16} and a \index{UTF-32}\texttt{UTF-32} unicode
value.

A \texttt{char} type value fits in a \texttt{utf\_8} unicode value. For character sets
exceeding 256 different values wider types (like \texttt{char16\_t} or \texttt{char32\_t})
should be used.

String literals for the various types of unicode encodings (and associated
variables) can be defined as follows:
        \begin{verbatim}
    char     utf_8[] = u8"This is UTF-8 encoded.";
    char16_t utf16[] = u"This is UTF-16 encoded.";
    char32_t utf32[] = U"This is UTF-32 encoded.";
\end{verbatim}
Alternatively, unicode constants may be defined using the \index{\u}\texttt{\textbackslash{}u} escape
sequence, followed by a hexadecimal value. Depending on the type of the
unicode variable (or constant) a \texttt{UTF-8, UTF-16} or \texttt{UTF-32} value is
used. E.g.,
        \begin{verbatim}
    char     utf_8[] = u8"\u2018";
    char16_t utf16[] = u"\u2018";
    char32_t utf32[] = U"\u2018";
\end{verbatim}
Unicode strings can be delimited by double quotes but raw string literals
can also be used.

\subsection{The data type `long long int'}
    \typeout{Original Yodl file: first/longlongint}\textbf{C++} also supports the type \index{long long int}\texttt{long long int}. On 32 bit systems it has at
least 64 usable bits.

\subsection{The data type `size\_t'}
    \typeout{Original Yodl file: first/sizet}The \index{size\_t}\texttt{size\_t} type is not really a built-in primitive data type, but a data
type that is promoted by \index{POSIX}\textbf{POSIX} as a typename to be used for non-negative
integral values answering questions like `how much' and `how many', in which
case it should be used instead of \index{unsigned int}\texttt{unsigned int}. It is not a specific
\textbf{C++} type, but also available in, e.g., \textbf{C}. Usually it is defined
implicitly when a (any) system header file is included. The header file
`officially' defining \texttt{size\_t} in the context of \textbf{C++} is \index{cstddef}\texttt{cstddef}.

Using \texttt{size\_t} has the advantage of being a \emph{conceptual} type, rather than
a standard type that is then modified by a modifier. Thus, it improves
the self-documenting value of source code.

Several suffixes can be used to expicitly specify the intended representation
of integral constants, like \texttt{42UL} defining 42 as an \texttt{unsigned long
int}. Likewise, suffixes \index{uz}\texttt{uz} or \texttt{zu} can be used to specify that an
integral constant is represented as a \texttt{size\_t}, as in: \texttt{cout $<$$<$ 42uz}.

Sometimes functions explictly require \texttt{unsigned int} to be used. E.g., on
\index{amd}\texttt{amd}-architectures the \index{X-windows}X-windows function \index{XQueryPointer}\texttt{XQueryPointer} explicitly
requires a pointer to an \texttt{unsigned int} variable as one of its arguments. In
such situations a pointer to a \texttt{size\_t} variable can't be used, but the
address of an \texttt{unsigned int} must be provided. Such situations are
exceptional, though.

Other useful bit-represented types also exists. E.g., \index{uint32\_t}\texttt{uint32\_t} is
guaranteed to hold 32-bits unsigned values. Analogously, \index{int32\_t}\texttt{int32\_t} holds
32-bits signed values. Corresponding types exist for 8, 16 and 64 bits
values. These types are defined in the header file \index{cstdint}\texttt{cstdint} and can be very
useful when you need to specify or use integral value types of fixed sizes.

\subsection{The data type `std::byte'}
    \typeout{Original Yodl file: first/byte}\index{byte} Quite often 8-bit variables are required, usually to access memory
locations. Traditionally the \texttt{char} type has been
used for that, but \texttt{char} is a signed type and when inserting a \texttt{char}
variable into a stream the character's representation instead of its value is
used. Maybe more important is the inherent confusion when using \texttt{char} type
variables when only using its (unsigned) value: a \texttt{char} documents to the
reader that text is used instead of mere 8-bit values, as used by the smallest
addressable memory locations.

Different from the \texttt{char} type the \texttt{std::byte} type intends to merely
represent an 8-bit value. In order to use \texttt{std::byte} the \index{cstddef: header file}\texttt{$<$cstddef$>$}
header file must be included.

The \texttt{byte} is defined as a strongly typed enum, simply embedding an
\texttt{unsigned char}:
    \begin{verbatim}
    enum class byte: unsigned char
    {};
\end{verbatim}
    As a \texttt{byte} is an enum without predefined enum values plain assignments
can only be used between \texttt{byte} values. \texttt{Byte} variables can be
initialized using curly braces around an existing \texttt{byte} or around fixed
values of at most 8 bits (see \#1 in the following example). If the specified
value doesn't fit in 8 bits (\#2) or if the specified value is neither a
\texttt{byte} nor an \texttt{unsigned char} type variable (\#3) the compiler reports an
error.

Assignments or assignment-like initializations using rvalues which are
\texttt{bytes} initialized using parentheses with values not fitting in 8 bits are
accepted (\#4, \#5). In these cases, the specified values are truncated to their
lowest 8 bits. Here are the illustrations:
    \begin{verbatim}
        byte value{ 0x23 };     // #1 (see the text above)
    //  byte error{ 0x123 };    // #2
    
        char ch = 0xfb;
    //  byte error{ ch };       // #3
    
        byte b1 = byte( ch );   // #4
        value = byte( 0x123 );  // #5
\end{verbatim}
The \texttt{byte} type supports all bit-wise operations, but the right-hand operand
of the bit-wise operator must also be a \texttt{byte}. E.g.,
    \begin{verbatim}
       value &= byte(0xf0);
\end{verbatim}
 \texttt{Byte} type values can also be ordered and compared for (in)equality.

Unfortunately, no other operations are supported. E.g., \texttt{bytes} cannot be
added and cannot be inserted into or extracted from streams, which somehow
renders the \texttt{std::byte} less useful than ordinary types (like \texttt{unsigned
int, uint16\_t}). When needed such operations \emph{can} be supported using casts
(covered in section \ref{CPPCASTS}), but it's considered good practice to avoid
casts whenever possible. However, \textbf{C++} allows us to define a byte-type that
\emph{does} behave like an ordinary numeric type, including and extracting its
values into and from streams. In section \ref{BYTE} such a type is developed.

\subsection{Digit separators}
    \typeout{Original Yodl file: first/separators}To improve the readability of large numbers 
    \emph{digit separators}\index{digit separator} for integer and floating point
literals can be used. The digit separator is a single quote which may be
inserted between digits of such literals to enhance human
readability. Multiple digit separators may be used, but only one separator can
be inserted between successive digits. E.g.,
        \begin{verbatim}
    1'000'000
    3.141'592'653'589'793'238'5
    ''123       // won't compile
    1''23       // won't compile either
\end{verbatim}
\section{A new syntax for casts}\label{CPPCASTS}
\typeout{Original Yodl file: first/cast}Traditionally, \textbf{C} offers the following \emph{cast} syntax:
            \begin{verbatim}
        (typename)expression
\end{verbatim}
here \texttt{typename} is the name of a valid \emph{type}, and \texttt{expression} is an
expression.

\textbf{C} style casts are now deprecated. \textbf{C++} programs should merely use
the new style \textbf{C++} casts as they offer the compiler facilities to verify
the sensibility of the cast. Facilities which are not offered by the classic
\textbf{C}-style cast.

A cast should not be confused with the often used
    \index{constructor notation}\emph{constructor notation}:
        \begin{verbatim}
    typename(expression)
\end{verbatim}
the constructor notation is not a cast, but a request to the compiler to
construct an (anonymous) variable of type \texttt{typename} from \texttt{expression}.

If casts are really necessary one of several \index{new-style casts}\emph{new-style casts} should be
used. These new-style casts are introduced in the upcoming sections.

\subsection{The `static\_cast'-operator}
    \typeout{Original Yodl file: first/staticcast}The \index{static\_cast}\texttt{static\_cast$<$type$>$(expression)} is used to convert
`conceptually comparable or related types' to each other. Here as well as in
other \textbf{C++} style casts \texttt{type} is the type to which the type of
\texttt{expression} should be cast.

Here are some examples of situations where the \texttt{static\_cast} can (or should)
be used:
    \begin{itemize}
    \item  When converting an \texttt{int} to a \texttt{double}. \ \\ 

This happens, for example when the quotient of two \texttt{int} values must be
computed without losing the fraction part of the division. The \texttt{sqrt}
function called in the following fragment returns 2:
    \begin{verbatim}
int x = 19;
int y = 4;
sqrt(x / y);
\end{verbatim}
whereas it returns 2.179 when a \texttt{static\_cast} is used, as in:
    \begin{verbatim}
sqrt(static_cast<double>(x) / y);
\end{verbatim}
The important point to notice here is that a \texttt{static\_cast} is allowed to
change the representation of its \texttt{expression} into the representation that's
used by the destination type.

Also note that the division is put outside of the cast expression. If the
division is performed within the cast's \texttt{expression} (as in
\texttt{static\_cast$<$double$>$(x / y)}) an \index{integer division}\emph{integer division} has already been
performed \emph{before} the cast has had a chance to convert the type of an
operand to \texttt{double}.

\item  When converting \texttt{enum} values to \texttt{int} values (in any
direction). \ \\ 

Here the two types use identical representations, but different
semantics. Assigning an ordinary \texttt{enum} value to an \texttt{int} doesn't require
a cast, but when the enum is a \emph{strongly typed enum} a cast \emph{is}
required. Conversely, a \texttt{static\_cast} is required when assigning an \texttt{int}
value to a variable of some enum type. Here is an example:
    \begin{verbatim}
enum class Enum
{
    VALUE
};

cout << static_cast<int>(Enum::VALUE);    // show the numeric value
\end{verbatim}
\item  When converting related pointers to each other.\ \\ 

The \texttt{static\_cast} is used in the context of class inheritance
(cf. chapter \ref{INHERITANCE}) to convert a pointer to a so-called `derived
class' to a pointer to its `base class'. It cannot be used for casting
unrelated types to each other (e.g., a \texttt{static\_cast} can\emph{not} be used to
cast a pointer to a \texttt{short} to a pointer to an \texttt{int}).

A \texttt{void $*$} is a \emph{generic pointer}. It is frequently used by
functions in the \textbf{C} library (e.g., \textbf{memcpy}(3)). Since it is the generic
pointer it is related to any other pointer, and a \texttt{static\_cast} should be
used to convert a \texttt{void $*$} to an intended destination pointer. This is a
somewhat awkward left-over from \textbf{C}, which should probably only be used in
that context. Here is an example:

The \texttt{qsort} function from the \textbf{C} library expects a pointer to a
(comparison) function having two \texttt{void const $*$} parameters. In fact, these
parameters point to data elements of the array to be sorted, and so the
comparison function must cast the \texttt{void const $*$} parameters to pointers to
the elements of the array to be sorted. So, if the array is an \texttt{int array{[}{]}}
and the compare function's parameters are \texttt{void const $*$p1} and \texttt{void const
$*$p2} then the compare function obtains the address of the \texttt{int} pointed
to by \texttt{p1} by using:
    \begin{verbatim}
static_cast<int const *>(p1);
\end{verbatim}
\item  When undoing or introducing the signed-modifier of an \texttt{int}-typed
variable (remember that a \texttt{static\_cast} is allowed to change the
expression's representation!). \ \\ 

Here is an example: the \textbf{C} function \texttt{tolower} requires an \texttt{int}
representing the value of an \texttt{unsigned char}. But \texttt{char} by default is a
signed type. To call \texttt{tolower} using an available \texttt{char ch} we should use:
        \begin{verbatim}
        tolower(static_cast<unsigned char>(ch))
\end{verbatim}
\end{itemize}

\subsection{The `const\_cast'-operator}
    \typeout{Original Yodl file: first/constcast}The \texttt{const} keyword has been given a special place in casting. Normally
anything \texttt{const} is \texttt{const} for a good reason. Nonetheless situations
may be encountered where the \texttt{const} can be ignored. For these special
situations the \texttt{const\_cast} should be used. Its syntax is:
                     \begin{verbatim}
        const_cast<type>(expression)
\end{verbatim}
A \index{const\_cast\textless{}type\textgreater{}(expression)}\texttt{const\_cast$<$type$>$(expression)} expression is used to undo the
\texttt{const} attribute of a (pointer) type.

The need for a \texttt{const\_cast} may occur in combination with functions from
the standard \textbf{C} library which traditionally weren't always as const-aware
as they should. A function \texttt{strfun(char $*$s)} might be available, performing
some operation on its \texttt{char $*$s} parameter without actually modifying the
characters pointed to by \texttt{s}. Passing \texttt{char const hello{[}{]} = "hello";} to
\texttt{strfun} produces the warning
   \begin{verbatim}
        passing `const char *' as argument 1 of `fun(char *)' discards const
\end{verbatim}
A \texttt{const\_cast} is the appropriate way to prevent the warning:
                 \begin{verbatim}
        strfun(const_cast<char *>(hello));
\end{verbatim}
\subsection{The `reinterpret\_cast'-operator}
    \typeout{Original Yodl file: first/reinterpretcast}The third new-style cast is used to change the \emph{interpretation} of
information: the \texttt{reinterpret\_cast}. It is somewhat reminiscent of the
\texttt{static\_cast}, but \texttt{reinterpret\_cast} should only be used when it is
\emph{known} that the information as defined in fact is or can be interpreted as
something completely different. Its syntax is:
        \begin{verbatim}
        reinterpret_cast<pointer type>(pointer expression)
\end{verbatim}
Think of the \texttt{reinterpret\_cast} as a cast offering a poor-man's union:
the same memory location may be interpreted in completely different ways.

The \texttt{reinterpret\_cast} is used, for example, in combination with the
\texttt{write} function that is available for \emph{streams}. In \textbf{C++} streams are
the preferred interface to, e.g., disk-files. The standard streams like
\texttt{std::cin} and \texttt{std::cout} also are stream objects.

Streams intended for writing (`output streams' like \texttt{cout}) offer \texttt{write}
members having the prototype
        \begin{verbatim}
        write(char const *buffer, int length)
\end{verbatim}
To write the value stored within a \texttt{double} variable to a stream in its
un-interpreted binary form the stream's \texttt{write} member is used. However, as
a \texttt{double $*$} and a \texttt{char $*$} point to variables using different and
unrelated representations, a \texttt{static\_cast} cannot be used. In this case a
\texttt{reinterpret\_cast} is required. To write the raw bytes of a variable
\texttt{double value} to \texttt{cout} we use:
        \begin{verbatim}
    cout.write(reinterpret_cast<char const *>(&value), sizeof(double));
\end{verbatim}
All casts are potentially dangerous, but the \texttt{reinterpret\_cast} is the
most dangerous of them all. Effectively we tell the compiler: back off, we
know what we're doing, so stop fuzzing. All bets are off, and we'd better
\emph{do} know what we're doing in situations like these. As a case in point
consider the following code:
        \begin{verbatim}
    int value = 0x12345678;     // assume a 32-bits int

    cout << "Value's first byte has value: " << hex <<
            static_cast<int>(
                *reinterpret_cast<unsigned char *>(&value)
                            );
\end{verbatim}
The above code produces different results on little and big endian
computers. Little endian computers show the value 78, big endian
computers the value 12. Also note that the different representations used by
little and big endian computers renders the previous example
(\texttt{cout.write(...)}) non-portable over computers of different architectures.

As a \index{rule of thumb}rule of thumb: if circumstances arise in which casts \emph{have} to be
used, clearly document the reasons for their use in your code, making double
sure that the cast does not eventually cause a program to misbehave. Also:
avoid \texttt{reinterpret\_casts} unless you \emph{have} to use them.

\subsection{The `dynamic\_cast'-operator}
    \typeout{Original Yodl file: first/dynamiccast}Finally there is a new style cast that is used in combination with
polymorphism (see chapter \ref{POLYMORPHISM}). Its syntax is:
                    \begin{verbatim}
        dynamic_cast<type>(expression)
\end{verbatim}
Different from the \texttt{static\_cast}, whose actions are completely determined
\emph{compile-time}, the \texttt{dynamic\_cast}'s actions are determined \emph{run-time} to
convert a pointer to an object of some class (e.g., \texttt{Base}) to a pointer to
an object of another class (e.g., \texttt{Derived}) which is found further down its
so-called \emph{class hierarchy} (this is also called \emph{downcasting}).

At this point in the \emph{Annotations} a \texttt{dynamic\_cast} cannot yet be
discussed extensively, but we return to this topic in section
\ref{DYNAMICCAST}.

\subsection{Casting 'shared\_ptr' objects}
    \typeout{Original Yodl file: first/sharedcast}This section can safely be skipped without loss of continuity.

In the context of the class \texttt{shared\_ptr}, which is covered in section
\ref{SHAREDPTR}, several more new-style casts are available.  Actual coverage of
these specialized casts is postponed until section \ref{SHAREDCAST}.

These specialized casts are:
    \begin{itemize}
    \item \texttt{static\_pointer\_cast}, returning a \texttt{shared\_ptr} to the base-class
section of a derived class object;
    \item \texttt{const\_pointer\_cast}, returning a \texttt{shared\_ptr} to a non-const object
from a \texttt{shared\_ptr} to a constant object;
    \item \texttt{dynamic\_pointer\_cast}, returning a \texttt{shared\_ptr} to a derived class
object from a \texttt{shared\_ptr} to a base class object.
    \end{itemize}

\section{Keywords and reserved names in C++}
\typeout{Original Yodl file: first/keywords}\textbf{C++}'s  \index{keywords}keywords are a superset of \textbf{C}'s  keywords. Here is a
list of all keywords of the language:
    
        \begin{verbatim}
alignas         char16_t   double       long      reinterpret_cast true     
alignof         char32_t   dynamic_cast module    requires         try      
and             class      else         mutable   return           typedef  
and_eq          co_await   enum         namespace short            typeid   
asm             co_return  explicit     new       signed           typename 
atomic_cancel   co_yield   export       noexcept  sizeof           union    
atomic_commit   compl      extern       not       static           unsigned 
atomic_noexcept concept    false        not_eq    static_assert    using    
auto            const      float        nullptr   static_cast      virtual  
bitand          const_cast for          operator  struct           void     
bitor           constexpr  friend       or        switch           volatile 
bool            continue   goto         or_eq     synchronized     wchar_t  
break           decltype   if           private   template         while    
case            default    import       protected this             xor      
catch           delete     inline       public    thread_local     xor_eq   
char            do         int          register  throw
\end{verbatim}
Notes:
    \begin{itemize}

    \item  Since the \index{C++17}C++17 standard the keyword \index{register}\texttt{register} is no longer
        used, but it remains a reserved identifier. In other words, definitions
        like \begin{verbatim}
    register int index;
\end{verbatim}
result in compilation errors. Also, \texttt{register} is no longer
        considered a \index{storage class specifier}storage class specifier (storage class specifiers are
        \texttt{extern, thread\_local, mutable} and \texttt{static}).
    \item  the \index{operator: keywords}\emph{operator keywords}: 
\texttt{
    and, and\_eq, bitand, bitor, compl, not, not\_eq, or, or\_eq, xor} and
\texttt{xor\_eq} are symbolic alternatives for, respectively, \texttt{\&\&, \&=, \&, \textbar{}, \textasciitilde{}, !,
!=, \textbar{}\textbar{}, \textbar{}=, \textasciicircum{}} and \texttt{\textasciicircum{}=}.
    \item  \textbf{C++} also recognizes the special identifiers \texttt{final, override,
transaction\_safe}, and \texttt{transaction\_safe\_override}. These identifiers are
special in the sense that they acquire special meanings when declaring classes
or polymorphic functions. Section \ref{FINAL} provides further details.
    \end{itemize}

Keywords can only be used for their intended purpose and cannot be used as
names for other entities (e.g., variables, functions, class-names, etc.). In
addition to keywords \index{identifiers starting with an underscore}identifiers starting with an underscore and living in
the \index{global namespace}\emph{global namespace} (i.e., not using any explicit namespace or using the
mere \texttt{::} namespace specification) or living in the \emph{std namespace} are
 \index{reserved identifiers}reserved identifiers in the sense that their use is a prerogative of the
implementor.


\cleardoublepage\chapter{Namespaces}\label{NAMESPACE}
\typeout{Original Yodl file: namespaces}\section{Namespaces}\label{Namespaces}
\typeout{Original Yodl file: namespaces/intro}Imagine a math teacher who wants to develop an interactive math program. For
this program functions like \texttt{cos, sin, tan} etc. are to be used
accepting arguments in degrees rather than arguments in
radians. Unfortunately, the function name \texttt{cos} is already in use, and that
function accepts radians as its arguments, rather than degrees.

Problems like these are usually solved by defining another name, e.g., the
function name \texttt{cosDegrees} is defined. \textbf{C++} offers an alternative
solution through \index{namespace}\emph{namespaces}. Namespaces can be considered as
areas or regions in the code in which identifiers may be defined. Identifiers
defined in a namespace normally won't conflict with names already defined
elsewhere (i.e., outside of their namespaces). So, a function \texttt{cos}
(expecting angles in degrees) could be defined in a namespace
\texttt{Degrees}. When calling \texttt{cos} from within \texttt{Degrees} you would call the
\texttt{cos} function expecting degrees, rather than the standard \texttt{cos} function
expecting radians.

\subsection{Defining namespaces}
    \typeout{Original Yodl file: namespaces/defining}Namespaces are defined according to the following syntax:
        \begin{verbatim}
    namespace identifier
    {
        // declared or defined entities
        // (declarative region)
    }
\end{verbatim}
The identifier used when defining a namespace is a standard \textbf{C++}
identifier.

Within the \index{declarative region}\emph{declarative region}, introduced in the above code example,
functions, variables, structs, classes and even (nested) namespaces can be
defined or declared. Namespaces cannot be defined within a function
body. However, it is possible to define a namespace using multiple
\emph{namespace} declarations. Namespaces are `\emph{open}' meaning that
a namespace \texttt{CppAnnotations} could be defined in a file \texttt{file1.cc} and
also in a file \texttt{file2.cc}. Entities defined in the \texttt{CppAnnotations}
namespace of files \texttt{file1.cc} and \texttt{file2.cc} are then united in one
\texttt{CppAnnotations} namespace region. For example:
        \begin{verbatim}
    // in file1.cc
    namespace CppAnnotations
    {
        double cos(double argInDegrees)
        {
            ...
        }
    }

    // in file2.cc
    namespace CppAnnotations
    {
        double sin(double argInDegrees)
        {
            ...
        }
    }
\end{verbatim}
Both \texttt{sin} and \texttt{cos} are now defined in the same
\texttt{CppAnnotations} namespace.

Namespace entities can be defined outside of their namespaces. This
topic is discussed in section \ref{OUTSIDE}.

\subsubsection{Declaring entities in namespaces}
        \typeout{Original Yodl file: namespaces/declaring}    Instead of \emph{defining} entities in a namespace, entities may also be
\emph{declared} in a namespace. This allows us to put all the
    \index{namespace declarations} declarations in a header file that can
thereupon be included in sources using the entities defined in the
namespace. Such a header file could contain, e.g.,
        \begin{verbatim}
    namespace CppAnnotations
    {
        double cos(double degrees);
        double sin(double degrees);
    }
\end{verbatim}
\subsubsection{A closed namespace}
        \typeout{Original Yodl file: namespaces/closed}Namespaces can be defined without a name. Such an \index{namespace: anonymous}
anonymous namespace restricts the visibility of the defined entities to the
source file defining the anonymous namespace.

Entities defined in the anonymous namespace are comparable to \textbf{C}'s
\index{static}\texttt{static} functions and variables. In \textbf{C++} the \texttt{static} keyword can
still be used, but its preferred use is in \texttt{class} definitions (see
chapter \ref{Classes}). In situations where in \textbf{C} static variables or
functions would have been used the  anonymous namespace should be used in
\textbf{C++}.

The anonymous namespace is a \index{namespace: closed} closed namespace: it is not
possible to add entities to the same anonymous namespace using different
source files.

\subsection{Referring to entities}
    \typeout{Original Yodl file: namespaces/referring}Given a namespace and its entities, the \index{scope resolution operator}scope resolution operator can be
used to refer to its entities. For example, the function \texttt{cos()}
defined in the \texttt{CppAnnotations} namespace may be used as follows:
        \begin{verbatim}
    // assume CppAnnotations namespace is declared in the
    // following header file:
    #include <cppannotations>

    int main()
    {
        cout << "The cosine of 60 degrees is: " <<
                CppAnnotations::cos(60) << '\n';
    }
\end{verbatim}
This is a rather cumbersome way to refer to the \texttt{cos()} function in the
\texttt{CppAnnotations} namespace, especially so if the function is frequently
used. In cases like these an \emph{abbreviated} form can be
used after specifying a \index{using declaration}\emph{using declaration}. Following
        \begin{verbatim}
    using CppAnnotations::cos;  // note: no function prototype,
                                // just the name of the entity
                                // is required.
\end{verbatim}
calling \texttt{cos} results in a call of the \texttt{cos} function defined in the
\texttt{CppAnnotations} namespace. This implies that the standard \texttt{cos}
function, accepting radians, is not automatically called anymore. To call that
latter \texttt{cos} function the plain
scope resolution operator should be used:
        \begin{verbatim}
    int main()
    {
        using CppAnnotations::cos;
        ...
        cout << cos(60)         // calls CppAnnotations::cos()
            << ::cos(1.5)       // call the standard cos() function
            << '\n';
    }
\end{verbatim}
A \texttt{using} declaration can have restricted scope. It can be used inside a
block. The \texttt{using} declaration prevents the definition of entities having
the same name as the one used in the \texttt{using} declaration. It is not possible
to specify a \texttt{using} declaration for a variable \texttt{value} in some namespace,
and to define (or declare) an identically named object in a block also
containing a \texttt{using} declaration. Example:
        \begin{verbatim}
    int main()
    {
        using CppAnnotations::value;
        ...
        cout << value << '\n';  // uses CppAnnotations::value
        int value;              // error: value already declared.
    }
\end{verbatim}
\subsubsection{The `using' directive}
        \typeout{Original Yodl file: namespaces/directive}A generalized alternative to the \texttt{using} declaration is the
\index{using directive}\emph{using directive}:
        \begin{verbatim}
    using namespace CppAnnotations;
\end{verbatim}
Following this directive, \emph{all} entities defined in the
\texttt{CppAnnotations} namespace are used as if they were declared by \texttt{using}
declarations.

While the \texttt{using} directive is a quick way to
 \index{namespace: import all names} import all the names of a namespace (assuming
the namespace has previously been declared or defined), it is at the same time
a somewhat dirty way to do so, as it is less clear what entity is actually
used in a particular block of code.

If, e.g., \texttt{cos} is defined in the \texttt{CppAnnotations} namespace,
\texttt{CppAnnotations::cos} is going to be used when \texttt{cos} is called. However,
if \texttt{cos} is \emph{not} defined in the \texttt{CppAnnotations} namespace, the
standard \texttt{cos} function will be used. The \texttt{using} directive does not
document as clearly as the \texttt{using} declaration what entity will actually be
used. Therefore use caution when applying the \texttt{using} directive.

Namespace declarations are context sensitive: when a \texttt{using namespace}
declaration is specified inside a compound statement then the declaration is
valid until the compound statement's closing curly brace has been
encountered. In the next example a string \texttt{first} is defined without
explicit specifying \texttt{std::string}, but once the compound statement has ended
the scope of the \texttt{using namespace std} declaration has also ended, and so
\texttt{std::} is required once again when defining \texttt{second}:
        \begin{verbatim}
    #include <string>
    int main()
    {
        {
            using namespace std;
            string first;
        }
        std::string second;
    }
\end{verbatim}
A \texttt{using namespace} directive cannot be used within the
declaration block of a class- or enumeration-type. E.g., the following example
won't compile:
        \begin{verbatim}
    struct Namespace
    {
        using namespace std;      // won't compile
    };
\end{verbatim}
\subsubsection{`Koenig lookup'}
        \typeout{Original Yodl file: namespaces/koenig}If \index{Koenig lookup}\emph{Koenig lookup} were called the `Koenig principle', it could have been
the title of a new \index{Ludlum}Ludlum novel. However, it is not. Instead it refers to
a \textbf{C++} technicality.

`Koenig lookup' refers to the fact that if a function is called without
specifying its namespace, then the namespaces of its argument types are used
to determine the function's namespace. If the namespace in which the argument
types are defined contains such a function, then that function is used. This
procedure is called the `Koenig lookup'.

As an illustration consider the next example. The function
\texttt{FBB::fun(FBB::Value v)} is defined in the \texttt{FBB} namespace. It
can be called without explicitly mentioning its namespace:
        \begin{verbatim}
    #include <iostream>

    namespace FBB
    {
        enum Value        // defines FBB::Value
        {
            FIRST
        };

        void fun(Value x)
        {
            std::cout << "fun called for " << x << '\n';
        }
    }

    int main()
    {
        fun(FBB::FIRST);    // Koenig lookup: no namespace
                            // for fun() specified
    }
    /*
        generated output:
    fun called for 0
    */
\end{verbatim}
    The compiler is rather smart when handling namespaces. If \texttt{Value} in the
\texttt{namespace FBB} would have been defined as \texttt{using Value = int} then
\texttt{FBB::Value} would be recognized as \texttt{int}, thus causing the Koenig lookup
to fail.

As another example, consider the next program. Here two namespaces are
involved, each defining their own \texttt{fun} function. There is no
ambiguity, since the argument defines the namespace and \texttt{FBB::fun} is
called:
        \begin{verbatim}
    #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
    */
\end{verbatim}
Here is an example in which there \emph{is} an ambiguity: \texttt{fun} has two
arguments, one from each namespace. The ambiguity must be resolved by the
programmer:
        \begin{verbatim}
    #include <iostream>

    namespace ES
    {
        enum Value        // defines ES::Value
        {
            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
    */
\end{verbatim}
An interesting subtlety with namespaces is that definitions in one
namespace may break the code defined in another namespace. It shows that
namespaces may affect each other and that namespaces may backfire if we're not
aware of their peculiarities. Consider the following example:
        \begin{verbatim}
    namespace FBB
    {
        struct Value
        {};

        void fun(int x);
        void gun(Value x);
    }

    namespace ES
    {
        void fun(int x)
        {
            fun(x);
        }
        void gun(FBB::Value x)
        {
            gun(x);
        }
    }
\end{verbatim}
    Whatever happens, the programmer'd better not use any of the functions
defined in the \texttt{ES} namespace, since that would result in infinite
recursion. However, that's not the point. The point is that the programmer
won't even be given the opportunity to call \texttt{ES::fun} since the compilation
fails.

Compilation fails for \texttt{gun} but not for \texttt{fun}. But why is that so? Why
is \texttt{ES::fun} flawlessly compiling while \texttt{ES::gun} isn't? In \texttt{ES::fun}
\texttt{fun(x)} is called. As \texttt{x}'s type is not defined in a namespace the Koenig
lookup does not apply and \texttt{fun} calls itself with infinite recursion.

With \texttt{ES::gun} the argument is defined in the \texttt{FBB}
namespace. Consequently, the \texttt{FBB::gun} function is a possible candidate to
be called. But \texttt{ES::gun} itself also is possible as \texttt{ES::gun}'s prototype
perfectly matches the call \texttt{gun(x)}.

Now consider the situation where \texttt{FBB::gun} has not yet been
declared. Then there is of course no ambiguity. The programmer responsible for
the \texttt{ES} namespace is resting happily. Some time after that the programmer
who's maintaining the \texttt{FBB} namespace decides it may be nice to add a
function \texttt{gun(Value x)} to the \texttt{FBB} namespace. Now suddenly the code in
the namespace \texttt{ES} breaks because of an addition in a completely other
namespace (\texttt{FBB}). Namespaces clearly are not completely independent of each
other and we should be aware of subtleties like the above. Later in the
\textbf{C++} Annotations (chapter \ref{OVERLOADING}) we'll return to this issue.

\emph{Koenig lookup} is only used in the context of namespaces. If a function
is defined outside of a namespace, defining a parameter of a type that's
defined inside a namespace, and that namespace also defines a function with an
identical signature, then the compiler reports an ambiguity when that function
is called. Here is an example, assuming the abovementioned namespace \texttt{FBB}
is also available:
        \begin{verbatim}
    void gun(FBB::Value x);

    int main(int argc, char **argv)
    {
        gun(FBB::Value{});          // ambiguity: FBB::gun and ::gun can both
                                    // be called.
    }
\end{verbatim}
\subsection{The standard namespace}
    \typeout{Original Yodl file: namespaces/std}The \texttt{std} namespace is reserved by \textbf{C++}. The standard defines many
entities that are part of the runtime available software (e.g., \texttt{cout, cin,
cerr}); the templates defined in the \emph{Standard Template Library} (cf.
chapter \ref{STL}); and the \emph{Generic Algorithms} (cf. chapter \ref{GENERIC})
are defined in the \texttt{std} namespace.

Regarding the discussion in the previous section, \texttt{using}
declarations may be used when referring to entities in the \texttt{std} namespace.
For example, to use the \texttt{std::cout}
stream, the code may declare this object as follows:
        \begin{verbatim}
    #include <iostream>
    using std::cout;
\end{verbatim}
Often, however, the identifiers defined in the \texttt{std} namespace can all
be accepted without much thought. Because of that, one frequently encounters a
\texttt{using} directive, allowing the programmer to omit a namespace prefix when
referring to any of the entities defined in the namespace specified with the
\texttt{using} directive. Instead of specifying  \texttt{using} declarations the
following \texttt{using} directive is frequently encountered:
construction like
        \begin{verbatim}
    #include <iostream>
    using namespace std;
\end{verbatim}
Should a \texttt{using} directive, rather than \texttt{using} declarations be used?
As a \index{rule of thumb}rule of thumb one might decide to stick to \texttt{using} declarations, up
to the point where the list becomes impractically long, at which point a
\texttt{using} directive could be considered.

Two \index{using: restrictions} restrictions apply to \texttt{using} directives and
declarations:
    \begin{itemize}
    \item  Programmers should not declare or define anything inside the
\texttt{namespace std}. This is \emph{not} compiler enforced but is imposed upon user
code by the standard;
    \item  \texttt{Using} declarations and directives should not be imposed upon
code written by third parties. In practice this means that \texttt{using}
directives and declarations should be banned from header files and should only
be used in source files (cf. section \ref{NAMESPACEHDR}).
    \end{itemize}

\subsection{Nesting namespaces and namespace aliasing}
    \typeout{Original Yodl file: namespaces/nesting}Namespaces can be nested. Here is an example:
        \begin{verbatim}
    namespace CppAnnotations
    {
        int value;
        namespace Virtual
        {
            void *pointer;
        }
    }
\end{verbatim}
The variable \texttt{value} is defined in the \texttt{CppAnnotations}
namespace. Within the \texttt{CppAnnotations} namespace another namespace
(\texttt{Virtual}) is nested. Within that latter namespace the variable
\texttt{pointer} is defined. To refer to these
variable the following options are available:
    \begin{itemize}
    \item  The \index{fully qualified name}\emph{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:
   \begin{verbatim}
int main()
{
    CppAnnotations::value = 0;
    CppAnnotations::Virtual::pointer = 0;
}
\end{verbatim}
\item  A \texttt{using namespace CppAnnotations} directive can be provided. Now
        \texttt{value} can be used without any prefix, but \texttt{pointer} must be used
        with the \texttt{Virtual::} prefix:
   \begin{verbatim}
using namespace CppAnnotations;

int main()
{
    value = 0;
    Virtual::pointer = 0;
}
\end{verbatim}
\item  A \texttt{using namespace} directive for the full namespace chain can be
        used. Now \texttt{value} needs its \texttt{CppAnnotations} prefix again, but
        \texttt{pointer} doesn't require a prefix anymore:
   \begin{verbatim}
using namespace CppAnnotations::Virtual;

int main()
{
    CppAnnotations::value = 0;
    pointer = 0;
}
\end{verbatim}
\item  When using two separate \texttt{using namespace} directives none of the
        namespace prefixes are required anymore:
   \begin{verbatim}
using namespace CppAnnotations;
using namespace Virtual;

int main()
{
    value = 0;
    pointer = 0;
}
\end{verbatim}
\item  The same can be accomplished (i.e., no namespace prefixes) for
        specific variables by providing specific \texttt{using} declarations:
   \begin{verbatim}
using CppAnnotations::value;
using CppAnnotations::Virtual::pointer;

int main()
{
    value = 0;
    pointer = 0;
}
\end{verbatim}
\item  A combination of \texttt{using namespace} directives and \texttt{using}
        declarations can also be used. E.g., a \texttt{using namespace} directive
        can be used for the \texttt{CppAnnotations::Virtual} namespace, and a
        \texttt{using} declaration can be used for the \texttt{CppAnnotations::value}
        variable:
   \begin{verbatim}
using namespace CppAnnotations::Virtual;
using CppAnnotations::value;

int main()
{
    value = 0;
    pointer = 0;
}
\end{verbatim}
\end{itemize}

Following a \texttt{using namespace} directive all entities of that namespace
can be used without any further prefix. If a single \texttt{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 \texttt{using namespace} directives or
\texttt{using} declarations namespace qualifications can be omitted.

When fully qualified names are preferred but a long name like
        \begin{verbatim}
    CppAnnotations::Virtual::pointer
\end{verbatim}
is considered too long, a \index{namespace alias}\emph{namespace alias} may be used:
        \begin{verbatim}
    namespace CV = CppAnnotations::Virtual;
\end{verbatim}
This defines \texttt{CV} as an \emph{alias} for the full name. The
variable \texttt{pointer} may now be accessed using:
        \begin{verbatim}
    CV::pointer = 0;
\end{verbatim}
A namespace alias can also be used in a \texttt{using namespace} directive or
\texttt{using} declaration:
        \begin{verbatim}
    namespace CV = CppAnnotations::Virtual;
    using namespace CV;
\end{verbatim}
\textbf{Nested namespace definitions}

Starting with the C++17 standard, when nesting namespaces a nested
namespace can directly be referred to using scope resolution operators. E.g.,
        \begin{verbatim}
    namespace Outer::Middle::Inner
    { 
        // entities defined/declared here are defined/declared in the Inner
        // namespace, which is defined in the Middle namespace, which is
        // defined in the Outer namespace
    }
\end{verbatim}
\subsubsection{Defining entities outside of their namespaces}\label{OUTSIDE}
        \typeout{Original Yodl file: namespaces/outside}It is not strictly necessary to \index{define members of namespaces}define members of namespaces inside a
namespace region. But before an entity is defined \emph{outside} of a namespace
it must have been declared \emph{inside} its namespace.

To define an entity outside of its namespace its name must be \emph{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 \texttt{A::B}
within the region of namespace \texttt{A}.

Assume the type \texttt{int INT8{[}8{]}} is defined in the \texttt{CppAnnotations::Virtual}
namespace. Furthermore assume that it is our intent to define a function
\texttt{squares}, inside the namespace \ \\ 
 \texttt{CppAnnotations::Virtual} returning a
pointer to \texttt{CppAnnotations::Virtual::INT8}.

Having defined the prerequisites within the \texttt{CppAnnotations::}\texttt{Virtual}
namespace, our function could be defined as follows (cf. chapter \ref{MEMORY}
for coverage of the memory allocation operator \texttt{new{[}{]}}):
        \begin{verbatim}
    namespace CppAnnotations
    {
        namespace Virtual
        {
            void *pointer;

            using INT8 = int[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;
            }
        }
    }
\end{verbatim}
The function \texttt{squares} defines an array of one \texttt{INT8} vector, and
returns its address after initializing the vector by the squares of the first
eight natural numbers.

Now the function \texttt{squares} can be defined outside of the
\texttt{CppAnnotations::}\texttt{Virtual} namespace:
        \begin{verbatim}
    namespace CppAnnotations
    {
        namespace Virtual
        {
            void *pointer;

            using INT8 = int[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;
    }
\end{verbatim}
In the above code fragment note the following:
    \begin{itemize}
    \item \texttt{squares} is declared inside of the \texttt{CppAnnotations::Virtual}
namespace.
    \item \texttt{} The definition outside of the namespace region requires us to use
the fully qualified name of the function \emph{and} of its return type.
    \item \texttt{} \emph{Inside} the body of the function \texttt{squares} we are within the
\texttt{CppAnnotations::}\texttt{Virtual} namespace, so inside the function fully
qualified names (e.g., for \texttt{INT8}) are not required any more.
    \end{itemize}

Finally, note that the function could also have been defined in the
\texttt{CppAnnotations} region. In that case the \texttt{Virtual} namespace would have
been required when defining \texttt{squares()} and when specifying its return type,
while the internals of the function would remain the same:
        \begin{verbatim}
    namespace CppAnnotations
    {
        namespace Virtual
        {
            void *pointer;

            using INT8 = int[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;
        }
    }
\end{verbatim}
\section{The std::chrono namespace (handling time)}\label{TIMESPEC}
\typeout{Original Yodl file: namespaces/chrono/intro}The \textbf{C} programming language offers tools like \textbf{sleep}(3) and
\textbf{select}(2) to suspend program execution for a certain amount of time. And
of course the family of \textbf{time}(3) functions for setting and displaying time

\texttt{Sleep} and \texttt{select} can be used for waiting, but as they were designed in
an era when multi threading was unavailable, their usefulness is
limited when used in multi threaded programs. Multi threading has become part
of \textbf{C++} (covered in detail in chapter \ref{THREADING}), and additional
time-related functions are available in the \texttt{std::filesystem} namespace,
covered below in this chapter. 

In multi threaded programs threads are frequently suspended, albeit usually
for a very short time. E.g., when a thread wants to access a variable, but the
variable is currently being updated by another thread, then the former thread
should wait until the latter thread has completed the update. Updating a
variable usually doesn't take much time, but if it takes an unexpectedly long
time, then the former thread may want to be informed about that, so it can do
something else while the latter thread is busy updating the
variable. Interactions between threads like these cannot be realized with
functions like \texttt{sleep} and \texttt{select}.

The \index{chrono}\texttt{std::chrono} namespace bridges the gap between the
traditionally available time-related functions and the time-related
requirements of multi-threading and of the \texttt{std::filesystem} name
space. All but the specific \texttt{std::filesystem} related time functionality is
available after including the \index{chrono: header file}\texttt{$<$chrono$>$} header file. After including the 
\index{filesystem: header file}\texttt{$<$filesystem$>$} header file the facilities of the \texttt{std::filesystem} are
available. 

Time can be measured in various resolutions: in Olympic Games time differences
of hundreds of seconds may make the distinction between gold and silver
medals, but when planning a vacation we might talk about it months before we
go on vacation. Time resolutions are specified by objects of the class
\texttt{std::ratio}, which (apart from including the \texttt{$<$chrono$>$} header file) is
also available after including the \texttt{$<$ratio$>$} header file.

Different events usually last for different amounts of time (given a specific
time resolution). Amounts of time are specified by objects of the class
\texttt{std::chrono::duration}.

Events can also be characterized by their points in time: midnight, January 1,
1970 GMT is a point in time, as is 19:00, December 5, 2010. Points in time are
specified by objects of the class \texttt{std::chrono::time\_point}. 

It's not just that resolutions, durations of events, and points in time of
events may differ, but the devices (clocks) we use for specifying time also
differ. In the past \emph{hour glasses} were used (and sometimes they're still
used when boiling eggs), but on the other hand we may use atomic clocks when
measurements should be very precise. Four different types of clocks are
available. The commonly used clock is \texttt{std::chrono::system\_clock}, but in
the context of the file system there's also a \texttt{std::chrono::file\_clock}.

In the upcoming sections the details of the \texttt{std::chrono} namespace are
covered. First we look at characteristics of time resolutions. How to
handle amounts of time given their resolutions is covered next. The next
section describes facilities for defining and handling time-points. The
relationships between these types and the various clock-types are covered
thereafter. 

In this chapter the specification \texttt{std::chrono::} is often omitted (in
practice \texttt{using namespace std} followed by \texttt{using namespace chrono} is
commonly used; \texttt{{[}std::{]}chrono::} specifications are occasionally used to
avoid ambiguities). Also, every now and then you'll encounter \emph{forward
references} to later chapters, like the reference to the chapter about
multi-threading. These are hard to avoid, but studying those chapters
at this point can safely be postponed without loss of continuity.

\subsection{Time resolutions: std::ratio}
    \typeout{Original Yodl file: namespaces/chrono/ratio}Time resolutions (or \emph{units of time}) are essential components of time
specifications. Time resolutions are defined by objects of the class
    \index{ratio}\texttt{std::ratio}. 

Before the class \texttt{ratio} can be used, the \index{ratio: header file}\texttt{$<$ratio$>$} header file must be
included. But the frquently included \texttt{$<$chrono$>$} header file already includes
the \texttt{ratio} header file.

The class \texttt{ratio} has two \emph{template arguments}. These are positive
integral numbers surrounded by pointed brackets defining, respectively, the
numerator and denominator of a fraction (by default the denominator equals
1). Examples:
        \begin{verbatim}
    ratio<1>        - representing one; 
    ratio<60>       - representing 60
    ratio<1, 1000>  - representing 1/1000.
\end{verbatim}
The class \texttt{ratio} defines two directly accessible static data
members: \texttt{num}\index{ratio: num} represents its numerator, \texttt{den}\index{ratio: den}
its denominator. A \texttt{ratio} definition by itself simply defines a certain
amount. E.g., when executing the following program
        \begin{verbatim}
    #include <ratio>
    #include <iostream>
    using namespace std;

    int main()
    {
        cout << ratio<5, 1000>::num << ',' << ratio<5, 1000>::den << '\n';
    }
\end{verbatim}
1,200 is displayed, as that's the `amount' represented by
\texttt{ratio$<$5, 1000$>$}: \texttt{ratio} simplifies its fraction whenever possible.

Several predefined \texttt{ratio} types exist. They are, like
\texttt{ratio} itself, defined in the standard namespace and can be used instead of
the more cumbersome \texttt{ratio$<$x$>$} or \texttt{ratio$<$x, y$>$} specifications:
    \begin{center}\begin{tabular}{llcllcll}

    \hline

    
 \\

    
\texttt{yocto} &   10$^{-24}$ &   & 
                     \texttt{zepto} &   10$^{-21}$ &   &  \multicolumn{2}{c}{} \\

    \hline

    
 \\

    
\texttt{atto} &   10$^{-18}$ &   & 
        \texttt{femto} &  10$^{-15}$ &   & 
        \texttt{pico} &   10$^{-12}$ \\

    
\texttt{nano} &   10$^{-9}$ &   & 
        \texttt{micro} &  10$^{-6}$ &   & 
        \texttt{milli} &  10$^{-3}$ \\

    
\texttt{centi} &  10$^{-2}$ &   & 
        \texttt{deci} &   10$^{-1}$ &  \\

    \hline

    
 \\

    
\texttt{deca} &   10$^{1}$ &   & 
        \texttt{hecto} &  10$^{2}$ &   & 
        \texttt{kilo} &   10$^{3}$ \\

    
\texttt{mega} &   10$^{6}$ &   & 
        \texttt{giga} &   10$^{9}$ &   & 
        \texttt{tera} &   10$^{12}$ \\

    
\texttt{peta} &   10$^{15}$ &   & 
        \texttt{exa} &    10$^{18}$ &  \\

    \hline

    
 \\

    
\texttt{zetta} &    10$^{21}$ &   & 
        \texttt{yotta} &    10$^{24}$ &  \\

    \hline

    
\end{tabular}\end{center}
 (\emph{note:} the definitions of the types \texttt{yocto, zepto, zetta} and \texttt{yotta}
use integral constants exceeding 64 bits. Although these constants are defined
in \textbf{C++}, they are not available on 64 bit or smaller architectures.)

Time related ratios can very well be interpreted as fractions or multiple of
seconds, with \texttt{ratio$<$1, 1$>$} representing a resolution of one second.

Here is an example showing how these abbreviations can be used:
        \begin{verbatim}
        cout << milli::num << ',' << milli::den << '\n' <<
                kilo::num << ',' << kilo::den << '\n';
\end{verbatim}
\subsection{Amounts of time: std::chrono::duration}\label{DURATION}
    \typeout{Original Yodl file: namespaces/chrono/duration}Amounts of time are specified by objects of the class
    \index{duration}\texttt{std::chrono::duration}.

Before using the class \texttt{duration} the \index{chrono: header file}\texttt{$<$chrono$>$} header file must be
included.

The class \texttt{duration} has two template arguments. A numeric type (\texttt{int64\_t}
is normally used) defining the type holding the duration's amount of time, and
a time-resolution \texttt{ratio} (called its \emph{resolution}).

Often the following predefined \texttt{duration} types are used:
    \begin{center}
    \begin{tabular}{lll}
    \hline
    \makecell[l]{\texttt{predefined:}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration type}} 
 \\
    \hline
    \makecell[l]{\texttt{nanoseconds}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration$<$int64\_t, nano$>$}} 
 \\
    \makecell[l]{\texttt{microseconds}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration$<$int64\_t, micro$>$}} 
 \\
    \makecell[l]{\texttt{milliseconds}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration$<$int64\_t, milli$>$}} 
 \\
    \makecell[l]{\texttt{seconds}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration$<$int64\_t$>$}} 
 \\
    \makecell[l]{\texttt{minutes}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration$<$int64\_t, ratio$<$60$>$$>$}} 
 \\
    \makecell[l]{\texttt{hours}}  & 
    \makecell[l]{~}  & 
    \makecell[l]{\texttt{duration$<$int64\_t, ratio$<$3600$>$$>$}} 
 \\
    \hline
\end{tabular}
\end{center}

E.g., to define a duration of 30 minutes use \texttt{minutes halfHour\{ 30 \}}.

The suffixes \texttt{h, min, s, ms, us, ns} are available for integral values,
creating the corresponding \texttt{duration} times. E.g., \texttt{minutes min =
1h} stores 60 minutes in \texttt{min}.

\textbf{Sub-types}:

\begin{itemize}
    \item \texttt{rep}: the duration's numeric type (commonly \texttt{int64\_t});
    \item \texttt{period}: the \texttt{ratio} type (like \texttt{kilo}). E.g.,
        \texttt{minutes::period::num} equals 60.
    \end{itemize}

\textbf{Constructors}:

\begin{itemize}
    \item \texttt{duration()}:\ \\ 
        the default constructor initializes the object to 0 units;
    \item \texttt{duration(Type const \&value)}:\ \\ 
        the object is initialized to \texttt{value} time units (\texttt{Type} refers to
        the duration's numeric type. E.g., when defining 
        \texttt{minutes halfHour\{ 30 \}} the argument 30 is stored inside its
        \texttt{int64\_t} data member). 
    \end{itemize}
    Copy- and move-constructors (cf. chapter \ref{MEMORY}) are available.

\textbf{Operators}:

Duration types support assignment, negation (e.g., \texttt{halfHour =
-halfHour}), addition and subtraction of duration values, and also
multiplication, division and modulo computations by numeric factors. Compound
assignment operators are also available. E.g.,
 \begin{verbatim}
    minutes time = 2 * halfHour;    // time: 60 minutes
    time += minutes{ 30 };          // time: 90 minutes 
\end{verbatim}
\textbf{Members}:

\begin{itemize}
    \item \texttt{Type count() const} returns the value stored inside the \texttt{duration}
        object. E.g., \texttt{minutes\{ 30 \}.count()} returns 30.  The following
        members are static members;

\item \texttt{duration::zero()} returns an (immutable) duration object whose
        \texttt{count} member returns 0. E.g., \texttt{seconds::zero().count()} returns
        \texttt{0s};

\item \texttt{duration::min()} returns an (immutable) duration object whose
        \texttt{count} member returns the lowest value of its \texttt{rep} type (i.e.,
        \texttt{std::numeric\_limits$<$duration::rep$>$::min()} (cf. section
        \ref{NUMLIM}));

\item \texttt{duration::max()}  returns an (immutable) duration object whose
        \texttt{count} member returns the maximum value of its \texttt{rep} type.
    \end{itemize}

\textbf{Conversions}:

The precision of left-hand side arguments of assignment operators must be
greater than or equal to the precision of the right-hand side arguments
(the left-hand argument may not lose precision). When using binary
arithmetic operators the resulting duration type has a precision equal to the
finer of the two precisions. E.g.,
 \begin{verbatim}
    cout << (1min + 1h).count() << '\n';  // shows: 61
    hours hr{ 1 };
    halfHour += hr;                 // OK
    // hr += halfHours;             // won't compile 
\end{verbatim}
Durations can be converted by the \index{duration\_cast}
\texttt{std::chrono::duration\_cast$<$destination$>$(source)} function template, where
\texttt{destination} is the destination's \texttt{duration} type and \texttt{source} is an
available \texttt{destination} object, but \texttt{duration\_cast} truncates the
destination value when \texttt{destination's} precision is less than \texttt{source's}
precision. E.g., \texttt{duration\_cast$<$minutes$>$(seconds\{ 90 \})} returns 
\texttt{minutes\{ 1 \}}.

When the left-hand side argument's precision \emph{is} less than the right-hand
side's precision some decision must be made about how to handle the loss of
precision. The following function template can be used to convert a duration
to a less precise type, returning a \texttt{double} value, which can be, e.g.,
truncated or rounded.
 \begin{verbatim}
    template <typename To, typename From>
    double durationCast(From from)
    {
        return static_cast<double>(from.count()) * 
                            To::period::den * From::period::num /
                            (To::period::num * From::period::den);
    } 
\end{verbatim}
returning a \texttt{double} value (1.5 when called as
\texttt{durationCast$<$minutes$>$(seconds\{ 90 \})}), leaving the decision how to use the
returned \texttt{double} value to the caller.

\subsection{Clocks measuring time}\label{CLOCKS}
    \typeout{Original Yodl file: namespaces/chrono/clock}Clocks are used to measure time. \textbf{C++} has several predefined \index{clock}\emph{clock}
types, defined in the \texttt{std::chrono} namespace.

Before using the \texttt{chrono} clocks the \index{chrono: header file}\texttt{$<$chrono$>$} header file must be
included.

`\texttt{Clock}' clock-types are used to define points in time and define the
following sub-types:
    \begin{itemize}
    \item  \texttt{Clock::duration}: the clock's time granularity type (by default
        using \texttt{nanoseconds}. E.g., \texttt{system\_clock::duration oneDay\{ 24h \}};

\item  \texttt{Clock::period}: the clock's \texttt{std::ratio} type. E.g., 
        \texttt{system\_clock::period::den};

\item  \texttt{Clock::rep}: the type storing amounts of time. By default using
        \texttt{int64\_t}). E.g., \texttt{system\_clock::rep amount};

\item  \texttt{Clock::time\_point}: the type storing time points (covered in the
        next section). By default using \texttt{time\_point$<$system\_clock,
        nanoseconds$>$} E.g., \texttt{system\_clock::time\_point start}.
    \end{itemize}

All clocks have a member \index{now}\texttt{now} returning the clock type's
\texttt{time\_point} corresponding to the current time (relative to the clock's
epoch). It is a static member which can be used like this:
    \texttt{system\_clock::time\_point tp = system\_clock::now()}.

Four clock types are defined in the chrono namespace:
    \begin{itemize}
        \item \index{system\_clock}\texttt{system\_clock} is the `wall clock', using the system's real time
            clock;
        \item \index{steady\_clock}\texttt{steady\_clock} is a clock whose time increases in parallel with the
            increase of real time;
        \item \index{high\_resolution\_clock}\texttt{high\_resolution\_clock} is the computer's fastest clock (i.e., the
            clock having the shortest timer-tick interval). In practice this is
            the same clock as \texttt{system\_clock}.
        \item \index{file\_clock}\texttt{file\_clock}: used for time specifications of file-system
            elements. \texttt{File\_clock} time specifications use a different
            starting (epoch) time than the other clocks, but it's easy to
            convert \texttt{file\_clock} times to/from other clock types.
    \end{itemize}

In addition to the member \texttt{now} the classes \texttt{system\_clock} and
\texttt{high\_resolution\_clock} (referred to as \texttt{Clock} below) provide two static
members:
    \begin{itemize}
    \item \index{to\_time\_t}\texttt{std::time\_t Clock::to\_time\_t(Clock::time\_point const \&tp)}\ \\  
       a \texttt{std::time\_t}\index{time\_t} value (the same type as returned by \textbf{C}'s
        \textbf{time}(2) function) converting a \texttt{time\_point} value to a
        \texttt{time\_t} value;

\item \index{from\_time\_t}\texttt{Clock::time\_point Clock::from\_time\_t(std::time\_tvseconds)}\ \\  
       the opposite conversion: returning a \texttt{time\_point} corresponding to a
        \texttt{time\_t} value.
    \end{itemize}

For example:
        \begin{verbatim}
    system_clock::time_point now = system_clock::now();
    time_t value = system_clock::to_time_t(now);
    system_clock::time_point now2 = system_clock::from_time_t(value);

    // now2 != now since time_t uses seconds, not nanoseconds    
\end{verbatim}
\subsection{Points in time: std::chrono::time\_point}\label{TIMEPOINT}
    \typeout{Original Yodl file: namespaces/chrono/timepoint}Points in time are specified by objects of the class
    \index{time\_point} \texttt{std::chrono::time\_point}.

Before using the class \texttt{time\_point} the \index{chrono: header file}\texttt{$<$chrono$>$} header file must be
included.

Like \texttt{duration} the class \texttt{time\_point} requires two template arguments: A
clock type and a duration type. The standard clock types define their own
\texttt{time\_point} types using \texttt{nanoseconds} as their duration type 
(\texttt{time\_point} by default uses \texttt{nanoseconds}).  The
following time point type definitions are therefore identical:
        \begin{verbatim}
    time_point<standard_clock, nanoseconds>
    time_point<standard_clock>
    standard_clock::time_point 
\end{verbatim}
\textbf{Constructors}:
    \begin{itemize}
    \item \texttt{time\_point()}:\ \\ 
       the default constructor is initialized to the beginning of the clock's
        \index{epoch}\emph{epoch}. For \texttt{system\_clock} it is January, 1, 1970, 00:00h, but
        note that \texttt{file\_clock::time\_point} has a different starting point
        (see the example at the end of this section);
    \end{itemize}
    Copy- and move-constructors as well as copy- and move-assignment operators
        (cf. chapter \ref{MEMORY}) are available

\textbf{Operators}:
    \begin{itemize}
    \item \texttt{time\_point \&operator+=(duration const \&amount)}
       adds the amount of time represented by \texttt{amount} to the current
        \texttt{time\_point} object;

\item \texttt{time\_point \&operator-=(duration const \&amount)} subtracts 
       the amount of time represented by \texttt{amount} from the
        current \texttt{time\_point} object;

\item \texttt{Type operator$<$$<$(std::ostream \&, time\_point const \&)} inserts a textual
        representation of the \texttt{time\_point's} UTC time into the \texttt{ostream}.
    \end{itemize}

The compound operators are also available as binary arithmetic operators using
a \texttt{time\_point const \&} and a \texttt{duration const \&} operand (in any
order). Example:
       \begin{verbatim}
    system_clock::now() + seconds{ 5 };
\end{verbatim}
\textbf{Members}:
    \begin{itemize}
    \item \index{time\_since\_epoch}\texttt{duration time\_since\_epoch() const}:\ \\ 
       \texttt{duration} is the duration type used by the time point object for
        which this member is called. To convert the returned \texttt{duration} to a
        \texttt{size\_t} value use \texttt{time\_since\_epoch().count()};

\item \texttt{time\_point min() const}:
       a static member returning the time point's \texttt{duration::min}
        value. Example:
       \begin{verbatim}
    cout << 
        time_point<system_clock>::min().time_since_epoch().count() << '\n';
        // shows -9223372036854775808
\end{verbatim}
\item \texttt{time\_point max() const}: 
       a static member returning the time point's \texttt{duration::max}
        value.
    \end{itemize}

\textbf{Conversions:}

All predefined clocks use nanoseconds for their duration types. Converting to
different \texttt{duration} types is covered in the previous section
(\ref{DURATION}). Alternatively, the members \texttt{to\_time\_t} of the
\texttt{system\_clock} and the \texttt{high\_resolution\_clock} can be used to convert
their \texttt{time\_point} values to \texttt{time\_t}. Such \texttt{time\_t} values are commonly
used to convert time to text, e.g., using the \emph{manipulator} \texttt{put\_time}
(cf. section \ref{IOFORMAT}).  The \texttt{put\_time} manipulator must be provided
with the address of a \texttt{std::tm} object, which can be obtained from a
\texttt{std::time\_t} value. See figure \ref{TIMEIMG} for a visual representation of
the involved elements.
    \begin{figure}[tbp]
\centerline{\epsffile{threading/time.eps}}
\caption{\label{TIMEIMG}Time according to \textbf{C++}}
\end{figure}

Use the following blueprint to insert a \texttt{system\_clock::time point}
value into a \texttt{std::ostream} (cf. section \ref{PUTTIME}):
    \begin{verbatim}
    int main()
    {
        auto now = system_clock::now();         // get a time_point
        cout << now << '\n';                    // now's UTC time
                                                // convert to a time_t
        time_t timeT = system_clock::to_time_t(now);
        tm *local = localtime(&timeT);          // get a tm *
        cout << put_time(local, "%c") << '\n';  // show the time
    }
\end{verbatim}
To convert a \texttt{time\_point} to another \texttt{std::chrono} clock's \texttt{time\_point}
the template
    \index{clock\_cast}
 \texttt{DestClock::time\_point std::chrono::clock\_cast$<$DestClock$>$(TimePoint tp)}
 can be used. The argument \texttt{tp} is an available \texttt{time\_point}, and
\texttt{DestClock} specifies the clock type of the returned \texttt{time\_point}. E.g.,
the following \texttt{cout} statement displays four identical times:
 \begin{verbatim}
    auto fNow = file_clock::now();
    auto sNow = file_clock::to_sys(fnow);

    cout << fNow << '\n' <<
        sNow << '\n' <<
        clock_cast<system_clock>(fNow) << '\n' <<
        clock_cast<file_clock>(sNow) << '\n'; 
\end{verbatim}
So, where is the starting point of the \texttt{file\_clock} clock? \ \\ 
 Since \texttt{time\_point's} default constructor is initialized to its clock's
starting point it can be obtained this way:
 \begin{verbatim}
    cout << file_clock::time_point{}<< '\n';
    // shows:  2174-01-01 00:00:00.000000000 
\end{verbatim}
\section{The std::filesystem namespace}\label{STDFS}
\typeout{Original Yodl file: namespaces/filesystem/intro}Computers commonly store information that must survive reboots in their file
systems. Traditionally, to manipulate the file system the \textbf{C} programming
language offers functions performing the required system calls.  Such
functions (like \textbf{rename}(2), \texttt{truncate}(2), \textbf{opendir}(2), and
\textbf{realpath}(3)) are of course also available in \textbf{C++}, but their signatures
and way of use are often less attractive as they usually expect \texttt{char const
$*$} parameters and may use static buffers or memory allocation based on
\textbf{malloc}(3) and \textbf{free}(3).

Since 2003 the \index{Boost Filesystem}\texttt{Boost library}\footnote{http://www.boost.org/doc/libs/1\_65\_1/libs/filesystem/doc/index.htm}
    offers \emph{wrappers} around these functions,
offering interfaces to those system calls that are more \textbf{C++}-like.

Currently \textbf{C++} directly supports these functions in the
\texttt{std::filesystem}\index{filesystem} namespace. These facilities can be used
after including the \index{filesystem: header file}\texttt{$<$filesystem$>$} header file.

The \texttt{filesystem} namespace is extensive: it contains more than 10 different
classes, and more than 30 free functions. To refer to the identifiers defined
in the \texttt{std::filesystem} namespace their fully qualified names (e.g.,
\texttt{std::filesystem::path}) can be used. Alternatively, after specifying
`\texttt{using namespace std::filesystem;}' the identifiers can be used without
further qualifications. Namespace specifications like `\texttt{namespace fs =
std::filesystem;}' are also encountered, allowing specifications like
\texttt{fs::path}.

Functions in the \texttt{filesystem} namespace may fail. When functions cannot
perform their assigned tasks they may throw exceptions (cf. chapter
\ref{EXCEPTIONS}) or they may assign values to \texttt{error\_code} objects that
are passed as arguments to those functions (see section \ref{ERRORCODE} below).

\subsection{The class 'error\_code'}\label{ERRORCODE}
    \typeout{Original Yodl file: namespaces/filesystem/errorcode}Objects of the class \index{std::error\_code}\texttt{std::error\_code} (note: \emph{not}
\texttt{std::filesystem::error\_code}!) encapsulate \emph{error values}, and
associated \emph{error categories} (cf. section \ref{SYSTEMERROR}; \texttt{error\_code}
can be used after including the \index{system\_error: header file}\texttt{$<$system\_error$>$} header, but it is also
available after including the \index{filesystem: header file}\texttt{$<$filesystem$>$} header file). Traditionally
error values are available as values assigned to the global \index{errno} \texttt{int
errno} variable. By convention, when \texttt{errno's} value equals zero there's no
error. This convention was adopted by \texttt{error\_code}.

Error codes can be defined for many conceptually different situations. Those
situations are characterized by their own \emph{error categories}. 

Error categories are used to associate \texttt{error\_code} objects with the errors
that are defined by those categories. Default available error categories may
use values like \texttt{EADDRINUSE} (or the equivalent \texttt{enum class errc} value
\texttt{address\_in\_use}) but new types of error categories, tailored to other
contexts, can also be defined. The \texttt{enum class errc} is defined in the
\index{bits/error\_constants.h: header file}\texttt{$<$bits/error\_constants.h$>$} header file. Error categories and how to define
them is covered near the end of the \textbf{C++} Annotations (section \ref{ERRCAT}).

\textbf{Constructors}:
    \begin{itemize}
    \item \texttt{error\_code() noexcept}:\ \\ the object is initialized with error \emph{value} 0 and the
        \texttt{system\_category} error category. Value 0 is not considered an
        error;

\item \texttt{error\_code(int ec, error\_category const \&cat) noexcept}:\ \\ the object is initialized from  error value \texttt{ec}
        (e.g., \texttt{errno}, set by a failing function), and a const reference to
         the applicable error \emph{category} (provided by, e.g.,
         \index{system\_category} \texttt{std::system\_category()} or
         \index{generic\_category} \texttt{std::generic\_category()}). Here is an example
         defining an \texttt{error\_code} object:
            \begin{verbatim}
    error_code ec{ 5, system_category() }; 
\end{verbatim}
\item \texttt{error\_code(ErrorCodeEnum value) noexcept}:\ \\ this is a member template (cf. section \ref{MEMTEMP}), using template
        header \texttt{template $<$class ErrorCodeEnum$>$}. It initializes the object
        with the return value of \texttt{make\_error\_code(value)} (see below). In
        section \ref{ERRCODEENUM} defining \texttt{ErrorCodeEnums} is
        covered.  Note: \texttt{ErrorCodeEnum} as such does not exist. It
        is a mere placeholder for existing \texttt{ErrorCodeEnum} enumerations; 
    \end{itemize}
    Copy- and move-constructors are available.

\textbf{Operators}:
    \begin{itemize}
    \item  Standard assignment operators and an assignment operator
        accepting an \texttt{ErrorCodeEnum} are available;

\item \texttt{operator std::errc() const noexcept}:\ \\ returns the object's \texttt{errc} error-code value. For \texttt{g++} these are
        defined in the \texttt{enum class errc}\index{errc} in the file
        \texttt{/usr/include/x86\_64-linux-gnu/c++/14/bits/error\_constants.h};

\item \texttt{explicit operator bool() const noexcept}:\ \\ returns \texttt{true} if the object's error value is unequal 0 (i.e., it
        represents and error).
    \end{itemize}

\textbf{Members}:
    \begin{itemize}
    \item \texttt{void assign(int val, error\_category const \&cat)}:\ \\ assigns new values to the object's error value and category. E.g,
        \texttt{ec.assign(0, generic\_category())};

\item \texttt{error\_category const \&category() const noexcept}:\ \\ returns a reference to the object's error category;

\item \texttt{void clear() noexcept}:\ \\ sets the \texttt{error\_code's} value to 0 and its error category to
        \texttt{system\_category};

\item \texttt{error\_condition default\_error\_condition() const noexcept}:\ \\ returns the current category's default error condition initialized
        with the current object's error value and error category (see section
        \ref{ERRCOND} for details about the class \texttt{error\_condition});

\item \texttt{string message() const}:\ \\ the message that is associated with the current object's error value
        is returned (equivalent to \texttt{category().message(ec.value())});

\item \texttt{int value() const noexcept}:\ \\ returns the object's error value.
    \end{itemize}

\textbf{Free functions}:
    \begin{itemize}
    \item  Two \texttt{error\_code} objects can be compared for (in) equality and can
        be ordered (using \texttt{operator$<$}). 

Ordering \texttt{error\_codes} associated with different error categories
        has no meaning. But when the error categories are identical then they
        are compared by their error code values (cf. this \texttt{SG14 discussion
        summary}\footnote{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0824r1.html});

\item \index{make\_error\_code}\texttt{error\_code make\_error\_code(errc value) noexcept}:\ \\ returns an \texttt{error\_code} object initialized with
        \texttt{static\_cast$<$int$>$(value)} and \texttt{generic\_category()}. This function
        converts an \texttt{enum class errc} value to an \texttt{error\_code}. 

Other error related enums may also be defined with which tailored
        \texttt{make\_error\_code} functions can be associated (cf. section
        \ref{ERRCODEENUM};)

\item \texttt{std::ostream \&operator$<$$<$(std::ostream \& os, error\_code const \&ec)}:\ \\ executes
    \begin{verbatim}
return os << ec.category().name() << ':' << ec.value();
\end{verbatim}
\end{itemize}

Many \texttt{filesystem} functions define an optional last \texttt{error\_code \&ec}
parameter. Those functions have \texttt{noexcept} specifications. If those
functions cannot complete their tasks, then \texttt{ec} is set to the appropriate
error code, calling \texttt{ec.clear()} if no error was encountered. If no \texttt{ec}
argument is provided then those functions throw a \texttt{filesystem\_error}
exception if they cannot complete their tasks.

\subsection{Types and permissions of file system elements: 
            file\_status}\label{FSSTATUS}
    \typeout{Original Yodl file: namespaces/filesystem/filestatus}File system entries (represented by \texttt{path} objects, cf. section \ref{PATH}
below), have attributes: permissions (e.g., the owner may modify an entry),
and types (like files, directories, and soft-links).  Those attributes are
defined in the class \texttt{std::filesystem::file\_status}.

\textbf{Types}:

\index{file\_type}
Defined in the \texttt{(std::filesystem) enum class file\_type}.

\begin{center}\begin{tabular}{ll}
    \hline
\multicolumn{2}{c}{\textbf{std::filesystem::file\_type}} \\
    \makecell[tl]{Type}  & 
    \makecell[tl]{Meaning} 
 \\
    \hline
    \makecell[tl]{\texttt{not\_found (= -1)}}  & 
    \makecell[tl]{the file system entry was not found\ \\ 
                (not considered an error)} 
 \\

        \makecell[tl]{\texttt{none}}  & 
    \makecell[tl]{the file status has not yet been evaluated\ \\ 
                 or an error occurred when evaluating the status} 
 \\

        \makecell[tl]{\texttt{regular}}  & 
    \makecell[tl]{a regular file} 
 \\

        \makecell[tl]{\texttt{directory}}  & 
    \makecell[tl]{a directory} 
 \\

        \makecell[tl]{\texttt{symlink}}  & 
    \makecell[tl]{a symbolic link} 
 \\

        \makecell[tl]{\texttt{block}}  & 
    \makecell[tl]{a block device} 
 \\

        \makecell[tl]{\texttt{character}}  & 
    \makecell[tl]{a character device} 
 \\

        \makecell[tl]{\texttt{fifo}}  & 
    \makecell[tl]{ a named pipe} 
 \\

        \makecell[tl]{\texttt{socket}}  & 
    \makecell[tl]{a socket file} 
 \\

        \makecell[tl]{\texttt{unknown}}  & 
    \makecell[tl]{an unknown file type} 
 \\

        \hline
\end{tabular}
\end{center}

\textbf{Permissions}:

\index{perms}
Defined in the \texttt{(std::filesystem) enum class perms}. 

The enumeration's symbols were defined to make their meanings more descriptive
than the constants defined in the \index{sys/stat.h: header file}\texttt{$<$sys/stat.h$>$} header file, but their
values are identical. The \texttt{enum class perms} supports all bitwise operators.

\begin{center}\begin{tabular}{lrll}
    \hline
\multicolumn{4}{c}{\textbf{std::filesystem::perms}} \\
Symbol~~ & Value & sys/stat.h &     \makecell[tl]{Meaning} 
 \\
    \hline
    \makecell[tl]{\texttt{none}}  & 
    \makecell[tr]{\texttt{0000}}  & 
    \makecell[tl]{~~~\texttt{-}\texttt{-}\texttt{-}}  & 
    \makecell[t{{p{7.5cm}}}]{No permission bits were set} 
 \\

        \makecell[tl]{\texttt{owner\_read}}  & 
    \makecell[tr]{\texttt{0400}}  & 
    \makecell[tl]{\texttt{S\_IRUSR}}  & 
    \makecell[t{{p{7.5cm}}}]{File owner has read permission} 
 \\

        \makecell[tl]{\texttt{owner\_write}}  & 
    \makecell[tr]{\texttt{0200}}  & 
    \makecell[tl]{\texttt{S\_IWUSR}}  & 
    \makecell[t{{p{7.5cm}}}]{File owner has write permission} 
 \\

        \makecell[tl]{\texttt{owner\_exec}}  & 
    \makecell[tr]{\texttt{0100}}  & 
    \makecell[tl]{\texttt{S\_IXUSR}}  & 
    \makecell[t{{p{7.5cm}}}]{File owner has execute/search\ \\ 
            permissions} 
 \\

        \makecell[tl]{\texttt{owner\_all}}  & 
    \makecell[tr]{\texttt{0700}}  & 
    \makecell[tl]{\texttt{S\_IRWXU}}  & 
    \makecell[t{{p{7.5cm}}}]{File owner has read, write, and\ \\ 
             execute/search permissions} 
 \\

        \makecell[tl]{\texttt{group\_read}}  & 
    \makecell[tr]{\texttt{0040}}  & 
    \makecell[tl]{\texttt{S\_IRGRP}}  & 
    \makecell[t{{p{7.5cm}}}]{The file's group has read permission} 
 \\

        \makecell[tl]{\texttt{group\_write}}  & 
    \makecell[tr]{\texttt{0020}}  & 
    \makecell[tl]{\texttt{S\_IWGRP}}  & 
    \makecell[t{{p{7.5cm}}}]{The file's group has write permission} 
 \\

        \makecell[tl]{\texttt{group\_exec}}  & 
    \makecell[tr]{\texttt{0010}}  & 
    \makecell[tl]{\texttt{S\_IXGRP}}  & 
    \makecell[t{{p{7.5cm}}}]{The file's group has execute/search\ \\ 
            permissions} 
 \\

        \makecell[tl]{\texttt{group\_all}}  & 
    \makecell[tr]{\texttt{0070}}  & 
    \makecell[tl]{\texttt{S\_IRWXG}}  & 
    \makecell[t{{p{7.5cm}}}]{The file's group has read, write, and\ \\ 
            execute/search permissions} 
 \\

        \makecell[tl]{\texttt{others\_read}}  & 
    \makecell[tr]{\texttt{0004}}  & 
    \makecell[tl]{\texttt{S\_IROTH}}  & 
    \makecell[t{{p{7.5cm}}}]{Other users have read permission} 
 \\

        \makecell[tl]{\texttt{others\_write}}  & 
    \makecell[tr]{\texttt{0002}}  & 
    \makecell[tl]{\texttt{S\_IWOTH}}  & 
    \makecell[t{{p{7.5cm}}}]{Other users have write permission} 
 \\

        \makecell[tl]{\texttt{others\_exec}}  & 
    \makecell[tr]{\texttt{0001}}  & 
    \makecell[tl]{\texttt{S\_IXOTH}}  & 
    \makecell[t{{p{7.5cm}}}]{Other users have execute/search\ \\ 
             permissions} 
 \\

        \makecell[tl]{\texttt{others\_all}}  & 
    \makecell[tr]{\texttt{0007}}  & 
    \makecell[tl]{\texttt{S\_IRWXO}}  & 
    \makecell[t{{p{7.5cm}}}]{Other users have read, write, and \ \\ 
            execute/search permissions} 
 \\

        \makecell[tl]{\texttt{all}}  & 
    \makecell[tr]{\texttt{0777}}  & 
    \makecell[tl]{~~~\texttt{-}\texttt{-}\texttt{-}}  & 
    \makecell[t{{p{7.5cm}}}]{All users have read, write, and\ \\ 
            execute/search permissions} 
 \\

        \makecell[tl]{\texttt{set\_uid}}  & 
    \makecell[tr]{\texttt{04000}}  & 
    \makecell[tl]{\texttt{S\_ISUID}}  & 
    \makecell[t{{p{7.5cm}}}]{Set user ID to file owner user ID on\ \\ 
            execution} 
 \\

        \makecell[tl]{\texttt{set\_gid}}  & 
    \makecell[tr]{\texttt{02000}}  & 
    \makecell[tl]{\texttt{S\_ISGID}}  & 
    \makecell[t{{p{7.5cm}}}]{Set group ID to file's user group ID on\ \\ 
             execution} 
 \\

        \makecell[tl]{\texttt{sticky\_bit}}  & 
    \makecell[tr]{\texttt{01000}}  & 
    \makecell[tl]{\texttt{S\_ISVTX}}  & 
    \makecell[t{{p{7.5cm}}}]{POSIX XSI specifies that when set on a\ \\ 
            directory only file owners may delete\ \\ 
            files even if the directory is writeable\ \\ 
             by others (used, e.g., with \texttt{/tmp})} 
 \\

        \makecell[tl]{\texttt{mask}}  & 
    \makecell[tr]{\texttt{07777}}  & 
    \makecell[tl]{~~~\texttt{-}\texttt{-}\texttt{-}}  & 
    \makecell[t{{p{7.5cm}}}]{All valid permission bits.} 
 \\

        \hline
\end{tabular}
\end{center}

\textbf{Perm\_options}:

\index{perm\_options}
The \texttt{(std::file\_system) enum class perm\_options} specifies the way file
system entries are modified

\begin{center}\begin{tabular}{ll}
    \hline
\multicolumn{2}{c}{\textbf{std::filesystem::perm\_options}} \\
    \makecell[tl]{Value}  & 
    \makecell[tl]{Meaning} 
 \\
    \hline
    \makecell[tl]{\texttt{replace}}  & 
    \makecell[tl]{current permisions are replaced new permissions} 
 \\

        \makecell[tl]{\texttt{remove}}  & 
    \makecell[tl]{the specified permissions are removed from the\ \\ 
                   file system entry's current permissions} 
 \\

        \makecell[tl]{\texttt{nofollow}}  & 
    \makecell[tl]{when the current file system entry refers\ \\ 
                to a symbolic link the permissions of the\ \\ 
                symbolic link itself are updated} 
 \\

        \hline
\end{tabular}
\end{center}

\textbf{Constructors}:

\begin{itemize}
    \item \texttt{explicit file\_status(file\_type type = file\_type::none,
                         perms permissions = perms::unknown)}
    \end{itemize}
    Copy and move constructors and assignment operators are avaialble;

\textbf{Members}:

\begin{itemize}
    \item \index{permissions}\texttt{perms permissions() const} 
        returns the permissions of the file system entry represented by the
        \texttt{file\_status} object.\ \\ 
        Refer to section \ref{FREEFS} for the function \texttt{permissions}
        changing the permissions of a file system entry; 

\item \index{type}\texttt{file\_type type() const}
       returns the type  of the file system entry to which the 
        \texttt{file\_status} object refers;

\item \texttt{void type(file\_type type)}
       changes the type of the file system entry to which the \texttt{file\_tatus}
        object refers.
    \end{itemize}

\subsubsection{The status of file system entries}\label{FSESTAT}
        \typeout{Original Yodl file: namespaces/filesystem/getstatus}The \texttt{std::path} free functions \texttt{status} and \texttt{symlink\_status}
(cf. section \ref{FREEFS}) return the \texttt{file\_status} of file system entries.

The following functions provide specific information about the status of
file system entries:

\begin{itemize}
    \item \index{status\_known}\texttt{bool status\_known(file\_status const \&status)}
       returns \texttt{true} if \texttt{status} refers to a determined status
        (\texttt{status} itself may indicate that the entity referred to by
        \texttt{status} does not exist). One way of receiving \texttt{false} is by
        passing it a default status object: \texttt{status\_known(file\_status\{\})};

\item \texttt{bool is\_WHATEVER(file\_status status)}, 
       replacing \texttt{WHATEVER} by the requested file type, returns \texttt{true} if
        \texttt{status} refers to an entry of the specified type.
    \end{itemize}

These following \texttt{is\_WHATEVER} functions are available:
    \begin{center}\begin{tabular}{ll}
    \hline
\multicolumn{2}{c}{\textbf{is\_WHATEVER(file\_status) }} \\
    \makecell[tl]{Function}  & 
    \makecell[tl]{Meaning} 
 \\
    \hline
    \makecell[tl]{\texttt{is\_block\_file}}  & 
    \makecell[tl]{'entry' is a block device} 
 \\

        \makecell[tl]{\texttt{is\_character\_file}}  & 
    \makecell[tl]{'entry' is a character device} 
 \\

        \makecell[tl]{\texttt{is\_directory}}  & 
    \makecell[tl]{'entry' is a directory} 
 \\

        \makecell[tl]{\texttt{is\_empty}}  & 
    \makecell[tl]{'entry' is an empty file or directory} 
 \\

        \makecell[tl]{\texttt{is\_fifo}}  & 
    \makecell[tl]{'entry' is a named pipe} 
 \\

        \makecell[tl]{\texttt{is\_other}}  & 
    \makecell[tl]{'entry' is not a directory,\ \\ 
                          regular file or symlink} 
 \\

        \makecell[tl]{\texttt{is\_regular\_file}}  & 
    \makecell[tl]{'entry' is a regular file} 
 \\

        \makecell[tl]{\texttt{is\_socket}}  & 
    \makecell[tl]{'entry' is a named socket} 
 \\

        \makecell[tl]{\texttt{is\_symlink}}  & 
    \makecell[tl]{'entry' is a symbolic link} 
 \\

        \hline
\end{tabular}
\end{center}

Here is a small program showing how file statuses can be obtained and
displayed (cf. sections \ref{PATH} and (for the \emph{map}) section \ref{MAP}):
    \begin{verbatim}
    namespace
    {
        std::unordered_map<file_type, char const *> statusMap =
        {
            { file_type::not_found, "an unknown file" },
            { file_type::none,      "not yet or erroneously evaluated "
                                                                "file type" },
            { file_type::regular,   "a regular file" },
            { file_type::directory, "a directory" },
            { file_type::symlink,   "a symbolic link" },
            { file_type::block,     "a block device" },
            { file_type::character, "a character device" },
            { file_type::fifo,      "a named pipe" },
            { file_type::socket,    "a socket file" },
            { file_type::unknown,   "an unknown file type" }
        };
    }
    
    int main()
    {
        cout << oct;
    
        string line;
        while (true)
        {
            cout << "enter the name of a file system entry: ";
            if (not getline(cin, line) or line.empty())
                break;
    
            path entry{ line };
    
            error_code ec;
            file_status stat = status(entry, ec);
    
            if (not status_known(stat))
            {
                cout << "status of " << entry << " is unknown. "
                                                "Ec = " << ec << '\n';
                continue;
            }
    
            cout << "status of " << entry << ": type = " <<
                     statusMap[stat.type()] <<
                     ", permissions: " <<
                        static_cast<size_t>(stat.permissions()) << '\n';
        }
    }
\end{verbatim}
\subsection{Names of file system entries: path}\label{PATH}
    \typeout{Original Yodl file: namespaces/filesystem/path}Objects of the class \texttt{filesysten::path}\index{path} commonly contain names of
file system entries. 

\textbf{Constructors}:

\begin{itemize}
    \item \texttt{path()}: the default constructor is initialized with an empty
        \texttt{path}; 
    \item \texttt{path(InputIter begin, InputIter end)}:\ \\ 
       the characters from \texttt{begin} to \texttt{end} define the \texttt{path's} name.
    \end{itemize}
 Copy- and move constructors are available, also using argument types
\texttt{std::string} and \texttt{char const $*$}.\ \\ 
    A \texttt{path} object doesn't have to refer to an existing file system
entry.\ \\ 
    Arguments of \texttt{path} constructors may contain (all optional):
    \begin{itemize}
    \item  a root-name, e.g., a disk-name (like \texttt{E:}) or device indicator
        (like \texttt{//nfs});
    \item  a root-directory, if it is the first character after the (optional)
        root-name;
    \item  filename characters (not containing directory separators). In
        addition the `single dot filename' (\texttt{.}) indicates the current
        directory and the `double dot filename' (\texttt{..}) indicates the current
        directory's parent directory;
    \item  directory separators (by default the forward slash). Multiple
        consecutive separators are automatically merged into one separator.
    \end{itemize}

The constructors also define a last \texttt{format ftmp = auto\_format}
parameter, for which in practice almost never an argument has to be provided
(for its details see \texttt{cppreference}\footnote{http://en.cppreference.com/w/cpp/experimental/fs/path}.)

\subsubsection{Accessors, modifiers and operators}
        \typeout{Original Yodl file: namespaces/filesystem/pathmembers}    \textbf{Operators:}
    \begin{itemize}
    \item \texttt{path \&operator/=(Type const \&arg)}:\ \\ 
       the arguments that can be passed to constructors can also be passed
        to this member. The \texttt{arg} argument is separated from the path's
        current content by a directory separator (unless the path is initially
        empty as in \texttt{cout $<$$<$ path\{\}.append("entry")}). See also the members
        \texttt{append} and \texttt{concat}, below. The free operator \texttt{/} accepts two
        \texttt{path} (promotable) arguments, returning a \texttt{path} containing both
        paths separated by a directory separator (e.g., \texttt{lhs / rhs} returns
        the \texttt{path} object \texttt{lhs/rhs});

\item \texttt{path \&operator+=(Type const \&arg)}:\ \\ 
       similar to \texttt{/=}, but \emph{no} directory separator is used when
        adding \texttt{arg} to the current \texttt{path};

\item  comparison operators: \texttt{path} objects can be compared using the
        (operators implied by the) \texttt{==} and \texttt{$<$=$>$} operators. Path objects
        are compared by lexicographical comparing their ascii-character
        content;

\item \texttt{ostream \&operator$<$$<$(ostream \&out, path const \&path)} (stream
        insertion) inserts \texttt{path's} content, surrounded by double quotes,
        into \texttt{out};

\item \texttt{istream \&operator$>$$>$(istream \&in, path \&path)} extracts
        \texttt{path's} content from \texttt{in}. The extracted path name may optionally
        be surrounded by double quotes. When inserting a previously extracted
        \texttt{path} object only one set of surrounding quotes are shown.
    \end{itemize}

\textbf{Accessors:} 

Accessors return specific \texttt{path} components. If a path doesn't contain
    the requested component then an empty \texttt{path} is returned.
    \begin{itemize}
    \item \texttt{char const $*$c\_str()}: the path's content is returned as an NTBS; 

\item \texttt{path extension()} returns the dot-extension of the path's last
        component (including the dot);

\item \texttt{path filename()} returns the last path-content of the current \texttt{path}
        object. See also the \texttt{stem()} accessor, below;

\item \texttt{bool is\_absolute()}: returns \texttt{true} if the \texttt{path} object contains
        an absolute path specification;

\item \texttt{bool is\_relative()}: returns \texttt{true} if the \texttt{path} object contains
        a relative path specification;

\item \texttt{path parent\_path()} returns the current path-content from which the
        last element has been removed. Note that if the \texttt{path} object
        contains a filename's path (like \texttt{"/usr/bin/zip"}) then
        \texttt{parent\_path} removes \texttt{/zip} and returns \texttt{/usr/bin}, so not
        \texttt{zip's} parent directory, but its actual directory;

\item \texttt{path relative\_path()}: returns the path's content beyond
        the path's root-directory component of the \texttt{path} object. E.g., if
        the \texttt{path ulb\{ "/usr/local/bin" \}} is defined then
        \texttt{ulb.relative\_path()} returns a path containing \texttt{"usr/local/bin"};

\item \texttt{path root\_directory()}: returns the root-directory component of the
        \texttt{path} object;

\item \texttt{path root\_name()}: returns the root-name's component of the \texttt{path}
        object;

\item \texttt{path root\_path()}: returns the root-path component of the \texttt{path}
        object;

\item \texttt{path stem()} returns the last path-content of the current \texttt{path}
        object from which the dot-extension hash been removed;

\item \texttt{string()}: returns the path's content as a \texttt{std::string}.\ \\ 
       Similar accessors are available for the following string-types:
        \texttt{wstring, u8string, u16string, , u32string, generic\_string,
        generic\_wstring, generic\_u8string, generic\_u16string,} and
        \texttt{generic\_u32string};
    \end{itemize}

Except for the family of \texttt{string()} and the \texttt{is\_...} accessors, there
    are also \texttt{bool has\_...} members returning \texttt{true} if the \texttt{path}
    contains the specified component (e.g., \texttt{has\_extension} returns \texttt{true}
    if the \texttt{path} contains an extension).

\textbf{Member functions:}
    \begin{itemize}
    \item \texttt{path \&append(Type const \&arg)} acts like the \texttt{/=} operator;

\item \texttt{path::iterator begin()} returns an iterator containing the first path
        component; Dereferencing a \texttt{path::iterator} returns a \texttt{path}
        object.\ \\ 
       When available root names and root directories are returned as initial
        components. When incrementing \texttt{path::iterators} the individual
        directories and finally filename components are returned. The
        directory separators themselves are not returned when dereferencing
        subsequent \texttt{path::iterators};

\item \texttt{path::const\_iterator begin() const} returns a iterator to the
        immutable first path component; Dereferencing a
        \texttt{path::const\_iterator} returns a \texttt{path const} object;

\item \texttt{void clear()}: the \texttt{path's} content is erased;

\item \texttt{int compare(Type const \&other)}:\ \\ 
       returns the result of lexicographically comparing the current path's
        content with \texttt{other}. \texttt{Other} can be a \texttt{path}, a string-type or
        an NTBS;

\item \texttt{path \&concat(Type const \&arg)} acts like the \texttt{+=} operator;

\item \texttt{path::iterator end()} returns an iterator beyond the last path
        component;

\item \texttt{path::const\_iterator end() const} returns an iterator beyond the
        immutable last path component 

\item \texttt{path \&remove\_filename()}:\ \\ 
       removes the last component of the stored path not ending in \texttt{/}. If
        the \texttt{path} doesn't contain a slash then the \texttt{path} object's
        cleared;

\item \texttt{path \&replace\_extension(path const \&replacement = path\{\} )}:\ \\ 
       replaces the extension of the last component of the stored path
        (including the extension's dot) with \texttt{replacement}. The extension is
        removed if \texttt{replacement} is empty. If the \texttt{path} calling
        \texttt{replace\_extension} has no extension then \texttt{replacement} is added.
        The replacement may optionally start with a dot. The path object's
        extension receives only one dot;

\item \texttt{path \&replace\_filename(path const \&replacement)}:\ \\ 
       replaces the last component of the stored path with \texttt{replacement},
        which itself may contain multiple path elements.  If only a
        root-directory is stored, then it is replaced by \texttt{replacement}. The
        member's behavior is undefined if the current path object is empty;
    \end{itemize}

\subsubsection{Free functions}\label{FREEFS}
        \typeout{Original Yodl file: namespaces/filesystem/freefunctions}\textbf{Copy\_options}:

\index{copy\_options}
Defined in the \texttt{(std::filesystem) enum class copy\_options}.

The enumeration supports bitwise operators.
The \texttt{copy\_options} enum values are used to fine-tune the behavior of
\texttt{filesystem} functions copying file system elements.

\begin{center}\begin{tabular}{lrll}
    \hline
\multicolumn{4}{c}{\textbf{std::filesystem::copy\_options}} \\
    \makecell[tl]{Symbol}  & 
     \makecell[tl]{Value}  & 
  &      \makecell[tl]{Meaning} 
 \\
    \hline
    \makecell[tl]{\texttt{none}}  & 
     \makecell[tr]{\texttt{0}}  & 
 ~~~ &      \makecell[tl]{default: copy like \texttt{cp}} 
 \\



        \makecell[tl]{\texttt{overwrite\_existing}}  & 
     \makecell[tr]{\texttt{2}}  & 
 ~~~ &      \makecell[tl]{replace the destination file} 
 \\

        \makecell[tl]{\texttt{update\_existing}}  & 
     \makecell[tr]{\texttt{4}}  & 
 ~~~ &      \makecell[tl]{
            replace the destination file only if it is \ \\ 
            older than the file being copied} 
 \\



        \makecell[tl]{\texttt{recursive}}  & 
     \makecell[tr]{\texttt{8}}  & 
 ~~~ &      \makecell[tl]{
        recursively copy subdirectories and their\ \\ 
        content} 
 \\

    
        \makecell[tl]{\texttt{copy\_symlinks}}  & 
     \makecell[tr]{\texttt{16}}  & 
 ~~~ &      \makecell[tl]{copy symlinks as symlinks} 
 \\

        \makecell[tl]{\texttt{skip\_symlinks}}  & 
     \makecell[tr]{\texttt{32}}  & 
 ~~~ &      \makecell[tl]{ignore symlinks} 
 \\



        \makecell[tl]{\texttt{directories\_only}}  & 
     \makecell[tr]{\texttt{64}}  & 
 ~~~ &      \makecell[tl]{
        copy the directory structure, but do not copy \ \\ 
        any non-directory files} 
 \\

        \makecell[tl]{\texttt{create\_symlinks}}  & 
     \makecell[tr]{\texttt{128}}  & 
 ~~~ &      \makecell[tl]{
        create symlinks instead of copying files.\ \\  
        The source path must be an absolute path unless \ \\ 
        the destination path is in the current directory} 
 \\

        \makecell[tl]{\texttt{create\_hard\_links}}  & 
     \makecell[tr]{\texttt{256}}  & 
 ~~~ &      \makecell[tl]{
        instead of copying files create hard links \ \\ 
        resolving to the same files as the original} 
 \\

        \hline
\end{tabular}
\end{center}

\textbf{Functions}:

\begin{itemize}
    \item \index{absolute}\texttt{path absolute(path const \&src,  {[}, error\_code \&ec{]})}:\ \\ returns \texttt{src} as an absolute path (i.e., starting at the
        filesystem's root (and maybe disk) name). It can be called as, e.g.,
        \texttt{absolute("tmp/filename")}, returning the (absolute) current working
        directory to which \texttt{absolute's} argument is appended as a final
        element, separated by a directory separator.  Relative path indicators
        (like \texttt{../} and \texttt{./}) are kept;  

\item \index{canonical}\texttt{path canonical(path const \&src {[}, error\_code \&ec{]})}:\ \\ returns \texttt{src's} canonical path. \texttt{Src} must exist. Example:
        \begin{verbatim}
    canonical("/usr/local/bin/../../share/man");
     // returns path{ "/usr/share/man" } 
\end{verbatim}
\item \index{copy}\texttt{void copy(path const \&src, path const \&dest {[}, copy\_options
        opts {[}, error\_code \&ec{]}{]})}:\ \\ \texttt{src} must exist. By default copies \texttt{src} to \texttt{dest} if the
            \texttt{cp} program would also succeed. Use \texttt{opts} to fine-tune
            \texttt{copy's} behavior.\ \\ 
       If \texttt{src} is a directory, and \texttt{dest} does not exist, \texttt{dest} is
        created. Directories are recursively copied if copy options
        \texttt{recursive} or \texttt{none} were specified;

\item \index{copy\_file}\texttt{bool copy\_file(path const \&src, path const \&dest {[},
        copy\_options opts {[}, error\_code \&ec{]}{]})}:\ \\ \texttt{src} must exist. Copies \texttt{src} to \texttt{dest} if the \texttt{cp} program
        would also succeed. Symbolic links are followed. The value \texttt{true} is
        returned if copying succeeded;

\item \index{copy\_symlink}\texttt{void copy\_symlink(path const \&src, path const \&dest {[},
        error\_code \&ec{]})}:\ \\ creates the symlink \texttt{dest} as a copy of the symlink \texttt{src};

\item \index{create\_directories}\texttt{bool create\_directories(path const \&dest {[},
        error\_code \&ec{]})}:\ \\ creates each component of \texttt{dest}, unless already existing. E.g.,
        using argument \texttt{"a/b/c"} and \texttt{"a"} doesn't yet exist then
        \texttt{"a/b/c"} are all created. The value \texttt{true} is returned if
        \texttt{dest} was actually created. If \texttt{false} is returned \texttt{ec}
        contains an error-code, which is zero (\texttt{ec.value() == 0}) if
        \texttt{dest} already existed. See also \texttt{create\_directory} below;

\item \index{create\_directory}\texttt{bool create\_directory(path const \&dest {[}, path
        const \&existing{]} {[}, error\_code \&ec{]})}:\ \\ \texttt{dest's} parent directory must exist. This function creates
        directory \texttt{dest} if it does not yet exist. Nested subdirectories are
        not created by \texttt{create\_directory}: using argument \texttt{"a/b/c"} and
        neither \texttt{"a"} nor \texttt{"a/b"} exist then this function fails. The
        value \texttt{true} is returned if \texttt{dest} was actually created. If
        \texttt{false} is returned \texttt{ec} contains an error-code, which is zero
        (\texttt{ec.value() == 0}) if \texttt{dest} already existed. If \texttt{existing} is
        specified, then \texttt{dest} receives the same attributes as
        \texttt{existing};

\item \index{create\_directory\_symlink}\texttt{void create\_directory\_symlink(path const
        \&dir, path const \&link {[}, error\_code \&ec{]})}:\ \\ like \texttt{create\_symlink} (see below), but is used to create a
        symbolic link to a directory;

\item \index{create\_hard\_link}\texttt{void create\_hard\_link(path const \&dest, path const
        \&link {[}, error\_code \&ec{]})}:\ \\ creates a hard link from \texttt{link} to \texttt{dest}. \texttt{Dest} must exist;

\item \index{create\_symlink}\texttt{void create\_symlink(path const \&dest, path const
        \&link {[}, error\_code \&ec{]})}:\ \\ creates a symbolic (soft) link from \texttt{link} to \texttt{dest}; \texttt{dest}
        does \emph{not} have to exist;

\item \index{current\_path}\texttt{path current\_path({[}error\_code \&ec{]})}, \texttt{void
        current\_path(path const \&toPath {[}, error\_code \&ec{]})}:\ \\ 
       the former function returns the current working directory (cwd),
        the latter changes the cwd to \texttt{toPath}. The returned path's last
        character is not a slash, unless called from the root-directory;

\item \index{equivalent}\texttt{bool equivalent(path const \&path1, path const \&path2 {[},
        error\_code \&ec{]})}:\ \\ \texttt{true} is returned if \texttt{path1} and \texttt{path2} refer to the same file
        or directory, and have identical statuses. Both paths must exist;

\item \index{exists}\texttt{bool exists(path const \&dest {[}, error\_code \&ec{]})},
        \texttt{exists(file\_status status)}:\ \\ 
       \texttt{true} is returned if \texttt{dest} exists (actually: if
        \texttt{status(dest{[}, ec{]})} (see below) returns \texttt{true}). Note: when
        iterating over directories, the iterator usually provides the entries'
        statuses. In those cases calling \texttt{exists(iterator-$>$status())} is
        more efficient than calling \texttt{exists($*$iterator)}. When \texttt{dest} is
        the path to a symbolic reference then \texttt{exists} returns whether the
        link's destination exists or not (see also the functions \texttt{status}
        and \texttt{symlink\_status} in section \ref{DIRENTRY});

\item \index{file\_size}\texttt{std::unintmax\_t file\_size(path const \&dest {[}, error\_code
        \&ec{]})}:\ \\ returns the size in bytes of a regular file (or symlink destination);

\item \index{hard\_link\_count}\texttt{std::uintmax\_t hard\_link\_count(path const \&dest {[},
        error\_code \&ec{]})}:\ \\ returns the number of hard links associated with \texttt{dest};

\item \index{last\_write\_time}\texttt{file\_clock::time\_point
        last\_write\_time(path const \&dest {[}, error\_code \&ec{]})},
       \texttt{void last\_write\_time(path const \&dest,
            file\_clock::time\_point newTime {[}, error\_code \&ec{]})}:\ \\ 
       the former function returns \texttt{dest's} last modification time;
        the latter function changes \texttt{dest's} last modification time to
        \texttt{newTime}.
       \texttt{last\_write\_time's} return type is defined through a \texttt{using} alias
        for \texttt{chrono::time\_point} (cf. section \ref{TIMEPOINT}). The returned
        \texttt{time\_point} is guaranteed to cover all file time values that may be
        encountered in the current file system. The function
        \texttt{file\_clock::to\_sys} (see below) can be used to convert
        \texttt{file\_clock} time points to \texttt{system\_clock} time\_points;

\item \index{permissions}\texttt{void permissions(Path const \&entry, 
                perms newPerms {[}, perm\_options opts = perm\_options::replace {]} 
                        {[}, error\_code \&ec{]})}:\ \\ Modifies the permissions of \texttt{entry}. Each of the two last arguments
        is optional. E.g., when specifying an \texttt{error\_code} as third argument
        then \texttt{opts} is implicitly specified as \texttt{replace};

\item \index{read\_symlink}\texttt{path read\_symlink(path const \&src {[}, error\_code \&ec{]})}:\ \\ \texttt{src} must refer to a symbolic link or an error is generated. The
        link's target is returned;

\item \index{remove}\texttt{bool remove(path const \&dest {[}, error\_code \&ec{]})},
        \index{remove\_all} \texttt{std::uintmax\_t remove\_all(path const \&dest {[},
        error\_code \&ec{]})}:\ \\ 
       \texttt{remove} removes the file, symlink, or empty directory
        \texttt{dest}, returning \texttt{true} if \texttt{dest} could be removed;
        \texttt{remove\_all} removes \texttt{dest} if it's a file (or symlink); and
        recursively removes directory \texttt{dest}, returning the number of
        removed entries;

\item \index{rename}\texttt{void rename(path const \&src, path const \&dest {[}, error\_code
        \&ec{]})}:\ \\ renames \texttt{src} to \texttt{dest}, as if using the standard \textbf{mv}(1)
        command (if \texttt{dest} exists it is overwritten);

\item \index{resize\_file}\texttt{void resize\_file(path const \&src, std::uintmax\_t size {[},
        error\_code \&ec{]})}:\ \\ \texttt{src's} size is changed to \texttt{size} as if using the standard
        \textbf{truncate}(1) command;

\item \index{space}\texttt{space\_info space(path const \&src {[}, error\_code \&ec{]})}:\ \\ returns information about the file system in which \texttt{src} is
        located;

\item \index{status}\texttt{file\_status status(path const \&entry {[}, error\_code \&ec{]})}:\ \\ returns \texttt{entry's file\_status}. If \texttt{entry} is the name of a symbolic
        link then the status of the link's destination is returned;

\item \index{symlink\_status}\texttt{file\_status symlink\_status(path const \&entry {[},
        error\_code \&ec{]})}:\ \\ returns \texttt{entry's} own \texttt{file\_status};

\item \index{system\_complete}\texttt{path system\_complete(path const \&src{[}, error\_code\&
        ec{]})}:\ \\ returns the absolute path matching \texttt{src}, using \texttt{current\_path} as
        its base;

\item \index{temp\_directory\_path}\texttt{path temp\_directory\_path({[}error\_code\& ec{]})}:\ \\  returns the path to a directory that can be used for temporary
        files. The directory is not created, but its name is commonly
        available from the environment variables \index{TMPDIR}\texttt{TMPDIR}, \texttt{TMP, TEMP}, or
        \texttt{TEMPDIR}. Otherwise, \texttt{/tmp} is returned.

\item \index{to\_sys}\texttt{system\_clock::time\_point
        file\_clock::to\_sys(file\_clock::time\_point timePoint)}:\ \\ here is how
        the time returned by \texttt{last\_write\_time} can be represented using the
        \texttt{system\_clock's} epoch:
            \begin{verbatim}
int main()
{
    time_t seconds = system_clock::to_time_t(
                    file_clock::to_sys(last_write_time("lastwritetime.cc"))
                );

    cout << "lastwritetime.cc's last (UTC) write time: " <<
             put_time(gmtime(&seconds), "%c") << '\n';
}
\end{verbatim}
\end{itemize}

\subsection{Handling directories: directory\_entry}\label{DIRENTRY}
    \typeout{Original Yodl file: namespaces/filesystem/directoryentry}The file system is a recursive data structure. Its top-level entry is a
directory (the root directory) containing plain directory entries (files,
(soft) links, named sockets, etc.) and possibly also (sub)directory
entries referring to nested directories which in turn may contiain plain-
and (sub)directory entries.

In the \texttt{std::filesystem} namespace the elements of directories are objects
of the class \index{directory\_entry}\texttt{directory\_entry}, containing names and statuses of the entries
of that directory. 

\textbf{Constructors}:

The class \texttt{directory\_entry} supports all standard constructors (and
assignment operators) and also a constructor expecting a \texttt{path}:
        \begin{verbatim}
    directory_entry(path const &entry);
\end{verbatim}
Objects of the class \texttt{directory\_entry} can be constructed by name, and do
not have to refer to existing entries in the file system. 

\textbf{Operators}:
    \begin{itemize}
    \item \texttt{ostream \&operator$<$$<$(ostream \&, directory\_entry const \&)} inserts the
        object's \texttt{path} into the \texttt{ostream};

\item  the comparsion operators (\texttt{==, $<$=$>$}) compare their \texttt{std::path}
        data members;

\item \index{path}\texttt{path const \&path() const}, \index{operator path const \&()}
        \texttt{operator path const \&() const}
       returns the current object's path name.
    \end{itemize}

\textbf{Members}:

\begin{itemize}
    \item \index{assign}\texttt{void assign(path const \&dest)}:\ \\ the current path is replaced by \texttt{dest} (identical to
        \texttt{directory\_entry's} assignment operator);

\item \index{replace\_filename}\texttt{void replace\_filename(path const \&dest)}:\ \\ the last element of the current object's path is replaced by
        \texttt{dest}. If that element is empty (e.g., when the object's path ends
        in a directory separator) then \texttt{dest} is appended to the current
        object's path;

\item \index{status}\texttt{filesystem::file\_status status({[}error\_code \&ec{]})}:\ \\ returns type and attributes of the directory entry referred to by the
        current object. If the current object refers to a symlink then the
        status of the entry the symlink refers to is returned. To obtain the
        status of the entry itself, even if it's a symlink use
        \index{symlink\_status}\texttt{symlink\_status} (see also section \ref{FSSTATUS} and \ref{FSESTAT}
        below).
    \end{itemize}

\subsubsection{Visiting directory entries: (recursive\_)directory\_iterator}
        \typeout{Original Yodl file: namespaces/filesystem/directoryiterator}The \texttt{filesystem} namespace has two classes simplifying directory
processing: objects of the class \texttt{directory\_iterator} are (input) iterators
iterating over the entries of directories; and objects of the class
\texttt{recursive\_directory\_iterator} are (input) iterators recursively visiting
all entries of directories.location 

\textbf{enum class directory\_options}

The \texttt{enum class directory\_options}\index{directory\_options} defines values that
are used to fine-tune the behavior of \texttt{recursive\_directory\_iterator}
objects, supporting bitwise operators (the values of its symbols are shown
between parentheses):
    \begin{itemize}
    \item \texttt{none} (0): directory symlinks are skipped, denied permission to enter
        a sub-directory generates an error;
    \item \texttt{follow\_directory\_symlink} (1): symlinks to sub-directories are
        followed;
    \item \texttt{skip\_permission\_denied} (2): directories that cannot be entered are
        silently skipped. 
    \end{itemize}

\textbf{Constructors}:

\begin{itemize}
    \item \texttt{(recursive\_)directory\_iterator()}:\ \\ the end-iterator of the \texttt{(recursive\_)directory\_iterator's}
        iterator-range;

\item \texttt{(recursive\_)directory\_iterator(path const \&from {[}, error\_code \&ec{]})}:\ \\ constructs a \texttt{(recursive-)directory\_iterator} using \texttt{from} as the
        starting directory of the iterator. All members of standard input
        iterators (cf. section \ref{ITERATORS}) are supported;

\item \texttt{recursive\_directory\_iterator(path const \&from, directory\_options opts
            {[}, error\_code \&ec{]})}:\ \\ constructs a \texttt{(recursive-)directory\_iterator} fine-tuning its
        behavior to the options specified by \texttt{opts}.
    \end{itemize}

Copy, and move constructors are available.

These iterators point to \texttt{directory\_entry} objects referring to
    entries in the computer's file system. E.g.,
 \begin{verbatim}
    cout << *directory_iterator{ "/home" } << '\n'; 
                // shows the first entry under /home 
\end{verbatim}
\texttt{(Recursive\_)directory\_iterators} can be used with range-based for-loops
and in standard \texttt{for} and \texttt{while} statements.

\textbf{Additional members of recursive\_directory\_iterators}

\begin{itemize}
    \item \index{depth}\texttt{int depth() const}:\ \\ returns the current iteration depth. The depth of the initial
        directory, specified at construction-time, equals 0;

\item \index{disable\_recursion\_pending}\texttt{void disable\_recursion\_pending()}:\ \\ when called before incrementing the iterator the next directory entry
        is not recursively visited. Once the iterator is incremented recursion
        is again allowed. If a recursion should end at a specific depth then
        once \texttt{depth()} returns that specific depth this member must be
        called each time before the iterator's increment operator is called;

\item \index{increment}\texttt{recursive\_directory\_iterator \&increment(error\_code \&ec)}:\ \\ acts identically to the iterator's increment operator. However, at
        errors \texttt{operator++} throws a \texttt{filesystem\_error} exception, while
        \texttt{increment} assigns the error to \texttt{ec};

\item \index{options}\texttt{directory\_options options() const}:\ \\ returns the option(s) specified at construction-time;

\item \index{pop}\texttt{void pop()}:\ \\ ends processing the current directory, and continues at the next
        entry in the current directory's parent;

\item \index{recursion\_pending}\texttt{bool recursion\_pending() const}:\ \\ \texttt{true} is returned if recursive processing of sub-directories of the
        currently processed directory is allowed. If so, and the 
        the iterator points at a sub-directory, then processing
        continues in that sub-directory at the iterator's next increment;
    \end{itemize}

Here's a small program displaying all elements and
all immediate sub-directories of a directory:
        \begin{verbatim}
    int main()
    {
        recursive_directory_iterator base{ "/var/log",
                                      directory_options::skip_permission_denied };
    
        for (auto entry = base, endIt = end(base); entry != endIt; ++entry)
        {
            cout << entry.depth() << ": " << *entry << '\n';
            if (entry.depth() == 1)
                entry.disable_recursion_pending();
        }
    }
\end{verbatim}
The above program handles entries as they come. Other strategies must be
implemented `by hand'. E.g., a breadth-first strategy first visits all the
non-directory entries and then visits the sub-directories, as illustrated in
the next example by processingthe directories stored in \texttt{level} in turn
(initially it merely contains the starting directory). 

`Processing a directory' means that its non-directory entries are directly
processed storing the names of sub-directories in \texttt{next}. Once
all entries at \texttt{level} have been processed the names of the next level
sub-directories are available (in \texttt{next}). By assigning \texttt{next} to
\texttt{level} all directories at the next level are processed. When reaching the
most deeply nested sub-directories its \texttt{next} is empty and the \texttt{while}
statement ends:
    \begin{verbatim}
    void breadth(path const &dir)           // starting dir.
    {
        vector<path> level{ dir };          // currently processed level
    
        while (not level.empty())           // process all its dirs.
        {
            vector<path> next;              // dirs of the next level
    
            for (auto const &dir: level)    // visit all dirs at this level
            {
                cout << "At " << dir << '\n';
                                            // at each dir: visit all entries
                for (auto const &entry: directory_iterator{ dir })
                {
                    if (entry.is_directory())   // store all dirs at the current
                        next.push_back(entry);  //  level
                    else                        // or process its non-dir entry
                        cout << "   entry: " << entry << '\n';
                }
            }
    
            level = next;                   // continue at the next level,
        }                                   // which eventually won't exist
    }
\end{verbatim}
\subsection{Information about the space of file systems: space\_info}
    \typeout{Original Yodl file: namespaces/filesystem/spaceinfo}Every existing \texttt{path} lives in a file system, Sizes of file systems
typically are quite large, but there is a limit to their sizes.

The size of file systems, the number of bytes that is currently being used
and the remaining number of bytes is made available by the function 
    \index{space(\_info)}\index{available space} \texttt{space(path const \&entry {[},
error\_code \&ec{]})}, returning the information about the file system containing
\texttt{entry} in a POD \texttt{struct space\_info}.

If the \texttt{error\_code} argument is provided then it is cleared if no error
occurs, and set to the operating system's error code if an error has
occurred. If an error occurs and the \texttt{error\_code} argument was not provided
then a \texttt{filesystem\_error} exception is thrown, receiving \texttt{path} as its
first argument and the operating system's error code as its \texttt{error\_code}
argument.  

The returned \texttt{space\_info} has three fields:
        \begin{verbatim}
    uintmax_t capacity;     // total size in bytes
    uintmax_t free;         // number of free bytes on the file system
    uintmax_t available;    // free bytes for a non-privileged process
\end{verbatim}
If a field cannot be determined it is set to -1 (i.e., the max. value of
the type \texttt{uintmax\_t}). 

The function can be used this way:
        \begin{verbatim}
    int main()
    {
        path tmp{ "/tmp" };
    
        auto pod = space(tmp);
    
        cout << "The filesystem containing /tmp has a capacity of " <<
                                                pod.capacity << " bytes,\n"
            "i.e., " << pod.capacity / (1024 * 1024) << " MB.\n"
            "# free bytes: " << pod.free << "\n"
            "# available:  " << pod.available << "\n"
            "free + available:  " << pod.free + pod.available << '\n';
    }
\end{verbatim}
\subsection{File system exceptions: filesystem\_error}
    \typeout{Original Yodl file: namespaces/filesystem/filesystemerror}The \texttt{std::filesystem} namespace offers its own exception type
\index{filesystem\_error}\texttt{filesystem\_error} (see also chapter \ref{EXCEPTIONS}). Its constructor has
the following signature (the bracketed parameters are optional):
        \begin{verbatim}
    filesystem_error(string const &what, 
                    [path const &path1, [path const &path2,]] 
                    error_code ec);
\end{verbatim}
As \texttt{filesystem} facilities are closely related to standard system
functions, \texttt{errc} error code enumeration values can be used to obtain
\texttt{error\_codes} to pass to \texttt{filesystem\_error}, as illustrated by the
following program:
    \begin{verbatim}
    int main()
    try
    {
        try
        {
            throw filesystem_error{ "exception encountered", "p1", "p2",
                                        make_error_code(errc::address_in_use) };
        }
        catch (filesystem_error const &fse)
        {
            cerr << "what:  " << fse.what() << "\n"
                    "path1: " << fse.path1() << "\n"
                    "path2: " << fse.path2() << "\n"
                    "code:  " << fse.code() << '\n';
    
            throw;
        }
    }
    catch (exception const &ec)
    {
        cerr << "\n"
                "plain exception's what: " << ec.what() << "\n\n";
    }
\end{verbatim}
\cleardoublepage\chapter{The `string' Data Type}\label{String}
\typeout{Original Yodl file: string}\typeout{Original Yodl file: string/string}\textbf{C++} offers many solutions for common problems. Most of these facilities
are part of the \emph{Standard Template Library} or they are implemented as
\emph{generic algorithms} (see chapter \ref{GENERIC}).

Among the facilities \textbf{C++} programmers have developed over and over again
are those manipulating chunks of text, commonly called \emph{strings}. The \textbf{C}
programming language offers rudimentary string support.

To process text \textbf{C++} offers a \index{string}\texttt{std::string} type. In \textbf{C++}
the traditional \textbf{C} library functions manipulating NTB strings are
deprecated in favor of using \texttt{string} objects. Many problems in \textbf{C}
programs are caused by buffer overruns, boundary errors and allocation
problems that can be traced back to improperly using these traditional \textbf{C}
string library functions. Many of these problems can be prevented using
\textbf{C++} string objects.

Actually, \texttt{string} objects are \emph{class type} variables, and in that sense
they are comparable to stream objects like \texttt{cin} and \texttt{cout}. In this
section the use of \texttt{string} type objects is covered. The focus is on their
definition and their use. When using \texttt{string} objects the
    \index{member function}\emph{member function} \emph{syntax} is commonly used:
    \begin{verbatim}
        stringVariable.operation(argumentList)
\end{verbatim}
For example, if \texttt{string1} and \texttt{string2} are variables of type
\texttt{std::string}, then
    \begin{verbatim}
        string1.compare(string2)
\end{verbatim}
can be used to compare both strings.

In addition to the common member functions the \texttt{string} class also offers a
wide variety of \emph{operators}, like the assignment (\texttt{=}) and the comparison
operator (\texttt{==}). 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
        \begin{verbatim}
    if (string1.compare(string2) == 0)
\end{verbatim}
the following is generally preferred:
        \begin{verbatim}
    if (string1 == string2)
\end{verbatim}
To define and use \texttt{string}-type objects, sources must include the header
file \index{string: header file}\texttt{$<$string$>$}. To merely \index{string: declaring} \emph{declare} the string type
the header \index{iosfwd}iosfwd can be included.

In addition to \texttt{std::string}, the header file \texttt{string} defines the
following string types:
    \begin{itemize}
    \item \index{wstring}\texttt{std::wstring}, a string type consisting of \texttt{wchar\_t}
        characters;
    \item \index{u16string}\texttt{std::u16string}, a string type consisting of \texttt{char16\_t}
        characters; 
    \item \index{u32string}\texttt{std::u32string}, a string type consisting of \texttt{char32\_t}
        characters. 
    \end{itemize}

\section{Operations on strings}
\typeout{Original Yodl file: string/ops}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 \emph{value} \index{npos}\texttt{string::npos} is returned. This value is a symbolic
value of type \index{size\_type}\index{string::size\_type}\texttt{string::size\_type}, which is (for all practical
purposes) an (\texttt{unsigned}) \texttt{int}.

All \texttt{string} member functions accepting \texttt{string} objects as arguments also
accept NTBS arguments. The same usually holds true for operators accepting
\texttt{string} objects.

Some \texttt{string}-members use \emph{iterators}. Iterators are formally introduced
in section \ref{ITERATORS}. Member functions using iterators are listed in
the next section (\ref{STRINGOVERVIEW}), 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: \textbf{C++} strings are
extremely versatile and there is hardly a reason for falling back on the \textbf{C}
library to process text. \textbf{C++} strings handle all the required memory
management and thus memory related problems, which are the \#1 source of
problems in \textbf{C} programs, can be prevented when \textbf{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, \texttt{std::string} doesn't offer case-insensitive
comparisons. But in the end it isn't even as simple as that. It \emph{is} there,
but it is somewhat hidden and at this point in the \textbf{C++} Annotations it's too
early to study into that hidden corner yet. Instead, realize that \textbf{C}'s
standard library \emph{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 \index{case-insensitive}case-insensitive comparison of the content
of two \texttt{std::string} objects \texttt{str1} and \texttt{str2} the following will do:
    \index{strcasecmp}
        \begin{verbatim}
    strcasecmp(str1.c_str(), str2.c_str());
\end{verbatim}
Strings support the following functionality:
    \begin{itemize}
    \item \texttt{initialization}:\ \\ when string objects are defined they are always properly
initialized. In other words, they are always in a \index{valid state}valid state. Strings may
be initialized empty or already existing text can be used to initialize
strings.
    \item \texttt{assignment}:\ \\ strings may be given new values. New values may be assigned using
member functions (like \texttt{assign}) but a plain assignment operator (i.e.,
\texttt{=})may also be used. Furthermore, assignment \emph{to} a character buffer is
also supported.
    \item \texttt{conversions}:\ \\ the partial or complete content of string objects may be interpreted
as \textbf{C} strings but the string's content 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 \textbf{C} strings
may be used where \texttt{std::string}s are accepted as well.
    \item \texttt{breakdown}:\ \\ the individual characters stored in a string can be accessed
using the familiar index operator (\texttt{{[}{]}}) allowing us to either access or
modify information in the middle of a string.
    \item \texttt{comparisons}:\ \\ strings may be compared to other strings (NTBSs) using the
familiar logical comparison operators \texttt{==, !=, $<$, $<$=, $>$} and \texttt{$>$=}. There
are also member functions available offering a more fine-grained comparison.
    \item \texttt{modification}:\ \\ the content 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 content.
    \item \texttt{swapping}:\ \\ the string's swapping capability allows us in principle to exchange
the content of two string objects without a byte-by-byte copying
operation of the string's content.
    \item \texttt{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.
    \item \texttt{housekeeping}:\ \\ several housekeeping facilities are offered: the string's length,
or its  empty-state may be interrogated. But string objects may also be
resized.
    \item \texttt{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 \emph{device independent}.
    \end{itemize}

\section{A std::string reference}\label{STRINGOVERVIEW}
\typeout{Original Yodl file: string/overview}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:
    \begin{itemize}
    \item  \texttt{object} is always a \texttt{string}-object;
    \item  \texttt{argument} is a \texttt{string const \&} or a \texttt{char const $*$} unless
indicated otherwise.  The content of an \texttt{argument} never is modified by the
operation processing the \texttt{argument};
    \item  \texttt{opos} refers to an offset into an \texttt{object} string;
    \item  \texttt{apos} refers to an offset into an \texttt{argument};
    \item  \texttt{on} represents a number of characters in an \texttt{object} (starting
at \texttt{opos});
    \item  \texttt{an} represents a number of characters in an \texttt{argument} (starting
at \texttt{apos}).
    \end{itemize}

Both \texttt{opos} and \texttt{apos} must refer to existing offsets, or an exception
(cf. chapter \ref{EXCEPTIONS}) is generated. In contrast, \texttt{an} and \texttt{on} may
exceed the number of available characters, in which case only the available
characters are considered.

Many members declare default values for \texttt{on, an} and \texttt{apos}. Some members
declare default values for \texttt{opos}. Default offset values are 0, the default
values of \texttt{on} and \texttt{an} is \texttt{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
content proceeding backwards, the default value of \texttt{opos} is the index of
the object's \emph{last} character, with \texttt{on} by default equal to \texttt{opos + 1},
representing the length of the substring \emph{ending} at \texttt{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
\texttt{char const $*$}. But even if that is not the case the first argument can
\emph{always} be of type \texttt{char const $*$} where a parameter of \texttt{std::string} is
defined.

Several member functions accept \emph{iterators}. Section \ref{ITERATORS} covers
the technical aspects of \emph{iterators}, but these may be ignored at this point
without loss of continuity.  Like \texttt{apos} and \texttt{opos}, iterators must refer
to existing positions and/or to an existing range of characters within the
string object's content.

All \texttt{string}-member functions computing indices return the
predefined constant \texttt{string::npos} on failure.

The \index{s}\texttt{s} \index{literal suffix}literal suffix to indicate that a \texttt{std::string} constant is
intended when a string literal (like \texttt{"hello world"}) is used. It can be
used after declaring \texttt{using namespace std} or, more specific, after
declaring 
        \index{literals namespace}\index{string\_literals namespace}
    \texttt{using namespace std::literals::string\_literals}. 

When string literals are used when explicitly defining or using
\texttt{std::string} objects the \texttt{s}-suffix is hardly ever required, but it may
come in handy when using the \texttt{auto} keyword. E.g., \texttt{auto str = "hello
world"s} defines \texttt{std::string str}, whereas it would have been a \texttt{char
const $*$} if the literal suffix had been omitted.

\subsection{Initializers}
    \typeout{Original Yodl file: string/initializers}After defining string objects they are guaranteed to be in a valid
state. At \emph{definition time}  string objects may be initialized in one of the
following ways:
    The following \texttt{string} constructors \index{string constructors} are
available:
    \begin{itemize}
    \item \texttt{string object}:\ \\ initializes \texttt{object} to an empty string.  When defining a \texttt{string}
        this way no argument list may be specified;
    \item \texttt{string object(string::size\_type count, char ch)}:\ \\ initializes \texttt{object} with \texttt{count} characters \texttt{ch}. \emph{Caveat:}
        to initialize a string object using this constructor do not use the
        curly braces variant, but use the constructor as shown, to avoid
        selecting the initializer-list constructor (see below);
    \item \texttt{string object(string const \&argument)}:\ \\ initializes \texttt{object} with \texttt{argument};
    \item \texttt{string object(std::string const \&argument, string::size\_type
            apos, string::size\_type an)}:\ \\ initializes \texttt{object} with \texttt{argument}'s content starting at index
        position \texttt{apos}, using at most \texttt{an} of \texttt{argument}'s characters;
    \item \texttt{string object(InputIterator begin, InputIterator end)}:\ \\ initializes \texttt{object} with the characters in the range of characters
        defined by the two \texttt{InputIterators}.
    \item \texttt{string object(std::initializer\_list$<$char$>$ chars)}:\ \\ initializes \texttt{object} with the characters specified in the 
        initializer list. The string may also directly be initialized, using
        the curly braced initialization. Here is an example showing both
        forms: 
       \begin{verbatim}
string str1({'h', 'e', 'l', 'l', 'o'});
string str2{ 'h', 'e', 'l', 'l', 'o' };
\end{verbatim}
\end{itemize}

\subsection{Iterators}
    \typeout{Original Yodl file: string/iterators}        See section \ref{ITERATORS} for details about \emph{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 \emph{generic algorithms}
(cf. chapter \ref{GENERIC}). The class \texttt{std::string} defines the following
\index{string: iterator types}\emph{iterator types}:
    \begin{itemize}
    \item \texttt{string::iterator} and \texttt{string::const\_iterator}:
        \begin{quote}these iterators are \index{forward iterators}\emph{forward iterators}. The
\texttt{const\_iterator} is returned by \texttt{string const} objects, the plain
\texttt{iterator} is returned by non-const string objects. Characters referred to
by \texttt{iterators} may be modified;\end{quote}
    \item \texttt{string::reverse\_iterator} and \texttt{string::const\_reverse\_iterator}:
        \begin{quote}these iterators are also \index{forward iterators}\emph{forward iterators} but when
\emph{incrementing} the iterator the \emph{previous} character in the string object
is reached. Other than that they are comparable to, respectively,
\texttt{string::iterator} and \texttt{string::const\_iterator}.\end{quote}
    \end{itemize}

\subsection{Operators}
    \typeout{Original Yodl file: string/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 \texttt{string} objects (in the examples
`object' and `argument' refer to existing \texttt{std::string} objects).
    \begin{itemize}
    \item  plain assignment:
    \begin{quote}a character, \textbf{C} or \textbf{C++} string may be assigned to a \texttt{string}
object. The assignment operator returns its left-hand side operand. Example:
    \begin{verbatim}
object =  argument;
object = "C string";
object = 'x';
object = 120;       // same as object = 'x'
\end{verbatim}
\end{quote}
    \item  addition:
    \begin{quote}the arithmetic additive assignment operator and the addition
operator add text to a \texttt{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 operand must be a
\texttt{std::string} object. The other operand may be a char, a \textbf{C} string or a
\textbf{C++} string. Example:
    \begin{verbatim}
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;
\end{verbatim}
\end{quote}
    \item  index operator:
    \begin{quote}The index operator may be used to retrieve \texttt{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 \texttt{at()} member
function for that). This operator returns a \texttt{char \&} or \texttt{char const \&}.
Example:
    \begin{verbatim}
object[3] = argument[5];
\end{verbatim}
\end{quote}
    \item  logical operators:
    \begin{quote}the logical comparison operators may be applied to two string
objects or to a string object and a \textbf{C} string to compare their
content. These operators return a \texttt{bool} value.
The \texttt{==, !=, $>$, $>$=, $<$,} and \texttt{$<$=} operators are available. The ordering
operators perform a lexicographical comparison of their content
using the ASCII character collating sequence. Example:
    \begin{verbatim}
object == object;           // true
object != (object + 'x');   // true
object <= (object + 'x');   // true
\end{verbatim}
\end{quote}
    \item  stream related operators:
    \begin{quote}the insertion-operator (cf. section \ref{CoutCinCerr}) may be used to
insert a \texttt{string} object into an \texttt{ostream}, the extraction-operator may be
used to extract a string object from an \texttt{istream}. The extraction operator
by default first ignores all whitespace characters and then extracts all
consecutively non-blank characters from an \texttt{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:
    \begin{verbatim}
cin >> object;
cout << object;
\end{verbatim}
\end{quote}
    \end{itemize}

\subsection{Member functions}\label{STRINGMEMBERS}
    \typeout{Original Yodl file: string/members}The \texttt{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 \texttt{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 `\texttt{object.find('x')}' (see
below) on a string object not containing the character \texttt{'x'}, \texttt{npos}
is returned, as the requested position does not exist.

The final 0-byte used in \textbf{C} strings to indicate the end of an NTBS is
\emph{not} considered part of a \textbf{C++} string, and so the member function will
return \texttt{npos}, rather than \texttt{length()} when looking for 0 in a string
object containing the characters of a \textbf{C} string.

Here are the standard functions that operate on objects of the class
string. When a parameter of \texttt{size\_t} is mentioned it may be interpreted as a
parameter of type \texttt{string::size\_type}, but without defining a default
argument value. The type \texttt{size\_type} should be read as
\texttt{string::size\_type}. With \texttt{size\_type} the default argument values
mentioned in section \ref{STRINGOVERVIEW} apply. All quoted functions are
member functions of the class \texttt{std::string}, except where indicated
otherwise.
    \begin{itemize}
    \item \index{at}\texttt{char \&at(size\_t opos)}:\ \\ a reference to the character at the indicated position is
        returned. When called with \texttt{string const} objects a \texttt{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.
    \item \index{append}\texttt{string \&append(InputIterator begin, InputIterator end)}:\ \\ the characters in the range defined by \texttt{begin} and \texttt{end} are
        appended to the current string object.
    \item \texttt{string \&append(string const \&argument, size\_type apos,
        size\_type an)}:\ \\ \texttt{argument} (or a substring) is appended to the current string
        object.
    \item \texttt{string \&append(char const $*$argument, size\_type an)}:\ \\ the first \texttt{an} characters of \texttt{argument} are appended to the
        string object.
    \item \texttt{string \&append(size\_type n, char ch)}:\ \\ \texttt{n} characters \texttt{ch} are appended to the current string object.
    \item \index{assign}\texttt{string \&assign(string const \&argument, size\_type
        apos, size\_type an)}:\ \\ \texttt{argument} (or a substring) is assigned to the string object.
        If \texttt{argument} is of type \texttt{char const $*$} and one additional
        argument is provided the second argument is interpreted as a value
        initializing \texttt{an}, using 0 to initialize \texttt{apos}.
    \item \texttt{string \&assign(size\_type n, char ch)}:\ \\ \texttt{n} characters \texttt{ch} are assigned to the current string object.
    \item \index{back}\texttt{char \&back()}:\ \\ returns a reference to the last \texttt{char} stored inside the string
        object. The result is undefined for empty strings.
    \item \index{begin}\texttt{string::iterator begin()}:\ \\ an iterator referring to the first character of the current string
        object is returned. With \texttt{const} string objects a \texttt{const\_iterator}
        is returned.
    \item \index{capacity}\texttt{size\_type capacity() const}:\ \\ the number of characters that can currently be stored in the string
        object without needing to resize it is returned.
    \item \index{cbegin}\texttt{string::const\_iterator cbegin()}:\ \\ a \texttt{const\_iterator} referring to the first character of the current
        string object is returned.
    \item \index{cend}\texttt{string::const\_iterator cend()}:\ \\ a \texttt{const\_iterator} referring to the end of the current
        string object is returned.
    \item \index{clear}\texttt{void clear()}:\ \\ the string's content is erased.
    \item \index{compare}\texttt{int compare(string const \&argument) const}:\ \\ the text stored in the current string object and the text stored in
        \texttt{argument} is compared using a lexicographical comparison using the
        ASCII character collating sequence. zero is returned if the two
        strings have identical content, a negative value is returned if the
        text in the current object should be ordered \emph{before} the text in
        \texttt{argument}; a positive value is returned if the text in the current
        object should be ordered \emph{beyond} the text in \texttt{argument}.
    \item \texttt{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 \texttt{argument}. At most \texttt{on} characters
        starting at offset \texttt{opos} are compared to the text in \texttt{argument}.
    \item \texttt{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 \texttt{argument}. At most
        \texttt{on} characters of the current string object, starting at offset
        \texttt{opos}, are compared to at most \texttt{an} characters of \texttt{argument},
        starting at offset \texttt{apos}. In this case \texttt{argument} \emph{must} be a
        string object.
    \item \texttt{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 \texttt{argument}. At most
        \texttt{on} characters of the current string object starting at offset
        \texttt{opos} are compared to at most \texttt{an} characters of
        \texttt{argument}. \texttt{Argument} must have at least \texttt{an} characters. The
        characters may have arbitrary values: 0-valued characters have no
        special meanings.
    \item \index{contains}\texttt{bool contains(argument) const}:\ \\ returns \texttt{true} if the object contains \texttt{argument's} characters as a
        substring. The argument can be a \texttt{string}, a \texttt{string\_view} (see
        section \ref{STRINGVIEW}), a \texttt{char} or an NTBS.
    \item \index{copy}\texttt{size\_t copy(char $*$argument, size\_t on, size\_type opos) const}:\ \\ the content of the current string object are (partially) copied into
        \texttt{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: 
       \begin{verbatim}
    argument[object.copy(argument, string::npos)] = 0;
\end{verbatim}
       Of course, the programmer should make sure that \texttt{argument}'s size is
        large enough to accommodate the additional 0-byte.
    \item \index{crbegin}\texttt{string::const\_reverse\_iterator crbegin()}:\ \\ a \texttt{const\_reverse\_iterator} referring to the last character of the
        current string object is returned.
    \item \index{crend}\texttt{string::const\_reverse\_iterator crend()}:\ \\ a \texttt{const\_reverse\_iterator} referring to the begin of the current
        string object is returned.
    \item \index{c\_str}\texttt{char const $*$c\_str() const}:\ \\ the content of the current string object as an NTBS.
    \item \index{data}\texttt{char const $*$data() const}:\ \\ the raw content of the current string object are returned. Since this
        member does not return an NTBS (as
        \texttt{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:
       \begin{verbatim}
    string s(2, 0);
    cout << static_cast<int>(s.data()[1]) << '\n';
\end{verbatim}
\item \index{empty}\texttt{bool empty() const}:\ \\ \texttt{true} is returned if the current string object contains no data.
    \item \index{end}\texttt{string::iterator end()}:\ \\ an iterator referring to the position just beyond the last character
        of the current string object is returned. With \texttt{const} string
        objects a \texttt{const\_iterator} is returned.
    \item \index{ends\_with}\texttt{bool ends\_with(argument) const}:\ \\ returns \texttt{true} if the object's characters end with \texttt{argument}. The
        argument can be a \texttt{string}, a \texttt{string\_view}, a \texttt{char} or an
        NTBS.
    \item \index{erase}\texttt{string \&erase(size\_type opos, size\_type on)}:\ \\ a (sub)string of the information stored in the current string object
        is erased.
    \item \texttt{string::iterator erase(string::iterator begin, string::iterator end)}:\ \\ the parameter \texttt{end} is optional. If omitted the value returned by
        the current object's \texttt{end} member is used. The characters defined by
        the \texttt{begin} and \texttt{end} iterators are erased. The iterator \texttt{begin}
        is returned, which is then referring to the position immediately
        following the last erased character.
    \item \index{find}\texttt{size\_t find(string const \&argument, size\_type opos) const}:\ \\ the first index in the current string object is returned where
        \texttt{argument} is found.
    \item \texttt{size\_t find(char const $*$argument, size\_type opos, size\_type an) const}:\ \\ the first index in the current string object is returned where
        \texttt{argument} is found. When all three arguments are specified the
        first argument \emph{must} be a \texttt{char const $*$}.
    \item \texttt{size\_t find(char ch, size\_type opos) const}:\ \\ the first index in the current string object is returned where \texttt{ch}
        is found.
    \item \index{find\_first\_of}\texttt{size\_t find\_first\_of(string const \&argument,
                                               size\_type opos) const}:\ \\ the first index in the current string object is returned whose
        character matches any character from \texttt{argument}.
    \item \texttt{size\_type find\_first\_of(char const $*$argument, size\_type opos,
        size\_type an) const}:\ \\ the first index in the current string object is returned whose
        character matches any character from \texttt{argument}. If \texttt{opos} is
        provided it refers to the first index in the current string object
        where the search for \texttt{argument} should start. If omitted, the string
        object is completely scanned.  If \texttt{an} is provided it indicates the
        number of characters of the \texttt{char const $*$} argument that should be
        used in the search. It defines a substring starting at the beginning
        of \texttt{argument}. If omitted, all of \texttt{argument}'s characters are
        used.
    \item \texttt{size\_type find\_first\_of(char ch, size\_type opos)}:\ \\ the first index in the current string object is returned whose
        character is equal to \texttt{ch}.
    \item \index{find\_first\_not\_of}\texttt{size\_t find\_first\_not\_of(string const \&argument,
                                               size\_type opos) const}:\ \\ the first index in the current string object is returned whose
        character does not match any character from \texttt{argument}.
    \item \texttt{size\_type find\_first\_not\_of(char const $*$argument, size\_type opos,
        size\_type an) const}:\ \\ the first index in the current string object is returned whose
        character does not match any character from \texttt{argument}. The \texttt{opos}
        and \texttt{an} parameters are handled as with \texttt{find\_first\_of}
    \item \texttt{size\_t find\_first\_not\_of(char ch, size\_type opos) const}:\ \\ the first index in the current string object is returned whose
        character is unequal to \texttt{ch}.
    \item \index{find\_last\_of}\texttt{size\_t find\_last\_of(string const \&argument,
                                               size\_type opos) const}:\ \\ the last index in the current string object is returned whose
        character matches any character from \texttt{argument}.
    \item \texttt{size\_type find\_last\_of(char const $*$argument, size\_type opos,
            size\_type an) const}:\ \\ the last index in the current string object is returned whose
        character matches any character from \texttt{argument}. If \texttt{opos} is
        provided it refers to the last index in the current string object
        where the search for \texttt{argument} should start (searching backward
        towards the beginning of the current object). If omitted, the string
        object is scanned completely.  If \texttt{an} is provided it indicates the
        number of characters of the \texttt{char const $*$} argument that should be
        used in the search. It defines a substring starting at the beginning
        of \texttt{argument}. If omitted, all of \texttt{argument}'s characters are
        used.
    \item \texttt{size\_type find\_last\_of(char ch, size\_type opos)}:\ \\ the last index in the current string object is returned whose
        character is equal to  \texttt{ch}.
    \item \index{find\_last\_not\_of}\texttt{size\_t find\_last\_not\_of(string const \&argument,
                                                size\_type opos) const}:\ \\ the last index in the current string object is returned whose
        character does not match any character from \texttt{argument}.
    \item \texttt{size\_type find\_last\_not\_of(char const $*$argument, size\_type opos,
        size\_type an) const}:\ \\ the last index in the current string object is returned whose
        character does not match any character from \texttt{argument}. The \texttt{opos}
        and \texttt{an} parameters are handled as with \texttt{find\_last\_of}.
    \item \texttt{size\_t find\_last\_not\_of(char ch, size\_type opos) const}:\ \\ the last index in the current string object is returned whose
        character is unequal to \texttt{ch}.
    \item \index{front}\texttt{char \&front()}:\ \\ returns a reference to the first \texttt{char} stored inside the string
        object. The result is undefined for empty strings.
    \item \index{get\_allocator}\texttt{allocator\_type get\_allocator()}:\ \\ returns the allocator of the class \texttt{std::string}
    \item \index{getline}\texttt{istream \&std::getline(istream \&istr, string \&object,
            char delimiter = '\textbackslash{}n')}:\ \\ Note: this is \emph{not} a member function of the class \texttt{string}.\ \\ 
       A line of text is read from \texttt{istr}. All characters until
        \texttt{delimiter} (or the end of the stream, whichever comes first) are
        read from \texttt{istr} and are stored in \texttt{object}. If the delimiter is
        encountered it is removed from the stream, but is not stored in
        \texttt{object}.\ \\ 
       If the delimiter is not found, \texttt{istr.eof} returns \texttt{true} (see
        section \ref{IOSTATES}). Since streams may be interpreted as \texttt{bool}
        values (cf. section \ref{IOSTATES}) a commonly encountered idiom to
        read all lines from a stream successively into a string object
        \texttt{line} looks like this:
       \begin{verbatim}
    while (getline(istr, line))
        process(line);
\end{verbatim}
       The content of the last line, whether or not it was terminated
        by a delimiter, is eventually also assigned to \texttt{object}.
    \item \index{insert}\texttt{string \&insert(size\_t opos, string const \&argument,
        size\_type apos, size\_type an)}:\ \\ a (sub)string of \texttt{argument} is inserted into the current string
        object at the current string object's index position
        \texttt{opos}. Arguments for \texttt{apos} and \texttt{an} must either both be
        provided or they must both be omitted.
    \item \texttt{string \&insert(size\_t opos, char const $*$argument,
                size\_type an)}:\ \\ \texttt{argument} (of type \texttt{char const $*$}) is inserted at index \texttt{opos}
        into the current string object.
    \item \texttt{string \&insert(size\_t opos, size\_t count, char ch)}:\ \\ \texttt{Count} characters \texttt{ch} are inserted at index \texttt{opos} into the
        current string object.
    \item \texttt{string::iterator insert(string::iterator begin, char ch)}:\ \\ the character \texttt{ch} is inserted at the current object's position
        referred to by \texttt{begin}. \texttt{Begin} is returned.
    \item \texttt{string::iterator insert(string::iterator begin, size\_t count,
        char ch)}:\ \\ \texttt{Count} characters \texttt{ch} are inserted at the current object's
        position referred to by \texttt{begin}. \texttt{Begin} is returned.
    \item \texttt{string::iterator insert(string::iterator begin, InputIterator
        abegin, InputIterator aend)}:\ \\ the characters in the range defined by the \texttt{InputIterators abegin}
        and \texttt{aend} are inserted at the current object's position referred to
        by \texttt{begin}. \texttt{Begin} is returned.
    \item \index{length}\texttt{size\_t length() const}:\ \\ the number of characters stored in the current string object is
        returned.
    \item \index{max\_size}\texttt{size\_t max\_size() const}:\ \\ the maximum number of characters that can be stored in the current
        string object is returned.
    \item \index{pop\_back}\texttt{void pop\_back()}:\ \\ The string's last character is removed from the string object.
    \item \index{push\_back}\texttt{void push\_back(char ch)}:\ \\ The character \texttt{ch} is appended to the string object.
    \item \index{rbegin}\texttt{string::reverse\_iterator rbegin()}:\ \\ a reverse iterator referring to the last character of the current
        string object is returned. With \texttt{const} string objects a
        \texttt{const\_reverse\_iterator} is returned.
    \item \index{rend}\texttt{string::reverse\_iterator rend()}:\ \\ a reverse iterator referring to the position just before the first
        character of the current string object is returned. With \texttt{const}
        string objects a \texttt{const\_reverse\_iterator} is returned.
    \item \index{replace}\texttt{string \&replace(size\_t opos, size\_t on, string const
        \&argument, size\_type apos, size\_type an)}:\ \\ a (sub)string of characters in \texttt{object} are replaced by the (subset
        of) characters of \texttt{argument}.  If \texttt{on} is specified as 0
        \texttt{argument} is inserted into \texttt{object} at offset \texttt{opos}.
    \item \texttt{string \&replace(size\_t opos, size\_t on, char const $*$argument,
        size\_type an)}:\ \\ a series of characters in \texttt{object} are replaced by the first \texttt{an}
        characters of \texttt{char const $*$} argument.
    \item \texttt{string \&replace(size\_t opos, size\_t on, size\_type count, char ch)}:\ \\ \texttt{on} characters of the current string object, starting at index
        position \texttt{opos}, are replaced by \texttt{count} characters \texttt{ch}.
    \item \texttt{string \&replace(string::iterator begin, string::iterator end,
        string const \&argument)}:\ \\ the series of characters in the current string object defined by the
        iterators \texttt{begin} and \texttt{end} are replaced by \texttt{argument}. If
        \texttt{argument} is a \texttt{char const $*$}, an additional argument \texttt{an} may
        be used, specifying the number of characters of \texttt{argument} that are
        used in the replacement.
    \item \texttt{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 \texttt{begin} and \texttt{end} are replaced by \texttt{count} characters
        having values \texttt{ch}.
    \item \texttt{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 \texttt{begin} and \texttt{end} are replaced by the characters in the
        range defined by the \texttt{InputIterators abegin} and \texttt{aend}.
    \item \index{reserve}\texttt{void reserve(size\_t request)}:\ \\ the current string object's capacity is changed to at least
        \texttt{request}. After calling this member, \texttt{capacity}'s return value
        will be at least \texttt{request}. A request for a smaller size than the
        value returned by \texttt{capacity} is ignored. A
        \index{length\_error}\texttt{std::length\_error} exception is thrown if
        \texttt{request} exceeds the value returned by \texttt{max\_size}
        (\texttt{std::length\_error} is defined in the \index{stdexcept}\texttt{stdexcept}
        header). Calling \texttt{reserve()} has the effect of redefining a string's
        capacity: when enlarging the capacity extra memory is allocated, but
        not immediately available to the program. This is illustrated by the
        exception thrown by the string's \texttt{at()} member when trying to access
        an element exceeding the string's \texttt{size} but not the string's
        \texttt{capacity}.
    \item \index{resize}\texttt{void resize(size\_t size, char ch = 0)}:\ \\ the current string object is resized to
        \texttt{size} characters. If the string object is resized to a size larger
        than its current size the additional characters will be initialized to
        \texttt{ch}. If it is reduced in size the characters having the highest
        indices are chopped off.
    \item \index{rfind}\texttt{size\_t rfind(string const \&argument, size\_type opos) const}:\ \\ the last index in the current string object where \texttt{argument} is
        found is returned. Searching proceeds from the current object's offset
        \texttt{opos} back to its beginning.
    \item \texttt{size\_t rfind(char const $*$argument, size\_type opos, size\_type an) const}:\ \\ the last index in the current string object where \texttt{argument} is
        found is returned.  Searching proceeds from the current object's
        offset \texttt{opos} back to its beginning.  The parameter \texttt{an} specifies
        the length of the substring of \texttt{argument} to look for, starting at
        \texttt{argument}'s beginning.
    \item \texttt{size\_t rfind(char ch, size\_type opos)const}:\ \\ the last index in the current string object where \texttt{ch} is found
        is returned.  Searching proceeds from the current object's offset
        \texttt{opos} back to its beginning.
    \item \index{shrink\_to\_fit}\texttt{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
       \begin{verbatim}
    string{ stringObject }.swap(stringObject)
\end{verbatim}
       idiom can be used.
    \item \index{size}\texttt{size\_t size() const}:\ \\ the number of characters stored in the current string object is
        returned. This member is a synonym of \texttt{length()}.
    \item \index{starts\_with}\texttt{bool starts\_with(argument) const}:\ \\ returns \texttt{true} if the object's character range starts with
        \texttt{argument}. The argument can be a \texttt{string}, a \texttt{string\_view}, a
        \texttt{char} or an NTBS.
    \item \index{substr}\texttt{string substr(size\_type opos, size\_type on) const}:\ \\ a substring of the current string object of at most \texttt{on} characters
        starting at index \texttt{opos} is returned.
    \item \index{swap}\texttt{void swap(string \&argument)}:\ \\ the content of the current string object are swapped with the
        content of \texttt{argument}. For this member \texttt{argument} must be a
        string object and cannot be a \texttt{char const $*$}.
    \end{itemize}

\subsection{Conversion functions}
    \typeout{Original Yodl file: string/convertors}Several string conversion functions are available operating on or producing
\texttt{std::string} objects. These functions are listed below in alphabetic
order. They are not member functions, but class-less (free) functions declared
in the \texttt{std} namespace. The \index{string: header file}\texttt{$<$string$>$} header file must be included
before they can be used.

\begin{itemize}
    \item \index{stof}\texttt{float stof(std::string const \&str, size\_t $*$pos = 0)}:\ \\ Initial whitespace characters in \texttt{str} are ignored. Then the
        following sequences of characters are converted to a \texttt{float} value,
        which is returned:
       \begin{itemize}
        \item  A decimal floating point constant:
            \begin{itemize}
           \item  An optional + or - character
           \item  A series of decimal digits, possibly containing one decimal
                point character
           \item  An optional e or E character, followed by an optional - or +
            character, followed by a series  of decimal digits
            \end{itemize}
        \item  A hexadecimal floating point constant:
           \begin{itemize}
           \item  An optional + or - character
            \item  0x or 0X
            \item  A series of hexadecimal digits, possibly containing one
                decimal point character
           \item  An optional p or P character, followed by an optional - or +
            character, followed by a series  of decimal digits
            \end{itemize}
        \item  An infinity expression:
           \begin{itemize}
           \item  An optional + or - character
            \item  The words \texttt{inf} or \texttt{infinity} (case insensitive words)
            \end{itemize}
        \item  A `not a number' expression:
           \begin{itemize}
           \item  An optional + or - character
            \item  The words \texttt{nan} or \texttt{nan(alphanumeric character sequence)}
                (\texttt{nan} is a case insensitive word), resulting in a \texttt{NaN}
                floating point value
            \end{itemize}
        \end{itemize}
        If \texttt{pos != 0} the index of the first character in \texttt{str} which was
        not converted is returned in \texttt{$*$pos}.  A \texttt{std::invalid\_argument}
        exception is thrown if the characters in \texttt{str} could not be
        converted to a \texttt{float}, a \texttt{std::out\_of\_range} exception is thrown
        if the converted value would have exceeded the range of \texttt{float}
        values.
    \item \index{stod}\texttt{double stod(std::string const \&str, size\_t $*$pos = 0)}:\ \\ A conversion as described with \texttt{stof} is performed, but now to a
        value of type \texttt{double}.
    \item \index{stold}\texttt{double stold(std::string const \&str, size\_t $*$pos = 0)}:\ \\ A conversion as described with \texttt{stof} is performed, but now to a
        value of type \texttt{long double}.
    \item \index{stoi}\texttt{int stoi(std::string const \&str, size\_t $*$pos = 0,
                                                    int base = 10)}:\ \\ Initial whitespace characters in \texttt{str} are ignored. Then all
        characters representing numeric constants of the number system whose
        \texttt{base} is specified are converted to an \texttt{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 \texttt{base} must be between 2 and 36. If \texttt{pos !=
        0} the index of the first character in \texttt{str} which was not converted
        is returned in \texttt{$*$pos}. A \texttt{std::invalid\_argument} exception is
        thrown if the characters in \texttt{str} could not be converted to an
        \texttt{int}, a \texttt{std::out\_of\_range} exception is thrown if the converted
        value would have exceeded the range of \texttt{int} values.

Here is an example of its use:
        \begin{verbatim}
int value = stoi(" -123"s);  // assigns value -123
value = stoi(" 123"s, 0, 5); // assigns value 38
\end{verbatim}
\item \index{stol}\texttt{long stol(std::string const \&str, size\_t $*$pos = 0, 
                                                    int base = 10)}:\ \\ A conversion as described with \texttt{stoi} is performed, but now to a
        value of type \texttt{long}.
    \item \index{stoll}\texttt{long long stoll(std::string const \&str, size\_t $*$pos = 0, 
                                                    int base = 10)}:\ \\ A conversion as described with \texttt{stoi} is performed, but now to a
        value of type \texttt{long long}.
    \item \index{stoul}\texttt{unsigned long stoul(std::string const \&str, size\_t $*$pos = 0, 
                                                    int base = 10)}:\ \\ A conversion as described with \texttt{stoi} is performed, but now to a
        value of type \texttt{unsigned long}.
    \item \index{stoull}\texttt{unsigned long long stoull(std::string const \&str, 
                                            size\_t $*$pos = 0, int base = 10)}:\ \\ A conversion as described with \texttt{stoul} is performed, but now to a
        value of type \texttt{unsigned long long}.
    \item \index{to\_string}\texttt{std::string to\_string(Type value)}:\ \\ Type can be of the types \texttt{int, long, long long, unsigned, unsigned
        long, unsigned long long, float, double,} or \texttt{long double}. The
        value of the argument is converted to a textual representation, which
        is returned as a \texttt{std::string} value.

\item \index{to\_wstring}\texttt{std::wstring to\_wstring(Type value)}:\ \\ The conversion as described at \texttt{to\_string} is performed, returning
        a \index{std::wstring}\texttt{std::wstring}.
    \end{itemize}

\section{std::string\_view}\label{STRINGVIEW}
\typeout{Original Yodl file: string/stringview}In addition to the class \texttt{std::string} the class \texttt{std::string\_view} can be
used as a wrapper-class of \texttt{char} arrays.  The class \texttt{string\_view} can
be considered a light-weight \texttt{string} class.  Before using
\texttt{std::string\_view} objects the \index{string\_view: header file}\texttt{$<$string\_view$>$} header file must have been
included.

In addition to the standard constructors (default, copy, move) it offers the
following constructors:
    \begin{itemize}
    \item \texttt{constexpr string\_view(char const $*$src, size\_t nChars)}, constructs a
\texttt{string\_view} object from the first \texttt{nChars} characters of \texttt{src}. The
characters in the range \texttt{[src, src + nChars)} may be 0-valued
characters;

\item \texttt{constexpr string\_view(char const $*$src)}, constructs a \texttt{string\_view}
object from the NTBS starting at \texttt{src}. The argument passed to this
constructor may not be a null pointer;

\item \texttt{constexpr string\_view(Iterator begin, Iterator end)}, constructs a
\texttt{string\_view} object from the characters in the iterator-range
\texttt{[begin, end)}.
    \end{itemize}
    A \texttt{string\_view} object does not contain its own copy of the initialized
data. Instead, it refers to the characters that were used when it was
initially constructed. E.g., the following program produces unpredictable
output, but when the \texttt{hello} array is defined as a static array it shows
\emph{hello}: 
    \begin{verbatim}
    #include <string_view>
    #include <iostream>
    using namespace std;
    
    string_view fun()
    {
        char hello[] = "hello";
        return { hello };
    }
    
    int main()
    {
        string_view obj = fun();
        cout << obj << '\n';
    }
\end{verbatim}
The \texttt{std::string\_view} class provides the same members as \texttt{std::string},
except for members extending the \texttt{string\_view's} characters (neither
appending nor inserting characters is possible). However, \texttt{string\_view}
objects \emph{can} modify their characters (using the index operator or \texttt{at}
member).

The \texttt{string\_view} class also offers some extra members:
    \begin{itemize}
    \item \index{remove\_prefix}\texttt{remove\_prefix(size\_t step)}:\ \\ moves the begin of the object's character range forward by \texttt{step}
        positions.
    \item \index{remove\_suffix}\texttt{remove\_suffix(size\_t step)}:\ \\ moves the end of the object's character range backward by \texttt{step}
        positions.
    \item \index{operator""sv}\texttt{constexpr string\_view operator""sv(char const $*$str,
        size\_t len)}:\ \\ returns a \texttt{string\_view} object containing \texttt{len} characters of
        \texttt{str}.
    \end{itemize}

Like \texttt{std::string} the \texttt{std::string\_view} class provides hashing
facilities, so \texttt{string\_view} objects can be used as keys in, e.g., \texttt{map}
containers (cf. chapter \ref{CONTAINERS}).


\cleardoublepage\chapter{The IO-stream Library}\label{IOStreams}
\typeout{Original Yodl file: iostreams}\typeout{Original Yodl file: iostreams/intro}Extending the standard stream (\index{FILE}\texttt{FILE}) approach, well known from the
\textbf{C} programming language, \textbf{C++} offers an \emph{input/output} (\index{I/O}I/O)
library \index{I/O library} based on \texttt{class} concepts.

All \textbf{C++} I/O facilities are defined in the namespace \index{std}\texttt{std}. The \texttt{std::}
prefix is omitted below, except for situations where this would result in
ambiguities.

Earlier (in chapter \ref{FirstImpression}) we've seen several examples of the
use of the \textbf{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 \textbf{C++}
programming language heavily uses the \texttt{class} concept and the notion of
member functions. Although class construction has not yet been covered (for
that see chapter \ref{Classes}) and although \emph{inheritance} is not covered
formally before chapter \ref{INHERITANCE}, it is quite possible to discuss I/O
facilities long before the technical background of class construction has been
covered.

Most \textbf{C++} I/O classes have names starting with \index{basic\_}\texttt{basic\_} (like
\texttt{basic\_ios}). However, these \index{basic\_}\texttt{basic\_} names are not regularly found in
\textbf{C++} programs, as most classes are also defined through \index{using}\texttt{using}
declarations  like:
        \begin{verbatim}
        using ios = basic_ios<char>;
\end{verbatim}
Since \textbf{C++} supports various kinds of character types (e.g., \index{char}\texttt{char},
\index{wchar\_t}\texttt{wchar\_t}), I/O facilities were developed using the \index{template}\emph{template} mechanism
allowing for easy conversions to character types other than the traditional
\texttt{char} type. As elaborated in chapter \ref{TEMPLATES}, this also allows the
construction of \index{generic software}generic software, that could thereupon be used for any
particular type representing characters. So, analogously to the above
using declaration there exists a
        \begin{verbatim}
        using wios = basic_ios<wchar_t>;
\end{verbatim}
This way, \texttt{wios} can be used for the \texttt{wchar\_t} type. Because of the
existence of these type definitions, the \texttt{basic\_} prefix was omitted from
the \textbf{C++} Annotations without loss of continuity. The \textbf{C++} Annotations primarily
focus on the standard 8-bits \texttt{char} type.

Iostream objects can\emph{not} be declared  using standard
    \index{forward declaration}forward declarations, like:
        \begin{verbatim}
    class std::ostream;     // now erroneous
\end{verbatim}
Instead, to \index{declare iostream classes}declare iostream classes the \index{iosfwd: header file}\texttt{$<$iosfwd$>$} header file
should be included:
        \begin{verbatim}
    #include <iosfwd>       // correct way to declare iostream classes
\end{verbatim}
Using \textbf{C++} I/O offers the additional advantage of
 \index{type safety}\emph{type safety}. Objects (or plain values) are inserted into
streams. Compare this to the situation commonly encountered in \textbf{C} where the
\index{fprintf}\texttt{fprintf} function is used to indicate by a format string what kind of
value to expect where. Compared to this latter situation \textbf{C++}'s
\emph{iostream} approach immediately uses the objects where their values should
appear, as in
        \begin{verbatim}
    cout << "There were " << nMaidens << " virgins present\n";
\end{verbatim}
The compiler notices the type of the \texttt{nMaidens} variable, inserting
its proper value at the appropriate place in the sentence inserted into
the \texttt{cout} iostream.

Compare this to the situation encountered in \textbf{C}. Although \textbf{C} compilers
are getting smarter and smarter, and although a well-designed
\textbf{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 \texttt{printf} statement, it can't do much more than \emph{warn} you.
The \emph{type safety} seen in \textbf{C++} \emph{prevents} you from making type
mismatches, as there are no types to match.

Apart from this, \emph{iostreams} offer more or less the same set of
possibilities as the standard \texttt{FILE}-based I/O used in \textbf{C}: files can be
opened, closed, positioned, read, written, etc.. In \textbf{C++} the basic \texttt{FILE}
structure, as used in \textbf{C}, is still available. But \textbf{C++} adds to this I/O
based on classes, resulting in type safety, extensibility, and a clean design.

The \index{ANSI/ISO}ANSI/ISO standard specifies architecture independent I/O. Not all of
the standard's specifications are covered in this chapter, as they often rely
on inheritance and polymorphism, which topics are formally covered by chapters
\ref{INHERITANCE} and \ref{POLYMORPHISM}. Some examples are
offered in chapter \ref{CONCRETE}, and in this chapter references to
specific sections in other chapters are given where appropriate.
        \begin{figure}[tbp]
\centerline{\epsffile{iostreams/ioclasses.eps}}
\caption{\label{IOCLASSESFIG}Central I/O Classes}
\end{figure}
This chapter is organized as follows (see also Figure \ref{IOCLASSESFIG}):
    \begin{itemize}
        \item  The class \index{ios\_base}\texttt{ios\_base} is the foundation upon which the
iostream I/O library was built. It defines the core of all I/O operations and
offers, among other things, facilities for inspecting the
 \index{state of I/O streams}state of I/O streams and facilities for \index{output formatting}output formatting.

\item  The class \index{ios}\texttt{ios} is directly \emph{derived} from
\texttt{ios\_base}. Every class of the I/O library doing input or output is itself
derived from this \texttt{ios} class, and therefore \emph{inherits} its (and, by
implication: \texttt{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 \ref{INHERITANCE}.\ \\ 
    The class \texttt{ios} is important because it implements communication with a
\emph{buffer} which is used by streams. This buffer is a \index{streambuf}\texttt{streambuf} object
which is responsible for the actual I/O to/from the actually used \emph{device},
which might be a file, a keyboard, a screen, an Internet connection, etc.,
etc.. Consequently \texttt{iostream} objects do not perform I/O operations
themselves, but leave these operations to the (stream)buffer objects with
which they are associated.

\item  Next, basic \textbf{C++} output facilities are discussed. The basic
class used for output operations is \index{ostream}\texttt{ostream}, defining the
 \index{insertion operator}insertion operator as well as other facilities writing information to
streams. Apart from inserting information into files it is possible to insert
information into \index{memory buffers}memory buffers, for which the \index{ostringstream}\texttt{ostringstream} class is
available. Formatting output is to a great extent possible using the
facilities defined in the \texttt{ios} class, but it is also possible to
\emph{insert} \index{formatting commands}\emph{formatting commands} directly into streams using
    \index{manipulator}\emph{manipulators}. This aspect of \textbf{C++} output is
discussed as well.

\item  Basic \textbf{C++} input facilities are implemented by the \index{istream}\texttt{istream}
class. This class defines the \index{extraction operator}extraction operator and related input
facilities. Comparably to inserting information into memory buffers (using
\texttt{ostringstream}) a class \index{istringstream}\texttt{istringstream} is available to extract
information from memory buffers.

\item  The class \index{iostream}\texttt{iostream} combines the facilities offered by
\texttt{istream} and \texttt{ostream}. Thus, \texttt{iostream} objects can be used to read
\emph{and} write from the same object.

\item  The class \texttt{fstream} is a frequently encountered example of an
\texttt{iostream} class: \texttt{fstream} objects are used to read and write from the
same file, which is often used in programs processing data bases. In this
chapter topics like \index{reading and writing}reading and writing from the same stream and
    \index{mixing \textbf{C} and \textbf{C++} I/O}mixing \textbf{C} and \textbf{C++} I/O using \index{filebuf}\texttt{filebuf} objects are also
covered. Other I/O related topics are covered elsewhere in the \textbf{C++} Annotations
(cf. section \ref{OSYNC} and chapter \ref{CONCRETE}).
    \end{itemize}

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 \texttt{streambuf}, which is responsible for the actual input and output
to the \index{device}device accessed by a \texttt{streambuf} object.

This approach allows us to construct a new kind of \texttt{streambuf} for a new
kind of device, and use that streambuf in combination with the `good old'
\texttt{istream}- and \texttt{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 \texttt{streambuf}
object. Interfacing to new devices (like \index{socket}\emph{sockets} or
 \index{file descriptor}\emph{file descriptors}) requires the construction of a new
kind of \texttt{streambuf}, rather than a new kind of \texttt{istream} or \texttt{ostream}
object. A \index{wrapper class}\emph{wrapper class} may be constructed around the \texttt{istream} or
\texttt{ostream} classes, though, to ease the access to a special device. This is
how the stringstream classes were constructed.

\section{Special header files}\label{IOHDRS}
\typeout{Original Yodl file: iostreams/headers}    Several iostream related \index{header file}header files are available. Depending on
the situation at hand, the following header files should be used:
    \begin{itemize}
    \item \index{iosfwd}\texttt{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 \texttt{ostream} then the compiler does not need to know
exactly what an \texttt{ostream} is. When declaring such a function
the \texttt{ostream} class merely needs to be be declared. One cannot use
        \begin{verbatim}
class std::ostream; // erroneous declaration

void someFunction(std::ostream &str);
\end{verbatim}
but, instead, one should use:
        \begin{verbatim}
#include <iosfwd>   // correctly declares class ostream

void someFunction(std::ostream &str);
\end{verbatim}
\item \index{ios: header file}\texttt{$<$ios$>$}: sources should include this header file when using
types and facilites (like \texttt{ios::off\_type}, see below) defined in the
\texttt{ios} class.
    \item \index{streambuf: header file}\texttt{$<$streambuf$>$}: sources should include this header file when using
\texttt{streambuf} or \index{filebuf}\texttt{filebuf} classes. See sections \ref{STREAMBUF} and
\ref{FILEBUF}.
    \item \index{istream: header file}\texttt{$<$istream$>$}: sources should include this preprocessor directive when
using the class \texttt{istream} or when using classes that do both input and
output.  See section \ref{ISTREAM}.
    \item \index{ostream: header file}\texttt{$<$ostream$>$}: sources should include this header file when using the class
\index{ostream}\texttt{ostream} class or when using classes that do both input and output.  See
section \ref{OSTREAM}.
    \item \index{iostream: header file}\texttt{$<$iostream$>$}: sources should include this header file when using the
global stream objects (like \index{cin}\texttt{cin} and \index{cout}\texttt{cout}) and also when defining a
stream capable of reading and writing from the same device (see also 
section \ref{IOSTREAMBUF}).
    \item \index{fstream: header file}\texttt{$<$fstream$>$}: sources should include this header file when using the file
stream classes.  See sections \ref{OFSTREAM}, \ref{IFSTREAM}, and \ref{FSTREAM}.
    \item \index{sstream: header file}\texttt{$<$sstream$>$}: sources should include this header file when using the
string stream classes. See sections \ref{OSTRINGSTREAM} and \ref{ISTRINGSTREAM}.
    \item \index{iomanip: header file}\texttt{$<$iomanip$>$}: sources should include this header file when using
parameterized manipulators. See section \ref{IOFORMAT}.
    \end{itemize}

\section{The foundation: the class `ios\_base'}
\typeout{Original Yodl file: iostreams/iosbase}The class \index{ios\_base}\texttt{std::ios\_base} forms the foundation of all I/O
operations, and defines, among other things, facilities for inspecting the
    \index{state of I/O streams}state of I/O streams and most \index{output formatting}output formatting facilities. Every
stream class of the I/O library is, through the class \index{ios}\texttt{ios}, \emph{derived}
from this class, and \emph{inherits} its capabilities.  As \texttt{ios\_base} is the
foundation on which all \textbf{C++} I/O was built, we introduce it here as the
first class of the \textbf{C++} I/O library.

Note that, as in \textbf{C}, I/O in \textbf{C++} is \emph{not} part of the language
(although it \emph{is} part of the \index{ANSI/ISO}ANSI/ISO standard on \textbf{C++}).  Although it
is technically possible to ignore all predefined I/O facilities, nobody does
so, and the I/O library therefore represents a \emph{de facto} I/O standard for
\textbf{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 \index{streambuf}\texttt{streambuf} or its derivatives.

It is neither possible nor required to construct an \texttt{ios\_base} object
directly. Its construction is always a side-effect of constructing an object
further down the class hierarchy, like \texttt{std::ios}. \texttt{Ios} is the next
class down the iostream hierarchy (see Figure \ref{IOCLASSESFIG}). Since all
stream classes in turn inherit from \texttt{ios}, and thus also from \texttt{ios\_base},
the distinction between \texttt{ios\_base} and \index{ios}\texttt{ios} is in practice not
important. Therefore, facilities actually provided by \texttt{ios\_base} will be
discussed as facilities provided by \texttt{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., \index{ios\_base.h}\texttt{ios\_base.h} and \index{basic\_ios.h}\texttt{basic\_ios.h}).

\section{Interfacing `streambuf' objects: the class `ios'}\label{IOS}
\typeout{Original Yodl file: iostreams/ios}The \index{ios}\texttt{std::ios} class is derived directly from \index{ios\_base}\texttt{ios\_base}, and it
defines \emph{de facto} the foundation for all stream classes of the \textbf{C++} I/O
library.

Although it \emph{is} possible to construct an \texttt{ios} object
directly, this is seldom done. The purpose of the class \texttt{ios} is to
provide the facilities of the class \texttt{basic\_ios}, and to add several new
facilites, all related to the \texttt{streambuf} object which is managed
by objects of the class \texttt{ios}.

All other stream classes are either directly or indirectly derived from
\texttt{ios}. This implies, as explained in chapter \ref{INHERITANCE}, that all
facilities of the classes \texttt{ios} and \texttt{ios\_base} are also available
to other stream classes. Before discussing these additional stream classes,
the features offered by the class \texttt{ios} (and by implication: by
\texttt{ios\_base}) are now introduced.

In some cases it may be required to include \index{ios}\texttt{ios} explicitly. An example
is the situations where the formatting flags themselves (cf. section
\ref{FORMATFLAGS}) are referred to in source code.

The class \texttt{ios} offers several member functions, most of which are related
to \index{formatting}formatting. Other frequently used member functions are:
    \begin{itemize}
    \item \index{rdbuf}\texttt{std::streambuf $*$ios::rdbuf()}:\ \\ A pointer to the \texttt{streambuf} object forming the interface between
the \texttt{ios} object and the device with which the \texttt{ios} object communicates
is returned. See sections \ref{STREAMBUF} and \ref{STRBUF} for more information
about the \texttt{class streambuf}.
    \item \texttt{std::streambuf $*$ios::rdbuf(std::streambuf $*$new)}:
        \begin{quote}The current \texttt{ios} object is associated with another
\texttt{streambuf} object. A pointer to the \texttt{ios} object's original \texttt{streambuf}
object is returned. The object to which this pointer points is not destroyed
when the \texttt{stream} object goes out of scope, but is owned by the caller of
\texttt{rdbuf}.\end{quote}
    \item \index{tie}\texttt{std::ostream $*$ios::tie()}:\ \\ A pointer to the \index{ostream}\texttt{ostream} object that is currently tied to the
\texttt{ios} object is returned (see the next member). The return value 0
indicates that currently no \texttt{ostream} object is tied to the \texttt{ios}
object. See section \ref{COUPLING} for details.
    \item \texttt{std::ostream $*$ios::tie(std::ostream $*$outs)}:
        \begin{quote}The ostream object is tied to current \texttt{ios} object. This means
that the \texttt{ostream} object is \emph{flushed} every time before an input or
output action is performed by the current \texttt{ios} object. A pointer to the
\texttt{ios} object's original \texttt{ostream} object is returned. To break the tie,
pass the argument 0. See section \ref{COUPLING} for an example.\end{quote}
    \end{itemize}

\subsection{Condition states}\label{IOSTATES}
    \typeout{Original Yodl file: iostreams/conditions}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
 \index{condition state}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 \index{condition flags}\emph{condition flags}:
    \begin{itemize}
        \item \index{badbit}\texttt{ios::badbit}:\ \\ if this flag has been raised an illegal operation has been
requested at the level of the \texttt{streambuf} object to which the stream
interfaces. See the member functions below for some examples.
        \item \index{eofbit}\texttt{ios::eofbit}:\ \\ if this flag has been raised, the \texttt{ios} object has sensed
end of file.
        \item \index{failbit}\texttt{ios::failbit}:\ \\ if this flag has been raised, an operation performed by the
stream object has failed (like an attempt to extract an \texttt{int} when no
numeric characters are available on input). In this case the stream itself
could not perform the operation that was requested of it.
        \item \index{goodbit}\texttt{ios::goodbit}:\ \\ this flag is raised when  none of the other three condition
flags were raised.
    \end{itemize}

Several \index{condition member functions}condition member functions are available to manipulate or
determine the states of \texttt{ios} objects. Originally they returned \texttt{int}
values, but their current return type is \texttt{bool}:
    \begin{itemize}
    \item \index{bad}\texttt{bool ios::bad()}:
            \begin{quote}the value \texttt{true} is returned when the stream's
\texttt{badbit} has been set and \texttt{false} otherwise.  If \texttt{true} is
returned it indicates that an illegal operation has been requested at the
level of the \texttt{streambuf} object to which the stream interfaces. What does
this mean? It indicates that the \texttt{streambuf} itself is behaving
unexpectedly. Consider the following example:
        \begin{verbatim}
std::ostream error(0);
\end{verbatim}
Here an \texttt{ostream} object is constructed \emph{without} providing it with a
working \texttt{streambuf} object. Since this `\texttt{streambuf}' will never operate
properly, its \texttt{badbit} flag is raised from the very beginning:
\texttt{error.bad()} returns \texttt{true}.
            \end{quote}
    \item \index{eof}\texttt{bool ios::eof()}:
            \begin{quote}the value \texttt{true} is returned when end of file
(\texttt{EOF}) has been sensed (i.e., the \texttt{eofbit} flag has been set) and
\texttt{false} otherwise. Assume we're reading lines line-by-line from \texttt{cin}, but
the last line is not terminated by a final \texttt{\textbackslash{}n} character. In that case
\index{getline}\texttt{std::getline} attempting to read the \texttt{\textbackslash{}n} delimiter hits
end-of-file first. This raises the \texttt{eofbit} flag and \texttt{cin.eof()} returns
\texttt{true}. For example, assume \texttt{std::string str} and \texttt{main} executing the
statements:
        \begin{verbatim}
getline(cin, str);
cout << cin.eof();
\end{verbatim}
Then
        \begin{verbatim}
echo "hello world" | program
\end{verbatim}
prints the value 0 (no EOF sensed). But after
        \begin{verbatim}
echo -n "hello world" | program
\end{verbatim}
the value 1 (EOF sensed) is printed.\end{quote}
    \item \index{fail}\texttt{bool ios::fail()}:
            \begin{quote}the value \texttt{true} is returned when \texttt{bad} returns \texttt{true}
or when the \texttt{failbit} flag was set. The value \texttt{false} is returned
otherwise.  In the above example, \texttt{cin.fail()} returns \texttt{false},
whether we terminate the final line with a delimiter or not (as we've read
a line). However, executing \emph{another} \texttt{getline} results in
raising the \texttt{failbit} flag, causing \texttt{cin::fail()} to return
\texttt{true}. In general: \texttt{fail} returns \texttt{true} if the requested stream
operation failed. A simple example showing this consists of an attempt to
extract an \texttt{int} when the input stream contains the text \texttt{hello
world}. The value \texttt{not fail()} is returned by the \texttt{bool}
interpretation of a stream object (see below).\end{quote}
    \item \index{good}\texttt{bool ios::good()}:
            \begin{quote}the value of the
\texttt{goodbit} flag is returned. It equals \texttt{true} when none of the other
condition flags (\texttt{badbit, eofbit, failbit}) was raised.
    Consider the following little program:
        \begin{verbatim}
#include <iostream>
#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();
}
\end{verbatim}
When this program processes a file having two lines, containing,
respectively, \texttt{hello} and \texttt{world}, while the second
line is not terminated by a \texttt{\textbackslash{}n} character the following is shown:
        \begin{verbatim}
    Bad: 0 Fail: 1 Eof: 0 Good: 0

    Bad: 0 Fail: 0 Eof: 0 Good: 1

    Bad: 0 Fail: 0 Eof: 1 Good: 0
\end{verbatim}
Thus, extracting \texttt{x} fails (\texttt{good} returning \texttt{false}). Then,
the error state is cleared, and the first line is successfully read
(\texttt{good} returning \texttt{true}). Finally the second line is read
(incompletely): \texttt{good} returning \texttt{false}, and \texttt{eof} returning \texttt{true}.
        \end{quote}
    \item  \index{ios object: as bool value}
         \index{stream: as bool value}
        Interpreting streams as \texttt{bool} values:
            \begin{quote}streams may be used in expressions expecting logical
values. Some examples are:
        \begin{verbatim}
if (cin)                // cin itself interpreted as bool
if (cin >> x)           // cin interpreted as bool after an extraction
if (getline(cin, str))  // getline returning cin
\end{verbatim}
When interpreting a stream as a logical value, it is actually `\texttt{not
fail()}' that is interpreted. The above examples may therefore be rewritten
as:
        \begin{verbatim}
if (not cin.fail())
if (not (cin >> x).fail())
if (not getline(cin, str).fail())
\end{verbatim}
The former incantation, however, is used almost exclusively.
            \end{quote}
    \end{itemize}

The following members are available to manage error states:
    \begin{itemize}
        \item \index{clear}\texttt{void ios::clear()}:
    \begin{quote}When an error condition has occurred, and the condition can be
repaired, then \texttt{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: \texttt{clear(int state)}. Its return
type is \texttt{void}\end{quote}
        \item \index{rdstate}\texttt{ios::iostate ios::rdstate()}:
        \begin{quote}\index{stream state flags}\index{flags: of ios objects}
    The current set of flags that are set for an \texttt{ios} object are returned
(as an \texttt{int}). To test for a particular flag, use the \index{bitwise and}bitwise and
operator:
        \begin{verbatim}
if (!(iosObject.rdstate() & ios::failbit))
{
    // last operation didn't fail
}
\end{verbatim}
Note that this test cannot be performed for the \texttt{goodbit} flag as its
value equals zero. To test for `good' use a construction
like:
        \begin{verbatim}
if (iosObject.rdstate() == ios::goodbit)
{
    // state is `good'
}
\end{verbatim}
\end{quote}
        \item \index{setstate}\texttt{void ios::setstate(ios::iostate state)}:
        \begin{quote}A stream may be assigned a certain set of states using
\texttt{setstate}. Its return type is \texttt{void}. E.g.,
        \begin{verbatim}
cin.setstate(ios::failbit);     // set state to `fail'
\end{verbatim}
To set multiple flags in one \texttt{setstate()} call use the \texttt{bitor}
operator:
        \begin{verbatim}
cin.setstate(ios::failbit | ios::eofbit)
\end{verbatim}
\end{quote}
    The member \texttt{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:
        \begin{itemize}
            \item  An error condition is detected,
            \item  The error is repaired
            \item  The member \texttt{clear} is called.
        \end{itemize}
        \end{itemize}
    \textbf{C++} supports an \index{exception}\emph{exception} mechanism to handle exceptional
situations. According to the \index{ANSI/ISO}ANSI/ISO standard, exceptions can be used
with stream objects. Exceptions are covered in chapter \ref{EXCEPTIONS}. Using
exceptions with stream objects is covered in section \ref{IOEXCEPTIONS}.

\subsection{Formatting output and input}\label{IOFORMAT}
    \typeout{Original Yodl file: iostreams/formatting}The way information is written to streams (or, occasionally, read from
streams) is controlled by \index{formatting flags}\emph{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 \index{radix}\emph{radix}) in
which values are displayed. Most formatting features belong to the realm of
the \texttt{ios} class. Formatting is controlled by flags, defined by the \texttt{ios}
class.  These flags may be manipulated in two ways: using specialized
member functions or using \emph{manipulators}, which 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., \texttt{iostream}) has been included. Some manipulators require
arguments. To use those latter manipulators the header file \index{iomanip}\texttt{iomanip} must
be included.

\subsubsection{Format modifying member functions}\label{FORMATMEMBERS}
        \typeout{Original Yodl file: iostreams/formatmembers}Several \emph{member functions} are available manipulating the I/O \index{formatting}formatting
flags. Instead of using the members listed below \emph{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.

\begin{itemize}
    \item \index{copyfmt}\texttt{ios \&ios::copyfmt(ios \&obj)}:\ \\ all format flags of \texttt{obj} are copied to the current \texttt{ios}
object. The current \texttt{ios} object is returned.
    \item \index{fill}\texttt{ios::fill() const}:\ \\ the current \index{padding}padding character is returned. By default, this is the
blank space.
    \item \texttt{ios::fill(char padding)}:
        \begin{quote}the padding character is redefined, the padding character that
was used before the redefinition is returned. Instead of using this member
function the \index{setfill}\texttt{setfill} \emph{manipulator} may be inserted directly into an
\texttt{ostream}. Example:
        \begin{verbatim}
cout.fill('0');         // use '0' as padding char
cout << setfill('+');   // use '+' as padding char
\end{verbatim}
\end{quote}
    \item \index{flags}\texttt{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 \texttt{bit\_and} operator. Example:
            \begin{verbatim}
if (cout.flags() & ios::hex)
    cout << "Integral values are printed as hex numbers\n"
\end{verbatim}
\item \texttt{ios::fmtflags ios::flags(ios::fmtflags flagset)}:
       \begin{quote}the \emph{previous} set of flags are returned and the new set of
flags are defined by \texttt{flagset}. Multiple flags are specified using the
\texttt{bitor} operator. Example:
        \begin{verbatim}
        // change the representation to hexadecimal
cout.flags(ios::hex | cout.flags() & ~ios::dec);
\end{verbatim}
\end{quote}
    \item \index{precision}\texttt{int ios::precision() const}:\ \\ the number of significant digits used when outputting floating point
values is returned (default: 6).
    \item \texttt{int ios::precision(int signif)}:\index{display floating point numbers}
        \begin{quote}the number of significant digits to use when outputting real
values is set to \texttt{signif}. The previously used number of significant digits
is returned. If the number of required digits exceeds \texttt{signif} then the
number is displayed in `scientific' notation (cf. section
\ref{FORMATFLAGS}). Manipulator: \index{setprecision}\texttt{setprecision}. Example:
            \begin{verbatim}
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
\end{verbatim}
\end{quote}
        \item  \index{setf}\label{SETF}\texttt{ios::fmtflags ios::setf(ios::fmtflags
flags)}: 
        \begin{quote}sets one or more formatting flags (use the \texttt{bitor}
operator to combine multiple flags). Already set flags are not affected. The
\emph{previous} set of flags is returned. Instead of using this member function
the manipulator \index{setiosflags}\texttt{setiosflags} may be used. Examples are provided in the next
section (\ref{FORMATFLAGS}).\end{quote}
    \item \texttt{ios::fmtflags ios::setf(ios::fmtflags flags, ios::fmtflags mask)}:
            \begin{quote}clears all flags mentioned in \texttt{mask} and sets the flags
specified in \texttt{flags}. The \emph{previous} set of flags is returned. Some
examples are (but see the next section (\ref{FORMATFLAGS}) for a more thorough
discussion):
            \begin{verbatim}
        // 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);
\end{verbatim}
\end{quote}
    \item  \index{unsetf}\label{UNSETF}\texttt{ios::fmtflags ios::unsetf(fmtflags flags)}:
        \begin{quote}the specified formatting flags are cleared (leaving the
remaining flags unaltered) and returns the \emph{previous} set of flags.  A
request to unset an active default flag (e.g., \texttt{cout.unsetf(ios::dec)})
is ignored. Instead of this member function the manipulator \index{resetiosflags}\texttt{resetiosflags}
may also be used. Example:
        \begin{verbatim}
cout << 12.24;              // displays  12.24
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
\end{verbatim}
\end{quote}
    \item \index{width}\index{display field width}
        \label{WIDTH}\texttt{int ios::width() const}:
        \begin{quote}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'.\end{quote}
    \item \texttt{int ios::width(int nchars)}:
        \begin{quote}the field width of the next insertion operation is set to
\texttt{nchars}, returning the previously used field width. This setting is not
persistent. It is reset to 0 after every insertion operation. Manipulator:
\index{setw}\texttt{std::setw(int)}. Example:
        \begin{verbatim}
cout.width(5);
cout << 12;                     // using 5 chars field width
cout << setw(12) << "hello";    // using 12 chars field width
\end{verbatim}
\end{quote}
    \end{itemize}

\subsubsection{Formatting flags}\label{FORMATFLAGS}
        \typeout{Original Yodl file: iostreams/flags}Most \index{formatting flags}\emph{formatting flags} are related to outputting information. Information
can be written to output streams in basically two ways: using
 \index{binary output}\emph{binary output} information is written directly to an output stream,
without converting it first to some \index{human-readable}human-readable format and using
 \index{formatted output}\emph{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.

\textbf{To display information in wide fields}:

\begin{itemize}
    \item  \index{internal}\index{adjustfield}\texttt{ios::internal}:
        \begin{quote}to add \index{fill characters}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: \texttt{std::internal}. Example:
        \begin{verbatim}
cout.setf(ios::internal, ios::adjustfield);
cout << internal;       // same, using the manipulator

cout << '\'' << setw(5) << -5 << "'\n";  // displays '-   5'
\end{verbatim}
\end{quote}
    \item \index{left}\texttt{ios::left}:\ \\ to left-adjust values in fields that are wider than needed to display
the values.  Manipulator: \texttt{std::left}. Example:
        \begin{verbatim}
cout.setf(ios::left, ios::adjustfield);
cout << left;           // same, using the manipulator

cout << '\'' << setw(5) << "hi" << "'\n";  // displays 'hi   '
\end{verbatim}
\item \index{right}\texttt{ios::right}:\ \\ to right-adjust values in fields that are wider than needed to
display the values.  Manipulator: \texttt{std::right}. This is the default.
Example:
        \begin{verbatim}
cout.setf(ios::right, ios::adjustfield);
cout << right;          // same, using the manipulator

cout << '\'' << setw(5) << "hi" << "'\n";  // displays '   hi'
\end{verbatim}
\end{itemize}

\textbf{Using various number representations}:

\begin{itemize}
    \item \index{dec}\texttt{ios::dec}:\ \\ to display integral values as decimal numbers. Manipulator:
\texttt{std::dec}. This is the default. Example:
        \begin{verbatim}
cout.setf(ios::dec, ios::basefield);
cout << dec;            // same, using the manipulator
cout << 0x10;           // displays 16
\end{verbatim}
\item \index{hex}\texttt{ios::hex}:\ \\ to display integral values as hexadecimal numbers. Manipulator:
\texttt{std::hex}. Example:
        \begin{verbatim}
cout.setf(ios::hex, ios::basefield);
cout << hex;            // same, using the manipulator
cout << 16;             // displays 10
\end{verbatim}
\item \index{oct}\texttt{ios::oct}:\ \\ to display integral values as octal numbers. Manipulator:
\texttt{std::oct}. Example:
        \begin{verbatim}
cout.setf(ios::oct, ios::basefield);
cout << oct;            // same, using the manipulator
cout << 16;             // displays 20
\end{verbatim}
\item \index{setbase}\texttt{std::setbase(int radix)}:\ \\ This is a manipulator that can be used to change the number
representation to decimal, hexadecimal or octal. Example:
        \begin{verbatim}
cout << setbase(8);     // octal numbers, use 10 for
                        // decimal, 16 for hexadecimal
cout << 16;             // displays 20
\end{verbatim}
\end{itemize}

\textbf{Fine-tuning displaying values}:

\begin{itemize}
    \item \index{boolalpha}\texttt{ios::boolalpha}:\ \\ logical values may be displayed as text using the text `\texttt{true}' for
the \texttt{true} logical value, and `\texttt{false}' for the \texttt{false} logical value
using \texttt{boolalpha}.  By default this flag is not set. Complementary flag:
\texttt{ios::noboolalpha}. Manipulators: \texttt{std::boolalpha} and
\index{noboolalpha}\texttt{std::noboolalpha}.  Example:
        \begin{verbatim}
cout.setf(ios::boolalpha);
cout << boolalpha;      // same, using the manipulator
cout << (1 == 1);       // displays true
\end{verbatim}
\item \index{showbase}\texttt{ios::showbase}:\ \\ to display the numeric base of integral values. With hexadecimal
values the \texttt{0x} prefix is used, with octal values the prefix \texttt{0}. For the
(default) decimal value no particular prefix is used. Complementary flag:
\texttt{ios::noshowbase}. Manipulators: \texttt{std::showbase} and
\index{noshowbase}\texttt{std::noshowbase}. Example:
        \begin{verbatim}
cout.setf(ios::showbase);
cout << showbase;       // same, using the manipulator
cout << hex << 16;      // displays 0x10
\end{verbatim}
\item \index{showpos}\texttt{ios::showpos}:\ \\ to display the \texttt{+} sign with positive decimal (only)
values. Complementary flag:\ \\ \texttt{ios::noshowpos}.  Manipulators:
\texttt{std::showpos} and \index{noshowpos}\texttt{std::noshowpos}. Example:
        \begin{verbatim}
cout.setf(ios::showpos);
cout << showpos;            // same, using the manipulator
cout << 16;                 // displays +16
cout.unsetf(ios::showpos);  // Undo showpos
cout << 16;                 // displays 16
\end{verbatim}
\item \index{uppercase}\texttt{ios::uppercase}:\ \\ to display letters in hexadecimal values using capital
letters. Complementary flag: \texttt{ios::nouppercase}.  Manipulators:
\texttt{std::uppercase} and \index{nouppercase}\texttt{std::nouppercase}.  By default lower
case letters are used. Example:
        \begin{verbatim}
cout.setf(ios::uppercase);
cout << uppercase;            // same, using the manipulator
cout << hex << showbase <<
        3735928559;           // displays 0XDEADBEEF
\end{verbatim}
\end{itemize}

\textbf{Displaying floating point numbers}

\begin{itemize}
    \item \index{fixed}\index{floatfield}\index{display floating point numbers}
        \texttt{ios::fixed}:
        \begin{quote}to display real values using a fixed decimal point (e.g., 12.25
rather than 1.225e+01), the \texttt{fixed} formatting flag is used. It can be used
to set a fixed number of digits behind the decimal point. Manipulator:
\texttt{fixed}. Example:
            \begin{verbatim}
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
\end{verbatim}
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
\texttt{fixed} has the same effect.
        \end{quote}
    \item \index{scientific}\texttt{ios::scientific}:\ \\ to display real values in \index{scientific notation}\emph{scientific notation} (e.g., 1.24e+03).
Manipulator: \texttt{std::scientific}.  Example:
        \begin{verbatim}
cout.setf(ios::scientific, ios::floatfield);
cout << scientific;         // same, using the manipulator
cout << 12.25;              // displays 1.22500e+01
\end{verbatim}
\item \index{showpoint}\texttt{ios::showpoint}:\ \\ to display a trailing decimal point \emph{and} trailing decimal zeros
when real numbers are displayed. Complementary flag:
\texttt{ios::noshowpoint}. Manipulators: \texttt{std::showpoint},
 \index{noshowpoint}\texttt{std::noshowpoint}. Example:
        \begin{verbatim}
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
\end{verbatim}
Note that the final 16 is an integral rather than a floating point number,
so it has no decimal point. So \texttt{showpoint} has no effect.
    If \texttt{ios::showpoint} is not active trailing zeros are discarded. If
the fraction is zero the decimal point is discarded as well. Example:
        \begin{verbatim}
cout.unsetf(ios::fixed, ios::showpoint);    // unset the flags

cout << 16.0 << ", " << 16.1;
// displays: 16, 16.1
\end{verbatim}
\end{itemize}

\textbf{Handling whitespace and flushing streams}

\begin{itemize}
    \item \index{endl}\texttt{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 \texttt{endl} should be
avoided (in favor of inserting \texttt{'\textbackslash{}n'}) unless flushing 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. \texttt{tie}
in section \ref{IOS}). Example:
        \begin{verbatim}
cout << "hello" << endl;    // prefer: << '\n';
\end{verbatim}
\item \index{ends}\texttt{std::ends}:\ \\ manipulator inserting a 0-byte into a stream. It is usually used in
combination with memory-streams (cf. section \ref{OSTRINGSTREAM}).

\item \index{flush}\texttt{std::flush}:\ \\ a stream may be flushed using this member. Often flushing the stream
is not required and doing so would needlessly slow down I/O
processing. Consequently, using \texttt{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. \texttt{tie} in section \ref{IOS}). Example:
        \begin{verbatim}
cout << "hello" << flush;    // avoid if possible.
\end{verbatim}
\item \index{skipws}\texttt{ios::skipws}:\ \\ leading \index{whitespace}whitespace 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 whitespace characters are not skipped.
Manipulator: \texttt{std::skipws}. Example:
        \begin{verbatim}
cin.setf(ios::skipws);  // to unset, use
                        //  cin.unsetf(ios::skipws)

cin >> skipws;          // same, using the manipulator
int value;
cin >> value;           // skips initial blanks
\end{verbatim}
\item \index{unitbuf}\texttt{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 \texttt{unitbuf}
should be avoided unless flushing 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. \texttt{tie} in section \ref{IOS}).  Complementary
flag: \texttt{ios::nounitbuf}. Manipulators: \texttt{std::unitbuf},
\index{nounitbuf}\texttt{std::nounitbuf}. Example:
        \begin{verbatim}
cout.setf(ios::unitbuf);
cout << unitbuf;            // same, using the manipulator

cout.write("xyz", 3);       // flush follows write.
\end{verbatim}
\item \index{ws}\texttt{std::ws}:\ \\ manipulator removing all \index{whitespace}whitespace characters (blanks, tabs,
newlines, etc.) at the current file position. White space characters are
removed if present even if the flag \texttt{ios::noskipws} has been set.  Example
(assume the input contains 4 blank characters followed by the character
\texttt{X}):
        \begin{verbatim}
cin >> ws;      // skip whitespace
cin.get();      // returns 'X'
\end{verbatim}
\end{itemize}

\subsubsection{The std::quoted manipulator}\label{QUOTED}
        \typeout{Original Yodl file: iostreams/quoted.yo}The \texttt{std::quoted}\index{quoted} manipulator can be used to extract or insert
quoted strings from, c.q. into, streams. The manipulator can, e.g., be used to
read the text in quoted strings from a comma-separated data file or to
surround text by quotes when writing such files.

The \texttt{quoted} manipulator defines three parameters, the second and third
parameters have default values.

When inserting a \texttt{quoted} manipulator into an \texttt{std::ostream} its first
parameter is a \texttt{char const $*$}, a \texttt{std::string const \&}, or a
\texttt{std::string\_view} object. It inserts its first argument, surrounded by
quotes, into the \texttt{std::ostream}.

When extracting a \texttt{quoted} manipulator from an \texttt{std::istream} its first
parameter is an \texttt{std::string \&}. It extracts a quoted string from the
\texttt{std::istream} and stores the extracted text without the surrounding quotes
into its first argument.

The second and third arguments specify, respectively, the delimiter that is
used surrounding the quoted string (by default a double quote (\texttt{"})), and
an escape character that can be prefixed to characters inside the quoted
string: the escape character will be ignored and the next character will be
used as-is.

The generic form of the \texttt{quoted} manipulator is:
    \begin{verbatim}
quoted(source-or-destination, char delim = '"', char escape = '\\')
\end{verbatim}
Within the quoted text blanks are not skipped.

Example, executing \texttt{a.out $<$ input}:
    \begin{verbatim}
    int main()
    {
        cout << quoted("hello \"world\"") << '\n';
    
        string str = "hello 'world'";
        cout << quoted(str, '\'', '%') << '\n';
    
        cin >> quoted(str);         // 1
        cin.ignore(100, '\n');
        cout << "1: " << str << '\n';
    
        cin >> quoted(str, '\'');   // 2
        cin.ignore(100, '\n');
        cout << "2: " << str << '\n';
    }
    
    // input
    //    "hello \"world\""
    //    'hello \'world\''
    
    // output:
    // "hello \"world\""
    // 'hello %'world%''
    // 1: hello "world"
    // 2: hello 'world'
\end{verbatim}
\section{Output}
\typeout{Original Yodl file: iostreams/output}In \textbf{C++} output is primarily based on the \index{ostream}\texttt{std::ostream}
class. The \texttt{ostream} class defines the basic operators and members inserting
information into streams: the \index{insertion operator}\emph{insertion operator} ($<<$), and special
members like \texttt{write} writing unformatted information to streams.

The class \texttt{ostream} acts as \emph{base class} for several other classes, all
offering the functionality of the \texttt{ostream} class, but adding their own
specialties. In the upcoming sections the following classes are discussed:
    \begin{itemize}
    \item  The class \texttt{ostream}, offering the basic output facilities;
    \item  The class \index{ofstream}\texttt{ofstream}, allowing us to write files
(comparable to \textbf{C}'s \index{fopen} \texttt{fopen(filename, "w")});
    \item  The class \index{ostringstream}\texttt{ostringstream}, allowing us to write information to
memory (comparable to \textbf{C}'s \index{sprintf}\texttt{sprintf} function).
    \end{itemize}

\subsection{Basic output: the class `ostream'}\label{OSTREAM}
    \typeout{Original Yodl file: iostreams/ostream}The class \index{ostream}\texttt{ostream} defines basic output facilities. The \index{cout}\texttt{cout}, \index{clog}\texttt{clog}
and \index{cerr}\texttt{cerr} objects are all \texttt{ostream} objects. All facilities related to
output as defined by the \texttt{ios} class are also available in the \texttt{ostream}
class.

We may define \texttt{ostream} objects using the following
 \index{ostream constructor}\emph{ostream constructor}:
    \begin{itemize}
    \item \texttt{std::ostream object(std::streambuf $*$sb)}:
        \begin{quote}this constructor creates an \texttt{ostream} object which is a
wrapper around an existing \texttt{std::streambuf} object.  It isn't possible to
define a plain \texttt{ostream} object (e.g., using \texttt{std::ostream out;}) that
can thereupon be used for insertions. When \texttt{cout} or its friends are used,
we are actually using a predefined \texttt{ostream} object that has already been
defined for us and interfaces to the standard output stream using a
(also predefined) \texttt{streambuf} object handling the actual interfacing.

It \emph{is}, however, possible to define an \texttt{ostream} object passing it
 \index{ostream: define using 0-pointer} a 0-pointer. Such an object cannot be
used for insertions (i.e., it raises its \texttt{ios::bad} flag when something
is inserted into it), but it may be given a \texttt{streambuf} later. Thus it may
be preliminary constructed, suspending its use until an appropriate
\texttt{streambuf} becomes available (see also section \ref{STREAMBUF}).
    \end{quote}
    \end{itemize}
    To define the \texttt{ostream} class in \textbf{C++} sources, the
    \index{ostream: header file}\texttt{$<$ostream$>$} header file must be included. To use the predefined
\texttt{ostream} objects (\texttt{std::cerr, std::cout} etc.) the \index{iostream: header file}\texttt{$<$iostream$>$} header
file must be included.

\subsubsection{Writing to `ostream' objects}
        \typeout{Original Yodl file: iostreams/ostreamwrite}The class \index{ostream}\texttt{ostream} supports both formatted and \index{binary output}\emph{binary output}.

The \index{insertion operator}\emph{insertion operator} ($<<$) is used to insert values in
a type safe way into \texttt{ostream} objects.  This is called
    \index{formatted output}formatted output, as binary values which are stored in the computer's
memory are converted to human-readable \index{ASCII}ASCII characters according to
certain formatting rules.

The insertion operator points to the \texttt{ostream} object to
receive the information.  The normal associativity of $<<$
remains unaltered, so when a statement like
        \begin{verbatim}
    cout << "hello " << "world";
\end{verbatim}
is encountered, the leftmost two operands are evaluated first (\texttt{cout}
$<<$ \texttt{"hello "}), and an \texttt{ostream \&} object, which is actually the
same \texttt{cout} object, is returned. Now, the statement is reduced to
        \begin{verbatim}
    cout << "world";
\end{verbatim}
and the second string is inserted into \texttt{cout}.

The $<<$ operator has a lot of (overloaded) variants, so many types of
variables can be inserted into \texttt{ostream} objects. There is an overloaded
$<<$-operator expecting an \texttt{int}, a \texttt{double}, a pointer, etc. etc..
Each operator returns the \texttt{ostream} object into which the information so far
has been inserted, and can thus immediately be followed by the next insertion.

In addition to insertion operators \texttt{ostreams} also support
\texttt{std::print}\index{print}. It is called as
 \begin{verbatim}
     std::ostream& os, std::format_string<Args...> fmt, Args&&... args
\end{verbatim}
    where \texttt{...} indicates that any number of arguments can be specified.
However, since a \texttt{print}-like functionality is hardly ever required in
\textbf{C++} programs it's not covered in detail in the \textbf{C++} Annotations. Refer to
\texttt{cppreference.com} for details about \texttt{std::print}.

When \index{binary file} binary files must be written, normally no
text-formatting is used or required: an \texttt{int} value should be written as a
series of raw bytes, not as a series of \index{ASCII}ASCII numeric characters 0 to
9. The following member functions of \texttt{ostream} objects may be used to
write `binary files':
    \begin{itemize}
    \item \index{put}\texttt{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.
     \item \index{write}\texttt{ostream\& write(char const $*$buffer, int length)}:\ \\ to write at most \texttt{length} bytes, stored in the \texttt{char const
$*$buffer} to the \texttt{ostream} object. Bytes are written as they are stored
in the buffer, no formatting is done whatsoever. Note that the first argument
is a \texttt{char const $*$}: a \emph{type cast} is required to write any other
type. For example, to write an \texttt{int} as an unformatted series of
byte-values use:
        \begin{verbatim}
int x;
out.write(reinterpret_cast<char const *>(&x), sizeof(int));
\end{verbatim}
The bytes written by the above \texttt{write} call are written to the
\texttt{ostream} in an order depending on the \index{endian}\emph{endian}\emph{-ness} of the
underlying hardware. Big-endian computers write the most significant byte(s)
of multi-byte values first, little-endian computers first write the least
significant byte(s).
    \end{itemize}

\subsubsection{`ostream' positioning}\label{OSTREAMPOS}
        \typeout{Original Yodl file: iostreams/ostreamseek}Although not every \texttt{ostream} object supports \index{repositioning}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:
    \begin{itemize}
    \item \index{tellp}\texttt{ios::pos\_type tellp()}:\ \\ the current (absolute) position in the file where the next
write-operation to the stream will take place is returned.
    \item \index{seekp}\texttt{ostream \&seekp(ios::off\_type step, ios::seekdir org)}:\ \\ modifies a stream's actual position. The function expects an
\index{off\_type}\texttt{off\_type} \texttt{step} representing the number of bytes the current stream
position is moved with respect to \texttt{org}. The \texttt{step} value
may be negative, zero or positive.

The origin of the step, \texttt{org} is a value in the
\index{seekdir}\texttt{ios::seekdir} enumeration. Its values are:
        \begin{itemize}
        \item \index{beg}\texttt{ios::beg}:\ \\ the stepsize is computed relative to the beginning of the
stream. This value is used by default.

\item \index{cur}\texttt{ios::cur}:\ \\ the stepsize is computed relative to the current position of the
stream (as returned by \texttt{tellp}).

\item \index{end}\texttt{ios::end}:\ \\ the stepsize is interpreted relative to the current end position
of the stream.
    \end{itemize}
    It is OK to
 \index{write beyond end of file}\index{seek beyond file boundaries}
    seek or write beyond the last file position.  Writing bytes to a location
beyond \texttt{EOF} will pad the intermediate bytes with 0-valued bytes:
\index{null-bytes}null-bytes.
    Seeking before \texttt{ios::beg} raises the \index{fail}\texttt{ios::fail} flag.

Different from \texttt{seekg} (cf. section \ref{ISTREAMPOS}) \texttt{seekp} does not
clear the stream's \texttt{ios::eofbit}. To reset an \texttt{ostream's} state to `good',
its \texttt{clear} member should be called.

\end{itemize}

\subsubsection{`ostream' flushing}
        \typeout{Original Yodl file: iostreams/ostreamflush}Unless the \texttt{ios::unitbuf} flag has been set, information written to an
\texttt{ostream} object is not immediately written to the physical stream. Rather,
an internal buffer is filled during the write-operations, and when full it
is flushed.

The stream's \index{internal buffer}internal buffer can be flushed under program control:
    \begin{itemize}
    \item \index{flush}\texttt{ostream\& flush()}:\ \\ any buffered information stored internally by the \texttt{ostream} object
is flushed to the device to which the \texttt{ostream} object interfaces. A stream
is flushed automatically when:
        \begin{itemize}
        \item  the object ceases to exist;
        \item  the \texttt{endl} or \texttt{flush} \emph{manipulators} (see section
            \ref{FORMATFLAGS}) are inserted into an \texttt{ostream} object;
        \item  a stream supporting the \index{close}\texttt{close}-operation is explicitly closed
(e.g., a \texttt{std::ofstream} object, cf. section \ref{OFSTREAM}).

\end{itemize}

\end{itemize}

\subsection{Output to files: the class `ofstream'}\label{OFSTREAM}
    \typeout{Original Yodl file: iostreams/ofstream}The \index{ofstream}\texttt{std::ofstream} class is derived from the \texttt{ostream} class:
it has the same capabilities as the \texttt{ostream} class, but can be used to
\index{access files}access files or \index{create files}create files for writing.

In order to use the \texttt{ofstream} class  in \textbf{C++} sources, the
    \index{fstream: header file}\texttt{$<$fstream$>$} header file must be included. Including \texttt{fstream} does not
automatically make available the standard streams \texttt{cin}, \texttt{cout} and
\texttt{cerr}. Include \index{iostream}\texttt{iostream} to declare these standard streams.

The following \index{ofstream constructors} constructors are available for
\texttt{ofstream} objects:
    \begin{itemize}
    \item \texttt{ofstream object}:
        \begin{quote}this is the basic constructor. It defines an \texttt{ofstream} object
which may be associated with an actual file later, using its \texttt{open()} member
(see below).
        \end{quote}
    \item \texttt{ofstream object(char const $*$name, ios::openmode mode = ios::out)}:
        \begin{quote}this constructor defines an \texttt{ofstream} object and associates
it immediately with the file named \texttt{name} using output mode
\texttt{mode}. Section \ref{OUTPUTMODES} provides an overview of available output
modes.  Example:
        \begin{verbatim}
ofstream out("/tmp/scratch");
\end{verbatim}
\end{quote}
    \end{itemize}
    It is not possible to open an \texttt{ofstream} using a
 \index{file descriptor}\emph{file descriptor}. The reason for this is (apparently) that file
descriptors are not universally available over different operating systems.
Fortunately, file descriptors can be used (indirectly) with a
\texttt{std::streambuf} object (and in some implementations: with a
\texttt{std::filebuf} object, which is also a \texttt{streambuf}). \texttt{Streambuf} objects
are discussed in section \ref{STREAMBUF}, \texttt{filebuf} objects are discussed in
section \ref{FILEBUF}.

Instead of directly associating an \texttt{ofstream} object with a file, the
object can be constructed first, and opened later.
    \begin{itemize}
        \item \index{open}\texttt{void open(char const $*$name,
                            ios::openmode mode = ios::out)}:\ \\ associates an \texttt{ofstream} object with an actual file. If the
\texttt{ios::fail} flag was set before calling \texttt{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:
        \begin{verbatim}
ofstream out("/tmp/out");
out << "hello\n";
out.close();        // flushes and closes out
out.open("/tmp/out2");
out << "world\n";
\end{verbatim}
\item \index{close}\texttt{void close()}:\ \\ closes the \texttt{ofstream} object. The function sets the \index{ios::fail}\texttt{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
\texttt{ofstream} object ceases to exist.

\item \index{is\_open}\texttt{bool is\_open() const}:\ \\ assume a stream was properly constructed, but it has not yet been
attached to a file. E.g., the statement \texttt{ofstream ostr} was executed. When
we now check its status through \texttt{good()}, a non-zero (i.e., \emph{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, \texttt{is\_open} should be called. If it returns \index{true}\texttt{true},
the stream is open. Example:
        \begin{verbatim}
    #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
    */
\end{verbatim}
\end{itemize}

\subsubsection{Modes for opening stream objects}\label{OUTPUTMODES}
        \typeout{Original Yodl file: iostreams/outmodes}The following \index{file modes}file modes or \index{file flags}file flags are available when constructing
or opening \texttt{ofstream} (or \texttt{istream}, see section \ref{IFSTREAM})
objects. The values are of type \index{openmode}\texttt{ios::openmode}. Flags may be
combined using the \texttt{bitor} operator.
        \begin{itemize}
        \item \index{app}\texttt{ios::app}:\ \\ reposition the stream to its end before every output command (see
also \texttt{ios::ate} below). The
file is created if it doesn't yet exist. When opening a stream in this mode
any existing content of the file is kept.
        \item \index{ate}\texttt{ios::ate}:\ \\ start initially at the end of the file.  Note that any existing
content is \emph{only} kept if some other flag tells the object to do so. For
example \texttt{ofstream out("gone", ios::ate)} \emph{rewrites} the file \texttt{gone},
because the implied \texttt{ios::out} causes the rewriting. If rewriting of an
existing file should be prevented, the \texttt{ios::in}
        \index{in}\index{file rewriting: preventing}
    mode should be specified too. However, when \texttt{ios::in} is specified the
file must already exist. The \texttt{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 \texttt{seekp}. When the \texttt{app} mode is used information is
\emph{only} written at end of file (effectively ignoring \texttt{seekp} operations).
        \item \index{binary}\texttt{ios::binary}:\ \\ open a file in \index{file: binary mode}binary mode (used on systems
distinguishing text- and binary files, like \index{MS-Windows}MS-Windows).

\item \index{in}\texttt{ios::in}:\ \\ open the file for reading. The file must exist.
        \item \index{out}\texttt{ios::out}:\ \\ open the file for writing. Create it if it doesn't yet exist. If
it exists, the \index{file is rewritten}file is rewritten.
        \item \index{trunc}\texttt{ios::trunc}:\ \\ start initially with an empty file.  Any existing content of the
file is lost.
        \end{itemize}
    The following combinations of file flags have special meanings:
        \begin{verbatim}
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.
\end{verbatim}
An interesting subtlety is that the \texttt{open} members of the \texttt{ifstream,
ofstream} and \texttt{fstream} classes have a second parameter of type
\texttt{ios::openmode}. In contrast to this, the \texttt{bitor} operator returns an
\texttt{int} when applied to two enum-values. The question why the \texttt{bitor}
operator may nevertheless be used here is answered in a later chapter
(cf. section \ref{EnumOverload}).

\subsection{Output to memory: the class `ostringstream'}\label{OSTRINGSTREAM}
    \typeout{Original Yodl file: iostreams/ostringstream}To \index{stream: writing to memory} write information to memory using \texttt{stream}
facilities, \index{ostringstream}\texttt{std::ostringstream} objects should be used.
As the class \texttt{ostringstream} is derived from the class \texttt{ostream} all
\texttt{ostream}'s facilities are available to \texttt{ostringstream} objects as
well. To use and define \texttt{ostringstream} objects the header file
\index{sstream: header file}\texttt{$<$sstream$>$} must be included. In addition the class \texttt{ostringstream} offers
the following constructors and members:
    \begin{itemize}
        \item \index{ostringstream}\texttt{ostringstream ostr(string const \&init,
                ios::openmode mode = ios::out)}:\ \\ when specifying \texttt{openmode} as \texttt{ios::ate}, the
\texttt{ostringstream} object is initialized by the \texttt{string init} and remaining
insertions are appended to the content of the \texttt{ostringstream} object.

\item \texttt{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 \texttt{ios::app}). Example:
        \begin{verbatim}
std::ostringstream out;
\end{verbatim}
        \item \index{str}\texttt{std::string str() const}:\ \\ a copy of the string that is stored inside the \texttt{ostringstream}
            object is returned.
        \item \texttt{void str(std::string const \&str)}:\ \\ 
            the current object is reinitialized with new initial content.
    \end{itemize}
    The following example illustrates the use of the \texttt{ostringstream} class:
several values are inserted into the object. Then, the text contained by the
\texttt{ostringstream} object is stored in a \texttt{std::string}, whose length and
content are thereupon printed.  Such \texttt{ostringstream} objects are most often
used for doing `type to string'\index{conversions: binary to text} conversions,
like converting \texttt{int} values to text. Formatting flags can be used with
\texttt{ostringstreams} as well, as they are part of the \texttt{ostream} class.

Here is an example showing an \texttt{ostringstream} object being used:
    \begin{verbatim}
    #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 << " -- ";
        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
    */
\end{verbatim}
\subsection{The `put\_time' manipulator}\label{PUTTIME}
    \typeout{Original Yodl file: iostreams/puttime}The manipulator \index{put\_time} \texttt{std::put\_time(std::tm const $*$specs, char const
$*$fmt)} can be used to insert time specifications into \texttt{std::ostream}
objects. Before using \texttt{put\_time} the \index{iomanip: header file}\texttt{$<$iomanip$>$} header must be included.

Time specifications are provided in \texttt{std::tm} objects, and the way the time
should be displayed is defined by the \index{format string}\emph{format string} \texttt{fmt}.

Starting with a \texttt{chrono::time\_point} the following steps must be performed
to insert the time point's time into a \texttt{std::ostream}:
    \begin{itemize}
    \item  Obtain a \texttt{time\_point} (e.g.: \texttt{system\_clock\{\}.now()});

\item  Pass the time point to the clock's \texttt{to\_time\_t} function, saving the
returned \texttt{time\_t} value:
        \begin{verbatim}
time_t secs = system_clock::to_time_t( system_clock{}.now() );
\end{verbatim}
\item  Pass \texttt{sec's} address to either \index{localtime}\texttt{std::localtime} or
\index{gmtime}\texttt{std::gmtime}. These functions return \texttt{std::tm} structs
containing the required time components expressed in, respectively, the
computer's local time or GMT;

\item  Pass the return value of either \texttt{localtime} or \texttt{gmtime} together
with a format string (e.g., \texttt{"\%c"}) to \texttt{put\_time}, inserting it into an
\texttt{std::ostream}:
        \begin{verbatim}
                // displays, e.g., Mon Nov  4 21:34:59 2019
time_t secs = system_clock::to_time_t( system_clock{}.now() );
std::cout << std::put_time(std::localtime(&secs), "%c") << '\n';
\end{verbatim}
\end{itemize}

A simple function returning \texttt{put\_time's} return value and expecting a
\texttt{time\_point} and format string can be defined which handles the above two
statements. E.g., (omitting the \texttt{std::} and \texttt{std::chrono::} specifications
for brevity):
        \begin{verbatim}
    auto localTime(time_point<system_clock> const &tp, char const *fmt)
    {
        time_t secs = system_clock::to_time_t( tp );
        return put_time(localtime(&secs), fmt);
    }
                // used as:
    cout << localTime(system_clock{}.now(), "%c") << '\n';
\end{verbatim}
Many more format specifiers are recognized by \texttt{put\_time}.  Specifiers start
with \texttt{\%}. To display a percent character as part of the format string write
it twice: \texttt{\%\%}. In addition to the standard escape sequences, \texttt{\%n} can be
used instead of \texttt{\textbackslash{}n}, and \texttt{\%t} can be used instead of \texttt{\textbackslash{}t}.

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Year specifiers}} \\

    Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\

        \hline
    \makecell[tl]{\%Y}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{year as a 4 digit decimal number}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%EY}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{year in an alternative representation}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%y}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{last 2 digits of year as a decimal number
                (range {[}00,99{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%Oy}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{last 2 digits of year using an alternative numeric
                system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%Ey}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{year as offset from locale's alternative calendar
                period \%EC (locale-dependent)}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%C}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{first 2 digits of year as a decimal number
                (range {[}00,99{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%EC}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{name of the base year (period) in the locale's
                alternative representation}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year} 
 \\

        \makecell[tl]{\%G}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{ISO 8601 week-based year, i.e. the year that contains
                the specified week}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \makecell[tl]{\%g}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{last 2 digits of ISO 8601 week-based year
                (range {[}00,99{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \hline
\end{tabular}
\end{center}

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Month specifiers}} \\

    Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\

        \hline
    \makecell[tl]{\%b}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{abbreviated month name, e.g. Oct}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mon} 
 \\
    \makecell[tl]{\%m}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{month as a decimal number (range {[}01,12{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mon} 
 \\
    \makecell[tl]{\%Om}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{month using an alternative numeric system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mon} 
 \\
    \hline
\end{tabular}
\end{center}

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Week specifiers}} \\

    Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\

        \hline
    \makecell[tl]{\%U}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{week of the year as a decimal number (Sunday is the first day
            of the week) (range {[}00,53{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\ tm\_wday,\ \\ tm\_yday} 
 \\

        \makecell[tl]{\%OU}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{week of the year, as by \%U, using an alternative numeric
            system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \makecell[tl]{\%W}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{week of the year as a decimal number (Monday is the first day
            of the week) (range {[}00,53{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \makecell[tl]{\%OW}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{week of the year, as by \%W, using an alternative numeric
            system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \makecell[tl]{\%V}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{ISO 8601 week of the year (range {[}01,53{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \makecell[tl]{\%OV}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{week of the year, as by \%V, using an alternative numeric
            system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_year,\ \\  tm\_wday,\ \\  tm\_yday} 
 \\

        \hline
\end{tabular}
\end{center}

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Day of the year/month specifiers}} \\

    Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\

        \hline
    \makecell[tl]{\%j}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{day of the year as a decimal number (range
                {[}001,366{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_yday} 
 \\

        \makecell[tl]{\%d}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{day of the month as a decimal number (range {[}01,31{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mday} 
 \\

        \makecell[tl]{\%Od}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{zero-based day of the month using an alternative numeric
                system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mday} 
 \\

        \makecell[tl]{\%e}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{day of the month as a decimal number (range {[}1,31{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mday} 
 \\

        \makecell[tl]{\%Oe}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{one-based day of the month using an alternative numeric
            system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mday} 
 \\

        \hline
\end{tabular}
\end{center}

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Day of the week specifiers}} \\

    Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\

        \hline
    \makecell[tl]{\%a}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{abbreviated weekday name, e.g. Fri}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_wday} 
 \\

        \makecell[tl]{\%A}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{full weekday name, e.g. Friday}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_wday} 
 \\

        \makecell[tl]{\%w}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{weekday as a decimal number, where Sunday is 0 (range
                {[}0-6{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_wday} 
 \\

        \makecell[tl]{\%Ow}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{weekday, where Sunday is 0, using an alternative numeric
                system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_wday} 
 \\

        \makecell[tl]{\%u}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{weekday as a decimal number, where Monday is 1 (ISO 8601
                format) (range {[}1-7{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_wday} 
 \\

        \makecell[tl]{\%Ou}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{weekday, where Monday is 1, using an alternative numeric
                system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_wday} 
 \\

        \hline
\end{tabular}
\end{center}

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Hour, minute, second  specifiers}} \\
Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\
    \hline
    \makecell[tl]{\%H}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{hour as a decimal number, 24 hour clock (range
                {[}00-23{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour} 
 \\
    \makecell[tl]{\%OH}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{hour from 24-hour clock using an alternative numeric
                system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour} 
 \\
    \makecell[tl]{\%I}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{hour as a decimal number, 12 hour clock (range
                {[}01,12{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour} 
 \\
    \makecell[tl]{\%OI}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{hour from 12-hour clock using the alternative numeric
                system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour} 
 \\
    \makecell[tl]{\%M}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{minute as a decimal number (range {[}00,59{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_min} 
 \\
    \makecell[tl]{\%OM}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{minute using an alternative numeric system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_min} 
 \\
    \makecell[tl]{\%S}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{second as a decimal number (range {[}00,60{]})}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_sec} 
 \\
    \makecell[tl]{\%OS}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{second using an alternative numeric system}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_sec} 
 \\
    \hline
\end{tabular}
\end{center}

\begin{center}\begin{tabular}{lllll}
    \hline
\multicolumn{5}{c}{\textbf{Additional specifiers}} \\
Specifier &  & Meaning &  &     \makecell[tl]{std::tm field(s)} 
 \\
    \hline
    \makecell[tl]{\%c}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{standard date and time string, e.g. Sun Oct 17 04:41:13
                2010}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{all} 
 \\
    \makecell[tl]{\%Ec}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{alternative date and time string}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{all} 
 \\
    \makecell[tl]{\%x}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{localized date representation}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{all} 
 \\
    \makecell[tl]{\%Ex}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{alternative date representation}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{all} 
 \\
    \makecell[tl]{\%X}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{localized time representation}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{all} 
 \\
    \makecell[tl]{\%EX}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{alternative time representation}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{all} 
 \\
    \makecell[tl]{\%D}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{equivalent to \texttt{"\%m/\%d/\%y"}}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mon,\ \\  tm\_mday,\ \\ 
                tm\_year} 
 \\
    \makecell[tl]{\%F}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{equivalent to \texttt{"\%Y-\%m-\%d"} (the ISO 8601 date
                format)}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_mon,\ \\  tm\_mday,\ \\  tm\_year} 
 \\
    \makecell[tl]{\%r}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{localized 12-hour clock time}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour,\ \\  tm\_min,\ \\ 
                tm\_sec} 
 \\
    \makecell[tl]{\%R}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{equivalent to \texttt{"\%H:\%M"}}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour,\ \\  tm\_min} 
 \\

        \makecell[tl]{\%T}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{equivalent to \texttt{"\%H:\%M:\%S"} (the ISO 8601 time
                format)}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour,\ \\  tm\_min,\ \\  tm\_sec} 
 \\
    \makecell[tl]{\%p}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{localized a.m. or p.m.}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_hour} 
 \\
    \makecell[tl]{\%z}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{offset from UTC in the ISO 8601 format (e.g. -0430;\ \\  no
                characters if time zone information is not
                available)}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_isdst} 
 \\
    \makecell[tl]{\%Z}  & 
    \makecell[l]{~}  & 
    \makecell[t{{p{7.5cm}}}]{time zone name or abbreviation\ \\ (no characters if time zone
                information is not available)}  & 
    \makecell[l]{~}  & 
    \makecell[tl]{tm\_isdst} 
 \\
    \hline
\end{tabular}
\end{center}

\section{Input}
\typeout{Original Yodl file: iostreams/input}In \textbf{C++} \index{input}input is primarily based on the \index{istream}\texttt{std::istream}
class. The \texttt{istream} class defines the basic operators and members
extracting information from streams: the \index{extraction operator}\emph{extraction operator} ($>>$),
and special members like \texttt{istream::read} reading unformatted
information from streams.

The class \texttt{istream} acts as \emph{base class} for several other classes, all
offering the functionality of the \texttt{istream} class, but adding their own
specialties. In the upcoming sections the following classes are discussed:
    \begin{itemize}
    \item  The class \texttt{istream}, offering the basic facilities for doing input;
    \item  The class \index{ifstream}\texttt{ifstream}, allowing us to read files
(comparable to \textbf{C}'s \index{fopen} \texttt{fopen(filename, "r")});
    \item  The class \index{istringstream}\texttt{istringstream}, allowing us to extract information from
memory rather than from file (comparable to \textbf{C}'s \index{sscanf}\texttt{sscanf} function).
    \end{itemize}

\subsection{Basic input: the class `istream'}\label{ISTREAM}
    \typeout{Original Yodl file: iostreams/istream}The class \index{istream}\texttt{istream} defines basic input facilities. The \index{cin}\texttt{cin} object, is
an \texttt{istream} object.  All facilities related to input as defined by the
\texttt{ios} class are also available in the \texttt{istream} class.

We may define \texttt{istream} objects using the following
 \index{istream constructor}\emph{istream constructor}:
    \begin{itemize}
        \item \texttt{istream object(streambuf $*$sb)}:
            \begin{quote}this constructor can be used to construct a wrapper around
an existing \texttt{std::streambuf} object. Similarly to \texttt{ostream} objects,
\texttt{istream} objects may be defined by passing it initially
 \index{ostream: define using 0-pointer} a 0-pointer. See section \ref{OSTREAM} for
a discussion, see also section \ref{STREAMBUF}, and see chapter \ref{CONCRETE}
for examples.
    \end{quote}
    \end{itemize}
    To define the \texttt{istream} class in \textbf{C++} sources, the
    \index{istream: header file}\texttt{$<$istream$>$} header file must be included. To use the predefined
\texttt{istream} object \index{cin}\texttt{cin}, the \index{iostream: header file}\texttt{$<$iostream$>$} header file must be included.

\subsubsection{Reading from `istream' objects}\label{ISTREAMREAD}
        \typeout{Original Yodl file: iostreams/istreamread}The class \texttt{istream} supports both formatted and unformatted (\emph{binary})
    \index{binary input} input.  The \index{extraction operator}\emph{extraction operator} (\index{operator\textgreater{}\textgreater{}}\texttt{operator$>$$>$}) is
used to extract values in a \index{type safe}type safe way from \texttt{istream} objects.  This
is called \index{formatted input}formatted input, whereby human-readable \index{ASCII}ASCII characters are
converted, according to certain formatting rules, to binary values.

The extraction operator points to the objects or variables to receive new
values.  The normal associativity of $>>$ remains unaltered, so when a
statement like
        \begin{verbatim}
    cin >> x >> y;
\end{verbatim}
is encountered, the leftmost two operands are evaluated first (\texttt{cin}
$>>$ \texttt{x}), and an \texttt{istream \&} object, which is actually the same
\texttt{cin} object, is returned. Now, the statement is reduced to
        \begin{verbatim}
    cin >> y
\end{verbatim}
and the \texttt{y} variable is extracted from \texttt{cin}.

The $>>$ operator has many (overloaded) variants and thus many types of
variables can be extracted from \texttt{istream} objects. There is an overloaded
$>>$ available for the extraction of an \texttt{int}, of a \texttt{double}, of a
string, of an array of characters, possibly to the location pointed at by a
pointer, etc., etc.. String or character array extraction
    \index{string extraction} \index{extracting strings}
    by default first skips all whitespace characters, and then extracts
all consecutive non-whitespace characters. Once an extraction operator has
been processed the \texttt{istream} object from which the information was extracted
is returned and it can immediately be used for additional \texttt{istream}
operations that appear in the same expression.

Streams do not support facilities for formatted input as offered by
\textbf{C}'s \index{scanf}\texttt{scanf} and \index{vscanf}\texttt{vscanf} functions. Although it is not difficult to
add such facilities to the world of streams, \texttt{scanf}-like functionality is
in practice never needed in \textbf{C++} programs. Furthermore, as it is
potentially type-\emph{unsafe}, it is better to avoid using \textbf{C}-type formatted
input.

When \index{binary file} binary files must be read, the information should
normally not be formatted: an \texttt{int} value should be read as a series of
unaltered bytes, not as a series of \index{ASCII}ASCII numeric characters 0 to 9. The
following member functions for reading information from \texttt{istream} objects
are available:
    \begin{itemize}
        \item \index{gcount}\texttt{int gcount() const}:\ \\ the number of characters read from the input stream
by the last unformatted input operation is returned.
        \item \index{get}\texttt{int get()}:\ \\ the next available single character is returned
as an unsigned \texttt{char} value using an \texttt{int} return type.
\texttt{EOF} is returned if no more character are available.
        \item \texttt{istream \&get(char \&ch)}:\ \\ the next single character read from the input stream is
stored in \texttt{ch}. The member function returns the stream itself which may be
inspected to determine whether a character was obtained or not.
        \item \texttt{istream \&get(char $*$buffer, int len, char delim = '\textbackslash{}n')}:\ \\ At most \texttt{len - 1} characters are read from the input
stream into the array starting at \texttt{buffer}, which should be at least \texttt{len}
bytes long. Reading also stops when the delimiter \texttt{delim} is
encountered. However, the delimiter itself is \emph{not removed} from the input
stream.

Having stored the characters into \texttt{buffer}, a 0-valued character is
written beyond the last character stored into the \texttt{buffer}.  The functions
\texttt{eof} and \texttt{fail} (see section \ref{IOSTATES}) return 0 (\texttt{false}) if the
delimiter was encountered before reading \texttt{len - 1} characters or if the
delimiter was not encountered after reading \texttt{len - 1} characters.  It is OK
to specifiy a 0-valued character delimiter: this way NTBSs may be read from a
(binary) file.

\item \index{getline}\texttt{istream \&getline(char $*$buffer, int len, char delim = '\textbackslash{}n')}:\ \\ this member function operates analogously to the \texttt{get} member
function, but \texttt{getline} removes \texttt{delim} from the stream if it is actually
encountered. The delimiter itself, if encountered, is \emph{not} stored in the
\texttt{buffer}. If \texttt{delim} was \emph{not} found (before reading \texttt{len - 1}
characters) the \texttt{fail} member function, and possibly also \texttt{eof} returns
true. Realize that the \texttt{std::string} class also offers a function
\texttt{std::getline} which is generally preferred over this \texttt{getline} member
function that is described here (see section \ref{STRINGMEMBERS}).

\item \index{ignore}\texttt{istream \&ignore()}:\ \\ one character is skipped from the input stream.
        \item \texttt{istream \&ignore(int n)}:\ \\ \texttt{n} characters are skipped from the input stream.
        \item \texttt{istream \&ignore(int n, int delim)}:\ \\ at most \texttt{n} characters are skipped but skipping characters
stops after having removed \texttt{delim} from the input stream.
        \item \index{peek}\texttt{int peek()}:\ \\ this function returns the next available input character,
but does not actually remove the character from the input stream. \texttt{EOF}
is returned if no more characters are available.
        \item \index{putback}\texttt{istream \&putback(char ch)}:\ \\ The character \texttt{ch} is `pushed back' into the input stream, to
be read again as the next available character. \texttt{EOF} is returned if this
is not allowed. Normally, it is OK to put back one character. Example:
            \begin{verbatim}
string value;
cin >> value;
cin.putback('X');
                // displays: X
cout << static_cast<char>(cin.get());
\end{verbatim}
\item \index{read}\texttt{istream \&read(char $*$buffer, int len)}:\ \\ At most \texttt{len} bytes are read from the input stream into the
buffer. If \texttt{EOF} is encountered first, fewer bytes are read, with the
member function \texttt{eof} returning \texttt{true}. This function is commonly used
when reading \emph{binary} files. Section \ref{IFSTREAM} contains an example in
which this member function is used. The member function \texttt{gcount()} may be
used to determine the number of characters that were retrieved by \texttt{read}.

\item \index{readsome}\texttt{istream \&readsome(char $*$buffer, int len)}:\ \\ at most \texttt{len} bytes are read from the input stream into the
buffer. All available characters are read into the buffer, but if \texttt{EOF}
is encountered, fewer bytes are read, without setting the \texttt{ios::eofbit}
or \texttt{ios::failbit}.

\item \index{unget}\texttt{istream \&unget()}:\ \\ the last character that was read from the stream is put back.
    \end{itemize}

\subsubsection{`istream' positioning}\label{ISTREAMPOS}
        \typeout{Original Yodl file: iostreams/istreamseek}Although not every \texttt{istream} object supports \index{repositioning}repositioning, some do. This
means that it is possible to read the same section of a stream
repeatedly. Repositioning is frequently used in \index{database applications}\emph{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:
    \begin{itemize}
    \item \index{tellg}\texttt{ios::pos\_type tellg()}:\ \\ \index{pos\_type}the stream's current (absolute) position where the
stream's next read-operation will take place is returned.
    \item \index{seekg}\texttt{istream \&seekg(ios::off\_type step, ios::seekdir org)}:\ \\ modifies a stream's actual position. The function expects an
\index{off\_type}\texttt{off\_type} \texttt{step} representing the number of bytes the current stream
position is moved with respect to \texttt{org}. The \texttt{step} value may be negative,
zero or positive.

The origin of the step, \texttt{org} is a value in the
\index{seekdir}\texttt{ios::seekdir} enumeration. Its values are:
        \begin{itemize}
        \item \index{beg}\texttt{ios::beg}:\ \\ the stepsize is computed relative to the beginning of the
stream. This value is used by default.

\item \index{cur}\texttt{ios::cur}:\ \\ the stepsize is computed relative to the current position of the
stream (as returned by \texttt{tellp}).

\item \index{end}\texttt{ios::end}:\ \\ the stepsize is interpreted relative to the current end position
of the stream.
    \end{itemize}
    It is OK to \index{seek beyond file boundaries} seek beyond the last file
position.  Seeking before \texttt{ios::beg} raises the \index{failbit}\texttt{ios::failbit}
flag.

Calling \texttt{seekg} clears the \texttt{istream's ios::failbit}, but not its
\texttt{ios::badbit} or \texttt{ios::badbit}. To ensure that the stream's state is reset
to `good' its member \texttt{clear} should be called.

To illustrate: in the following example \texttt{cin's ios::eofbit} is
set. Following \texttt{seekg} that bit is cleared, but its \texttt{ios::goodbit} stil
isn't set. Since its \texttt{goodbit} isn't set, extraction fails following
\texttt{seekg}:
        \begin{verbatim}
    int main()                  // in 'src.cc'
    {
        cin.setstate(ios::eofbit | ios::failbit);
        cerr << cin.good() << ' ' << cin.eof() << '\n';
    
        cin.seekg(0);
        cerr << cin.good() << ' ' << cin.eof() << '\n' <<
                (cin.get() == EOF ? "failed" : "OK") << '\n';
    
        cin.clear();
        cerr << cin.good() << ' ' << cin.eof() << '\n' <<
                (cin.get() == EOF ? "failed" : "OK") << '\n';
    }
    outputs when called as 'a.out < src.cc':
        0 1
        0 0
        failed
        1 0
        OK
\end{verbatim}
\end{itemize}

\subsection{Input from files: the class `ifstream'}\label{IFSTREAM}
    \typeout{Original Yodl file: iostreams/ifstream}The \index{ifstream}\texttt{std::ifstream} class is derived from the \texttt{istream} class:
it has the same capabilities as the \texttt{istream} class, but can be used to
\index{access files}access files  for reading.

In order to use the \texttt{ifstream} class  in \textbf{C++} sources, the
    \index{fstream: header file}\texttt{$<$fstream$>$} header file must be included. Including \texttt{fstream} does not
automatically make available the standard streams \texttt{cin}, \texttt{cout} and
\texttt{cerr}. Include \index{iostream}\texttt{iostream} to declare these standard streams.

The following \index{ifstream constructors} constructors are available for
\texttt{ifstream} objects:
    \begin{itemize}
    \item \texttt{ifstream object}:
        \begin{quote}this is the basic constructor. It defines an \texttt{ifstream} object
which may be associated with an actual file later, using its \texttt{open()} member
(see below).
        \end{quote}
    \item \texttt{ifstream object(char const $*$name, ios::openmode mode = ios::in)}:
        \begin{quote}this constructor can be used to define an \texttt{ifstream} object
and associate it immediately with the file named \texttt{name} using input mode
\texttt{mode}. Section \ref{OUTPUTMODES} provides an overview of available input
modes.  Example:
        \begin{verbatim}
ifstream in("/tmp/input");
\end{verbatim}
\end{quote}
    \end{itemize}

Instead of directly associating an \texttt{ifstream} object with a file, the
object can be constructed first, and opened later.
    \begin{itemize}
        \item \index{open}\texttt{void open(char const $*$name,
                            ios::openmode mode = ios::in)}:\ \\ associates an \texttt{ifstream} object with an actual file. If the
\texttt{ios::fail} flag was set before calling \texttt{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:
        \begin{verbatim}
ifstream in("/tmp/in");
in >> variable;
in.close();        // closes in
in.open("/tmp/in2");
in >> anotherVariable;
\end{verbatim}
\item \index{close}\texttt{void close()}:\ \\ closes the \texttt{ifstream} object. The function sets the \index{ios::fail}\texttt{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
\texttt{ifstream} object ceases to exist.

\item \index{is\_open}\texttt{bool is\_open() const}:\ \\ assume a stream was properly constructed, but it has not yet been
attached to a file. E.g., the statement \texttt{ifstream ostr} was executed. When
we now check its status through \texttt{good()}, a non-zero (i.e., \emph{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, \texttt{is\_open} should be called. If it returns \index{true}\texttt{true},
the stream is open.  Also see the example in section \ref{OFSTREAM}. The
following example  illustrates reading from a binary file (see also section
\ref{ISTREAMREAD}):
        \begin{verbatim}
    #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));
    }
\end{verbatim}
\end{itemize}

\subsection{Input from memory: the class `istringstream'}\label{ISTRINGSTREAM}
    \typeout{Original Yodl file: iostreams/istringstream}To \index{stream: reading to memory} read information from memory using
\texttt{stream} facilities, \index{istringstream}\texttt{std::istringstream} objects should
be used.  As the class \texttt{istringstream} is derived from the class \texttt{istream}
all \texttt{istream}'s facilities are available to \texttt{istringstream} objects as
well. To use and define \texttt{istringstream} objects the header file
\index{sstream: header file}\texttt{$<$sstream$>$} must be included. In addition the class \texttt{istringstream} offers
the following constructors and members:
    \begin{itemize}
        \item \index{istringstream}\texttt{istringstream istr(string const \&init,
                ios::openmode mode = ios::in)}:\ \\ the object is initialized with \texttt{init}'s content
        \item \texttt{istringstream istr(ios::openmode mode = ios::in)}:\ \\ this constructor is usually used as the default
            constructor. Example:
        \begin{verbatim}
std::istringstream in;
\end{verbatim}
\item \index{str}\texttt{void str(std::string const \&str)}:\ \\ the current object is reinitialized with new initial content.
    \end{itemize}
    The following example illustrates the use of the \texttt{istringstream} class:
several values are extracted from the object. Such \texttt{istringstream} objects
are most often used for doing `string to type'\index{conversions: text to binary}
conversions, like converting text to \texttt{int} values (cf. \textbf{C}'s \index{atoi}\texttt{atoi}
function). Formatting flags can be used with \texttt{istringstreams} as well, as
they are part of the \texttt{istream} class.  In the example note especially the
use of the member \texttt{seekg}:
    \begin{verbatim}
    #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
    */
\end{verbatim}
\subsection{Copying streams}\label{CPSTREAM}
    \typeout{Original Yodl file: iostreams/copying}Usually, files are copied \index{file: copying} either by reading a source file
character by character or line by line. The basic \emph{mold} to process streams
 \index{stream: processing} is as follows:
        \begin{itemize}
            \item  Continuous loop:
            \begin{enumerate}
                \item  read from the stream
                \item  if reading did not succeed (i.e., \texttt{fail} returns
                        \texttt{true}), \texttt{break} from the loop
                \item  process the information that was read
            \end{enumerate}
        \end{itemize}
    Note that reading must \emph{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:
\texttt{getline(istream \&, string \&)} (see section \ref{ISTREAMREAD}) returns an
\texttt{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 \texttt{cin} to \texttt{cout}:
        \begin{verbatim}
#include <iostream>
using namespace::std;

int main()
{
    while (true)
    {
        char c;

        cin.get(c);
        if (cin.fail())
            break;
        cout << c;
    }
}
\end{verbatim}
Contraction is possible here by combining \texttt{get} with the
\texttt{if}-statement, resulting in:
        \begin{verbatim}
    if (!cin.get(c))
        break;
\end{verbatim}
Even so, this would still follow the basic rule:
 `\index{read first, test later}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 \texttt{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 \index{streambuf}\texttt{streambuf} pointer \index{inserting streambuf *} is inserted into
a stream. As the member \texttt{rdbuf} returns a stream's \texttt{streambuf $*$}, we have
a simple means of inserting a stream's content into an \texttt{ostream}:
        \begin{verbatim}
    #include <iostream>
    using namespace std;

    int main()
    {
        cin.ignore(80, '\n');   // skip the first line and...
        cout << cin.rdbuf();    // copy the rest through the streambuf *
    }
\end{verbatim}
    This way of copying streams only assumes the existence of a \texttt{streambuf}
object. Consequently it can be used with all specializations of the
\texttt{streambuf} class.

\subsection{Coupling streams}\label{COUPLING}
    \typeout{Original Yodl file: iostreams/coupling}Ostream objects \index{ostream coupling} can be \emph{coupled} to \index{ios}\texttt{ios} objects
using the \index{tie}\texttt{tie} member function. Tying results in flushing the \texttt{ostream}'s
buffer whenever an \index{input}input or \index{output}output operation is performed on the \texttt{ios}
object to which the \texttt{ostream} object is tied.  By default \index{cout}\texttt{cout} is tied
to \index{cin}\texttt{cin} (using \texttt{cin.tie(cout)}).  This tie means that whenever an
operation on \texttt{cin} is requested, \texttt{cout} is flushed first. To break the
tie, \texttt{ios::tie(0)} can be called. In the example: \texttt{cin.tie(0)}.

Another useful coupling of streams is shown by the tie between \index{cerr}\texttt{cerr} and
\index{cout}\texttt{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:
    \begin{verbatim}
    #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
    */
\end{verbatim}
An alternative way to couple streams is to make streams use a common
\texttt{streambuf} object. This can be implemented using the \index{rdbuf}
\texttt{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.

\section{Advanced topics}\label{ADVANCEDIO}

\subsection{Moving streams}
    \typeout{Original Yodl file: iostreams/moving}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:
        \begin{verbatim}
    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 fail: copy assignment
                                        // is not available for streams
    }
\end{verbatim}
\subsection{Redirecting streams}\label{REDIR}
    \typeout{Original Yodl file: iostreams/redirection}Using \index{rdbuf}\texttt{ios::rdbuf} streams can be forced to share their
\texttt{streambuf} objects. Thus information written to one
stream is actually written to another stream; a phenomenon normally
called \index{redirection}\emph{redirection}. Redirection is commonly implemented at the
operating system level, and sometimes that is still necessary (see
section \ref{REDIRECTION}).

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 \index{file descriptor}file descriptor number 2. In the \index{Unix}Unix operating system using the
\index{bash}\texttt{bash} shell, this can be realized as follows:
        \begin{verbatim}
    program 2>/tmp/error.log
\end{verbatim}
Following this command any error messages written by \texttt{program} are
written to \texttt{/tmp/error.log}, instead of appearing on the screen.

Here is an example showing how this can be implemented using \texttt{streambuf}
objects. Assume \texttt{program} expects an argument defining the name
of the file to write the error messages to. It could be called as follows:
        \begin{verbatim}
    program /tmp/error.log
\end{verbatim}
The program looks like this, an explanation is provided below the
program's source text:
        \begin{verbatim}
    #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
    */
\end{verbatim}
    \begin{itemize}
    \item  At lines 1-2 local variables are defined: \texttt{errlog} is the
\texttt{ofstream} to write the error messages to, and \texttt{cerr\_buffer} is a pointer
to a \texttt{streambuf}, to point to the original \texttt{cerr} buffer.
    \item  At line 3  the alternate error stream is opened.
    \item  At line 4  redirection takes place: \texttt{cerr} now writes to
the \texttt{streambuf} defined by \texttt{errlog}. It is important that
the original buffer used by \texttt{cerr} is saved, as explained below.
    \item  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 content:
there were indeed two lines written to the file.
    \item  At line 6  the redirection is terminated. This is very important, as
the \texttt{errlog} object is destroyed at the end of \texttt{main}. If \texttt{cerr}'s
buffer would not have been restored, then at that point
\texttt{cerr} would refer to a non-existing \texttt{streambuf} object, which might
produce unexpected results. It is the responsibility of the programmer to
make sure that an original \texttt{streambuf} is saved before redirection, and is
restored when the redirection ends.
    \item  Finally, at line 7, \texttt{Done} is again written to the screen, as
the redirection has been terminated.
    \end{itemize}

\subsection{Reading AND Writing streams}\label{FSTREAM}
    \typeout{Original Yodl file: iostreams/readwrite}Streams can be read \emph{and} written 
    \index{stream: read and write} using \index{iostream}\texttt{std::iostream}
objects. Commonly encountered are \index{fstream}\texttt{std::fstream} objects and
sometimes \index{stringstream}\texttt{std::stringstream} objects. Other types of
readable and writable streams can be defined, by deriving such streams from
the \texttt{std::iostream} class (cf. chapter \ref{POLYMORPHISM}, in particular its
section \ref{IOSTREAMBUF}). 

In this section we concentrate on the \texttt{std::fstream} class.  As with
\texttt{ifstream} and \texttt{ofstream} objects, the \texttt{fstream} constructor expects the
name of the file to be opened:
        \begin{verbatim}
        fstream inout("iofile", ios::in | ios::out);
\end{verbatim}
Note the use of the constants \index{in}\texttt{ios::in} and \index{out}\texttt{ios::out},
indicating that the file must be opened for both reading and writing. Multiple
mode indicators may be used, concatenated by the \texttt{bitor} operator.
Alternatively, instead of \texttt{ios::out}, \index{app}\texttt{ios::app} could have been
used and mere writing would become appending (at the end of the file).

Reading and writing to the same stream is always a bit awkward: what to do
when the stream may not yet exist, but if it already exists it should not
be rewritten? To realize this the following approach can be used:
    \begin{verbatim}
    #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';

                            // 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';
    }
\end{verbatim}
    Under this approach if the construction fails \texttt{fname} didn't yet
exist. But then, after clearing the failure flag, \texttt{open} is used also
specifying the \index{trunc}\texttt{ios::trunc} flag: this creates an empty file, but
because of \texttt{ios::in} the file is also readable.  In addition
\index{ate}\texttt{ios::ate} could be specified, ensuring that the initial read/write
action would by default occur at \texttt{EOF}.

Under \index{MS-Windows} \index{DOS} \textbf{DOS}-like operating systems that use the
multiple character sequence \texttt{\textbackslash{}r\textbackslash{}n} to separate lines in \index{text files}text files the
flag \index{binary}\texttt{ios::binary} is required to process \index{binary file}binary files ensuring
that \texttt{\textbackslash{}r\textbackslash{}n} combinations are processed as two characters. In general,
\texttt{ios::binary} should be specified when binary (non-text) files are to be
processed. By default files are opened as text files. \index{Unix}Unix operating
systems do not distinguish text files from binary files.

With \texttt{fstream} (in general: \texttt{iostream}) objects, combinations of file
flags are used to make sure that a stream is or is not (re)created empty when
opened. See section \ref{OUTPUTMODES} 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 \texttt{seekg} or \texttt{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
\emph{vice versa}). The \texttt{istream} and \texttt{ostream} parts of \texttt{fstream} objects
share the stream's data buffer and by performing the seek operation the stream
either activates its \texttt{istream} or its \texttt{ostream} part. If the seek is
omitted, reading after writing and writing after reading simply fails. The
example shows a whitespace-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:
        \begin{verbatim}
    fstream f("filename", ios::in | ios::out);
    string  str;

    f >> str;       // read the first word

                    // write a well-known text
    f.seekp(0, ios::cur);
    f << "hello world";

    f.seekg(0, ios::cur);
    f >> str;       // and read again
\end{verbatim}
Since a \emph{seek} or \emph{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 extractions are required can be
controlled and monitored by the \texttt{seekg}, \texttt{seekp, tellg} and \texttt{tellp}
members (see sections \ref{OSTREAMPOS} and \ref{ISTREAMPOS}).

Error conditions (see section \ref{IOSTATES}) 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 \texttt{clear} member function.  Following \texttt{clear}
processing may continue. E.g.,
        \begin{verbatim}
    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
\end{verbatim}
A situation where files are both read and written is seen in
    \emph{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 \index{binary file}\emph{binary file} \texttt{index} allows for the quick
retrieval of the location of lines.
        \begin{verbatim}
    #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
        (
            !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"
                "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';
        }
    }
\end{verbatim}
    Another example showing reading \emph{and} writing of files is provided by
the next program. It also illustrates the processing of NTBSs:
        \begin{verbatim}
    #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';

        buffer[5] = ' ';                    // change asciiz to ' '
        cout << buffer << '\n';             // show 2 times `hello'
    }
    /*
        Generated output:
    5
    11
    hello hello
    */
\end{verbatim}
A completely different way to read and write streams may be implemented
using \texttt{streambuf} members. All considerations mentioned so far remain valid
(e.g., before a read operation following a write operation \texttt{seekg} must be
used). When  \texttt{streambuf} objects are used, either an
\texttt{istream} is associated with the \texttt{streambuf} object of another \texttt{ostream}
object, or an \texttt{ostream} object is associated with the
\texttt{streambuf} object of another \texttt{istream} object. Here is the previous
program again, now using
    \index{stream: associating} \emph{associated streams}:
        \begin{verbatim}
    #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";

        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';
        }
    }
\end{verbatim}
    In this example
    \begin{itemize}
    \item  the streams associated with the \texttt{streambuf} objects of existing
streams are not \index{ifstream}\texttt{ifstream} or \index{ofstream}\texttt{ofstream} objects but basic \index{istream}\texttt{istream} and
\index{ostream}\texttt{ostream} objects.
    \item  The \texttt{streambuf} object is not defined by an \texttt{ifstream} or
\texttt{ofstream} object. Instead it is defined outside of the streams, using
a \texttt{filebuf} (cf. section \ref{FILEBUF}) and constructions like:
        \begin{verbatim}
filebuf fb("index", ios::in | ios::out | ios::trunc);
istream index_in(&fb);
ostream index_out(&fb);
\end{verbatim}
\item  An \texttt{ifstream} object can be constructed using stream modes normally
used with \texttt{ofstream} objects. Conversely, an \texttt{ofstream} objects can be
constructed using stream modes normally used with \texttt{ifstream} objects.
    \item  If \texttt{istream} and \texttt{ostreams} share a \texttt{streambuf}, then their
read and write pointers (should) point to the shared buffer: they are tightly
coupled. However, instead of using two objects, defining/using a \texttt{iostream}
object receiving the \texttt{streambuf} automatically ensures that positioning for
reading and writing is synchronized (see also section \ref{IOSTREAMBUF}).
    \item  The advantage of using an external (separate) \texttt{streambuf} used by
an \texttt{iostream} object over using a predefined \texttt{fstream} object is that the
stream doesn't have to be a named file (see also section \ref{STREAMBUF}).
    \end{itemize}

Like \texttt{fstream} objects string-stream objects can also be used for reading
and writing. After including the \index{sstream: header file}\texttt{$<$sstream$>$} header file a
\index{stringstream}\texttt{std::stringstream} can be defined which supports both
reading and writing. After inserting information into a \texttt{stringstream}
object \texttt{seekg(0)} can be called to read its info from the beginning of its
content. When a \texttt{stringstream} must repeatedly be used for reading and
writing call its \texttt{clear} and \texttt{str} members before starting a new writing
cycle. Alternatively, a \texttt{stringstream str} can be reinitialized using \texttt{str
= stringstream\{\}}. Here is an example:
        \begin{verbatim}
    #include <iostream>
    #include <sstream>
    using namespace std;

    int main(int argc, char **argv)
    {
        stringstream io;
        for (size_t redo = 0; redo != 2; ++redo)
        {
            io.clear();                 // clears the not-good flags
            io.str("");
            io << argv[0] << '\n';

            io.seekg(0);
            string line;
            while (getline(io, line))   // results in io.eof()
                cout << line << '\n';
        }
    }
\end{verbatim}
\cleardoublepage\chapter{Classes}\label{Classes}
\typeout{Original Yodl file: classes}\typeout{Original Yodl file: classes/intro}The \textbf{C} programming language offers two methods for structuring data of
different types. The \textbf{C} \texttt{struct} holds data members of various types, and
the \textbf{C} \texttt{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 \texttt{class} is a kind of \texttt{struct},
but its content is by default inaccessible to the outside world, whereas the
content of a \textbf{C++} \texttt{struct} is by default accessible to the outside
world. In \textbf{C++} \texttt{struct}s find little use: they are mainly used to
aggregate data within the context of classes or to define elaborate return
values. Often a \textbf{C++} \texttt{struct} merely contains \emph{plain old data} (POD,
cf. section \ref{POD}). In \textbf{C++} the \texttt{class} is the main data structuring
device, by default enforcing two core concepts of current-day software
engineering: \emph{data hiding} and \emph{encapsulation} (cf. sections \ref{HIDING}
and \ref{APPLICATION}).

The \texttt{union} is another data structuring device the language offers. The
traditional \textbf{C} union is still available, but \textbf{C++} also offers
\emph{unrestricted unions}. Unrestricted unions are unions whose data fields may
be of class types. The \textbf{C++} Annotations covers these unrestricted unions in
section \ref{UNIONS}, after having introduced several other new concepts of
\textbf{C++},

\textbf{C++} extends the \textbf{C} \texttt{struct} and \texttt{union} concepts by allowing the
definition of \emph{member}
        \index{member function}
    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 \emph{constructor}) or ends its life (the
so-called \emph{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 \texttt{Person}, which could be used in a
database application to store a person's name, address and phone number.

\label{PERSON} Let's start by creating a \texttt{class Person} right away. From the
onset, it is important to make the distinction between the class
\index{interface}\emph{interface} and its \index{implementation}\emph{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 \texttt{int variable} the compiler ensures that some memory is reserved in
the final program storing \texttt{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 \index{one definition rule}\emph{one definition rule}: in
\textbf{C++} entities may be defined only once. As a \emph{class definition} does not
imply that memory is being reserved the term \emph{class interface} is preferred
instead.

Class interfaces are normally contained in a class \emph{header file}, e.g.,
\texttt{person.h}. We'll start our \texttt{class Person} interface here (cf section
\ref{ConstFunctions} for an explanation of the \texttt{const} keywords behind some
of the class's member functions):
        \begin{verbatim}
    #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;
    };
\end{verbatim}
 The member functions that are \emph{declared} in the interface must still be
implemented. The implementation of these members is properly called their
definition.

In addition to member \emph{functions} classes also commonly define the \emph{data}
that are manipulated by those member functions. These data are called the
\index{data member}\emph{data members}. In \texttt{Person} they are \texttt{d\_name, d\_address,
d\_phone} and \texttt{d\_mass}. Data members should be given private 
    \index{access rights}access rights. Since the class uses private access rights by default
they are usually simply listed at the top of the class 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
\texttt{setName}) or they may be retrieved for inspection (e.g., using
\texttt{name}). Functions merely returning values stored inside the object, not
allowing the caller to modify these internally stored values, are called
 \index{accessor}\emph{accessors}.

Syntactically there is only a marginal difference between a class and a
struct. Classes by default define \emph{private} members, structs define
\emph{public} members. Conceptually, though, there are differences.  In \textbf{C++}
structs are used in the way they are used in \textbf{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 \index{data hiding}\emph{data hiding})
and offer member functions to define the communication between the outer world
and the class's data members.

Following \emph{Lakos} (Lakos, J., 2001)
    \index{Lakos, J.} \textbf{Large-Scale C++ Software Design} (Addison-Wesley) I
suggest the following setup of class interfaces:
    \begin{itemize}
    \item  All data members have \emph{private access rights}, and are
placed at the top of the interface.
    \item  All data members start with \texttt{d\_}, followed by a name suggesting
their meaning (in chapter \ref{StaticDataFun} we'll also
encounter data members starting with \texttt{s\_}).
    \item  Non-private data members \emph{do} exist, but one should be hesitant to
define non-private access rights for data members (see also chapter
\ref{INHERITANCE}).
    \item  Two broad categories of member functions are
    \index{manipulator}\emph{manipulators} and \emph{accessors}. Manipulators allow
the users of objects to modify the internal data of the objects. By
convention, manipulators start with \texttt{set}. E.g., \texttt{setName}.
    \item  With \emph{accessors}, a \texttt{get}-prefix is still frequently encountered,
e.g., \texttt{getName}. However, following the conventions promoted by \index{Qt}\textbf{Qt} (see
\index{https://doc.qt.io}\texttt{https://doc.qt.io}, e.g., its classes \texttt{QByteArray} and
\texttt{QString}), using the \texttt{get}-prefix is deprecated. So, rather than defining
a member \texttt{getAddress}, it should simply be named \texttt{address}.
    \item  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 \texttt{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.
    \end{itemize}
    Style conventions usually take a long time to develop. There is nothing
obligatory about them, though. I suggest that readers who have compelling
reasons \emph{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 \ref{INTRONAME} that
        \begin{verbatim}
    using namespace std;
\end{verbatim}
must be used in most (if not all) examples of source code. As
explained in sections \ref{CLASSHEADER} and \ref{NAMESPACEHDR} the \texttt{using}
directive should follow the preprocessor directive(s) including the header
files, using a setup like the following:
        \begin{verbatim}
    #include <iostream>
    #include "person.h"

    using namespace std;

    int main()
    {
        ...
    }
\end{verbatim}
\section{The constructor}
\typeout{Original Yodl file: classes/construc}\textbf{C++} classes usually contain two special categories of member functions
which are essential to the proper working of classes. These categories are the
constructors and the \index{destructor}destructor. The \emph{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 \ref{MEMORY}, and
an in-depth coverage of destructors is therefore postponed until we reach that
chapter.  In the current chapter the emphasis is on the class's internal
organization and on its constructors.

Constructors are recognized by their names which are equal to their class
names.  Constructors do not specify return values, not even \texttt{void}.  E.g.,
the class \texttt{Person} may define a constructor \texttt{Person::Person()}. The
\textbf{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
 \index{constructor: default} default constructor that is called when an object of
that class is defined. What actually happens in that case depends on the data
members that are defined by that class (cf. section \ref{MemberInitializers}).

Objects may be defined locally or globally. However, in \textbf{C++} most objects
are defined locally. Globally defined objects are hardly ever required and are
somewhat deprecated.

When a function defines a local object, that object's 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
 \index{static object}\index{object: static/global} it is constructed when
the program starts. In this case its constructor is called even
before the function \texttt{main} starts. Example:
    \begin{verbatim}
    #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
    */
\end{verbatim}
 The program contains one global object of the class \texttt{Demo} with \texttt{main}
having an empty body. Nonetheless, the program produces some output generated
by the constructor of the globally defined \texttt{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 \emph{default constructor}\index{constructor: default} has no
argument. It is defined by the compiler unless another constructor is defined
and unless its definition is suppressed (cf. section \ref{DEFAULTED}). If a
default constructor is required in addition to another constructor then the
default constructor must explicitly be defined as well. \textbf{C++} provides
special syntax to realize that without much effort, which is also covered by
section \ref{DEFAULTED}.

\subsection{A first application}\label{APPLICATION}
    \typeout{Original Yodl file: classes/application}Our example class \texttt{Person} has three string data members and a \texttt{size\_t
d\_mass} data member. Access to these data members is controlled by
 \index{interface functions}interface functions.

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
 \index{data hiding}\emph{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 \emph{encapsulates} all
actions performed on its data members and due to this
 \index{encapsulation}\emph{encapsulation} the class object may assume the `responsibility' for its
own data-integrity. Here is a minimal definition of \texttt{Person}'s manipulating
members:
    \begin{verbatim}
    #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;
    }
\end{verbatim}
 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:
        \begin{verbatim}
    void Person::setPhone(string const &phone)
    {
        if (phone.empty())
            d_phone = " - not available -";
        else if (phone.find_first_not_of("0123456789") == string::npos)
            d_phone = phone;
        else
            cout << "A phone number may only contain digits\n";
    }
\end{verbatim}
Note the double negation in this implementation. Double negations are very
hard to read, and an encapsulating member \texttt{bool hasOnly} handles the test,
and improves \texttt{setPhone's} readability:
        \begin{verbatim}
    bool Person::hasOnly(char const *characters, string const &object)
    {
                        // object only contains 'characters'
        return object.find_first_not_of(characters) == string::npos;
    }
\end{verbatim}
and \texttt{setPhone} becomes:
        \begin{verbatim}
    void Person::setPhone(string const &phone)
    {
        if (phone.empty())
            d_phone = " - not available -";
        else if (hasOnly("0123456789", phone))
            d_phone = phone;
        else
            cout << "A phone number may only contain digits\n";
    }
\end{verbatim}
Since \texttt{hasOnly} is an encapsulated member function we can ensure that
it's only used with non-empty string objects, so \texttt{hasOnly} itself doesn't
have to check for that.

Access to the data members is controlled by \index{accessor}\emph{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
\texttt{const}. They are called \index{member: const}\index{const member}\emph{const member} \emph{functions},
which, as they are guaranteed not to modify their object's data, are available
to both modifiable and constant objects (cf. section \ref{ConstFunctions}).

To prevent \index{backdoors}\emph{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 is 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:
        \begin{verbatim}
    string &Person::name() const
    {
        return d_name;
    }

    Person somebody;
    somebody.setName("Nemo");

    somebody.name() = "Eve";    // Oops, backdoor changing the name
\end{verbatim}
To prevent the backdoor objects are returned as \emph{const references} from
accessors. Here are the implementations of \texttt{Person}'s accessors:
    \begin{verbatim}
    #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;
    }
\end{verbatim}
The \texttt{Person} class interface remains the starting point for the class
design: its member functions define what can be asked of a \texttt{Person}
object. In the end the implementation of its members merely is a technicality
allowing \texttt{Person} objects to do their jobs.

The next example shows how the class \texttt{Person} may be used. An object is
initialized and passed to a function \texttt{printperson()}, printing the person's
data. Note the reference operator in the parameter list of the function
\texttt{printperson}.  Only a reference to an existing \texttt{Person} object is passed
to the function, rather than a complete object.  The fact that
\texttt{printperson} does not modify its argument is evident from the fact that
the parameter is declared \texttt{const}.
    \begin{verbatim}
    #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';
    }

    int main()
    {
        Person p;

        p.setName("Linus Torvalds");
        p.setAddress("E-mail: Torvalds@cs.helsinki.fi");
        p.setPhone("");
        p.setMass(75);           // kg.

        printperson(p);
    }
/*
    Produced output:

Name    : Linus Torvalds
Address : E-mail: Torvalds@cs.helsinki.fi
Phone   :  - not available -
Mass  : 75

*/
\end{verbatim}
\subsection{Constructors: with and  without arguments}
    \typeout{Original Yodl file: classes/arguments}The class \texttt{Person}'s constructor so far has not received any
parameters. \textbf{C++} allows constructors to be defined with or without
parameter lists. The arguments are supplied when an object is defined.

For the class \texttt{Person} a constructor expecting three strings and a
\texttt{size\_t} might be useful. Representing, respectively, the person's name,
address, phone number and mass. This constructor can be implemented like this
(but see also section \ref{MemberInitializers}):
        \begin{verbatim}
    Person::Person(string const &name, string const &address,
                   string const &phone, size_t mass)
    {
        d_name = name;
        d_address = address;
        setPhone(phone);
        d_mass = mass;
    }
\end{verbatim}
It must of course also be declared in the class interface:
        \begin{verbatim}
    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)
    };
\end{verbatim}
Now that this constructor has been declared, the default constructor must
explicitly be declared as well if we still want to be able to construct a
plain \texttt{Person} object without any specific initial values for its data
members.  The class \texttt{Person} would thus support two constructors, and the
part declaring the constructors now becomes:
        \begin{verbatim}
    class Person
    {
        // data members
        public:
            Person();
            Person(std::string const &name, std::string const &address,
                   std::string const &phone, size_t mass);

            // additional members
    };
\end{verbatim}
In this case, the default constructor doesn't have to do very much, as it
doesn't have to initialize the \texttt{string} data members of the \texttt{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
\texttt{size\_t} data member. That member is a variable of a built-in type and such
variables do not have constructors and so are not initialized automatically.
Therefore, unless the value of the \texttt{d\_mass} data member is explicitly
initialized its value is:
    \begin{itemize}
    \item  a \emph{random} value for local \texttt{Person} objects;
    \item  0 for global and static \texttt{Person} objects.
    \end{itemize}
    The 0-value might not be too bad, but normally we don't want a \emph{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:
        \begin{verbatim}
    Person::Person()
    {
        d_mass = 0;
    }
\end{verbatim}
Using constructors with and without arguments is illustrated next. The
object \texttt{karel} is initialized by the constructor defining a non-empty
parameter list while the default constructor is used for the \texttt{anon}
object. When constructing objects using constructors requiring arguments you
are advised to surround the arguments by curly braces. Parentheses can often
also be used, and sometimes even \emph{have} to be used (cf. section
\ref{VECTOR}), but mindlessly using parentheses instead of curly braces may
easily result in unexpected problems (cf. section \ref{AMBIGUITY}). Hence the
advice to prefer curly braces rather than parentheses. Here's the
example showing two constructor-calls:
        \begin{verbatim}
    int main()
    {
        Person karel{ "Karel", "Rietveldlaan 37", "542 6044", 70 };
        Person anon;
    }
\end{verbatim}
The two \texttt{Person} objects are defined when \texttt{main} starts as they are
\emph{local} objects, living only for as long as \texttt{main} is active.

If \texttt{Person} objects must be definable using other arguments,
corresponding constructors must be added to \texttt{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:
        \begin{verbatim}
    class Person
    {
        public:
            Person(std::string const &name,
                   std::string const &address = "--unknown--",
                   std::string const &phone   = "--unknown--",
                   size_t mass = 0);

    };
\end{verbatim}
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 \texttt{phone} number but requiring a \texttt{mass} cannot
be defined using default arguments, since \texttt{phone} is not the constructor's
last parameter. Consequently a special constructor is required not having
\texttt{phone} in its parameter list. However, this doesn't necessarily mean that
constructors must duplicate their code, as constructors may call each other
(called \emph{constructor delegation}). Constructor delegation is illustrated in
section \ref{CONSCALL} below.

\subsubsection{The order of construction}
        \typeout{Original Yodl file: classes/order}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 \texttt{Test}. The program defines a global
\texttt{Test} object and two local \texttt{Test} objects. The order of construction is
as expected: first global, then main's first local object, then \texttt{func}'s
local object, and then, finally, \texttt{main}'s second local object:
    \begin{verbatim}
    #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");

    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
*/
\end{verbatim}
\section{Ambiguity resolution}\label{AMBIGUITY}
\typeout{Original Yodl file: classes/ambiguity}Calling constructors using parentheses may result in unwelcome
surprises. Assume the following class interface is available:
        \begin{verbatim}
    class Data
    {
        public:
            Data();
            Data(int one);
            Data(int one, int two);

            void display();
    };
\end{verbatim}
The intention is to define two objects of the class Data, using, respectively,
the first and second constructors, while using parentheses in the object
definitions. Your code looks like this (and, ignoring the 'not used' warnings,
compiles correctly):
        \begin{verbatim}
    #include "data.h"
    int main()
    {
        Data d1();
        Data d2(argc);
    }
\end{verbatim}
Let's get rid of the 'not used' warnings by adding two statements to \texttt{main}:
            \begin{verbatim}
        d1.display();
        d2.display();
\end{verbatim}
But, surprise, the compiler complains about the first of these two:

\emph{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: \texttt{Data()}, rather than \texttt{Data}. What are those \texttt{()} doing there?

Before answering that question, let's broaden our story somewhat. We know that
somewhere in a library a \index{factory function}\emph{factory function} \texttt{dataFactory} exists. A
factory function creates and returns an object of a certain type. This
\texttt{dataFactory} function returns a \texttt{Data} object, constructed using
\texttt{Data}'s default constructor. Hence, \texttt{dataFactory} needs no arguments. We
want to use \texttt{dataFactory} in our program, but must declare the function. So
we add the declaration to \texttt{main}, as that's the only location where
\texttt{dataFactory} will be used. It's a function, not requiring arguments,
returning a \texttt{Data} object:
            \begin{verbatim}
        Data dataFactory();
\end{verbatim}
This, however, looks remarkably similar to our \texttt{d1} object definition:
            \begin{verbatim}
        Data d1();
\end{verbatim}
Here we found the solution of our problem: \texttt{Data d1()} apparently is \emph{not}
the definition of a \texttt{d1} object, but the \emph{declaration} of a function,
returning a \texttt{Data} object. So, what's happening here and how should we
define a \texttt{Data} object using \texttt{Data}'s default constructor?

First: what's happening here is that the compiler, when confronted with
\texttt{Data d1()}, actually had a choice. It could either define a \texttt{Data}
object, or declare a function. It declares a function. 

Here we're encountering an \index{ambiguity}ambiguity in \textbf{C++}'s grammar 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 in the way we
want it to be solved. To define an object using its default constructor:
    \begin{itemize}
    \item  merely mention it (like \texttt{int x}): \texttt{Data d1};
    \item  use the curly brace initialization: \texttt{Data d1\{\}};
    \item  use the assignment operator and an anonymous default constructed
        \texttt{Data} object: \texttt{Data d1 = Data\{\}}, or possibly \texttt{Data d1 =
        Data()}. 
    \end{itemize}

\subsection{Types `Data' vs. `Data()'}
    \typeout{Original Yodl file: classes/types}
    \texttt{Data()} in the last example of the previous section defines a default
constructed anonymous \texttt{Data} object. This takes us back to the compiler
error. According to the compiler, our original \texttt{d1} apparently was not of
type \texttt{Data}, but of type \texttt{Data()}. So what's that?

Let's first have a look at our second constructor. It expects an
\texttt{int}. We would like to define another \texttt{Data} object, using the second
constructor and want to pass the default \texttt{int} value to the constructor,
using \texttt{int()}. We know this defines a default \texttt{int} value, as \texttt{cout $<$$<$
int() $<$$<$ '\textbackslash{}n'} nicely displays 0, and \texttt{int x = int()} also initialized x to 
0. So we try \texttt{`Data di(int())'} in \texttt{main}.

Not good: again the compiler complains when we try to use
\texttt{di}. After \texttt{`di.display()'} the compiler tells us:
    \begin{quote}\emph{error: request for member 'display' in 'di', which is of
non-class type 'Data(int ($*$)())'}\end{quote}

Oops, again not as expected.... Didn't we pass 0? Why the sudden pointer?
Well, we're once again encountering the compiler's same `use a declaration
when possible' strategy. The notation \texttt{Type()} not only represents the
default value of type \texttt{Type}, but it's also a shorthand notation for an
anonymous pointer to a function, not expecting arguments, and returning a
\texttt{Type} value, which you can verify by defining \texttt{`int ($*$ip)() = nullptr'},
and passing \texttt{ip} as argument to \texttt{di}: \texttt{di(ip)} compiles fine.

So why doesn't the error occur when inserting \texttt{int()} or assigning \texttt{int()}
to \texttt{int x}? In these latter cases nothing is declared. Rather, `\texttt{cout}'
and `\texttt{int x =}' require expressions resulting in values, which is provided
by \texttt{int()}'s `natural' interpretation. But with \texttt{`Data di(int())'} the
compiler again has a choice, and (by design) it chooses a declaration because
the declaration takes priority. Now \texttt{int()}'s interpretation as an anonymous
pointer is available and therefore used.

Likewise, if \texttt{int x} has been defined, \texttt{`Data b1(int(x))'} declares \texttt{b1}
as a function, expecting an \texttt{int} (as \texttt{int(x)} represents a type), while
\texttt{`Data b2((int)x)'} defines \texttt{b2} as a \texttt{Data} object, using the
constructor expecting a single \texttt{int} value.

Again, to use default entities, values or objects, prefer \texttt{\{\}} over \texttt{()}:
\texttt{Data di\{ int\{\} \}} defines \texttt{di} of type \texttt{Data}, calling the \texttt{Data(int
x)} constructor and uses \texttt{int's} default value 0.

But what about the compiler's original complaint? The compiler told us that
our original \texttt{d1} was not of type \texttt{Data}, but of type \texttt{Data()}. But
what's that? The parentheses in the error message are important: it indicates
a function: \texttt{d1}, because of the subsequent parentheses, declares a
function, not expecting arguments, and returning a \texttt{Data} object. Shorthand:
\texttt{Data()}, more verbosely: \texttt{Data ($*$)()}. As a final illustration: the
following program writes \texttt{hello world} twice, and \texttt{Data d1()} in \texttt{main}
simply is an explicit local declaration of the globally defined function
\texttt{d1}, further illustrated by the assignment of \texttt{d1} to the explicitly
declared pointer to a function \texttt{pf}, returning a \texttt{Data} object:
    \begin{verbatim}
    #include <iostream>
    #include "data.h"
    
    Data::Data()
    {}

    Data d1()
    {
        std::cout << "hello world\n";
        return Data{};
    }
    
    int main()
    {
        Data d1();
    
        d1();
        Data (*pf)() = d1;
    
        pf();   // or (same): (*pf)()
    }
\end{verbatim}
    Also, as \texttt{d1()} returns a \texttt{Data} object, a statement like
\texttt{d1().display()} correctly compiles.

\subsection{Superfluous parentheses}
    \typeout{Original Yodl file: classes/parentheses}Let's play some more. At some point in our program we defined \texttt{int b}. Then,
in a compound statement we need to construct an \emph{anonymous} \texttt{Data} object,
initialized by \texttt{b}, and then we're supposed to display \texttt{b} itself:
    
            \begin{verbatim}
    int b = 18;
    {
        Data(b);
        cout << b;
    }
\end{verbatim}
About that \texttt{cout} statement the compiler tells us (I modified the
error message to reveal its meaning):

\emph{error: cannot bind `std::ostream \& $<$$<$ Data const \&'}

Here we didn't insert \texttt{int b} but \texttt{Data b}. Had we omitted the compound
statement, the compiler would have complained about a doubly defined \texttt{b}
entity, as \texttt{Data(b)} simply means \texttt{Data b}, a \texttt{Data} object constructed
by default. Here, the parentheses around \texttt{b} are superfluous and may be
omitted by the compiler when parsing a definition or declaration.

Of course, the question now becomes how a temporary object \texttt{Data},
initialized with \texttt{int b} \emph{can} be defined. Remember that the compiler may
remove superfluous parentheses. So, what we need to do is to pass an \texttt{int}
to the anonymous \texttt{Data} object, without using the \texttt{int}'s name.
    \begin{itemize}
    \item  We can use a cast: \texttt{Data(static\_cast$<$int$>$(b))};
    \item  We can use a curly brace initialization: \texttt{Data\{ b \}}.
    \end{itemize}

Values and types make big differences. Consider the following definitions:
        \begin{verbatim}
    Data (*d4)(int);    // 1
    Data (*d5)(3);      // 2
\end{verbatim}
Definition 1 should cause no problems: it's a pointer to a function,
expecting an \texttt{int}, returning a \texttt{Data} object. Hence, \texttt{d4} is a pointer
variable.  

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: variables can be initialized using assignment
statements, using parentheses, or using curly braes. In general, they're
interchangeable. So instead of \texttt{`(3)'} we could have written \texttt{`= 3'} or
\texttt{`\{3\}'}. Let's pick the first alternative, resulting in:
        \begin{verbatim}
    Data (*d5) = 3;
\end{verbatim}
Now we get to `play compiler' again. Removing some more superfluous
parentheses we get:
        \begin{verbatim}
    Data *d5 = 3;
\end{verbatim}
It's a pointer to a \texttt{Data} object, initialized to 3. This is
\emph{syntactically} correct, but \emph{semantically} incorrect: at address 3
there's no \texttt{Data} object. If we had initially written
        \begin{verbatim}
     Data (*d5)(&d1);      // 2
\end{verbatim}
the fun resulting from contrasting \texttt{int} and \texttt{3} would most likely
have been masked.

\subsection{Existing types}
    \typeout{Original Yodl file: classes/existingtypes}Once a type name has been defined it prevails over identifiers representing
variables if the compiler is given a choice. This, too, may result in
interesting constructions.

Assume a function \texttt{process} expecting an \texttt{int} exists in a library. We
want to use this function to process some \texttt{int} data values. So in \texttt{main}
\texttt{process} is declared and called:
        \begin{verbatim}
    int process(int Data);
    process(argc);
\end{verbatim}
No problems here. But unfortunately we once decided to `beautify' our
code, by throwing in some superfluous parentheses, like so:
        \begin{verbatim}
    int process(int (Data));
    process(argc);
\end{verbatim}
we're in trouble. Now the compiler generates an error, caused by the rule to
let declarations prevail over definitions. \texttt{Data} now becomes the name of
the \texttt{class Data}, and analogous to \texttt{int (x)} the parameter \texttt{int (Data)}
is parsed as \texttt{int ($*$)(Data)}: a pointer to a function, expecting a \texttt{Data}
object, returning an \texttt{int}.

Here is another example. When, instead of declaring 
        \begin{verbatim}
    int process(int Data[10]);
\end{verbatim}
we declare, e.g., to emphasize the fact that an array is passed to
\texttt{process}:
        \begin{verbatim}
    int process(int (Data[10]));
\end{verbatim}
the \texttt{process} function does not expect a pointer to \texttt{int} values, but
a pointer to a function expecting a pointer to \texttt{Data} elements, returning an
\texttt{int}. The size 10 is considered just a number, and is not taken literally,
as it's part of a function parameter specification.

To summarize the findings in the `Ambiguity Resolution' section:
    \begin{itemize}
    \item  The compiler will try to remove superfluous parentheses;
    \item  But if the parenthesized construction represents a type, it will try
        to use the type;
    \item  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).
    \item  Most problems that result from the compiler interpreting
        constructions as declarations are caused by us using parentheses. As a
        \index{rule of thumb}rule of thumb: use curly braces, rather than parentheses when
        constructing objects (or values).
    \end{itemize}

\section{Objects inside objects: composition}\label{Composition}
\typeout{Original Yodl file: classes/composition}In the class \texttt{Person} objects are used as data members. This construction
technique is called \index{composition}\emph{composition}.

Composition is neither extraordinary nor \textbf{C++} specific: in \textbf{C}
a \texttt{struct} or \texttt{union} field is commonly used in other compound types. In
\textbf{C++} it requires some special thought as their initialization sometimes is
subject to restrictions, as discussed in the next few sections.

\subsection{Composition and (const) objects: (const) member initializers}\label{MemberInitializers}
    \typeout{Original Yodl file: classes/comconst}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 \texttt{Person}:
        \begin{verbatim}
    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;
    }
\end{verbatim}
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 \emph{must}
have been called. The initialization of those objects is thereupon immediately
undone by the body of \texttt{Person}'s constructor. That is
not only inefficient but sometimes downright impossible. Assume that the class
interface mentions a \texttt{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 \texttt{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
\emph{initialization} of data members happens before that. \textbf{C++} defines the
 \index{member initializer}\emph{member initializer} syntax allowing us to specify the way data members
are initialized at construction time. Member initializers are specified as a
list of constructor specifications between  a colon following a constructor's
parameter list and the opening curly brace of a constructor's body, as
follows:
        \begin{verbatim}
    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)
    {}
\end{verbatim}
In this example the member initialization used parentheses surrounding the
intialization expression. \index{member initializer: using { }}Instead of
parentheses \emph{curly braces} may also be used. E.g., \texttt{d\_name} could also be
initialized this way:
        \begin{verbatim}
        d_name{ name },
\end{verbatim}
Member initialization \emph{always} occurs when objects are composed in
classes: if \emph{no} constructors are mentioned in the member initializer list
the default constructors of the objects are called. Note that this only holds
true for \emph{objects}. Data members of primitive data types are \emph{not}
initialized automatically.

Member initialization can, however, also be used for primitive data members,
like \texttt{int} and \texttt{double}. The above example shows the initialization of the
data member \texttt{d\_mass} from the parameter \texttt{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 \emph{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 \emph{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 \index{rule of thumb}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.

\subsection{Composition and reference objects: reference member initializers}\label{REFMEMBERS}
    \typeout{Original Yodl file: classes/comref}Apart from using member initializers to initialize composed objects (be they
\texttt{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 \texttt{Configfile}, defined in \texttt{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 \texttt{main} is an object of the class \texttt{Process},
doing `all the work'. What possibilities do we have to tell the object of the
class \texttt{Process} that an object of the class \texttt{Configfile} exists?
    \begin{itemize}
    \item  The objects could have been declared as \emph{global} objects. This
\emph{is} a possibility, but not a very good one, since all the advantages of
local objects are lost.
    \item  The \texttt{Configfile} object may be passed to the \texttt{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 \texttt{Configfile}
parameter, and then a data member of the \texttt{Process} class can be used to make
the \texttt{Configfile} object accessible throughout the \texttt{Process} class. This
might involve yet another object-copying task, as in the following situation:
    \begin{verbatim}
Process::Process(Configfile conf)   // a copy from the caller
{
    d_conf = conf;                  // copying to d_conf member
}
\end{verbatim}
\item  The copy-instructions can be avoided if \emph{pointers} to
the \texttt{Configfile} objects are used, as in:
    \begin{verbatim}
Process::Process(Configfile *conf)  // pointer to external object
{
    d_conf = conf;                  // d_conf is a Configfile *
}
\end{verbatim}
This construction as such is OK, but forces us to use the `\texttt{-$>$}' field
selector operator, rather than the `\texttt{.}' operator, which is (disputably)
awkward. Conceptually one tends to think of the \texttt{Configfile} object as an
object, and not as a pointer to an object. In \textbf{C} this would probably have
been the preferred method, but in \textbf{C++} we can do better.
    \item  Rather than using value or pointer parameters, the \texttt{Configfile}
parameter could be defined as a \index{reference parameter}\emph{reference parameter} of \texttt{Process}'s
constructor. Next, use a \texttt{Config} reference data member in the
\texttt{class Process}.
    \end{itemize}
    But a reference variable cannot be initialized using an assignment, and so
the following is incorrect:
        \begin{verbatim}
    Process::Process(Configfile &conf)
    {
        d_conf = conf;        // wrong: no assignment
    }
\end{verbatim}
The statement \texttt{d\_conf = conf} fails, because it is not an
initialization, but an assignment of one \texttt{Configfile} object (i.e.,
\texttt{conf}), to another (\texttt{d\_conf}). An assignment to a reference variable is
actually an assignment to the variable the reference variable refers to. But
which variable does \texttt{d\_conf} refer to? To no variable at all, since we
haven't initialized \texttt{d\_conf}.  After all, the whole purpose of the statement
\texttt{d\_conf = conf} was to initialize \texttt{d\_conf}....

How to initialize \texttt{d\_conf}? We once again use the member initializer
syntax. Here is the correct way to  initialize \texttt{d\_conf}:
        \begin{verbatim}
    Process::Process(Configfile &conf)
    :
        d_conf(conf)      // initializing reference member
    {}
\end{verbatim}
The above syntax must be used in all cases where reference data members
are used. E.g., if \texttt{d\_ir} would have been an \texttt{int} reference data member,
a construction like
        \begin{verbatim}
    Process::Process(int &ir)
    :
        d_ir(ir)
    {}
\end{verbatim}
would have been required.

\section{Data member initializers}
    \typeout{Original Yodl file: classes/memberinit}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:
        \begin{verbatim}
    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);
    };
\end{verbatim}
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 \texttt{d\_nr}
which must be given the value \texttt{++s\_nObjects}. Since these are
\emph{non}-default actions, we can't declare the default constructor using \texttt{=
default}, but we must provide an actual implementation:
            \begin{verbatim}
    Container()
    :
        d_data(0),
        d_size(0),
        d_nr(++s_nObjects)
    {}
\end{verbatim}
In fact, \emph{all} constructors require us to state the
\texttt{d\_nr(++s\_nObjects)} initialization. So if \texttt{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.

\textbf{C++}, however, also supports 
        \index{data member: initialization}\emph{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
\texttt{++s\_nObjects} can be an initial value.

Using data member initializers for the class \texttt{Container} we get:
        \begin{verbatim}
    class Container
    {
        Data *d_data = 0;
        size_t d_size = 0;
        size_t d_nr = ++s_nObjects;

        static size_t s_nObjects;

        public:
            Container() = default;
            Container(Container const &other);
            Container(Data *data, size_t size);
            Container(Container &&tmp);
    };
\end{verbatim}
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-constructor may now be implemented like
this:
        \begin{verbatim}
    Container(Container &&tmp)
    :
        d_data(tmp.d_data),
        d_size(tmp.d_size)
    {
        tmp.d_data = 0;
    }
\end{verbatim}
Although \texttt{d\_nr}'s intialization is left out of the implementation it
\emph{is} initialized due to the data member initialization provided in the
class's interface.

An \index{aggregate}\emph{aggregate} is an array or a \texttt{class} (usually a \texttt{struct} with no
user-defined constructors, no private or protected non-static data members,
no base classes (cf. chapter \ref{INHERITANCE}), and no virtual functions
(cf. chapter \ref{POLYMORPHISM})). E.g.,
        \begin{verbatim}
    struct POD      // defining aggregate POD
    {
        int first = 5; 
        double second = 1.28; 
        std::string hello{ "hello" };
    };
\end{verbatim}
To initialize such aggregates \emph{braced initializer lists} can be used. In
fact, their use is preferred over using the older form (using parentheses), as
using braces avoids confusion with function declarations. E.g.,
        \begin{verbatim}
    POD pod{ 4, 13.5, "hi there" };
\end{verbatim}
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.,
        \begin{verbatim}
    POD pod{ 4 };   // uses second: 1.28, hello: "hello"
\end{verbatim}
\subsection{Delegating constructors}\label{CONSCALL}
    \typeout{Original Yodl file: classes/constructorscall}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 \texttt{init}
performing all initializations common to constructors. Such an \texttt{init}
function, however, cannot be used to initialize \texttt{const} or reference data
members, nor can it be used to perform so-called \emph{base class}
initializations (cf. chapter \ref{INHERITANCE}).

Here is an example where such an \texttt{init} function might have been used. A
class \texttt{Stat} is designed as a wrapper class around \textbf{C}'s \index{stat}\textbf{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 \texttt{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 \texttt{init} which
is called by the constructors.

\textbf{C++} offers an alternative by allowing constructors to call each
other. This is called
    \index{constructor: delegation}
    \index{delegating constructors}\emph{delegating constructors}
        which is illustrated by the next example:
        \begin{verbatim}
    class Stat
    {
        public:
            Stat()
            :
                Stat("", "")        // 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
            }
    };
\end{verbatim}
\textbf{C++} allows static const integral data members to be initialized within
the \index{data member: initialization} class interfaces (cf. chapter
\ref{StaticDataFun}). The \index{C++11}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 \texttt{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 \texttt{Stat} uses a data member \texttt{bool d\_hasPath} which is \texttt{false} by
default but the third constructor (see above) should initialize it to \texttt{true}
then the following approach is possible:
        \begin{verbatim}
    class Stat
    {
        bool d_hasPath = false;

        public:
            Stat(std::string const &fileName, std::string const &searchPath)
            :
                d_hasPath(true)     // overrule the interface-specified
            {}                      // value
    };
\end{verbatim}
Here \texttt{d\_hasPath} receives its value only once: it's always initialized
to \texttt{false} except when the shown constructor is used in which case it is
initialized to \texttt{true}.

\section{Uniform initialization}\label{UNIFORMINIT}
\typeout{Original Yodl file: classes/uniforminit}When defining variables and objects they may immediately be given
initial values. Class type objects are always initialized by one of their
available constructors. \textbf{C} already supports the array and struct
 \index{initialization}\index{initializer list}\emph{initializer list} consisting of a list of constant
expressions surrounded by a pair of curly braces.

\textbf{C++} supports a comparable initialization, called 
    \index{uniform initialization}\emph{uniform initialization}. It uses the following syntax:
        \begin{verbatim}
    Type object{ value list };
\end{verbatim}
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 sometimes results in an ambiguity as constructing an
object may sometimes be confused with using the object's overloaded function
call operator (cf. section \ref{FUNOBJ}). As initializer lists can only be used
with \emph{plain old data} (POD) types (cf. section \ref{POD}) and with classes
that are `initializer list aware' (like \texttt{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 (in-class implementations for brevity):
        \begin{verbatim}
    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};
            }
    };
\end{verbatim}
Object definitions may be encountered in unexpected places, easily resulting in
(human) confusion. Consider a function `\texttt{func}' and a very simple
class \texttt{Fun} (\texttt{struct} is used, as data hiding is not an issue here):
        \begin{verbatim}
    void func();

    struct Fun
    {
        Fun(void (*f)())
        {
            std::cout << "Constructor\n";
        };

        void process()
        {
            std::cout << "process\n";
        }
    };
\end{verbatim}
Assume that in \texttt{main} a \texttt{Fun} object is defined as follows: 
        \begin{verbatim}
    Fun fun(func);
\end{verbatim}
Running this program displays \texttt{Constructor}, confirming that the object
\texttt{fun} is constructed. Next we change this line of code, calling \texttt{process}
from an anonymous \texttt{Fun} object:
        \begin{verbatim}
    Fun(func).process();
\end{verbatim}
As expected, \texttt{Constructor} appears, followed by the text \texttt{process}.

What about merely defining an anonymous \texttt{Fun} object? We do:
        \begin{verbatim}
    Fun(func);
\end{verbatim}
Now we're in for a surprise. The compiler complains that \texttt{Fun}'s default
constructor is missing. Why's that? Insert a blank immediately after
\texttt{Fun} and you get \texttt{Fun (func)}. Parentheses around an identifier are OK,
and are removed while the parenthesized expression is parsed. In
this case: \texttt{(func)} equals \texttt{func}, and so we have \texttt{Fun func}: the
definition of a \texttt{Fun func} object, using \texttt{Fun}'s default constructor (which
isn't declared in \texttt{Fun's} class interface).

So why does \texttt{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 \texttt{Fun(func)} represents that object. It's not the name
of an existing object, but a constructor expecting a function (like \texttt{func})
as its argument. So the compiler creates an \emph{anonymous} \texttt{Fun} object,
which receives \texttt{func} as its argument.

Clearly, with \texttt{Fun(func)} parentheses cannot be used to create an anonymous
\texttt{Fun} object. However, a uniform initialization \emph{can} be used. To define
the anonymous \texttt{Fun} object we use this syntax:
        \begin{verbatim}
    Fun{ func };
\end{verbatim}
(which can also be used to immediately call one of its members. E.g.,
\texttt{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:
        \begin{verbatim}
    class Vector
    {
        public:
            Vector(size_t size);
            Vector(std::initializer_list<int> const &values);
    };

    Vector vi = {4};
\end{verbatim}
When defining \texttt{vi} the constructor expecting the initializer list is
called rather than the constructor expecting a \texttt{size\_t} argument. If the
latter constructor is required the standard constructor
syntax must be used. I.e., \texttt{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.

Initializer lists support a basic set of member functions and constructors:
    \begin{itemize}
    \item \index{initializer\_list}\texttt{initializer\_list$<$Type$>$ object}:\ \\ defines \texttt{object} as an empty initializer list
    \item \texttt{initializer\_list$<$Type$>$ object \{ list of Type values \}}:\ \\ defines \texttt{object} as an initializer list containing \texttt{Type} values
    \item \texttt{initializer\_list$<$Type$>$ object(other)}:\ \\ initializes \texttt{object} using the values stored in \texttt{other}
    \item \index{size}\texttt{size\_t size() const}:\ \\ returns the number of elements in the initializer list
    \item \index{begin}\texttt{Type const $*$begin() const}:\ \\ returns a pointer to the first element of the initializer list
    \item \index{end}\texttt{Type const $*$end() const}:\ \\ returns a pointer just beyond the location of the last element of the
initializer list
    \end{itemize}

\section{Defaulted and deleted class members}\label{DEFAULTED}
\typeout{Original Yodl file: classes/defaulted}In everyday class design two situations are frequently encountered:
    \begin{itemize}
        \item  A class offering constructors explicitly has to define a default
constructor;
        \item  A class (e.g., a class implementing a stream)
cannot initialize objects by copying the values from an existing object of
that class (called
 \index{copy construction}\emph{copy construction}) and cannot assign objects to each other.
    \end{itemize}
    Once a class defines at least one constructor its default constructor is
not automatically defined by the compiler. \textbf{C++} relaxes that
restriction somewhat by offering the \index{default}`\index{= default}\texttt{= default}'
syntax. A class specifying `\texttt{= default}' with its default constructor
declaration indicates that the \index{trivial default constructor}trivial default constructor should be
provided by the compiler. A trivial default constructor performs the following
actions:
    \begin{itemize}
    \item  Its data members of built-in or primitive types are not initialized;
    \item  Its composed (class type) data members are initialized by their
default constructors.
    \item  If the class is derived from a base class (cf. chapter
\ref{INHERITANCE}) the base class is initialized by its default constructor.
    \end{itemize}
    Trivial implementations can also be provided for the \emph{copy constructor},
the \emph{overloaded assignment operator}, and the \emph{destructor}. Those members
are introduced in chapter \ref{MEMORY}.

Conversely, situations exist where some (otherwise automatically provided)
members should \emph{not} be made available. This is realized by specifying
 \index{delete}`\index{= delete}\texttt{= delete}'. Using \texttt{= default} and \texttt{= delete} is illustrated
by the following example. The default constructor receives its trivial
implementation, copy-construction is prevented:
        \begin{verbatim}
    class Strings
    {
        public:
            Strings() = default;
            Strings(std::string const *sp, size_t size);

            Strings(Strings const &other) = delete;
    };
\end{verbatim}
\section{Const member functions and const objects}\label{ConstFunctions}
\typeout{Original Yodl file: classes/member}The keyword \texttt{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
    \index{const member functions}\emph{const member functions}. In the class \texttt{Person}, we see that the
accessor functions were declared \texttt{const}:
        \begin{verbatim}
    class Person
    {
        public:
            std::string const &name()    const;
            std::string const &address() const;
            std::string const &phone()   const;
            size_t mass()              const;
    };
\end{verbatim}
The rule of thumb given in section \ref{ConstRule} applies here too:
whichever appears to the \emph{left} of the keyword \texttt{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 \texttt{const} attribute must be
repeated:
        \begin{verbatim}
    string const &Person::name() const
    {
        return d_name;
    }
\end{verbatim}
The compiler prevents the data members of a class from being modified
by one of its const member functions. Therefore a statement like
        \begin{verbatim}
    d_name[0] = toupper(static_cast<unsigned char>(d_name[0]));
\end{verbatim}
results in a compiler error when added to the above function's definition.

\texttt{Const} member functions are used to prevent inadvertent data
modification. Except for constructors and the destructor (cf. chapter
\ref{MEMORY}) only const member functions can be used with (plain, references
or pointers to) \texttt{const} objects.

Const objects are frequently encountered as \texttt{const \&} parameters of
functions. Inside such functions only the object's const members may be
used. Here is an example:
        \begin{verbatim}
    void displayMass(ostream &out, Person const &person)
    {
        out << person.name() << " weighs " << person.mass() << " kg.\n";
    }
\end{verbatim}
Since \texttt{person} is defined as a \texttt{Person const \&} the function
\texttt{displayMass} cannot call, e.g.,\ \\ 
    \texttt{person.setMass(75)}.

The \texttt{const} member function attribute can be used to
 \index{function overloading} overload member functions. When functions are
overloaded by their \texttt{const} attribute the compiler uses the member
function matching most closely the \index{const-qualification}const-qualification of the object:
    \begin{itemize}
    \item  When the object is a \texttt{const} object, only \texttt{const} member
functions can be used.
    \item  When the object is not a \texttt{const} object, non-\texttt{const} member
functions are used, \emph{unless} only a \texttt{const} member function is
available. In that case, the \texttt{const} member function is used.
    \end{itemize}
    The next example illustrates how (non) \texttt{const} member functions are
selected:
        \begin{verbatim}
    #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;

        constObject.member();
        nonConstObject.member();
    }
    /*
            Generated output:

        const member
        non const member
    */
\end{verbatim}
    As a general principle of design: member functions should always be given
the \texttt{const} attribute, unless they actually modify the object's data.

\subsection{Anonymous objects}\label{ANONYMOUS}
    \typeout{Original Yodl file: classes/anonymous}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 \texttt{Print} offers a facility to
print a string, using a configurable prefix and suffix. A partial class
interface could be:
        \begin{verbatim}
    class Print
    {
        public:
            Print(ostream &out);
            void print(std::string const &prefix, std::string const &text,
                     std::string const &suffix) const;
    };
\end{verbatim}
An interface like this would allow us to do things like:
        \begin{verbatim}
    Print print{ cout };
    for (int idx = 0; idx != argc; ++idx)
        print.print("arg: ", argv[idx], "\n");
\end{verbatim}
This works fine, but it could greatly be improved if we could pass
\texttt{print}'s invariant arguments to \texttt{Print}'s constructor.  This would
simplify \texttt{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 \texttt{Print} object:
        \begin{verbatim}
    void allArgs(Print const &print, int argc, char **argv)
    {
        for (int idx = 0; idx != argc; ++idx)
            print.print(argv[idx]);
    }
\end{verbatim}
The above is a fairly generic piece of code, at least it is with respect
to \texttt{Print}. Since \texttt{prefix} and \texttt{suffix} don't change they can be passed
to the constructor which could be given  the prototype:
        \begin{verbatim}
    Print(ostream &out, string const &prefix = "", string const &suffix = "");
\end{verbatim}
Now \texttt{allArgs} may be used as follows:
        \begin{verbatim}
    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
\end{verbatim}
But now we note that \texttt{p1} and \texttt{p2} are only used inside the
\texttt{allArgs} function. Furthermore, as we can see from \texttt{print}'s prototype,
\texttt{print} doesn't modify the internal data of the \texttt{Print} object it is
using.

In such situations it is actually not necessary to define objects before
they are used. Instead \index{anonymous object}\emph{anonymous object}\emph{s}\index{object: anonymous} may be
used. Anonymous objects can be used:
    \begin{itemize}
    \item  to initialize a function parameter which is a \texttt{const} reference to
an object;
    \item  if the object is \emph{only} used inside the function call.
    \end{itemize}
    When passing anonymous objects as arguments of \texttt{const \&} parameters of
functions they are considered constant as they merely exist for passing the
information of (class type) objects to those functions. This way, they cannot
be modified, nor may their non-const member functions be used.  Of course, a
\texttt{const\_cast} could be used to cast away the const reference's constness, but
that's considered bad practice on behalf of the function receiving the
anonymous objects. Also, any modification to the anonymous object is lost once
the function returns as the anonymous object ceases to exist after calling the
function. These anonymous objects used to initialize const references should
not be confused with passing anonymous objects to parameters defined as rvalue
references (section \ref{RREF}) 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:
        \begin{verbatim}
    allArgs(Print{ cout, "arg: ", "\n" }, argc, argv);    // prints to cout
    allArgs(Print{ cerr, "err: --", "--\n" }, argc, argv);// prints to cerr
\end{verbatim}
In this situation the \texttt{Print} objects are constructed and immediately
passed as first arguments to the \texttt{allArgs} functions, where they are
accessible as the function's \texttt{print} parameter. While the \texttt{allArgs}
function is executing they can be used, but once the function has completed,
the anonymous \texttt{Print} objects are no longer accessible.

\subsubsection{Subtleties with anonymous objects}
        \typeout{Original Yodl file: classes/subtleties}Anonymous objects can be used to initialize function parameters
that are \texttt{const} references to objects. These objects are created just
before such a function is called, and are destroyed once the function has
terminated. \textbf{C++}'s grammar allows us to use anonymous objects in other
situations as well. Consider the following snippet of code:
        \begin{verbatim}
    int main()
    {
        // initial statements
        Print{ "hello", "world" };      // assume a matching constructor
                                        // is available
        // later statements
    }
\end{verbatim}
In this example an anonymous \texttt{Print} object is constructed, and it is
immediately destroyed thereafter. So, following the `initial
statements' our \texttt{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. \index{lifetime: anonymous objects}
 \index{anonymous object: lifetime} Their lifetimes are limited to the
\emph{statements}, rather than to the \emph{end of the block} in which they are
defined.

Plain anonymous object are at least useful in one situation. Assume we
want to put \emph{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.

\textbf{C++}'s grammar contains another remarkable characteristic illustrated
by the next example:
        \begin{verbatim}
    int main(int argc, char **argv)
    {
              // assume a matching constructor is available:
        Print p{ cout, "", "" };            // 1
        allArgs(Print{ p }, argc, argv);    // 2
    }
\end{verbatim}
In this example a non-anonymous object \texttt{p} is constructed in statement
1, which is then used in statement 2 to \emph{initialize} an anonymous
object. The anonymous object, in turn, is then used to initialize
\texttt{allArgs}'s \texttt{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
    \index{copy constructor}\emph{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 \ref{MEMORY}, 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 \texttt{p} can't be redefined (in statement
3, below):
        \begin{verbatim}
    int main(int argc, char *argv[])
    {
        Print p{ "", "" };                  // 1
        allArgs(Print(p), argc, argv);      // 2
        Print(p);                           // 3 error!
    }
\end{verbatim}
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:
        \begin{verbatim}
    error: redeclaration of 'Print p'
\end{verbatim}
which solves the problem when realizing that within a compound statement
objects and variables may be defined. Inside a compound statement, a
\emph{type name} followed by a \texttt{variable name} is the grammatical form of a
variable definition. \emph{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
        \begin{verbatim}
        Print (p);
\end{verbatim}
which is, since the parentheses are superfluous, equal to
        \begin{verbatim}
        Print p;
\end{verbatim}
thus producing \texttt{p}'s redeclaration.

As a further example: when we define a variable using a built-in type (e.g.,
\texttt{double}) using superfluous parentheses the compiler quietly removes
these parentheses for us:
        \begin{verbatim}
    double ((((a))));       // weird, but OK.
\end{verbatim}
To summarize our findings about anonymous variables:
    \begin{itemize}
    \item  Anonymous objects are great for initializing \texttt{const} reference
parameters.
    \item  The same syntax, 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.
    \item  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.
    \end{itemize}

\section{The keyword `inline'}\label{INLINE}
\typeout{Original Yodl file: classes/inline}Let us take another look at the implementation of the function
\texttt{Person::name()}:
        \begin{verbatim}
    std::string const &Person::name() const
    {
        return d_name;
    }
\end{verbatim}
This function is used to retrieve the name field of an object of the class
\texttt{Person}. Example:
        \begin{verbatim}
    void showName(Person const &person)
    {
        cout << person.name();
    }
\end{verbatim}
To insert \texttt{person}'s name the following actions are performed:
    \begin{itemize}
    \item  The function \texttt{Person::name()} is called.
    \item  This function returns \texttt{person}'s \texttt{d\_name} as a reference.
    \item  The referenced name is inserted into \texttt{cout}.
    \end{itemize}
    Especially the first part of these actions causes some time loss, since an
extra function call is necessary to retrieve the value of the \texttt{name} field.
Sometimes a faster procedure immediately making the \texttt{d\_name} data member
available is preferred without ever actually calling a function
\texttt{name}. This can be realized using \index{inline}\texttt{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 \texttt{inline} is a \emph{request} to the compiler: the
compiler may decide to ignore it, and \emph{will} probably ignore it when the
function's body contains much code. Good programming discipline suggests to be
aware of this, and to avoid \texttt{inline} unless the function's body is 
small (e.g., at most one statement and it's highly unlikely that that
statement will ever change). More on this in section \ref{WHENINLINE}.

\subsection{Defining members inline}\label{DEFINLINE}
    \typeout{Original Yodl file: classes/defineinline}Inline functions may be implemented \emph{in the class interface itself}. For the
class \texttt{Person} this results in the following implementation of \texttt{name}:
        \begin{verbatim}
    class Person
    {
        public:
            std::string const &name() const
            {
                return d_name;
            }
    };
\end{verbatim}
Note that the \index{inline}inline code of the function \texttt{name} now literally
occurs inline in the interface of the class \texttt{Person}. The keyword \texttt{const}
is again added to the function's header.

Although members can be defined \index{member: in-class} \emph{in-class} (i.e.,
inside the class interface itself), it is considered bad practice
for the following reasons:
    \begin{itemize}
    \item  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.
    \item  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 (\emph{unless} inline public members use such inline private
members).
    \item  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.
    \end{itemize}
    Because of the above considerations inline members should not be defined
in-class. Rather, they should be defined following the class interface. The
\texttt{Person::name} member is therefore preferably defined as follows:
        \begin{verbatim}
    class Person
    {
        public:
            std::string const &name() const;
    };

    inline std::string const &Person::name() const
    {
        return d_name;
    }
\end{verbatim}
If it is ever necessary to cancel \texttt{Person::name}'s inline
implementation, then this becomes its non-inline implementation:
        \begin{verbatim}
    #include "person.ih"

    std::string const &Person::name() const
    {
        return d_name;
    }
\end{verbatim}
Only the \texttt{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 compiler may \emph{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 \index{inline function}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
\emph{request} rather than a \emph{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.

Note that \texttt{constexpr} functions (cf. section \ref{GENCONST}) are implicitly
defined as inline functions.

\subsection{When to use inline functions}\label{WHENINLINE}
    \typeout{Original Yodl file: classes/when2use}When should \index{inline}inline functions be used, and when not? There are some
    \index{rule of thumb} rules of thumb which may be followed:
    \begin{itemize}
    \item  In general inline functions should \textbf{not} be used.
\emph{Voil\`{a}}; that's simple, isn't it?
    \item  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 \index{profiler}profiler, which
runs a program and determines where most of the time is spent, is necessary to
perform such optimizations.
    \item  Defining inline functions may be considered when they consist of
one very simple statement (such as the return statement in the function
\texttt{Person::name}).
    \item  When a function is defined inline, its implementation is inserted
in the code wherever the function is used. As a consequence, when the
\emph{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, which we call the \index{inline-inconsistency}inline-inconsistency.
    \item  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:
    \begin{verbatim}
inline void Person::printname() const
{
    cout << d_name << '\n';
}
\end{verbatim}
This function contains only one statement.  However, the statement takes a
relatively long time to execute. In general, functions which perform input and
output take lots of time. The effect of the conversion of this function
\texttt{printname()} to inline would therefore lead to an insignificant gain in
execution time.
    \end{itemize}
    All inline functions \index{inline: disadvantage} 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 \textbf{declaration} of a class,
but also part of its \textbf{implementation}, thus always blurring the distinction
between interface and implementation.

\subsubsection{A prelude: when NOT to use inline functions}\label{NOTINLINE}
       \typeout{Original Yodl file: classes/whennot2use}    \index{inline: avoid!}
As a prelude to chapter \ref{POLYMORPHISM} (Polymorphism), there is one
situation in which inline functions should definitely be avoided. At this
point in the \textbf{C++} Annotations it's a bit too early to expose the full details,
but since the keyword \texttt{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
        \index{vague linkage}\emph{vague linkage}
    \ \\ (cf.
\texttt{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 \ref{POLYMORPHISM}, when using polymorphism
the compiler must ignore the \texttt{inline} keyword and define so-called
\emph{virtual members} as true (\emph{out-of-line})
        \index{out-of-line functions}
    functions. In this situation the vague linkage may cause problems, as the
compiler must decide in what object files(s) to put their code. Usually that's
not a big problem as 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 \emph{never} be defined
inline, but they should always be defined \emph{out-of-line}. I.e., they should
be defined in source files.

\subsection{Inline variables}
    \typeout{Original Yodl file: classes/inlinevars}    In addition to inline functions, \index{variable: inline} 
inline variables can be defined (and identically initialized) in multiple
translation units. E.g., a header file could contain
        \begin{verbatim}
    inline int value = 15;                      // OK

    class Demo
    {
        // static int s_value = 15;             // ERROR
        static constexpr int s_value = 15;      // OK

        static int s_inline;                    // OK: see below: the inline 
                                                //   definition follows the 
                                                //   class declaration
    };
    inline int Demo::s_inline = 20;             // OK
\end{verbatim}
\section{Local classes: classes inside functions}\label{LOCAL}
\typeout{Original Yodl file: classes/local}Classes are usually defined at the global or namespace level. However, it is
entirely possible to define \index{class: local} a local class, i.e., inside a
function. Such classes are called \index{local class}\emph{local classes}.

Local classes can be very useful in advanced applications involving
inheritance or templates (cf. section \ref{NONDEFINIT}). At this point in the
\textbf{C++} Annotations they have limited use, although their main features can be
described. At the end of this section an example is provided.

\begin{itemize}
    \item  Local classes may use almost all characteristics of normal classes.
They may have constructors, destructors, data members, and member functions;
    \item  Local classes cannot define static data members. Static member
functions, however, \emph{can} be defined.
    \item  Since a local class may define static member functions, it is
possible to define \index{nested functions}\emph{nested functions} in \textbf{C++} somewhat comparable to the
way programming languages like \index{Pascal}\textbf{Pascal} allow nested functions to be
defined.
    \item  If a local class needs access to a constant integral value, a
local \emph{enum} can be used. The \texttt{enum} may be anonymous, exposing only the
\texttt{enum} values.
    \item  Local classes cannot directly access the non-static variables of their
surrounding context. For example, in the example shown below the class
\texttt{Local} cannot directly access \texttt{main}'s \texttt{argc} parameter.
    \item  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.
    \item  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.
    \item  As a prelude to \index{inheritance}\emph{inheritance} (chapter \ref{INHERITANCE}):
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 via a base class pointer or reference.
    \end{itemize}
    \begin{verbatim}
#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;
            }
            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.
}
\end{verbatim}
\section{The keyword `mutable'}\label{MUTABLE}
\typeout{Original Yodl file: classes/mutable}Earlier, in section \ref{ConstFunctions}, the concepts of const member
functions and const objects were introduced.

\textbf{C++} also allows the declaration of data members which may be modified,
even by const member function. Declarations of such data members start with
the keyword \index{mutable}\texttt{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 \texttt{mutable} is appropriately used is found in
the implementation of a string class. Consider the \texttt{std::string}'s \texttt{c\_str}
and \texttt{data} members. The actual data returned by the two members are
identical, but \texttt{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 \texttt{c\_str} is to ensure that the string's capacity exceeds its
length by at least one character. This invariant allows \texttt{c\_str} to be
implemented as follows:
        \begin{verbatim}
    char const *string::c_str() const
    {
        d_data[d_length] = 0;
        return d_data;
    }
\end{verbatim}
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 \texttt{d\_data} must be declared
\texttt{mutable}:
        \begin{verbatim}
    mutable char *d_data;
\end{verbatim}
The keyword \texttt{mutable} is also useful in classes implementing, e.g.,
reference counting. Consider a class implementing reference counting for
strings. The object doing the reference counting might 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 \texttt{mutable} keyword may profitably be used, as it can be
incremented and decremented, even though its object is a const object.

The keyword \texttt{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 \index{rule of thumb}rule of thumb: do not use \texttt{mutable}
unless there is a very clear reason (the object is logically not altered) for
violating this rule.

\section{Header file organization}\label{CLASSHEADER}
\typeout{Original Yodl file: classes/headers}In section \ref{CHeaders} the requirements for header files when a \textbf{C++}
program also uses \textbf{C} functions were discussed.
 \index{header file} 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.
Basically,  there are two approaches:
    \begin{itemize}
    \item  All required header files for a member function are included in each
individual source file.
    \item  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.
    \end{itemize}
    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 source files: it both takes time to type the
\texttt{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
\texttt{MyClass} could be organized according to the following example:
        \begin{verbatim}
    #include <myclass.h>

    int MyClass::aMemberFunction()
    {}
\end{verbatim}
There is only one \texttt{include}-directive. Note that the directive refers to
a header file in a directory mentioned in the \index{INCLUDE}\texttt{INCLUDE}-file environment
variable. Local header files (using \texttt{\#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 \texttt{File} and \texttt{String} are
used.

Assume the \texttt{File} class has a member \texttt{gets(String \&destination)}, while
the class \texttt{String} has a member function \texttt{getLine(File \&file)}. The
(partial) header file for the \texttt{class String} is then:
        \begin{verbatim}
    #ifndef STRING_H_
    #define STRING_H_

    #include <project/file.h>   // to know about a File

    class String
    {
        public:
            void getLine(File &file);
    };
    #endif
\end{verbatim}
Unfortunately a similar setup is required for the class \texttt{File}:
        \begin{verbatim}
    #ifndef FILE_H_
    #define FILE_H_

    #include <project/string.h>   // to know about a String

    class File
    {
        public:
            void gets(String &string);
    };
    #endif
\end{verbatim}
Now we have created a problem. The compiler, trying to compile the source
file of the function \texttt{File::gets} proceeds as follows:
    \begin{itemize}
    \item  The header file \texttt{project/file.h} is opened to be read;
    \item  \texttt{FILE\_H\_} is defined
    \item  The header file \texttt{project/string.h} is opened to be read
    \item  \texttt{STRING\_H\_} is defined
    \item  The header file \texttt{project/file.h} is (again) opened to be read
    \item  Apparently, \texttt{FILE\_H\_} is already defined, so the remainder of
            \texttt{project/file.h} is skipped.
    \item  The interface of the class \texttt{String} is now parsed.
    \item  In the class interface a reference to a \texttt{File} object is
            encountered.
    \item  As the \texttt{class File} hasn't been parsed yet, a \texttt{File} is still
        an undefined type, and the compiler quits with an error.
    \end{itemize}
    The solution to this problem is to use a
 \index{forward class reference}\emph{forward class reference} \emph{before} the class interface, and to include
the corresponding class header file \emph{beyond} the class interface. So we get:
        \begin{verbatim}
    #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
\end{verbatim}
A similar setup is required for the class \texttt{File}:
        \begin{verbatim}
    #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
\end{verbatim}
This works well in all situations where either references or pointers to
other classes are involved and with (non-inline) member functions having
    \index{class-type return values}class-type return values or \index{class-type parameters} parameters.

This setup doesn't work with \index{composition}composition, nor with in-class inline
member functions. Assume the class \texttt{File} has a \emph{composed} data member of
the class \texttt{String}. In that case, the class interface of the class \texttt{File}
\emph{must} include the header file of the class \texttt{String} before the class
interface itself, because otherwise the compiler can't tell how big a \texttt{File}
object is. A \texttt{File} object contains a \texttt{String} member, but the compiler
can't determine the size of that \texttt{String} data member and thus, by
implication, it can't determine the size of a \texttt{File} object.

In cases where classes contain composed objects (or are derived from other
classes, see chapter \ref{INHERITANCE}) the header files of the classes of the
composed objects must have been read \emph{before} the class interface itself.
In such a case the \texttt{class File} might be defined as follows:
        \begin{verbatim}
    #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
\end{verbatim}
The class \texttt{String} can't declare a \texttt{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:
    \begin{itemize}
    \item  Header files defining a class interface should \emph{declare} what can
be declared before defining the class interface itself. So, classes that are
mentioned in a class interface  should be specified using
 \index{forward declaration} forward declarations \emph{unless}
        \begin{itemize}
        \item  They are a \emph{base class} of the current class (see chapter
\ref{INHERITANCE});
        \item  They are the class types of composed data members;
        \item  They are used in inline member functions.
        \end{itemize}
    In particular: additional actual header files are \emph{not} required for:
        \begin{itemize}
            \item  class-type return values of functions;
            \item  class-type value parameters of functions.
        \end{itemize}
    Class header files  of objects that are either composed or inherited
or that are used in inline functions, \emph{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 \texttt{\#ifndef ... \#endif} construction introduced
in section \ref{CHeaders}.
    \item  Program sources in which the class is used only need to include this
header file. \index{Lakos, J.} \emph{Lakos}, (2001) refines this process even
further. See his book \textbf{Large-Scale \textbf{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 \index{INCLUDE}\texttt{INCLUDE} path.
    \item  To implement member functions the class's header file is required
and usually additional header files (like the \texttt{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
\texttt{.ih} \index{.ih extension} (`\index{internal header}internal header') is suggested).

The \texttt{.ih} file should be defined in the same directory as the source
files of the class. It has the following characteristics:
        \begin{itemize}
        \item  There is \emph{no} need for a protective \texttt{\#ifndef} .. \texttt{\#endif}
shield, as the header file is never included by other header files.
        \item  The standard \texttt{.h} header file defining the class interface
is included.
        \item  The header files of all classes used  as forward references in
the standard \texttt{.h} header file are included.
        \item  Finally, all other header files that are required in the source
files of the class are included.
        \end{itemize}
    An example of such a header file organization is:
        \begin{itemize}
        \item  First part, e.g., \texttt{/usr/local/include/myheaders/file.h}:
    \begin{verbatim}
#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
\end{verbatim}
\item  Second part, e.g., \texttt{\textasciitilde{}/myproject/file/file.ih}, where all
sources of the class File are stored:
    \begin{verbatim}
#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.
\end{verbatim}
\end{itemize}
    \end{itemize}

\subsection{Using namespaces in header files}\label{NAMESPACEHDR}
    \typeout{Original Yodl file: classes/namespaces}When entities from \index{namespace} namespaces are used in \index{header file} header
files, no \index{using}\texttt{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 \index{library}library. When the \texttt{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 \texttt{special} an object \texttt{Inserter cout} is
declared, then \texttt{special::cout} is of course a different object than
\texttt{std::cout}. Now, if a class \texttt{Flaw} is constructed, in which the
constructor expects a reference to a \texttt{special::Inserter}, then the class
should be constructed as follows:
        \begin{verbatim}
    class special::Inserter;

    class Flaw
    {
        public:
            Flaw(special::Inserter &ins);
    };
\end{verbatim}
Now the person designing the class \texttt{Flaw} may be in a lazy mood, and
might get bored by continuously having to prefix \texttt{special::} before every
entity from that namespace. So, the following construction is used:
        \begin{verbatim}
    using namespace special;

    class Inserter;
    class Flaw
    {
        public:
            Flaw(Inserter &ins);
    };
\end{verbatim}
This works fine, up to the point where somebody wants to include
\texttt{flaw.h} in other source files: because of the \texttt{using} directive, this
latter person is now by implication also \texttt{using namespace special}, which
could produce unwanted or unexpected effects:
        \begin{verbatim}
    #include <flaw.h>
    #include <iostream>

    using std::cout;

    int main()
    {
        cout << "starting\n";       // won't compile
    }
\end{verbatim}
The compiler is confronted with two interpretations for \texttt{cout}: first,
because of the \texttt{using} directive in the \texttt{flaw.h} header file, it considers
\texttt{cout} a \texttt{special::Inserter}, then, because of the \texttt{using} directive in
the user program, it considers \texttt{cout} a \texttt{std::ostream}. Consequently,
the compiler reports an error.

As a \index{rule of thumb}rule of thumb, header files intended for general use
should not contain \texttt{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 \texttt{using} declarations as desired, as
these directives never reach other sources.

\section{Sizeof applied to class data members}
\typeout{Original Yodl file: classes/sizeof}In \textbf{C++} the well-known \index{sizeof}\texttt{sizeof} operator can be applied to data
members of classes without the need to specify an object as well. Consider:
        \begin{verbatim}
    class Data
    {
        std::string d_name;
        ...
    };
\end{verbatim}
To obtain the size of \texttt{Data}'s \texttt{d\_name} member the following
expression can be used:
        \begin{verbatim}
    sizeof(Data::d_name);
\end{verbatim}
Note, however, that the compiler observes data protection here as well. It's
only possible to use \texttt{sizeof(Data::d\_name)} when \texttt{d\_name} is visible,
i.e., it can be used by \texttt{Data}'s member functions and friends.


\cleardoublepage\chapter{Static Data And Functions}\label{StaticDataFun}
\typeout{Original Yodl file: static}\typeout{Original Yodl file: static/intro}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
    \index{common data fields}\emph{common data fields}, that may be accessed by \emph{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 \textbf{C}, where several functions need to
access the same variable. A common solution in \textbf{C} is to define all these
functions in one source file and to define the variable \index{static}\texttt{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 \textbf{C}-solution is to give the variable in question an
unusual name, e.g., \texttt{\_6uldv8}, hoping that other program parts won't use
this name by accident. Neither the first, nor the second legacy \textbf{C} solution
is elegant.

\textbf{C++} solves the problem by defining \index{static members}\texttt{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 \index{virtual: vs static} virtual
functions. A virtual member function is an ordinary member in that it has a
\index{this}\texttt{this} pointer. As static member functions have no \texttt{this} pointer, they
cannot be declared virtual.

\section{Static data}\label{StaticData}
    \typeout{Original Yodl file: static/data}Any data member of a class can be declared \texttt{static}; be it in the \texttt{public}
or \texttt{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.

\index{static: data members} 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 \texttt{s\_} so they may
easily be distinguished (in class member functions) from the class's data
members (which should preferably start with \texttt{d\_}).

Public static data members are \index{global variable}global variables. They may
be accessed by \emph{all of the program's code}, simply by using their class
names, the scope resolution operator and their member names. Example:
        \begin{verbatim}
    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
    }
\end{verbatim}
The example does not present an executable program.  It merely illustrates
the \emph{interface}, and not the \emph{implementation} of \texttt{static} data members,
which is discussed next.

\subsection{Private static data}
        \typeout{Original Yodl file: static/private}To illustrate the use of a static data member which is a private
variable in a class, consider the following:
        \begin{verbatim}
    class Directory
    {
        static char s_path[];

        public:
            // constructors, destructors, etc.
    };
\end{verbatim}
The data member \texttt{s\_path{[}{]}} is a private static data member. During
the program's execution only \emph{one} \texttt{Directory::s\_path{[}{]}} exists,
even though multiple objects of the class \texttt{Directory} may exist. This
data member could be inspected or altered by the constructor, destructor or by
any other member function of the class \texttt{Directory}.

Since constructors are called for each new object of a class, static
data members \index{initialization: static data member}
    \index{static data members: initialization} are not \emph{initialized} by
constructors. At most they are \emph{modified}. The reason for this is that
static data members exist \emph{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 \texttt{data.cc}.

The data member \texttt{s\_path{[}{]}}, used above, could thus be
defined and initialized as follows in a file \texttt{data.cc}:
        \begin{verbatim}
    #include "directory.ih"

    char Directory::s_path[200] = "/usr/local";
\end{verbatim}
In the class interface the static member is actually only \emph{declared}. In
its implementation (definition) its type and class name are explicitly
mentioned. Note also that the \index{size specification}size specification can be left out of the
interface, as shown above. However, its size \emph{is} (either explicitly or
implicitly) required when it is defined.

Note that \emph{any} source file could contain the definition of the static
data members of a class. A separate \texttt{data.cc} source file is advised, but
the source file containing, e.g., \texttt{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 \texttt{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 \texttt{static} flag variable
\texttt{s\_nobjects}. The variable \texttt{s\_nobjects} simply counts the number of
\texttt{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
\texttt{Graphics} object ceases to exist.  The class interface for this
\texttt{Graphics} class might be:
        \begin{verbatim}
    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
    };
\end{verbatim}
The purpose of the variable \texttt{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
\texttt{Graphics} object, the switch from graphics mode to text mode is made:
        \begin{verbatim}
    int Graphics::s_nobjects = 0;           // the static data member

    Graphics::Graphics()
    {
        if (!s_nobjects++)
            setgraphicsmode();
    }

    Graphics::~Graphics()
    {
        if (!--s_nobjects)
            settextmode();
    }
\end{verbatim}
Obviously, when the class \texttt{Graphics} would define more than one
constructor, each constructor would need to increase the variable
\texttt{s\_nobjects} and would possibly have to initialize the graphics mode.

\subsection{Public static data}
        \typeout{Original Yodl file: static/public}Data members could also be declared in the \index{public}public section of a class. This,
however, is deprecated (as it violates the principle of \index{data hiding}data hiding).  The
static data member \texttt{s\_path{[}{]}} (cf.  section \ref{StaticData}) could be
declared in the public section of the class definition. This would allow all
the program's code to access this variable directly:
        \begin{verbatim}
    int main()
    {
        getcwd(Directory::s_path, 199);
    }
\end{verbatim}
A declaration is not a definition. Consequently the variable \texttt{s\_path}
still has to be defined.  This implies that some source file still needs to
contain \texttt{s\_path{[}{]}} array's definition.

\subsection{Initializing static const data}
        \typeout{Original Yodl file: static/const}Static \texttt{const} \index{static data: const} data members should be initialized
like other static data members: 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 data
members. 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 \texttt{-O2} may result in a successful compilation, but
        \index{-O0}\texttt{-O0}\index{O0}\index{noopt}
    (no-optimizations) may fail to compile, but then maybe only when shared
libraries are used...).

In-class initializations of integer constant values (e.g., of types \texttt{char,
int, long}, etc, maybe \texttt{unsigned}) is nevertheless possible using (e.g.,
anonymous) enums.  The following example illustrates how this can be done:
        \begin{verbatim}
    class X
    {
        public:
            enum         { s_x = 34 };
            enum: size_t { s_maxWidth = 100 };
    };
\end{verbatim}
To avoid confusion caused by different compiler options static data members
should always explicitly be defined and initialized in a (single) source file,
whether or not they are \texttt{const} data. Additionally, by defining them in a
source file you avoid the inline-inconsistency.

\subsection{Generalized constant expressions (constexpr)}\label{GENCONST}
        \typeout{Original Yodl file: static/genconst}In \textbf{C} macros are often used to let the preprocessor perform simple
calculations. These \index{macro} \emph{macro functions} may have arguments,
as illustrated in the next example:
        \begin{verbatim}
    #define xabs(x) ((x) < 0 ? -(x) : (x))
\end{verbatim}
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
\index{preprocessor}preprocessor resulting in mere text replacements and thus avoid type-safety
or syntactic checks of the macro definition by itself. Furthermore, since
macros are processed by the preprocessor their use is unconditional, without
acknowledging the context in which they are applied. \index{NULL}\texttt{NULL} is an infamous
example. Ever tried to define an \texttt{enum} symbol \texttt{NULL}? or \texttt{EOF}? Chances
are that, if you did, the compiler threw strange error messages at you.

Generalized \index{const: generalized expression}
            \index{generalized const expression}
    const expressions can be used as an alternative.

Generalized const expressions are recognized by the modifier \index{constexpr}\texttt{constexpr} (a
keyword), that is applied to the expression's type.

There is a small syntactic difference between the use of the \texttt{const}
modifier and the use of the \texttt{constexpr} modifier.  While the \texttt{const}
modifier can be applied to definitions and declarations alike, the
\texttt{constexpr} modifier can only be applied to definitions:
        \begin{verbatim}
    extern int const externInt;     // OK: declaration of const int
    extern constexpr int error;     // ERROR: not a definition
\end{verbatim}
Variables defined with the \texttt{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 \texttt{constexpr} keyword is
usually applied to functions, turning the function into a
    \index{function: constant-expression}
    \index{constant-expression function}\emph{constant-expression function}.

A constant-expression function should not be confused with a function
returning a \texttt{const} value (although a constant-expression function \emph{does}
return a (const) value).  A constant expression function has the
following characteristics:
    \begin{itemize}
    \item  it returns a value;
    \item  its return type is given the \texttt{constexpr} modifier;
    \end{itemize}
    Such functions are also called
        \index{named constant expression}
        \emph{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
\texttt{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 \texttt{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 one-dimensional array must have \texttt{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 \texttt{nrows} and
\texttt{ncols} have been defined as globally available \texttt{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.

Now that constant-expression functions are available the expression returning
the number of the required elements can be encapsulated in such a function:
        \begin{verbatim}
    size_t const nRows = 45;
    size_t const nCols = 10;

    constexpr size_t 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) ];
    };
\end{verbatim}
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.,
        \begin{verbatim}
    string stringLinear[ nElements(10, 4) ];
\end{verbatim}
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 \texttt{nElements}:
        \begin{verbatim}
    constexpr size_t halfNElements(size_t rows, size_t cols)
    {
        return (nElements(rows, cols) + 1) >> 1;
    }
\end{verbatim}
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 \texttt{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:
        \begin{verbatim}
    class Data
    {
        static size_t const s_size = 7;

        public:
            static constexpr size_t size();
            constexpr size_t mSize();
    };

    constexpr size_t Data::size()
    {
        return s_size;
    }

    constexpr size_t Data::mSize()
    {
        return size();
    }

    double data[ Data::size() ];        // OK: 7 elements
    short data2[ Data().mSize() ];      // also OK: see below
\end{verbatim}
Please note the following:
    \begin{itemize}
    \item  Constant-expression functions are implicitly declared inline. As an
        illustration: the file \texttt{sum.h} declares a \texttt{constexpr}
        function: \texttt{constexpr int sum(int x, int y);} It's used by  \texttt{main}:
        \begin{verbatim}
    #include <iostream>
    #include "sum.h"
    
    int main()
    {
        std::cout << "sum: " << sum(21, 21) << '\n';
    }
\end{verbatim}
        When this file (\texttt{main.cc}) is compiled the compiler reports:
       \begin{quote}sum.h:1:15: warning: inline function 
            `\texttt{constexpr int sum(int, int)}' used but never defined.\end{quote}
       Here the compiler explicitly states that \texttt{sum} is an inline
        function. Moreover, even if \texttt{sum.cc} \emph{defines} \texttt{sum} and
        \texttt{main.o} and \texttt{sum.o} are linked the linker reports:
       \begin{quote}undefined reference to `\texttt{sum(int, int)}'.\end{quote} 
       Consequently, the definitions of \texttt{constexpr} functions must
        compile-time be available which in practice means that they're
        \emph{defined} in (class) header files;
    \item  Non-static constant-expression member functions are implicitly
        \texttt{const}, and a \texttt{const} member modifier for them is optional;
    \item  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 \texttt{s\_size} was
        initialized in \texttt{Data}'s class interface.
    \end{itemize}

Some final notes: \texttt{constexpr} functions may
    \begin{itemize}
    \item  define any kind of variable except for 
        \texttt{static} or \texttt{thread\_local} variables;
    \item  define variables  without initializers;
    \item  use  conditional statements (\texttt{if} and \texttt{switch});
    \item  use repetition statements, including the range-based \texttt{for}
        statement;
    \item  use expressions changing the values of objects that are local to
        the \texttt{constexpr} function;
    \item  \texttt{constexpr} member functions can be non-const.  But 
        non-const \texttt{constexpr} member functions can only modify data members
        of objects that were defined local to the \texttt{constexpr} function
        calling the non-const \texttt{constexpr} member function.
    \end{itemize}

\subsubsection{Constant expression data}\label{CONSTEXPR}
            \typeout{Original Yodl file: static/constexprdata}As we've seen, (member) functions and variables of primitive data types can be
defined using the \texttt{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 \texttt{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 \texttt{constexpr} modifier. Note again that the \texttt{constexpr}
constructor's definition must have been seen by the compiler before the
\texttt{constexpr} object can be constructed:
        \begin{verbatim}
    class ConstExpr
    {
        public:
            constexpr ConstExpr(int x);
    };

    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
\end{verbatim}
A \index{constant-expression constructor}constant-expression constructor has the following characteristics:
    \begin{itemize}
    \item  it is declared with the \texttt{constexpr} modifier;
    \item  its member initializers only use constant expressions;
    \item  its body is empty.
    \end{itemize}

An object constructed with a constant-expression constructor is called a
        \index{user-defined literal}\emph{user-defined literal}.
    Destructors and copy constructors of user-defined literals must be
trivial.

The \texttt{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
\texttt{constexpr} return value, then using that member does not result in a
constant-expression. If a member \emph{does} declare a \texttt{constexpr} return value
then that member's return value is considered a \texttt{constexpr} if it is by
itself a constant expression function. To maintain its \texttt{constexpr}
characteristics it can refer to its classes' data members \emph{only} if its
object has been defined with the \texttt{constexpr} modifier, as illustrated by the
example:
        \begin{verbatim}
    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 {
        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
\end{verbatim}
\section{Static member functions}
    \typeout{Original Yodl file: static/function}In addition to static data members, \textbf{C++} allows us to define
    \index{static member functions}\emph{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 \index{static member functions} can access all static
members of their class, but \emph{also} the members (\texttt{private} or \texttt{public})
of objects of their class \emph{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
\index{this}\texttt{this} pointer. In fact, a static member function is completely comparable
to a \index{global function}global function, not associated with any class (i.e., in practice they
are. See the next section (\ref{CALLINGCONVENTION}) 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:
        \begin{verbatim}
    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()
    {
        Directory dir;

        Directory::setpath("/etc");                 // 4
        dir.setpath("/etc");                        // 5

        Directory::preset(dir, "/usr/local/bin");   // 6
        dir.preset(dir, "/usr/local/bin");          // 7
    }
\end{verbatim}
\begin{itemize}
    \item  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 \index{static inline member functions}
    static member functions can be defined as inline
 \index{inline: static members} functions.
    \item  at 2 a relatively long array is defined to be able to accommodate
long paths. Alternatively, a \texttt{string} or a pointer to dynamic memory could
be used.
    \item  at 3 a (possibly longer, but not too long) new pathname is stored in
the static data member \texttt{s\_path{[}{]}}. Note that only static members are used.
    \item  at 4, \texttt{setpath()} is called. It is a static member, so no
object is required. But the compiler must know to which class the function
belongs, so the class is mentioned using the scope resolution operator.
    \item  at 5, the same is implemented as in 4. Here \texttt{dir} is used to tell
the compiler that we're talking about a function in the \texttt{Directory}
class. Static member functions \emph{can} be called as normal member
functions, but this does not imply that the static member function receives
the object's address as a \texttt{this} pointer. Here the member-call syntax is
used as an alternative for the classname plus scope resolution operator
syntax.
    \item  at 6, \texttt{currentPath} is altered. As in 4, the class and the scope
resolution operator are used.
    \item  at 7, the same is implemented as in 6. But here \texttt{dir} is used to
tell the compiler that we're talking about a function in the \texttt{Directory}
class. Here in particular note that this is \emph{not} using \texttt{preset()} as an
ordinary member function of \texttt{dir}: the function still has no
\index{this}\texttt{this}-pointer, so \texttt{dir} must be passed as argument to inform the static
member function \texttt{preset} about the object whose \texttt{currentPath} member it
should modify.
    \end{itemize}

In the example only public static member functions were used.  \textbf{C++}
also allows the definition of private static member functions. Such functions
can only be called by member functions of their class.

\subsection{Calling conventions}\label{CALLINGCONVENTION}
        \typeout{Original Yodl file: static/calling}    As noted in the previous section, static (public) member functions are
comparable to classless functions. However, formally this statement is not
true, as the \textbf{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
    \index{pointer: to function} pointers to (global) functions.

If unpleasant surprises must be avoided at all cost, it is suggested to
create global classless \index{wrapper functions}\emph{wrapper functions} around static member functions
that must be used as \index{call back}\emph{call back} functions for other functions.

Recognizing that the traditional situations in which call back functions
are used in \textbf{C} are tackled in \textbf{C++} using template algorithms
(cf. chapter \ref{GENERIC}), let's assume that we have a class \texttt{Person}
having data members representing the person's name, address, phone and
mass. Furthermore, assume we want to sort an array of pointers to \texttt{Person}
objects, by comparing the \texttt{Person} objects these pointers point to. Keeping
things simple, we assume that the following public static member exists:
        \begin{verbatim}
    int Person::compare(Person const *const *p1, Person const *const *p2);
\end{verbatim}
A useful characteristic of this member is that it may directly inspect the
required data members of the two \texttt{Person} objects passed to the member
function using pointers to pointers (\index{double pointers}double pointers).

Most compilers allow us to pass this function's address as the address of
the comparison function for the standard \textbf{C} \index{qsort()}\texttt{qsort()} function. E.g.,
        \begin{verbatim}
    qsort
    (
        personArray, nPersons, sizeof(Person *),
        reinterpret_cast<int(*)(void const *, void const *)>(Person::compare)
    );
\end{verbatim}
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:
        \begin{verbatim}
    int compareWrapper(void const *p1, void const *p2)
    {
        return
            Person::compare
            (
                static_cast<Person const *const *>(p1),
                static_cast<Person const *const *>(p2)
            );
    }
\end{verbatim}
resulting in the following call of the \texttt{qsort()} function:
        \begin{verbatim}
    qsort(personArray, nPersons, sizeof(Person *), compareWrapper);
\end{verbatim}
Note:
    \begin{itemize}
    \item  The wrapper function takes care of any mismatch in the calling
conventions of static member functions and classless functions;
    \item  The wrapper function handles the required type casts;
    \item  The wrapper function might perform small additional services (like
dereferencing pointers if the static member function expects references to
\texttt{Person} objects rather than double pointers);
    \item  As an aside: in \textbf{C++} programs functions like \texttt{qsort()},
requiring the specification of call back functions are seldom used. Instead
using existing generic template algorithms is preferred (cf. chapter
\ref{GENERIC}).
    \end{itemize}


\cleardoublepage\chapter{Classes And Memory Allocation}\label{MEMORY}
\typeout{Original Yodl file: memory}\typeout{Original Yodl file: memory/intro}In contrast to the set of functions that handle \index{memory allocation}memory allocation in \textbf{C}
(i.e., \index{malloc}\texttt{malloc} etc.), memory allocation in \textbf{C++} is handled by
the operators \index{new}\texttt{new} and \index{delete}\texttt{delete}.
Important differences between \texttt{malloc} and \texttt{new} are:
    \begin{itemize}
    \item  The function \texttt{malloc} doesn't `know' what the allocated memory
will be used for. E.g., when memory for \texttt{int}s is allocated, the programmer
must supply the correct expression using a multiplication by
\texttt{sizeof(int)}. In contrast, \texttt{new} requires a type to be specified; the
\index{sizeof}\texttt{sizeof} expression is implicitly handled by the compiler. Using \texttt{new} is
therefore \index{type safe}\emph{type safe}.
    \item  Memory allocated by \texttt{malloc} is initialized by \index{calloc}\texttt{calloc},
initializing the allocated characters to a configurable initial value.  This
is not very useful when objects are available. As operator \texttt{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.
    \item  All \textbf{C}-allocation functions must be inspected for
\index{NULL}\texttt{NULL}-returns. This is not required anymore when \texttt{new} is used. In fact,
\texttt{new}'s behavior when confronted with failing memory allocation is
configurable through the use of a \emph{new\_handler} (cf. section
\ref{NEWHANDLER}).
    \end{itemize}
    A comparable relationship exists between \index{free}\texttt{free} and \texttt{delete}:
\texttt{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 \textbf{C} program development are caused by incorrect
memory allocation or \index{memory leak}memory leaks: memory is not allocated, not
freed, not initialized, boundaries are overwritten, etc..  \textbf{C++} does not
`magically' solve these problems, but it \emph{does} provide us with tools to
prevent these kinds of problems.

As a consequence of \texttt{malloc} and friends becoming deprecated
the very frequently used \index{str...}\texttt{str...} functions, like
\index{strdup}\texttt{strdup}, that are all \texttt{malloc} based, should be avoided in
\textbf{C++} programs. Instead, the facilities of the \texttt{string} class and
operators \texttt{new} and \texttt{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 \texttt{new} and
\texttt{delete}. We'll first cover the peculiarities of operators \texttt{new} and
\texttt{delete}, followed by a discussion about:
    \begin{itemize}
    \item  the destructor: the member function that's called when an object
ceases to exist;
    \item  the assignment operator, allowing us to assign an object to another
object of its own class;
    \item  the \texttt{this} pointer, allowing explicit references to the object for
which a member function was called;
    \item  the copy constructor: the constructor creating a copy of an object;
    \item  the move constructor: a constructor creating an object from
an anonymous temporary object.
    \end{itemize}

\section{Operators `new' and `delete'}
\typeout{Original Yodl file: memory/new}\textbf{C++} defines two operators to allocate memory and to return it to the
`\index{common pool}common pool'. These operators are, respectively, \index{new}\texttt{new} and \index{delete}\texttt{delete}.

Here is a simple example illustrating their use. An \texttt{int} pointer variable
points to memory allocated by operator \texttt{new}. This memory is later released
by operator \texttt{delete}.
        \begin{verbatim}
    int *ip = new int;
    delete ip;
\end{verbatim}
Here are some characteristics of operators \texttt{new} and \texttt{delete}:
    \begin{itemize}
    \item  \texttt{new} and \texttt{delete} are \emph{operators} and therefore do not
require parentheses, as required for \emph{functions} like \texttt{malloc} and
\texttt{free};
    \item  \texttt{new} returns a pointer to the kind of memory that's asked for by
its operand (e.g., it returns a pointer to an \texttt{int});
    \item  \texttt{new} uses a \emph{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;
    \item  as a consequence, \texttt{new} is a \index{type safe}type safe operator as it always
returns a pointer to the type that was mentioned as its operand. In addition,
the type of the receiving pointer
must match the type specified with operator \texttt{new};
    \item  \texttt{new} may fail, but this is normally of \emph{no} concern to the
programmer. In particular, the program does \emph{not} have to test the success
of the memory allocation, as is required for \texttt{malloc} and
friends. Section \ref{NEWHANDLER} delves into this aspect of \texttt{new};
    \item  \texttt{delete} returns \texttt{void};
    \item  for each call to \texttt{new} a matching \texttt{delete} should eventually be
executed, lest a \index{memory leak}memory leak occurs;
    \item  \texttt{delete} can safely operate on a \index{0-pointer}0-pointer (doing nothing);
    \item  otherwise \texttt{delete} must only be used to return memory allocated
by \texttt{new}. It should \emph{not} be used to return memory allocated by
\texttt{malloc} and friends.
    \item  in \textbf{C++} \index{malloc}\texttt{malloc} and friends are \emph{deprecated} and should be
avoided.
    \end{itemize}

Operator \texttt{new} can be used to \index{allocate primitive types}allocate primitive types but also to
 \index{object: allocation}\index{allocate objects}allocate objects. When a primitive type
or a \texttt{struct} type without a constructor is allocated the allocated
memory is \emph{not} guaranteed to be initialized to 0, but an
\index{initialization}initialization expression may be provided:
        \begin{verbatim}
    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
\end{verbatim}
When a class-type object is allocated, the arguments of its constructor
(if any) are specified immediately following the type specification in the
\texttt{new} expression and the object is initialized by to the thus specified
constructor. For example, to allocate \texttt{string} objects the following
statements could be used:
        \begin{verbatim}
    string *s1 = new string;            // uses the default constructor
    string *s2 = new string{};          // same
    string *s3 = new string(4, ' ');    // initializes to 4 blanks.
\end{verbatim}
In addition to using \texttt{new} to allocate memory for a single entity or an
array of entities (see the next section) there also exists a variant
allocating \index{raw memory}\emph{raw memory}:
 \index{operator new(sizeInBytes)}\texttt{operator new(sizeInBytes)}. Raw memory is returned as a \texttt{void $*$}. Here
\texttt{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 \texttt{new} is returned as a
\texttt{void $*$} its return value can be assigned to a \texttt{void $*$} variable. More
often it is assigned to a \texttt{char $*$} variable, using a cast. Here is an
example:
        \begin{verbatim}
    char *chPtr = static_cast<char *>(operator new(numberOfBytes));
\end{verbatim}
The use of raw memory is frequently encountered in combination with the
\emph{placement new} operator, discussed in section \ref{PLACEMENT}.

\subsection{Allocating arrays}\label{NEWARRAY}
    \typeout{Original Yodl file: memory/newarray}Operator \index{new[]}\texttt{new{[}{]}} is used to \index{allocate arrays}allocate arrays. The generic notation
\texttt{new{[}{]}} is used in the \textbf{C++} Annotations. Actually, the number of elements to be
allocated must be specified between the square brackets and it must, in turn,
be \emph{prefixed} by the type of the entities that must be allocated. Example:
        \begin{verbatim}
    int *intarr = new int[20];          // allocates 20 ints
    string *stringarr = new string[10]; // allocates 10 strings.
\end{verbatim}
Operator \texttt{new} is a different operator than operator \texttt{new{[}{]}}. A
consequence of this difference is discussed in the next section
(\ref{DELETEARRAY}).

Arrays allocated by operator \texttt{new{[}{]}} are called
 \index{array: dynamic}\index{dynamic arrays}\emph{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 \texttt{new{[}{]}} is used to allocate an array of primitive values or an
array of objects, \texttt{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 \texttt{new{[}{]}} is used the array's elements are stored
consecutively in memory. An array index expression may thereafter be used to
access the array's individual elements: \texttt{intarr{[}0{]}} represents the first
\texttt{int} value, immediately followed by \texttt{intarr{[}1{]}}, and so on until the last
element (\texttt{intarr{[}19{]}}).

\index{memory: initialization}With non-class types (primitive types, POD
types without constructors) the block of memory returned by operator \texttt{new{[}{]}}
is \emph{not} guaranteed to be initialized to 0. Alternatively, adding \texttt{()} to
the \texttt{new} expression \emph{will} initialize the block of memory to
zeroes. E.g.,
        \begin{verbatim}
    struct POD
    {
        int iVal;
        double dVal;
    };
    new POD[5]();       // returns a pointer to 5 0-initialized PODs
    new double[9]();    // returns a pointer to 9 0-initialized doubles
\end{verbatim}
In addition to using \texttt{new Type{[}size{]}()}, the array's size can also be
inferred by the compiler by specifying comma-separated initialization values
between the parentheses, like \texttt{new int{[}{]}(1, 2, 3)}. This allocates an array
of three \texttt{ints} which are initialized to, respectively, the values 1, 2 and
3. Specifying a larger value between the square brackets is also possible. In
that case the first values are initialized as specified, the remaining values
are initialized to zeroes (or by the objects' default constructors). Instead
of using parentheses curly braces can also be used.

If there are members of the \texttt{struct POD} that are explicitly initialized
in the struct's interface (e.g., \texttt{int iVal = 12}), or if the struct uses
composition, and the composed data member's type defines a default
constructor, then initializations in the struct's interface and
initializations performed by the composed data member's constructor takes
precedence over the 0-initialization. Here is an example:
        \begin{verbatim}
    struct Data
    {
        int value = 100;
    };
    struct POD
    {
        int iVal = 12;
        double dVal;
        Data data;
    };

    POD *pp = new POD[5]();
\end{verbatim}
Here, \texttt{pp} points to five \texttt{POD} objects, each having their \texttt{iVal}
data members initialized to 12, their \texttt{dVal} data members initialized to 0,
and their \texttt{data.value} members initialized to 100.

When operator \texttt{new{[}{]}} is used to allocate arrays of objects of class
types defining default constructors these constructors are automatically
used. Consequently \texttt{new string{[}20{]}} results in a block of 20 \emph{initialized}
\texttt{string} objects. A non-default constructor cannot be called, but often it
is possible to work around that (as discussed in section \ref{NONDEFINIT}).

The expression between brackets of operator \texttt{new{[}{]}} represents the
number of elements of the array to allocate. The \textbf{C++} standard allows
allocation of \index{array: 0-sized} 0-sized arrays. The statement
 \index{new Type[0]}\texttt{new int{[}0{]}} is correct \textbf{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 \texttt{if (ptr) ...}

Without using operator \texttt{new{[}{]}}, arrays of variable sizes can also be
constructed as
 \index{array: local}\index{local arrays}\emph{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 \index{array: fixed size} have fixed sizes. There is no
\emph{simple} way to enlarge or shrink arrays. \textbf{C++} has no operator
`\index{renew}\texttt{renew}'. Section \ref{ENLARGEARRAY} illustrates how to \index{array: enlarge}
enlarge arrays.

\subsection{Deleting arrays}\label{DELETEARRAY}
    \typeout{Original Yodl file: memory/deletearray}Dynamically allocated arrays are deleted using operator
 \index{delete[]}\texttt{delete{[}{]}}. It expects a pointer to a block of memory, previously allocated
by operator \index{new[]}\texttt{new{[}{]}}.

When operator \texttt{delete{[}{]}}'s operand is a pointer to an array of objects
two actions are performed:
    \begin{itemize}
    \item  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.
    \item  Second, the memory pointed at by the pointer is returned to the
common pool.
    \end{itemize}
    Here is an example showing how to allocate and delete an array of 10
string objects:
        \begin{verbatim}
    std::string *sp = new std::string[10];
    delete[] sp;
\end{verbatim}
No special action is performed if a dynamically allocated array of
primitive typed values is deleted. Following \texttt{int $*$it = new int{[}10{]}} the
statement \texttt{delete{[}{]} it} simply returns the memory pointed at by \texttt{it}.
Realize that, as a pointer is a primitive type, deleting a dynamically
allocated array of pointers to objects does \emph{not} result in the proper
destruction of the objects the array's elements point at. So, the following
example results in a \index{memory leak}\emph{memory leak}:
        \begin{verbatim}
    string **sp = new string *[5];
    for (size_t idx = 0; idx != 5; ++idx)
        sp[idx] = new string;
    delete[] sp;            // MEMORY LEAK !
\end{verbatim}
In this example the only action performed by \texttt{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 \emph{should} be performed:
    \begin{itemize}
    \item  Call \texttt{delete} for each of the array's elements;
    \item  Delete the array itself
    \end{itemize}
    Example:
        \begin{verbatim}
    for (size_t idx = 0; idx != 5; ++idx)
        delete sp[idx];
    delete[] sp;
\end{verbatim}
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 \texttt{delete{[}{]}} is a different operator than operator
\texttt{delete}. The \index{rule of thumb}rule of thumb is: if \index{new[]}\texttt{new{[}{]}} was used, also use
\texttt{delete{[}{]}}.

\subsection{Enlarging arrays}\label{ENLARGEARRAY}
    \typeout{Original Yodl file: memory/enlargearray}Once allocated, all arrays have fixed \index{array: fixed size} sizes.
There is no simple way to enlarge or shrink arrays. \textbf{C++} has no
 \index{renew}\texttt{renew} operator. The basic steps to take when enlarging an array are the
following:
    \begin{itemize}
    \item  Allocate a new block of memory of larger size;
    \item  Copy the old array content to the new array;
    \item  Delete the old array;
    \item  Let the pointer to the array point to the newly allocated array.
    \end{itemize}
    Static and local arrays cannot be resized. Resizing is only possible for
dynamically allocated arrays. Example:
    \begin{verbatim}
    #include <string>
    using namespace std;

    string *enlarge(string *old, size_t oldsize, size_t 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.
    }
\end{verbatim}
The procedure to enlarge shown in the example also has several drawbacks.
    \begin{itemize}
    \item  The new array requires \texttt{newsize} constructors to be called;
    \item  Having initialized the strings in the new array, \texttt{oldsize} of them
are immediately reassigned to the corresponding values in the original array;
    \item  All the objects in the old arrays are destroyed.
    \end{itemize}
    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).

\subsection{Managing `raw' memory}
    \typeout{Original Yodl file: memory/raw}As we've seen operator \texttt{new} allocates the memory for an object and
subsequently initializes that object by calling one of its
constructors. Likewise, operator \texttt{delete} calls an object's destructor and
subsequently returns the memory allocated by operator \texttt{new} to the common
pool.

In the next section we'll encounter another use of \texttt{new}, allowing us to
initialize objects in so-called \index{raw memory}\emph{raw memory}: memory merely consisting of
bytes that have been made available by either static or dynamic allocation.

Raw memory is made available by
 \index{operator new} \texttt{operator new(sizeInBytes)} and also by \texttt{operator
new{[}{]}(sizeInBytes)}. The returned memory should not be interpreted as an array
of any kind but just a series of memory locations that were dynamically made
available. No initialization whatsoever is performed by these variants of
\texttt{new}.

Both variants return \texttt{void $*$s} so (static) casts are required to use the
return values as memory of some type.

Here are two examples:
        \begin{verbatim}
                                // room for 5 ints:
    int *ip = static_cast<int *>(operator new(5 * sizeof(int)));
                                // same as the previous example:
    int *ip2 = static_cast<int *>(operator new[](5 * sizeof(int)));
                                // room for 5 strings:
    string *sp = static_cast<string *>(operator new(5 * sizeof(string)));
\end{verbatim}
As \texttt{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 \texttt{operator new} therefore somewhat
resembles the use of \index{malloc}\texttt{malloc}.

The counterpart of \texttt{operator new} is \index{operator delete}\texttt{operator delete}. \texttt{Operator
delete} (or, equivalently, \texttt{operator delete{[}{]}}), expects a \texttt{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 \texttt{operator delete}. The
use of \texttt{operator delete} therefore resembles the use of \index{free}\texttt{free}. To return
the memory pointed at by the abovementioned variables \texttt{ip} and \texttt{sp}
\texttt{operator delete} should be used:
        \begin{verbatim}
                    // delete raw memory allocated by operator new
    operator delete(ip);
    operator delete[](ip2);
    operator delete(sp);
\end{verbatim}
\subsection{The `placement new' operator}\label{PLACEMENT}
    \typeout{Original Yodl file: memory/placement}A remarkable form of operator \texttt{new} is called the \index{placement new}\emph{placement new}
 \index{new: placement} operator. Before using placement \texttt{new} the \index{memory: header file}\texttt{$<$memory$>$}
header file must be included.

Placement \texttt{new} is passed an existing block of memory into which \texttt{new}
initializes an object or value.  The block of memory should be large enough to
contain the object, but apart from that there are no further requirements. It
is easy to determine how much memory is used by an entity (object or variable)
of type \texttt{Type}: the
 \index{sizeof}\texttt{sizeof} operator returns the number of bytes used by an \texttt{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 \texttt{sizeof} returns the same value when applied to
different \texttt{string} objects that return different length and capacity values.

The placement \texttt{new} operator uses the following syntax (using \texttt{Type} to
indicate the used data type):
        \begin{verbatim}
    Type *new(void *memory) Type{ arguments };
\end{verbatim}
Here, \texttt{memory} is a block of memory of at least \texttt{sizeof(Type)} bytes
and \texttt{Type(arguments)} is any constructor of the class \texttt{Type}.

The placement \texttt{new} operator is useful in situations where classes set
aside memory to be used later. This is used, e.g., by \texttt{std::string} to
change its capacity. Calling \texttt{string::reserve} may enlarge that capacity
without making memory beyond the string's length immediately available to the
\texttt{string} object's users. But the object itself \emph{may} use its additional
memory. E.g, when information is added to a \texttt{string} object it can draw
memory from its capacity rather than performing a reallocation for each single
character that is added to its content.

Let's apply that philosophy to a class \texttt{Strings} storing \texttt{std::string}
objects. The class defines a \texttt{string $*$d\_memory} accessing the memory holding
its \texttt{d\_size} string objects as well as \texttt{d\_capacity - d\_size} reserved
memory. Assuming that a default constructor initializes \texttt{d\_capacity} to 1,
doubling \texttt{d\_capacity} whenever an additional \texttt{string} must be stored, the
class must support the following essential operations:
    \begin{itemize}
    \item  doubling its capacity when all its spare memory (e.g., made available
by \texttt{reserve}) has been consumed;
    \item  adding another \texttt{string} object
    \item  properly deleting the installed strings and memory when a
\texttt{Strings} object ceases to exist.
    \end{itemize}
    The private member \texttt{void Strings::reserve} is called when the current
capacity must be enlarged to \texttt{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).
    \begin{verbatim}
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;
}
\end{verbatim}
The member \texttt{append} adds another \texttt{string} object to a \texttt{Strings}
object. A (public) member \texttt{reserve(request)} (enlarging \texttt{d\_capacity} if
necessary and if enlarged calling \texttt{reserve()}) ensures that the \texttt{String}
object's capacity is sufficient. Then placement \texttt{new} is used to install the
latest string into the raw memory's appropriate location:
    \begin{verbatim}
void Strings::append(std::string const &next)
{
    reserve(d_size + 1);
    new (d_memory + d_size) std::string{ next };
    ++d_size;
}
\end{verbatim}
At the end of the \texttt{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 \texttt{destroy}, which is
called by the class's destructor and by \texttt{reserve()}. More about the
destructor itself in the next section, but the
implementation of the support member \texttt{destroy} is discussed below.

With placement \texttt{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 \texttt{delete{[}{]}} can't be used.  On the other hand,
a \texttt{delete} for each of the objects that \emph{are} available can't be used
either, since those \texttt{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 \texttt{new} is used: memory allocated by objects initialized
using placement \texttt{new} is returned by
        \index{destructor: explicit call}
    \emph{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, \texttt{std::string}'s destructor is named
\texttt{\textasciitilde{}string}. An object's destructor \emph{only} returns memory allocated by the
object itself and, despite of its name, does \emph{not} destroy its object.  Any
memory allocated by the \emph{strings} stored in our class \texttt{Strings} is
therefore properly destroyed by explicitly calling their
destructors. Following this \texttt{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 \texttt{operator delete}:
    \begin{verbatim}
void Strings::destroy()
{
    for (std::string *sp = d_memory + d_size; sp-- != d_memory; )
        sp->~string();

    operator delete(d_memory);
}
\end{verbatim}
So far, so good. All is well as long as we're using only one object. What
about allocating an array of objects? Initialization is performed as usual.
But as with \texttt{delete}, \texttt{delete{[}{]}} cannot be called when the buffer was
allocated statically. Instead, when multiple objects were initialized using
placement \texttt{new} in combination with a statically allocated
buffer all the objects' destructors must be called explicitly, as in the
following example:
        \begin{verbatim}
    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();
\end{verbatim}
Several standard template library functions are available for handling
unitialized (raw) memory. See section \ref{UNINIT} for a description.

\section{The destructor}\label{DESTRUCTOR}
\typeout{Original Yodl file: memory/destructor}Comparable to the constructor, classes may define a \index{destructor}\emph{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 \index{exit: avoid}\texttt{exit} call, only the destructors of
already initialized global objects are called.  In that situation destructors
of objects defined \emph{locally} by functions are also \emph{not} called. This is
one (good) reason for avoiding \texttt{exit} in \textbf{C++} programs.

Destructors obey the following syntactical requirements:
    \begin{itemize}
    \item  a destructor's name is equal to its class name prefixed by a tilde;
    \item  a destructor has no arguments;
    \item  a destructor has no return value.
    \end{itemize}
    Destructors are declared in their class interfaces. Example:
        \begin{verbatim}
    class Strings
    {
        public:
            Strings();
            ~Strings();     // the destructor
    };
\end{verbatim}
By convention the constructors are declared first. The destructor is
declared next, to be followed by other member functions.

A destructor's \index{destructor: main task} 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 \texttt{Strings}:
        \begin{verbatim}
    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;
    };
\end{verbatim}
The constructor's task is to initialize the data fields of the object. E.g,
its constructors are defined as follows:
        \begin{verbatim}
    Strings::Strings()
    :
        d_string(0),
        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];
    }
\end{verbatim}
    As objects of the class \texttt{Strings} allocate memory a destructor is
clearly required. Destructors may or may not be called automatically, but note
that destructors are \emph{only} called (or, in the case of dynamically allocated
objects: should only be called) for fully constructed objects.

\textbf{C++} considers objects `fully constructed' once at least one of its
constructors could normally complete. It used to be \emph{the} constructor, but
as \textbf{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;
    \begin{itemize}
    \item  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.
    \item  Destructors of static or global objects are called when the program
itself terminates.
    \item  The destructor of a dynamically allocated object is called by
\texttt{delete} using the object's address as its operand;
    \item  The destructors of a dynamically allocated array of objects are
called by \texttt{delete{[}{]}} using the address of the array's first element as its
operand;
    \item  The destructor of an object initialized by placement \texttt{new} is
activated  by explicitly calling the object's destructor.
    \end{itemize}
    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 \texttt{Strings}'s
destructor would therefore be to delete the memory to which \texttt{d\_string}
points. Its implementation is:
        \begin{verbatim}
    Strings::~Strings()
    {
        delete[] d_string;
    }
\end{verbatim}
The next example shows \texttt{Strings} at work. In \texttt{process}
a \texttt{Strings store} is created, and its data are displayed. It returns a
dynamically allocated \texttt{Strings} object to \texttt{main}. A
\texttt{Strings $*$} receives the address of the allocated object and deletes the
object again. Another \texttt{Strings} object is then created in a block of
memory made available locally in \texttt{main}, and an
    \index{destructor: explicit call}explicit call to \texttt{\textasciitilde{}Strings} is required
to return the memory allocated by that object. In the example only once a
\texttt{Strings} object is automatically destroyed: the local \texttt{Strings}
object defined by \texttt{process}. The other two \texttt{Strings} objects require
explicit actions to prevent memory leaks.
        \begin{verbatim}
    #include "strings.h"
    #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[], size_t 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, static_cast<size_t>(argc) };
        sp->~Strings();
    }
\end{verbatim}
\subsection{Object pointers revisited}\label{DELETEPTRS}
    \typeout{Original Yodl file: memory/objectp}    Operators \texttt{new} and \texttt{delete} are used when an object or variable is
allocated. One of the advantages of the operators \texttt{new} and
\texttt{delete} over functions like \index{malloc}\texttt{malloc} and \index{free}\texttt{free} is that \texttt{new} and
\texttt{delete} call the corresponding object constructors and destructors.

The allocation of an object by operator \texttt{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 \texttt{new} and
\texttt{delete}. When allocating an array of objects using operator \texttt{new} the
default constructor is called for each object in the array. In cases like this
operator \index{delete[]}\texttt{delete{[}{]}} must be used to ensure that the destructor is called for
each of the objects in array.

However, the addresses returned by \texttt{new Type} and \texttt{new Type{[}size{]}}
are of identical types, in both cases a \texttt{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 \texttt{delete} rather than \texttt{delete{[}{]}} is used? Consider the
following situation, in which the destructor \texttt{\textasciitilde{}Strings} is modified so that
it tells us that it is called.  In a \texttt{main} function an array of two
\texttt{Strings} objects is allocated using \texttt{new}, to be deleted by \texttt{delete{[}{]}}.
 Next, the same actions are repeated, albeit that the \texttt{delete} operator is
called without \texttt{{[}{]}}:
        \begin{verbatim}
    #include <iostream>
    #include "strings.h"
    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
*/
\end{verbatim}
    From the generated output, we see that the destructors of the individual
\texttt{Strings} objects are called when \texttt{delete{[}{]}} is used, while only the
first object's destructor is called if the \texttt{{[}{]}} is omitted.

Conversely, if \texttt{delete{[}{]}} is called in a situation where \texttt{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
\emph{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 \texttt{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 \index{trivial destructor}\emph{trivial destructor} is defined by the
compiler. The trivial destructor ensures that the destructors of composed
objects (as well as the destructors of \emph{base classes} if a class is a
derived class, cf. chapter \ref{INHERITANCE}) are called. This has serious
implications: objects allocating memory create memory leaks \index{memory leak}
unless precautionary measures are taken (by defining an appropriate
destructor). Consider the following program:
        \begin{verbatim}
    #include <iostream>
    #include "strings.h"
    using namespace std;

    Strings::~Strings()
    {
        cout << "Strings destructor called" << '\n';
    }

    int main()
    {
        Strings **ptr = new Strings* [2];

        ptr[0] = new Strings[2];
        ptr[1] = new Strings[2];

        delete[] ptr;
    }
\end{verbatim}
    This program produces no output at all. Why is this? The variable \texttt{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 \texttt{Strings} destructor is called.

Of course, we don't want this, but require the \texttt{Strings} objects
pointed to by the elements of \texttt{ptr} to be deleted too. In this case we have
two options:
    \begin{itemize}
    \item  In a for-statement visit all the elements of the \texttt{ptr} array,
calling \texttt{delete} for each of the array's elements. This procedure was
demonstrated in the previous section.
    \item  A \index{wrapper}wrapper class is designed around a pointer (to, e.g., an object
of some class, like \texttt{Strings}).  Rather than using a pointer to a
pointer to \texttt{Strings} objects a pointer to an array of wrapper-class
objects is used. As a result \texttt{delete{[}{]} ptr} calls the destructor of each of
the wrapper class objects, in turn calling the \texttt{Strings} destructor for
their \texttt{d\_strings} members. Example:
        \begin{verbatim}
    #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;
    }

    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
    */
\end{verbatim}
    \end{itemize}

\subsection{The function set\_new\_handler()}\label{NEWHANDLER}
    \typeout{Original Yodl file: memory/setnew}The \textbf{C++} run-time system ensures that when memory allocation fails an
error function is activated. By default this function throws a
  \index{bad\_alloc}\index{exception: bad\_alloc}\emph{bad\_alloc} exception (see section
\ref{STDEXC}), terminating the program. Therefore it is not necessary to check
the return value of operator \texttt{new}. Operator \texttt{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:
    \begin{itemize}
    \item  it has no parameters;
    \item  its return type is \texttt{void}.
    \end{itemize}

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 \index{set\_new\_handler}\texttt{set\_new\_handler}.

Such an error function is illustrated below\footnote{ This implementation
applies to the \index{GNU}GNU \textbf{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 \index{swap area}\emph{swap area}.}:
        \begin{verbatim}
    #include <iostream>
    #include <string>

    using namespace std;

    void outOfMemory()
    {
        cout << "Memory exhausted. Program terminates." << '\n';
        exit(1);
    }

    int main()
    {
        long allocated = 0;

        set_new_handler(outOfMemory);       // install error function

        while (true)                        // eat up all memory
        {
            new int [100000]();
            allocated += 100000 * sizeof(int);
            cout << "Allocated " << allocated << " bytes\n";
        }
    }
\end{verbatim}
    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 `\index{out of memory}out of memory' condition
may actually never be reached, as the operating system may interfere before
the \index{run-time support system}run-time support system gets a chance to stop the program.

The traditional memory allocation functions (like \index{strdup}\texttt{strdup}, \index{malloc}\texttt{malloc},
\index{realloc}\texttt{realloc} etc.) do not trigger the \texttt{new} handler when memory allocation
fails and should be avoided in \textbf{C++} programs.

\section{The assignment operator}\label{ASSIGNMENT}
\typeout{Original Yodl file: memory/assignment}In \textbf{C++} struct and class type objects  can be directly assigned new values
in the same way as this is possible in \textbf{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 \texttt{Person}: \index{strdupnew}
        \begin{verbatim}
    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);
    }
\end{verbatim}
\texttt{Person}'s data members are initialized to zeroes or to copies of the
NTBSs passed to \texttt{Person}'s constructor, using some variant of
\index{strdup}\texttt{strdup}. The allocated memory is eventually returned by \texttt{Person}'s
destructor.

Now consider the consequences of using \texttt{Person} objects in the following
example:
        \begin{verbatim}
    void tmpPerson(Person const &person)
    {
        Person tmp;
        tmp = person;
    }
\end{verbatim}
Here's what happens when \texttt{tmpPerson} is called:
    \begin{itemize}
    \item  it expects a reference to a \texttt{Person} as its parameter \texttt{person}.
    \item  it defines a local object \texttt{tmp}, whose data members are initialized
to zeroes.
    \item  the object referenced by \texttt{person} is copied to \texttt{tmp}:
\texttt{sizeof(Person)} number of bytes are copied from \texttt{person} to \texttt{tmp}.
    \end{itemize}
    Now a potentially dangerous situation has been created.  The actual values
in \texttt{person} are \emph{pointers}, pointing to allocated memory.  After the
assignment this memory is addressed by two objects: \texttt{person} \emph{and}
\texttt{tmp}.
    \begin{itemize}
    \item  The potentially dangerous situation develops into an acutely
dangerous situation once the function \texttt{tmpPerson} terminates: \texttt{tmp} is
destroyed. The destructor of the class \texttt{Person} releases the memory pointed
to by the fields \texttt{d\_name}, \texttt{d\_address} and \texttt{d\_phone}: unfortunately,
this memory is also pointed at by \texttt{person}....
    \end{itemize}
    This problematic assignment is illustrated in Figure \ref{badassign}.

\begin{figure}[tbp]
\centerline{\epsffile{memory/badassign.eps}}
\caption{\label{badassign}Private data and public interface functions of the class Person,
        using byte-by-byte assignment}
\end{figure}

\index{pointer: to deleted memory}
    Having executed \texttt{tmpPerson}, the object referenced by \texttt{person} now
contains pointers to deleted memory.

This is undoubtedly not a desired effect of using a function like
\texttt{tmpPerson}.  The deleted memory is likely to be reused by subsequent
allocations. The pointer members of \texttt{person} have effectively become
 \index{wild pointer}\emph{wild pointers}, as they don't point to allocated
memory anymore. In general it can be concluded that
    \begin{center}\emph{every class containing pointer data members is a potential
        candidate for trouble}.\end{center}
    Fortunately, it is possible to prevent these troubles, as discussed next.

\subsection{Overloading the assignment operator}\label{OVERLOADASSIGN}
    \typeout{Original Yodl file: memory/overload}Obviously, the right way to assign one \texttt{Person} object to another, is
\textbf{not} to copy the content 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 \index{object: assign} assign a \texttt{Person} object to another is
illustrated in Figure \ref{rightass}.
    \begin{figure}[tbp]
\centerline{\epsffile{memory/rightass.eps}}
\caption{\label{rightass}Private data and public interface functions of the class Person,
     using the `correct' assignment.}
\end{figure}
    There are several ways to assign a \texttt{Person} object to another.  One way
would be to define a special member function to handle the assignment. The
purpose of this member function would be to create a copy of an object having
its own \texttt{name}, \texttt{address} and \texttt{phone} strings.  Such a member function
could be:
        \begin{verbatim}
    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);
    }
\end{verbatim}
Using \texttt{assign} we could rewrite the offending function \texttt{tmpPerson}:
        \begin{verbatim}
    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..
    }
\end{verbatim}
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 \emph{operator overloading}: the
possibility \textbf{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
\texttt{cin}, \texttt{cout} and \texttt{cerr}), see section \ref{CoutCinCerr}.

Overloading the assignment operator is probably the most common form of
operator overloading in \textbf{C++}. A word of warning is appropriate, though.
The fact that \textbf{C++} allows \index{operator overloading}operator overloading does not mean that this
feature should indiscriminately be used. Here's what you should keep in mind:
    \begin{itemize}
    \item  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 \texttt{Person}.
    \item  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
\texttt{std::string}: assigning one string object to another provides the
destination string with a copy of the content of the source string. No
surprises here.
    \item  in all other cases a member function should be defined instead of
redefining an operator.
        \end{itemize}
    An operator should simply do what it is designed to do. The phrase that's
often encountered in the context of operator overloading is \emph{do as the
\texttt{int}s do}. The way operators behave when applied to \texttt{int}s 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.

\subsubsection{The member 'operator=()'}
    \typeout{Original Yodl file: memory/operator}To add operator overloading to  a class, the class interface is simply
provided  with a (usually \emph{public}) member function naming the particular
operator. That member function is thereupon implemented.

To overload the assignment operator \texttt{=}, a member \texttt{operator=(Class const
\&rhs)} is added to the class interface.  Note that the function name consists
of two parts: the keyword \index{operator}\texttt{operator}, followed by the operator itself.  When
we augment a class interface with a member function \texttt{operator=}, then that
operator is \emph{redefined} for the class, which prevents the default operator
from being used. In the previous section the function
\texttt{assign} was provided to solve the problems resulting from using the
default assignment operator. Rather than using an ordinary member
function \textbf{C++} commonly uses a dedicated operator generalizing the
operator's default behavior to the class in which it is defined.

The \texttt{assign} member mentioned before may be redefined as follows (the member
\texttt{operator=} presented below is a first, rather unsophisticated, version of
the overloaded assignment operator.  It will shortly be improved):
        \begin{verbatim}
    class Person
    {
        public:                             // extension of the class Person
                                            // earlier members are assumed.
            void operator=(Person const &other);
    };
\end{verbatim}
Its implementation could be
        \begin{verbatim}
    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);
    }
\end{verbatim}
This member's actions are similar to those of the previously mentioned
member \texttt{assign}, but this member is automatically called when the assignment
operator \texttt{=} is used. Actually there are \emph{two} ways to
call overloaded operators as shown in the next example:
        \begin{verbatim}
    void tmpPerson(Person const &person)
    {
        Person tmp;

        tmp = person;
        tmp.operator=(person);  // the same thing
    }
\end{verbatim}
Overloaded operators are seldom called explicitly, but explicit calls must
be used (rather than using the plain operator syntax) when you explicitly
\emph{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):
        \begin{verbatim}
    void tmpPerson(Person const &person)
    {
        Person *tmp = new Person;

        tmp->operator=(person);
        *tmp = person;          // yes, also possible...

        delete tmp;
    }
\end{verbatim}
\section{The `this' pointer}
\typeout{Original Yodl file: memory/this}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. \textbf{C++} defines a keyword, \index{this}\texttt{this}, to reach this substrate.

The \texttt{this} keyword is a pointer variable that always contains the
address
 \index{object: address} \index{address of objects} of the object for which the member
function was called. The \texttt{this} pointer is implicitly declared by each
member function (whether \texttt{public, protected}, or \texttt{private}). The \texttt{this}
pointer is a constant pointer to an object of the member function's
class. For example, the members of the class \texttt{Person} implicitly declare:
        \begin{verbatim}
    extern Person *const this;
\end{verbatim}
A member function like \texttt{Person::name} could be implemented in two ways:
with or without using the \texttt{this} pointer:
        \begin{verbatim}
    char const *Person::name() const    // implicitly using `this'
    {
        return d_name;
    }

    char const *Person::name() const    // explicitly using `this'
    {
        return this->d_name;
    }
\end{verbatim}
The \texttt{this} pointer is seldom explicitly used, but situations do exist
where the \texttt{this} pointer is actually required (cf. chapter
\ref{PointMembers}).

\subsection{Sequential assignments and this}
    \typeout{Original Yodl file: memory/sequential}    \textbf{C++}'s syntax allows for \index{assignment: sequential} sequential
assignments, with the assignment operator associating from right to left. In
statements like:
        \begin{verbatim}
    a = b = c;
\end{verbatim}
the expression \texttt{b = c} is evaluated first, and its result in turn is
assigned to \texttt{a}.

The implementation of the overloaded assignment operator we've encountered
thus far does not permit such constructions, as it returns \texttt{void}.

This imperfection can easily be remedied using the \texttt{this} pointer. The
overloaded assignment operator expects a reference to an object of its
class. It can also \emph{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., \texttt{$*$this}).  The next version of the overloaded
assignment operator for the class \texttt{Person} thus becomes:
        \begin{verbatim}
    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;
    }
\end{verbatim}
Overloaded operators may themselves be overloaded. Consider the \texttt{string}
class, having overloaded assignment operators \texttt{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 \texttt{$*$this} is returned.

\section{The copy constructor: initialization vs. assignment}\label{COPYCONS}
\typeout{Original Yodl file: memory/initialization}Consider the class \texttt{Strings}, introduced in section \ref{DESTRUCTOR},
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 \texttt{char const $*$const $*$} and a \texttt{size\_t}.

Now consider the following code fragment. The statement references are
discussed following the example:
        \begin{verbatim}
    int main(int argc, char **argv)
    {
        Strings s1(argv, argc);     // (1)
        Strings s2;                 // (2)
        Strings s3(s1);             // (3)

        s2 = s1;                        // (4)
    }
\end{verbatim}
\begin{itemize}
    \item  At 1 we see  an \index{initialization}initialization.  The object
\texttt{s1} is initialized using \texttt{main}'s parameters: \texttt{Strings}'s second
constructor is used.
    \item  At 2 \texttt{Strings}'s \index{default constructor}\emph{default constructor} is used, initializing
an empty \texttt{Strings} object.
    \item  At 3 yet another \texttt{Strings} object is created, using a
constructor accepting an existing \texttt{Strings} object. This form of
initializations has not yet been discussed. It is called a
 \index{copy constructor} \emph{copy construction} and the constructor performing the
initialization is called the \emph{copy constructor}. Copy constructions are also
encountered in the following form:
        \begin{verbatim}
    Strings s3 = s1;
\end{verbatim}
This is a \emph{construction} and therefore an \emph{initialization}. It is not
an \emph{assignment} as an assignment needs a left-hand operand that has already
been defined. \textbf{C++} allows the assignment syntax to be used for constructors
having only one parameter. It is somewhat deprecated, though.
    \item  At 4 we see a plain assignment.
    \end{itemize}
    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:
    \begin{quote}
    A copy constructor is (almost) always available, even if it isn't declared
    in the class's interface.
    \end{quote}
    The reason for the `(almost)' is given in section \ref{MOVECONS}.

The copy constructor made available by the compiler is also called the
\index{trivial copy constructor}trivial copy constructor. Its use can easily be suppressed (using the \texttt{=
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-by-byte copy operation of the object's
primitive type data members that is exactly what happens at statement 3.
By the time \texttt{s3} ceases to exist its destructor deletes its array of
strings. Unfortunately \texttt{d\_string} is of a primitive data type and so it also
deletes \texttt{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 \emph{duplicated}, so that it contains its own allocated
data. But note that if a class also reserves extra (raw) memory, i.e., if it
supports extra memory capacity, then that unused extra capacity is not made
available in the copy-constructed object. 

\index{capacity: reduce} Copy construction \emph{can} be used to shed excess
capacity. Copy constructors do not \emph{have} to shed excess capacity. E.g.,
when copy-constructing \texttt{std::string} objects the destination object defines
the same capacity as the source object. 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 memory
has already been allocated.

\texttt{Strings}'s copy constructor can be implemented as follows:
        \begin{verbatim}
    Strings::Strings(Strings const &other)
    :
        d_string(new string[other.d_size]),
        d_size(other.d_size)
    {
        for (size_t idx = 0; idx != d_size; ++idx)
            d_string[idx] = other.d_string[idx];
    }
\end{verbatim}
The copy constructor is always called when an object is initialized using
another object of its class. Apart from the plain copy construction that we
encountered thus far, here are other situations where the copy constructor is
used:
    \begin{itemize}
    \item  it is used when a function defines a \index{object: parameter} 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:
    \begin{verbatim}
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);
}
\end{verbatim}
\item  it is used when a function defines a class type value return type.
Example:
    \begin{verbatim}
Strings copy(Strings const &store)
{
    return store;
}
\end{verbatim}
\end{itemize}
    Here \texttt{store} is used to initialize \texttt{copy}'s return value. The returned
\texttt{Strings} object is a temporary, anonymous object that may be
immediately used by code calling \texttt{copy} but no assumptions can be made about
its lifetime thereafter.

\section{Revising the assignment operator}\label{CopyDestroy}
\typeout{Original Yodl file: memory/revising} The overloaded assignment operator has characteristics also encountered with
the copy constructor and the destructor:
    \begin{itemize}
    \item  The \emph{copying of (private) data} occurs (1) in the copy constructor
and (2) in the overloaded assignment function.
    \item  Allocated memory is deleted (1) in the overloaded assignment function
and (2) in the destructor.
    \end{itemize}
    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
\ref{DESTRUCTOR}) 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:
    \begin{itemize}
    \item  It should delete the dynamically allocated memory controlled by the
current object;
    \item  It should reassign the current object's data members using a provided
existing object of its class.
    \end{itemize}
    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:
        \begin{verbatim}
    Strings &operator=(Strings const &other)
    {
        Strings tmp(other);
        // more to follow
        return *this;
    }
\end{verbatim}
You may think the optimization \texttt{operator=(Strings tmp)} is attractive,
but let's postpone that for a little while (at least until section \ref{MOVE}).

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, \texttt{$*$this}) object.

At this point it's time to introduce \emph{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
\texttt{swap(Strings \&other)} to our class \texttt{Strings}. This allows us to
complete \texttt{String}'s \texttt{operator=} implementation:
        \begin{verbatim}
    Strings &operator=(Strings const &other)
    {
        Strings tmp(other);
        swap(tmp);
        return *this;
    }
\end{verbatim}
This implementation of \texttt{operator=} is generic: it can be applied to
every class whose objects are swappable. How does it work?
    \begin{itemize}
    \item  The information in the \texttt{other} object is used to initialize a
local \texttt{tmp} object. This takes care of the copying part of the assignment
operator;
    \item  Calling \texttt{swap} ensures that the current object receives its new
values (with \texttt{tmp} receiving the current object's original values);
    \item  When \texttt{operator=} terminates its local \texttt{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.
    \end{itemize}
    Nice?

\subsection{Swapping}
    \typeout{Original Yodl file: memory/swapping}Many classes (e.g., \texttt{std::string}) offer \index{swap}\texttt{swap} members allowing us to
swap two of their objects. The \emph{Standard Template Library} (STL, cf. chapter
\ref{STL}) offers various functions related to swapping. There is even a
\texttt{swap} \emph{generic algorithm} (cf. section \ref{SWAP}), which is commonly
implemented using the assignment operator. When implementing a \texttt{swap} member
for our class \texttt{Strings} it could be used, provided that all of \texttt{String}'s
data members can be swapped. As this is true (\emph{why} this is true is
discussed shortly) we can augment \texttt{class Strings} with a \texttt{swap} member:
        \begin{verbatim}
    void Strings::swap(Strings &other)
    {
        std::swap(d_string, other.d_string);
        std::swap(d_size, other.d_size);
    }
\end{verbatim}
Having added this member to \texttt{Strings} the copy-and-swap implementation
of \texttt{String::operator=} can now be used.

When two variables (e.g., \texttt{double one} and \texttt{double two}) are swapped,
each one holds the other one's value after the swap. So, if \texttt{one == 12.50}
and \texttt{two == -3.14} then after \texttt{swap(one, two) one == -3.14} and \texttt{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 \texttt{swap}
member.

So should we provide our classes with a swap member, and if so, how should
it be implemented?

The above example (\texttt{Strings::swap}) shows the standard way to implement
a \texttt{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 \ref{SWAPLIST}.

\begin{figure}[tbp]
\centerline{\epsffile{memory/fswap.eps}}
\caption{\label{SWAPLIST}Swapping a linked list}
\end{figure}

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:
        \begin{verbatim}
    class List
    {
        List *d_next;
        ...
    };
\end{verbatim}
Initially four objects have their \texttt{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 are
swapped: 3's \texttt{d\_next} point is now at object 2, which still points to 4; 2's
\texttt{d\_next} pointer points to 3's address, but 2's \texttt{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 \ref{SWAPSELF}.

\begin{figure}[tbp]
\centerline{\epsffile{memory/fswap2.eps}}
\caption{\label{SWAPSELF}Swapping objects with self-referential data}
\end{figure}

Here, objects have two data members, as in the following class setup:
        \begin{verbatim}
    class SelfRef
    {
        size_t *d_ownPtr;       // initialized to &d_data
        size_t d_data;
    };
\end{verbatim}
The top-half of figure \ref{SWAPSELF} 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 \ref{SWAPSELF} 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 \texttt{SelfRef} objects does not
imply that two \texttt{SelfRef} objects cannot be swapped; it only means that we
must be careful when designing \texttt{swap} members. Here is an implementation of
\texttt{SelfRef::swap}:
        \begin{verbatim}
    void SelfRef::swap(SelfRef &other)
    {
        swap(d_data, other.d_data);
    }
\end{verbatim}
In this implementation swapping leaves the self-referential data member
as-is, and merely swaps the remaining data. A similar \texttt{swap} member could be
designed for the linked list shown in figure \ref{SWAPLIST}.

\subsubsection{Fast swapping}\label{FSWAP}
        \typeout{Original Yodl file: memory/fastswap}    As we've seen with placement \texttt{new} objects can be constructed in blocks
of memory of \texttt{sizeof(Class)} bytes large. And so, two objects of the same
class each occupy \texttt{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 content of the \texttt{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 probably overstretches the allowed operations as described by the
\textbf{C++} ANSI/ISO standard) also be used in classes having reference data
members. It simply defines a buffer of \texttt{sizeof(Class)} bytes and performs a
circular \index{memcpy}\texttt{memcpy} operation. Here is its implementation for a hypothetical
class \texttt{Class}. It results in very fast swapping:
        \begin{verbatim}
    #include <cstring>

    void Class::swap(Class &other)
    {
        char buffer[sizeof(Class)];
        memcpy(buffer, &other, sizeof(Class));
        memcpy(static_cast<void *>(&other), this,   sizeof(Class));
        memcpy(static_cast<void *>(this), buffer, sizeof(Class));
    }
\end{verbatim}
The \texttt{static\_cast} for \texttt{memcpy's} destination address is used to prevent a
compiler complaint: since \texttt{Class} is a class-type, the compiler (rightly)
warns against bluntly copying bytes. But using \texttt{memcpy} is fine if you're
\texttt{Class's} developer and know what you're doing.

Here is a simple example of a class defining a reference data member and
offering a \texttt{swap} member implemented like the one above. The reference data
members are initialized to external streams. After running the program \texttt{one}
contains two \emph{hello to 1} lines, \texttt{two} contains two \emph{hello to 2} lines
(for brevity all members of \texttt{Reference} are defined inline):

\begin{verbatim}
    #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(static_cast<void *>(this), &other, sizeof(Reference));
                memcpy(static_cast<void *>(&other), buffer,
                                                    sizeof(Reference));
            }
            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";
    }
\end{verbatim}
Fast swapping should only be used for self-defined classes for which it can be
proven that fast-swapping does not corrupt its objects, when swapped.

\section{Moving data}\label{MOVE}
\typeout{Original Yodl file: memory/moving.yo}Traditionally, \textbf{C++} offered two ways to assign the information pointed to
by a data member of a temporary object to an \emph{lvalue} object. Either a copy
constructor or reference counting had to be used. In addition to these two
methods \textbf{C++} now also supports \index{move semantics}\emph{move semantics}, allowing \emph{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 \texttt{operator-()} and
\texttt{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 (\texttt{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 \emph{move
construction} and \emph{move assignment}. Classes supporting move operations are
called \index{class: move-aware}\emph{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 using composition (or
inheritance where the base class uses composition) can benefit from move
operations as well.

Movable parameters for class \texttt{Class} take the form \texttt{Class \&\&tmp}. The
parameter is an \emph{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 \texttt{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 \texttt{Class const \&} or \texttt{Class \&\&tmp}
parameters as within such functions the names of these parameters are
available) it is no longer an \emph{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 \texttt{fun} for which these kinds of parameters were
defined. Each of these functions call a function \texttt{gun} for which these kinds
of parameters were also defined. The first time \texttt{fun} is called it (as
expected) calls \texttt{gun(Class \&)}. Then \texttt{fun(Class \&\&)} is called as its
argument is an anonymous (temporary) object. However, inside \texttt{fun} the
anonymous value has received a name, and so it isn't anonymous
anymore. Consequently, \texttt{gun(Class \&)} is called once again. Finally
\texttt{fun(Class const \&)} is called, and (as expected) \texttt{gun(Class const \&)} is
now called.
    \begin{verbatim}
#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)
    {
        cout << "gun: Class &&\n";
    }
};

int main()
{
    Class c1;

    c1.fun(c1);
    c1.fun(Class());

    Class const c0;
    c1.fun(c0);
}
\end{verbatim}
Generally it is pointless to define a
 \index{function: returning rvalue reference} function having an 
 \index{rvalue reference return type}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. An
rvalue reference return type is used, e.g., with the \texttt{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
\texttt{const \&}, is less attractive as it requires a \texttt{const\_cast} before the
object can be modified. Here is an example:
        \begin{verbatim}
    std::string &&doubleString(std::string &&tmp)
    {
        tmp += tmp;
        return std::move(tmp);
    }
\end{verbatim}
This allows us to do something like
        \begin{verbatim}
    std::cout << doubleString("hello "s);
\end{verbatim}
to insert \texttt{hello hello } into \texttt{cout}.

The compiler, when selecting a function to call applies a fairly simple
algorithm, and also considers copy elision. This is covered shortly (section
\ref{RVO}).

\subsection{The move constructor (dynamic data)}\label{MOVECONS}
    \typeout{Original Yodl file: memory/move}Our class \texttt{Strings} has, among other members, a data member \texttt{string
$*$d\_string}. Clearly, \texttt{Strings} should define a copy constructor, a
destructor and an overloaded assignment operator.

Now consider the following function \texttt{loadStrings(std::istream \&in)}
extracting the strings for a \texttt{Strings} object from \texttt{in}. Next, the
\texttt{Strings} object filled by \texttt{loadStrings} is returned by value. The
function \texttt{loadStrings} returns a temporary object, which can then used to
initialize an external \texttt{Strings} object:
        \begin{verbatim}
    Strings loadStrings(std::istream &in)
    {
        Strings ret;
        // load the strings into 'ret'
        return ret;
    }
    // usage:
    Strings store(loadStrings(cin));
\end{verbatim}
In this example two full copies of a \texttt{Strings} object are required:
    \begin{itemize}
    \item  initializing \texttt{loadString}'s value return type from its local
\texttt{Strings ret} object;
    \item  initializing \texttt{store} from \texttt{loadString}'s return value
    \end{itemize}
    We can improve the above procedure by defining a
 \index{move constructor}\emph{move constructor}.  Here is the declaration of the \texttt{Strings} class move
constructor:
        \begin{verbatim}
    Strings(Strings &&tmp);
\end{verbatim}
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 copies 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 \emph{grabbed} or
 \index{resource: stealing} \emph{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 we may assume that the temporary objects
cease to exist shortly after the move-constructor's call. Here is an
implementation of \texttt{Strings} move constructor:
        \begin{verbatim}
    Strings::Strings(Strings &&tmp)
    :
        d_string(tmp.d_string),
        d_size(tmp.d_size),
        d_capacity(tmp.d_capacity)
    {
        tmp.d_string = 0;
        tmp.d_capacity = 0;
        tmp.d_size = 0;
    }
\end{verbatim}
    Move construction (in general: moving) must leave the object from which
information was moved in a valid state. It is not specified in what way that
valid state must be realized, but a good \index{rule of thumb}rule of thumb is to return the
object to its default constructed state. In the above illustration of a move
constructor \texttt{tmp.d\_size, tmp.d\_capacity} and \texttt{tmp.d\_string} are all set to
0. It's up to the author of the \texttt{Strings} class to decide whether or not
the \texttt{String's} members can all be set to 0. If there's a default constructor
doing exactly that then assigning zeroes is fine. If \texttt{d\_capacity} is doubled
once \texttt{d\_size == d\_capacity} then setting \texttt{d\_capactiy} to 1 and letting
\texttt{d\_string} point to a newly allocated block of raw memory the size of a
\texttt{string} might be attractive. The source object's capacity might even
remain as-is. E.g., when moving \texttt{std::string} objects the source object's
capacity isn't altered.

In section \ref{COPYCONS} it was stated that the copy constructor is almost
    \index{copy constructor: suppressed}
always available. \emph{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 \emph{move assignment operator} is declared
(cf. section \ref{MOVEASS}).

The following example shows a simple class \texttt{Class}, declaring a move
constructor. In the \texttt{main} function following the class interface a
\texttt{Class} object is defined which is then passed to the constructor of a
second \texttt{Class} object. Compilation fails with the compiler reporting:
        \begin{verbatim}
    error: cannot bind 'Class' lvalue to 'Class&&'
    error:   initializing argument 1 of 'Class::Class(Class&&)'
\end{verbatim}
\begin{verbatim}
class Class
{
    public:
        Class() = default;
        Class(Class &&tmp)
        {}
};

int main()
{
    Class one;
    Class two{ one };
}
\end{verbatim}
The cure is easy: after declaring a (possibly \texttt{default}) copy
constructor the error disappears:
        \begin{verbatim}
class Class
{
    public:
        Class() = default;
        Class(Class const &other) = default;
        Class(Class &&tmp)
        {}
};

int main()
{
    Class one;
    Class two{ one };
}
\end{verbatim}
\subsection{The move constructor (composition)}
    \typeout{Original Yodl file: memory/movecomposition}    Classes not using pointer members pointing to memory controlled by its
objects (and not having base classes doing so, see chapter \ref{INHERITANCE})
may also  benefit from overloaded members expecting rvalue references. The
class benefits from move operations when one or more of the composed data
members 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, \texttt{stream} classes fall
into this category.

An example of a move-aware class is the class \texttt{std:string}. A class
\texttt{Person} could use composition by defining \texttt{std::string d\_name} and
\texttt{std::string d\_address}. Its move constructor would then have the following
prototype:
        \begin{verbatim}
    Person(Person &&tmp);
\end{verbatim}
However, the following implementation of this move constructor is
incorrect:
        \begin{verbatim}
    Person::Person(Person &&tmp)
    :
        d_name(tmp.d_name),
        d_address(tmp.d_address)
    {}
\end{verbatim}
It is incorrect as \texttt{string}'s copy constructors rather than
\texttt{string}'s move constructors are called. If you're wondering why this
happens then remember that move operations are \emph{only} performed for
anonymous objects. To the compiler anything having a name isn't anonymous. And
so, by implication, having available a rvalue reference does \emph{not} mean that
we're referring to an anonymous object. But we \emph{know} that the move
constructor is only called for anonymous arguments. To use the corresponding
\texttt{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.,
\texttt{static\_cast$<$Person \&\&$>$(tmp)}), but the C++-0x standard provides the
function
 \index{move}\texttt{std::move} to \index{anonymous}anonymize a named object. The correct
implementation of \texttt{Person}'s move construction is, therefore:
        \begin{verbatim}
    Person::Person(Person &&tmp)
    :
        d_name( std::move(tmp.d_name) ),
        d_address( std::move(tmp.d_address) )
    {}
\end{verbatim}
The function \texttt{std::move}\index{move} is (indirectly) declared by many header
files.  If no header is already declaring \texttt{std::move} then include
\index{utility}\texttt{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 and
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
the class \texttt{Class} offers a move constructor and a copy constructor:
        \begin{verbatim}
    Class factory();

    void fun(Class const &other);   // a
    void fun(Class &&tmp);          // b

    void callee(Class &&tmp)
    {
        fun(tmp);                   // 1
    }

    int main()
    {
        callee(factory());
    }
\end{verbatim}
\begin{itemize}
    \item  At 1 function a is called. At first sight this might be surprising,
but \texttt{fun}'s argument is not an \emph{anonymous} temporary object but a
\emph{named} temporary object.
    \end{itemize}
    Realizing that \texttt{fun(tmp)} might be called twice the compiler's choice is
understandable. If \texttt{tmp}'s data would have been grabbed at the first call,
the second call would receive \texttt{tmp} without any data. But at the last call
we might know that  \texttt{tmp} is never used again and so we might like to ensure
that \texttt{fun(Class \&\&)} is called. For this, once again, \texttt{std::move} is used:
        \begin{verbatim}
    fun(std::move(tmp));            // last call!
\end{verbatim}
\subsection{Move-assignment}\label{MOVEASS}
    \typeout{Original Yodl file: memory/moveassignment}In addition to the overloaded assignment operator a \index{move assignment}\emph{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:
        \begin{verbatim}
    Class &operator=(Class &&tmp)
    {
        swap(tmp);
        return *this;
    }
\end{verbatim}
If swapping is not supported then the assignment can be performed for each
of the data members in turn, using \texttt{std::move} as shown in the previous
section with a class \texttt{Person}. Here is an example showing how to do this
with that class  \texttt{Person}:
        \begin{verbatim}
    Person &operator=(Person &&tmp)
    {
        d_name = std::move(tmp.d_name);
        d_address = std::move(tmp.d_address);
        return *this;
    }
\end{verbatim}
As noted previously (section \ref{MOVECONS}) 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 \texttt{= default} default implementation).

\subsection{Revising the assignment operator (part II)}\label{REVISEDASS}
    \typeout{Original Yodl file: memory/revising2}Now that we've familiarized ourselves with the overloaded assignment operator
and the move-assignment, let's once again have a look at their
implementations for a class \texttt{Class}, supporting swapping through its
\texttt{swap} member. Here is the generic implementation of the overloaded
assignment operator:
        \begin{verbatim}
    Class &operator=(Class const &other)
    {
        Class tmp{ other };
        swap(tmp);
        return *this;
    }
\end{verbatim}
and this is the move-assignment operator:
        \begin{verbatim}
    Class &operator=(Class &&tmp)
    {
        swap(tmp);
        return *this;
    }
\end{verbatim}
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 \texttt{other} object is available. Since the overloaded assignment
operator's \texttt{tmp} object really is nothing but a temporary \texttt{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:
        \begin{verbatim}
    Class &operator=(Class const &other)
    {
        Class tmp{ other };
        return *this = std::move(tmp);
    }
\end{verbatim}
\subsection{Moving and the destructor}
    \typeout{Original Yodl file: memory/movedestructor}    Once a class becomes a \index{move-aware}\emph{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
commonly ensures that the temporary object'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 \texttt{size\_t} defining the number of
elements in the array of pointers.

Once again, consider the class \texttt{Strings}. Its destructor is implemented
like this:
        \begin{verbatim}
    Strings::~Strings()
    {
        for (string **end = d_string + d_size; end-- != d_string; )
            delete *end;
        delete[] d_string;
    }
\end{verbatim}
The move constructor (and other move operations!) must realize that the
destructor not only deletes \texttt{d\_string}, but also considers \texttt{d\_size}. When
\texttt{d\_size} and \texttt{d\_string} are set to 0, the destructor (correctly) won't
delete anything. In addition, when the class uses 
capacity-doubling once \texttt{d\_size ==
d\_capacity} then the move constructor can still reset the source's
(d\_capacity) to 0, since it's \emph{known} that the \texttt{tmp} object ceases to
exist following the move-assignment:
        \begin{verbatim}
    Strings::Strings(Strings &&tmp)
    :
        d_string(tmp.d_string),
        d_size(tmp.d_size),
        d_capacity(tmp.d_capacity)
    {
        tmp.d_string = 0;
        tmp.d_capacity = 0;
        tmp.d_size = 0;
    }
\end{verbatim}
Other variations are possible as well. The bottom line: the move construcor
must ensure that after the destination object has grabbed the source object's
data the source object remains in a valid state. That's easily accomplished by
assigning the same values to its data members as set by the default
constructor.

\subsection{Move-only classes}
    \typeout{Original Yodl file: memory/moveonly}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
 \emph{factory functions}\index{factory function} 
    (functions returning an object constructed by the function) can easily be
implemented. E.g.,
        \begin{verbatim}
    // assume char *filename
    ifstream inStream(openIstream(filename));
\end{verbatim}
For this example to work an \texttt{ifstream} constructor must offer a move
constructor. This ensures that only one object refers to the open \texttt{istream}.

Once classes offer move semantics their objects can also safely be stored
in standard containers (cf. chapter \ref{CONTAINERS}). 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.

\subsection{Default move constructors and assignment operators}
    \typeout{Original Yodl file: memory/default}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 copy constructors c.q. assignment
operators are called.  The compiler also attempts to provide default
implementations for move constructors and move assignment operators. However,
the default constructors and assignment operators cannot always be provided.

These are the rules the compiler applies when deciding what to provide or not
to provide:
    \begin{itemize}
    \item  If the copy constructor, the copy assignment operator,
or a destructor is declared (even if it's declared using \texttt{= default}),
then the default move constructor and move assignment operator are suppressed;
their use is replaced by the corresponding copy operation (constructor or
assignment operator);

\item  If the move constructor or the move assignment operator is declared
then the copy constructor and the copy assignment operator are implicitly
declared as deleted, and can therefore not be used anymore;

\item  If \emph{either} the move constructor \emph{or} the move assignment
operator is declared, then (in addition to suppressing the copy operations)
the default implementation of the other move-member is also suppressed;

\item  In all other cases the default copy and move constructors \emph{and} the
default copy and assignment operators are provided.
    \end{itemize}

If default implementations of copy or move constructors or assignment
operators are suppressed, but they should be available, then it's easy to
provide the default implementations by specifying the required signatures, to
which the specification `\texttt{= default}' is added.

Here is an example of a class offering all defaults: constructor, copy
constructor, move constructor, copy assignment operator and move assignment
operator:
        \begin{verbatim}
    class Defaults
    {
        int d_x;
        Mov d_mov;
    };
\end{verbatim}
Assuming that \texttt{Mov} is a class offering move operations in addition
to the standard copy operations, then the following actions are performed
on the destination's \texttt{d\_mov} and \texttt{d\_x}:
        \begin{verbatim}
    Defaults factory();

    int main()
    {                              Mov operation:    d_x:
                                   ---------------------------
      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)
    }
\end{verbatim}
If, \texttt{Defaults} declares at least one constructor (not being the copy- or
move constructor) as well as the copy assignment operators then only the
default copy- and declared assignment operator are available. E.g.:

\begin{verbatim}
    class Defaults
    {
        int d_x;
        Mov d_mov;

        public:
            Defaults(int x);
            Defaults &operator=(Default const &rhs);
    };

    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());   Mov(Mov const &),        one.d_x

      one = two;                   Mov::operatpr=(          two.d_x
                                        Mov const &)
      one = factory();             Mov::operator=(          tmp.d_x
                                        Mov const &)
    }
\end{verbatim}
To reestablish the defaults, append \texttt{= default} to the appropriate
declarations:
        \begin{verbatim}
    class Defaults
    {
        int d_x;
        Mov d_mov;

        public:
            Defaults()               = default;
            Defaults(int x);
            // Defaults(Default const &) remains available (by default)

            Defaults(Defaults &&tmp) = default;

            Defaults &operator=(Defaults const &rhs);
            Defaults &operator=(Defaults &&tmp) = default;
    };
\end{verbatim}
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 \index{= default}\texttt{= default} suffix can only be used when declaring constructors or
assignment operators in the class's public section.

\subsection{Moving: implications for class design}\label{MOVEPRINCIPLE}
    \typeout{Original Yodl file: memory/moveimplications}Here are some general rules to apply when designing classes offering value
semantics (i.e., classes whose objects can be used to initialize other
objects of their class and that can be asssigned to other objects of their
class):
    \begin{itemize}
    \item  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;
    \item  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;
    \item  Classes using composition may benefit from move constructors and
move assignment operators as well. Some classes support neither move 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.
    \end{itemize}

In the previous sections we've also encountered an important  design
        \index{move: design principle}
    principle that can be applied to move-aware classes:
    \begin{quote}
    \emph{Whenever a member of a class receives a \texttt{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.}
    \end{quote}
    The former function can now call the latter by passing \texttt{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
\emph{move-aware} with respect to the involved function.

We've seen an initial example of the use of this principle in section
\ref{REVISEDASS}. 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.

\section{Copy Elision and Return Value Optimization}\label{RVO}
\typeout{Original Yodl file: memory/elision.yo}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.

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 \texttt{T} if the argument
is:
    \begin{itemize}
    \item  a \emph{named}  argument (an lvalue or a named rvalue)
        \begin{center}
    \begin{tabular}{ccc}

        \hline

        
 &   \multicolumn{2}{c}{the argument is:} \\

        

             &   non-const &   const
         \\

        \hline

        

            Use the topmost &  (T \&) & 
         \\

        

            available function &  (T const \&) &   (T const \&)
         \\

        \hline

    
\end{tabular}
        \end{center}
        Example: for an \texttt{int x} argument a function \texttt{fun(int \&)} is
selected rather than a function \texttt{fun(int const \&)}. If no \texttt{fun(int \&)} is
available the \texttt{fun(int const \&)} function is used. If neither is available
(and \texttt{fun(int)} hasn't been defined instead) the compiler reports an error.

\item  an \emph{anonymous} argument (an anonymous temporary or a literal value)
        \begin{center}
    \begin{tabular}{ccc}

        \hline

        
 &   \multicolumn{2}{c}{the argument is:} \\

        

             &  non-const &   const
         \\

        \hline

        

            Use the topmost &  (T \&\&) & 
         \\

        

            available function &  (T const \&) &   (T const \&)
         \\

        \hline

        
\end{tabular}\end{center}
        Example: when the return value of an \texttt{int arg()} function is passed
to a function \texttt{fun} for which various overloaded versions are available
\texttt{fun(int \&\&)} is selected. If this function is unavailable but \texttt{fun(int
const \&)} is, then the latter function is used.  If none of these two
functions is available the compiler reports an error.
        \end{itemize}
    The tables show that eventually \emph{all} arguments can be used with a
function specifying a \texttt{T const \&} parameter. For \emph{anonymous} arguments a
similar \emph{catch all} is available having a higher priority: \texttt{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 \texttt{T const \&} parameter. Since
the temporary can apparently not be modified a function defining a \texttt{T const
\&\&} parameter has no alternative but to copy the temporary's resources. As
this task is already performed by functions expecting a \texttt{T const \&}, there
is no need for implementing functions expecting \texttt{T const \&\&} parameters, and
it's considered bad style if you do.

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 \emph{no} copy and \emph{not} moving is
more efficient than copying or moving.

The option the compiler has to avoid making copies (or perform move
operations) is called \index{copy elision}\emph{copy elision} or \index{return value optimization}\emph{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:
    \begin{itemize}
    \item  if a copy or move constructor exists, try copy elision
    \item  if a move constructor exists, move.
    \item  if a copy constructor exists, copy.
    \item  report an error
    \end{itemize}
 All modern compilers apply copy elision. Here are some examples where it may
be encountered:
        \begin{verbatim}
    class Elide;

    Elide fun()         // 1
    {
        Elide ret;
        return ret;
    }

    void gun(Elide par);

    Elide elide(fun()); // 2

    gun(fun());         // 3
\end{verbatim}
\begin{itemize}
    \item  At 1 \texttt{ret} may never exist. Instead of using \texttt{ret} and copying
\texttt{ret} eventually to \texttt{fun}'s return value it may directly use the area used
to contain \texttt{fun}'s return value.
    \item  At 2 \texttt{fun}'s return value may never exist. Instead of defining an
area containing \texttt{fun}'s return value and copying that return value to
\texttt{elide} the compiler may decide to use \texttt{elide} to create \texttt{fun}'s return
value in.
    \item  At 3 the compiler may decide to do the same for gun's \texttt{par}
parameter: \texttt{fun}'s return value is directly created in \texttt{par}'s area, thus
eliding the copy operation from \texttt{fun}'s return value to \texttt{par}.
    \end{itemize}

\section{Unrestricted Unions}\label{UNIONS}
\typeout{Original Yodl file: memory/unrestricted}Standard (\textbf{C}-type) unions can only have fields of basic types, like \texttt{int,
double} and pointers. \textbf{C++} extends the \textbf{C}-type union concept by offering 
    \index{unrestricted union}\emph{unrestricted unions}.

Unrestricted unions also allow data fields of types for which non-trivial copy
constructors were defined. Such data fields commonly are of class-types. Here
is an example of such an unrestricted union:
        \begin{verbatim}
    union Union
    {
        int u_int;
        std::string u_string;
    };
\end{verbatim}
One of its fields is defined as a \texttt{std::string} (having a constructor),
turning this union into an \emph{unrestricted} union.  As an unrestricted union
defines at least one field of a type having a constructor the question becomes
how these unions can be constructed and destroyed.

The destructor of a union consisting of, e.g. a \texttt{std::string} and an
\texttt{int} should of course not call the \texttt{string}'s destructor if the
union's last (or only) use referred to its \texttt{int} field. Likewise, when
the \texttt{std::string} field is used, and processing switches from the
\texttt{std::string} to the \texttt{int} field, \texttt{std::string}'s destructor
should be called before any assignment to the \texttt{int} field takes place.

The compiler does not solve the issue for us, and in fact does not at all
implement default constructors or destructors for unrestricted unions. If we
try to define an unrestricted union like the one shown above, an error message
is issued. E.g.,
        \begin{verbatim}
    error: use of deleted function 'Union::Union()'
    error: 'Union::Union()' is implicitly deleted because the default
            definition would be ill-formed:
    error: union member 'Union::u_string' with non-trivial
            'std::basic_string<...>::basic_string() ...'
\end{verbatim}
\subsection{Implementing the destructor}
    \typeout{Original Yodl file: memory/uniondestructor}Although the compiler won't provide (default) implementations for constructors
and destructors of unrestricted unions, \emph{we} can (and \emph{must}). The task
isn't difficult, but there are some caveats.

Consider our unrestricted union's destructor. It clearly should destroy
\texttt{u\_string}'s data if that is its currently active field; but it should do
nothing if \texttt{u\_int} is its currently active field. But how does the
destructor know what field to destroy? It doesn't, as the unrestricted union
contains no information about what field is currently active.

This problem is tackled by embedding the unrestricted union in a larger
aggregate (like a class or a struct) where it becomes a regular data
member. We still consider the unrestricted union a data type by itself, but
its use requires caution. The surrounding class is provided with a \emph{d\_field}
data member keeping track of the currently active union-field. The \texttt{d\_field}
value is an enumeration value which is defined by the union. The actual use of
the unrestricted union is completely controlled by the aggregate, freeing the
aggregate's users from any administration related to the unrestricted union.

Using this design we start out with an explicit and empty implementation of
the destructor, as there's no way to tell the destructor itself what field to
destroy:
        \begin{verbatim}
    Data::Union::~Union()
    {};
\end{verbatim}
Nevertheless, unrestricted unions must properly destroy their class-type
fields. Since an unrestricted union itself doesn't know what its active field
is, it must be informed about that by its surrounding class. To simplify the
generalization to other types a static array of pointers to functions
destroying the current field's value is used. This array is defined in the
union's private section as
        \begin{verbatim}
    static void (Union::*s_destroy[])();
\end{verbatim}
and it is initialized as:
        \begin{verbatim}
    void (Union::*Union::s_destroy[])() = 
    {
        &Union::destroyText,
        &Union::destroyValue
    };
\end{verbatim}
Primitive data types normally don't need any special attention when they
go out of scope, so \texttt{destroyValue} can be defined as an empty function:
        \begin{verbatim}
    void Union::destroyValue()
    {}
\end{verbatim}
On the other hand, the member \texttt{destroyText} must explicitly call
\texttt{u\_text's} destructor:
        \begin{verbatim}
    void Union::destroyText()
    {
        u_text.std::string::~string();
    }
\end{verbatim}
Proper destruction can now be realized by a single function \texttt{void
destroy(Field field)} which simply calls the appropriate function:
        \begin{verbatim}
    void Union::destroy(Field type)
    {
        (this->*s_destroy[type])();
    }
\end{verbatim}
Since the unrestricted union is defined as a data member of a surrounding
class, the surrounding class's destructor is responsible for the proper
destruction of its unrestricted union. As the surrounding class keeps track of
the currently active unrestricted union's field its implementation is easy:
        \begin{verbatim}
    Data::~Data()
    {
        d_union.destroy(d_field);
    }
\end{verbatim}
\subsection{Embedding an unrestricted union in a surrounding class}
    \typeout{Original Yodl file: memory/unionembedding}The unrestricted union becomes a data member of the surrounding aggregate
(e.g., \texttt{class Data}). The \texttt{class Data} is provided with a data member
\texttt{Union::Field d\_field} and \texttt{Data}'s users might query the currently active
field from, e.g., an accessor \texttt{field}:

\begin{verbatim}
    class Data
    {
        Union::Field d_field;
        Union d_union;
    
        public:
            Data(int value = 0);
            Data(Data const &other);
            Data(Data &&tmp);
            Data(std::string const &text);

            ~Data();                // empty body

            Union::Field field() const;
            ...
    };
\end{verbatim}
\texttt{Data}'s constructors receive \texttt{int} or \texttt{string} values. To pass these
values to \texttt{d\_union}, we need \texttt{Union} constructors for the various union
fields.

The unrestricted union itself starts out like this:
        \begin{verbatim}
    union Union
    {
        enum Field
        {
            TEXT,
            VALUE
        };
    
        private:
            std::string u_text;
            int u_value;
    
        public:
            Union(Union const &other) = delete;
            ~Union();               // empty
    
            Union(int value);
            Union(std::string const &text);

            Union(Union const &other, Field type);
            Union(Union &&tmp, Field type);
            ...
    };
\end{verbatim}
The last two \texttt{Union} constructors are comparable to the standard copy-
and move constructors. With unrestricted unions, however, the existing union's
actual type needs to be specified so that the correct field is initialized.
To simplify the generalization to other types we apply a procedure that is
comparable to the procedure we followed for destroying an understricted union:
we define a static array of pointers to copy-functions. This array is declared
in the union's private section as
        \begin{verbatim}
    static void (Union::*s_copy[])(Union const &other);
\end{verbatim}
and it is defined as:
        \begin{verbatim}
    void (Union::*Union::s_copy[])(Union const &other) = 
    {
        &Union::copyText,
        &Union::copyValue
    };
\end{verbatim}
The \texttt{copyText} and \texttt{copyValue} private members are responsible for
copying \texttt{other's} data fields. However, there is a little snag. Although
basic types can directly be assigned, class-type fields cannot.  Destination
fields cannot be initialized using member initializers as the field to
initialize depends on the \texttt{Field} type that's passed to the
constructor. Because of that the initialization must be performed inside the
constructors' bodies. At that point the data fields are
merely a series of uninitialized bytes, and so placement new is used to
copy-construct class-type fields. Here are the implementations of the copy
functions:
        \begin{verbatim}
    void Union::copyValue(Union const &other)
    {
        u_value = other.u_value;
    }

    void Union::copyText(Union const &other)
    {
        new(&u_text) string{ other.u_text };
    }
\end{verbatim}
When implementing the union's move constructor other considerations must be
taken into account. Since we're free to do whatever we want with the move
constructor's \texttt{Union \&\&tmp} object, we can simply grab its current field,
and store a \texttt{VALUE} type of value into \texttt{tmp}. For that we use the
\texttt{Union's} \texttt{swap} facility, the current object's field, another \texttt{Union}
object, and the other \texttt{Union's} field type (swapping is discussed in the
next section). Of course, if there isn't any primitive typed field this
doesn't work. In that case field-specific move functions must be used,
comparable to the ones used when copy-constructing a \texttt{Union} object.

Now we're ready for the constructors' implementations:
        \begin{verbatim}
    Union::Union(std::string const &text)
    :
        u_text(text)
    {}
    
    Union::Union(int value)
    :
        u_value(value)
    {}

    Union::Union(Union &&tmp, Field type)
    {
        swap(VALUE, tmp, type);
    }

    Union::Union(Union const &other, Field type)
    {
        (this->*s_copy[type])(other);
    }

    Data::Data(Data const &other)
    :
        d_field(other.d_field),
        d_union(other.d_union, d_field)
    {}
    
    Data::Data(Data &&tmp)
    :
        d_field(Union::VALUE),
        d_union(0)
    {
        swap(tmp);      // see the next section
    }

    Data::Data(int value)
    :
        d_field(Union::VALUE),
        d_union(value)
    {}
\end{verbatim}
\subsection{Swapping unrestricted unions}
    \typeout{Original Yodl file: memory/unionswap}Unrestricted unions should define a non-throwing \texttt{swap} member. It needs
three arguments: the current object's field, another union object, and that
union's field. The prototype of our unrestricted union's \texttt{swap} member,
therefore, is:
        \begin{verbatim}
    void swap(Field current, Union &other, Field next);
\end{verbatim}
To implement it similar considerations as encountered with the copy
constructor apply. An unrestricted union having \emph{k} fields must support \emph{k
$*$ k} different swap situations. Representing these in a \emph{k $*$ k} matrix we
note that the diagonal elements refer to swapping identical elements for which
no special considerations apply (assuming swapping of identical data types is
supported). The lower-triangle elements are identical to their transposed
upper-triangle elements, and so they can use those elements after reverting
the current and other union objects. All field-specific swap functions can be
organized in a \emph{k x k} static matrix of pointers to swapping members. For
\texttt{Union} the declaration of that matrix is
        \begin{verbatim}
    static void (Union::*s_swap[][2])(Union &other);
\end{verbatim}
and its definition is
        \begin{verbatim}
    void (Union::*Union::s_swap[][2])(Union &other) = 
    {
      {  &Union::swap2Text,     &Union::swapTextValue},
      {  &Union::swapValueText, &Union::swap2Value},
    };
\end{verbatim}
The diagonal and lower-triangle elements are
straightforwardly implemented. E.g.,
        \begin{verbatim}
    void Union::swap2Text(Union &other)
    {
        u_text.swap(other.u_text);
    }

    void Union::swapValueText(Union &other)
    {
        other.swapTextValue(*this);
    }
\end{verbatim}
but implementing the upper-triangle elements requires some thought. To
install a class-type field placement new must again be used. But this time
we're not copying but moving, as the current object is going to lose its
content. Like swapping, moving should always succeed. Following the move
construction the other object has received the current object's data. As the
current object keeps its valid state after the move, it must also explicitly
be destroyed to properly end its lifetime. Here is the implementation of
\texttt{swapTextValue}:
        \begin{verbatim}
    void Union::swapTextValue(Union &other)
    {
        int value = other.u_value;  // save the int value
                                    // install string at other
        new(&other.u_text) string{ std::move(u_text) }; 
        u_text.~string();           // remove the old field's union
    
        u_value = value;            // store current's new value
    }
\end{verbatim}
When an unrestricted union has multiple class-type fields then when
swapping move construction must be applied to both unrestricted unions. This
requires a temporary. Assume an unrestricted union supports fields of classes
\texttt{This} and \texttt{That} then to swap unrestricted unions using, respectively the
\texttt{This} and \texttt{That} fields we do as follows:
        \begin{verbatim}
    void ThisThat::swapThisThat(ThisThat &other)
    {
        This tmp{ std::move(u_this) };  // save the current object
        u_this.~This();                 // properly destroy it

                                        // install the other object at
                                        // this object
        new(&u_that) That{ std::move(other.u_that) };
        other.u_that.~That();           // properly destroy the other 
                                        // object

                                        // install this object's original 
                                        // value at the other object
        new(&other.u_this) This{ std::move(tmp) };

    }                                   // tmp is automatically destroyed
\end{verbatim}
Now that unrestricted unions can be swapped, their \texttt{swap} member can be
used by \texttt{swap} members of surrounding classes. E.g.,
        \begin{verbatim}
    void Data::swap(Data &other)
    {
        d_union.swap(d_field, other.d_union, other.d_field);
    
        Union::Field field = d_field;   // swap the fields
        d_field = other.d_field;
        other.d_field = field;
    }
\end{verbatim}
\subsection{Assignment}
    \typeout{Original Yodl file: memory/unionassignment}There are two ways to assign a \texttt{Data} object to another one: copy assignment
and move assignment. Their implementations are standard:
        \begin{verbatim}
    Data &Data::operator=(Data const &other)    // copy-assignment
    {
        Data tmp{ other };
        swap(tmp);
        return *this;
    }

    Data &Data::operator=(Data &&tmp)           // move-assignment
    {
        swap(tmp);
        return *this;
    }
\end{verbatim}
Since \texttt{swap} has already been defined the assignment operators need no
further attention: they are implemented using their standard implementations.

When unrestricted unions are used outside of surrounding classes a
situation may arise where two unrestricted unions are directly assigned to
each other. In that case the unions' active fields must somehow be
available. Since \texttt{operator=} can only be defined having one parameter,
simply passing an unrestricted union as its rvalue would lack information
about the lvalue's and rvalue's active fields. Instead two members are
suggested: \texttt{copy}, doing copy assignment and \texttt{move}, doing move
assignment. Their implementations closely resemble those of the standard
assignment operators:
        \begin{verbatim}
    void Union::copy(Field type, Union const &other, Field next)
    {
        Union tmp{ other, next };   // create a copy
        swap(type, tmp, next);      // swap *this and tmp
        tmp.destroy(type);          // destroy tmp
    }
        
    void Union::move(Field type, Union &&tmp, Field next)
    {
        swap(type, tmp, next);
    }
\end{verbatim}
In the source distribution you'll find a directory
\texttt{yo/memory/examples/unions}. It contains a small demo-program in which
\texttt{Union} and \texttt{Data} are used.

\section{Aggregate Data Types}\label{POD}
\typeout{Original Yodl file: memory/aggregate}\textbf{C++} inherited the struct concept from \textbf{C} and extended it with the class
concept. Structs are still used in \textbf{C++}, mainly to store and pass around
aggregates of different data types. A commonly used term for these structs is
\index{aggregate}\emph{aggregate} (in some languages known as \index{plain old data}\emph{plain old data}
(\index{pod}pod)). Aggregates are commonly used in \textbf{C++} programs to merely combine
data in dedicated (struct) types. E.g., when a function must return a
\texttt{double}, a \texttt{bool} and \texttt{std::string} these three different data types
may be aggregated using a \texttt{struct} that merely exists to pass along
values. Data protection and functionality is hardly ever an issue. For such
cases \textbf{C} and \textbf{C++} use \texttt{structs}. But as a \textbf{C++} \texttt{struct} is just a
\texttt{class} with special access rights some members (constructors, destructor,
overloaded assignment operator) may implicitly be defined. Aggregates
capitalize on this concept by requiring that their definitions remain as
simple as possible, showing the following characteristics:
    \begin{itemize}
    \item  there are no user provided constructors or user provided inherited
        constructors  (cf. chapter \ref{INHERITANCE}); 
    \item  their non-static data members have public access rights;
    \item  they have no virtual members;
    \item  when using inheritance, the base classes aren't virtual and only
        public inheritance is used.
    \end{itemize}

Aggregates can also be arrays, in which case the array elements are the
aggregate's elements. If an aggregate is a \texttt{struct} its direct base classes
are its elements (if any), followed by the \texttt{struct's} data members, in their
declaration order. Here is an example:
        \begin{verbatim}
    struct Outer
    {
        struct Inner
        {
            int     d_int;
            double  d_double;
        };

        std::string d_string;
        Inner d_inner;
    };

    Outer out{ "hello", { 1, 12.5} };
\end{verbatim}
\texttt{Outer out's d\_string} is initialized with \texttt{hello"}, its \texttt{d\_inner}
member has two data members: \texttt{d\_int} is initialized to 1, \texttt{d\_double} to
12.5.

(Designated) initializer lists can also be used (cf. section
\ref{INILIST}). Also, often \emph{structured binding declarations} (cf. section
\ref{STRUCTBIND}) can be used to avoid explicitly defining an aggregate data
type.

\section{Conclusion}
\typeout{Original Yodl file: memory/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
\emph{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
\emph{destructor}, an \emph{overloaded assignment operator} and a
 \emph{copy constructor}. Implementing a \emph{move constructor} remains
optional, but it allows us to use \emph{factory functions} with classes \emph{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 \emph{copy elision}. The compiler is free to
use copy elision wherever possible; it is, 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.


\cleardoublepage\chapter{Exceptions}\label{EXCEPTIONS}
\typeout{Original Yodl file: exceptions}\typeout{Original Yodl file: exceptions/intro}\textbf{C} supports several ways for a program to react to situations breaking
the normal unhampered flow of a program:
    \begin{itemize}
    \item  The function may notice the abnormality and issue a message. This is
probably the least disastrous reaction a program may show.
    \item  The function in which the abnormality is observed may decide to stop
its intended task, returning an \index{error code}error code to its caller. This is a great
example of \index{postponing decisions}postponing decisions: now the \emph{calling function} is faced with
a problem. Of course the calling function may act similarly, by passing the
error code up to \emph{its} caller.
    \item  The function may decide that things are going out of hand, and may
call \index{exit}\texttt{exit} to terminate the program completely. A tough way to handle a
problem if only because the destructors of local objects aren't activated.
    \item  The function may use a combination of the functions \index{setjmp}\texttt{setjmp} and
\index{longjmp}\texttt{longjmp} to enforce non-local exits. This mechanism implements a kind
of \index{goto}\texttt{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.
    \end{itemize}
    In \textbf{C++} all these \index{flow-breaking methods}flow-breaking methods are still
available. However, of the mentioned alternatives, \texttt{setjmp} and
\texttt{longjmp}  isn't frequently encountered in \textbf{C++} (or even in \textbf{C})
programs, due to the fact that the program flow is completely disrupted.

\textbf{C++} offers \index{exceptions}\emph{exceptions} as the preferred alternative to, e.g.,
\texttt{setjmp} and \texttt{longjmp}. Exceptions allow \textbf{C++} programs to perform a
controlled \index{non-local return}non-local return, without the disadvantages of \texttt{longjmp} and
\texttt{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 \index{return}\texttt{return} and the crude \index{exit}\texttt{exit}.

In this chapter exceptions are covered. First an example is given of the
different impact exceptions and the \texttt{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.

\section{Exception syntax}
\typeout{Original Yodl file: exceptions/syntax}Before contrasting the traditional \textbf{C} way of handling non-local gotos with
exceptions let's introduce the  \index{syntactic elements}syntactic elements that are involved when
using exceptions.
    \begin{itemize}
    \item  Exceptions are generated by a \index{throw}\texttt{throw} statement. The keyword
\texttt{throw}, followed by an expression of a certain type, throws the expression
value as an exception. In \textbf{C++} anything having value semantics may be
thrown as an exception: an \texttt{int}, a \texttt{bool}, a \texttt{string}, etc. However,
there also exists a \emph{standard exception} type (cf. section \ref{STDEXC}) that
may be used as \emph{base class} (cf. chapter \ref{INHERITANCE}) when defining new
exception types.

\item  Exceptions are generated within a well-defined local environment,
called a \texttt{try}-block. The run-time support system ensures that all of the
program's code is itself surrounded by a \index{global \texttt{try} block}\emph{global \texttt{try} block}. Thus, every
exception generated by our code will always reach the boundary of at least one
\texttt{try}-block.  A program terminates when an exception reaches
the boundary of the global \texttt{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 \texttt{try}-block explicitly defined by
the program. Here is an example of a string exception thrown from within a
\texttt{try}-block:
    \begin{verbatim}
try
{
    // any code can be defined here
    if (someConditionIsTrue)
        throw "this is the std::string exception"s;
    // any code can be defined here
}
\end{verbatim}
\item \index{catch}\texttt{catch}: Immediately following the \texttt{try}-block, one or more
\texttt{catch}-clauses must be defined. A \texttt{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:
    \begin{verbatim}
catch (string const &msg)
{
    // statements in which the caught string object are handled
}
\end{verbatim}
Multiple \texttt{catch} clauses may appear underneath each other, one for each
exception type that has to be caught. In general the \texttt{catch} clauses may
appear in any order, but there are exceptions requiring a specific order. To
avoid confusion it's best to put a \texttt{catch} clause for the most general
exception last. At most \emph{one} exception clause will be activated. \textbf{C++}
does not support a \textbf{Java}-style \texttt{finally}-clause activated after
completing a catch clause.
    \end{itemize}

\section{An example using exceptions}\label{BASICEXCEPTION}
\typeout{Original Yodl file: exceptions/example}In the following examples the same basic program is used. The program uses
two classes, \texttt{Outer} and \texttt{Inner}.

First, an \texttt{Outer} object is defined in \texttt{main}, and its member
\texttt{Outer::fun} is called.  Then, in \texttt{Outer::fun} an \texttt{Inner} object is
defined. Having defined the \texttt{Inner} object, its member \texttt{Inner::fun} is
called.

That's about it. The function \texttt{Outer::fun} terminates calling
\texttt{inner}'s destructor. Then the program terminates, activating
\texttt{outer}'s destructor. Here is the basic program:
        \begin{verbatim}
    #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();
    }

    /*
        Generated output:
    Outer constructor
    Inner constructor
    Outer fun
    Inner fun
    Inner destructor
    Outer destructor
    */
\end{verbatim}
    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 \texttt{Inner::fun} function. This event must supposedly be
handled near \texttt{main}'s end.

We'll consider two variants. In the first variant the event is handled by
\index{setjmp}\texttt{setjmp} and \index{longjmp}\texttt{longjmp}; in the second variant the event is handled using
\textbf{C++}'s exception mechanism.

\subsection{Anachronisms: `setjmp' and `longjmp'}\label{EXCEPTIONJMP}
    \typeout{Original Yodl file: exceptions/jmp}The basic program from the previous section is slightly modified to contain a
variable
 \index{jmp\_buf} \texttt{jmp\_buf jmpBuf} used by \index{setjmp}\texttt{setjmp} and \index{longjmp}\texttt{longjmp}.

The function \texttt{Inner::fun} calls \texttt{longjmp}, simulating a disastrous
event, to be handled near \texttt{main}'s end. In \texttt{main} a target location for
the long jump is defined through the function \texttt{setjmp}. \texttt{Setjmp}'s zero
return indicates the initialization of the \texttt{jmp\_buf} variable, in which case
\texttt{Outer::fun} is called. This situation represents the `normal flow'.

The program's return value is zero \emph{only} if \texttt{Outer::fun} terminates
normally. The program, however, is designed in such a way that this won't
happen: \texttt{Inner::fun} calls \texttt{longjmp}. As a result the execution flow
returns to the \texttt{setjmp} function. In this case it does \emph{not} return a zero
return value. Consequently, after calling \texttt{Inner::fun} from \texttt{Outer::fun}
\texttt{main}'s \texttt{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
\ref{BASICEXCEPTION}:
        \begin{verbatim}
    #include <iostream>
    #include <setjmp.h>
    #include <cstdlib>

    using namespace std;

    jmp_buf jmpBuf;

    class Inner
    {
        public:
            Inner();
            ~Inner();
            void fun();
    };

    Inner::Inner()
    {
        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
    */
\end{verbatim}
    This program's output clearly shows that \texttt{inner}'s destructor is not
called. This is a direct consequence of the non-local jump performed by
\texttt{longjmp}. Processing proceeds immediately from the \texttt{longjmp} call inside
\texttt{Inner::fun} to \texttt{setjmp} in \texttt{main}. There, its return value is unequal
zero, and the program terminates with return value 1. Because of the non-local
jump \texttt{Inner::\textasciitilde{}Inner} is never executed: upon return to \texttt{main}'s \texttt{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 \texttt{longjmp} and \texttt{setjmp} are used and \textbf{C++} programs should therefore
avoid those functions like the plague.

\subsection{Exceptions: the preferred alternative}
    \typeout{Original Yodl file: exceptions/exception}Exceptions are \textbf{C++}'s answer to the problems caused by \texttt{setjmp} and
\texttt{longjmp}. Here is an example using exceptions. The program is once again
derived from the basic program of section \ref{BASICEXCEPTION}:
        \begin{verbatim}
    #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()
    {
        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
    */
\end{verbatim}
    \texttt{Inner::fun} now throws an \texttt{int} exception where a \texttt{longjmp} was
previously used. Since \texttt{in.fun} is called by \texttt{out.fun}, the exception is
generated within the \texttt{try} block surrounding the \texttt{out.fun} call. As an
\texttt{int} value was thrown this value reappears in the \texttt{catch} clause beyond
the \texttt{try} block.

Now \texttt{Inner::fun} terminates by throwing an exception instead of calling
\texttt{longjmp}. The exception is caught in \texttt{main}, and the program
terminates. Now we see that \texttt{inner}'s destructor is properly called.  It is
interesting to note that \texttt{Inner::fun}'s execution really terminates at the
\texttt{throw} statement: The \texttt{cout} statement, placed just beyond the \texttt{throw}
statement, isn't executed.

What did this example teach us?
    \begin{itemize}
    \item  Exceptions provide a means to break a function's (and program's)
normal flow without having to use a cascade of \texttt{return}-statements, and
without the need to terminate the program using blunt tools like the function
\index{exit}\texttt{exit}.
    \item  Exceptions do not disrupt the proper activation of destructors. Since
\texttt{setjmp} and \texttt{longjmp} \emph{do} distrupt the proper activation of
destructors their use is strongly deprecated in \textbf{C++}.
    \end{itemize}

\section{Throwing exceptions}\label{THROW}
\typeout{Original Yodl file: exceptions/throw}Exceptions are generated by \index{throw}\texttt{throw} statements. The \texttt{throw} keyword is
followed by an expression, defining the thrown exception value.  Example:
        \begin{verbatim}
    throw "Hello world";        // throws a char *
    throw 18;                   // throws an int
    throw string{ "hello" };    // throws a string
\end{verbatim}
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 \texttt{catch} clause.

The following examples illustrates this process.
\texttt{Object::fun} defines a local \texttt{Object toThrow}, that is
thrown as an exception. The exception is caught
in \texttt{main}. But by then the object originally thrown doesn't exist anymore,
and \texttt{main} received a copy:
        \begin{verbatim}
    #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
        {
            out.fun();
        }
        catch (Object o)
        {
            cout << "Caught exception\n";
            o.hello();
        }
    }
\end{verbatim}
    \texttt{Object}'s copy constructor is special in that it defines its name as
the other object's name to which the string \texttt{" (copy)"} is appended. This
allow us to monitor the construction and destruction of objects more closely.
\texttt{Object::fun} generates an exception, and throws its locally defined
object. Just before throwing the exception the program has produced the
following output:
        \begin{verbatim}
    Constructor of 'main object'
    Constructor of 'local object'
    Calling fun of 'main object'
\end{verbatim}
When  the exception is generated the next line of output is produced:
        \begin{verbatim}
    Copy constructor for 'local object' (copy)
\end{verbatim}
The local object is passed to \texttt{throw} where it is treated  as a value
argument, creating a copy of \texttt{toThrow}. This copy is thrown as the
exception, and the local \texttt{toThrow} object ceases to exist. The thrown
exception is now caught by the \texttt{catch} clause, defining an
\texttt{Object} value parameter. Since this is a \emph{value} parameter yet another
copy is created. Thus, the program writes the following text:
        \begin{verbatim}
    Destructor of 'local object'
    Copy constructor for 'local object' (copy) (copy)
\end{verbatim}
The \texttt{catch} block now displays:
        \begin{verbatim}
    Caught exception
\end{verbatim}
Following this \texttt{o}'s  \texttt{hello} member is called, showing us that we
indeed received a \emph{copy of the copy} of the original \texttt{toThrow} object:
        \begin{verbatim}
    Hello by 'local object' (copy) (copy)
\end{verbatim}
Then the program terminates and its remaining  objects are now
destroyed, reversing  their order of creation:
        \begin{verbatim}
    Destructor of 'local object' (copy) (copy)
    Destructor of 'local object' (copy)
    Destructor of 'main object'
\end{verbatim}
The copy created by the \texttt{catch} clause clearly is superfluous. It can be
avoided by defining object \emph{reference parameters} in \texttt{catch} clauses:
`\texttt{catch (Object \&o)}'. The program now produces the following output:
        \begin{verbatim}
    Constructor of 'main object'
    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'
\end{verbatim}
Only a single copy of \texttt{toThrow} was created.

It's a bad idea to \index{throw: pointer} throw a \emph{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
\index{wild pointer}wild pointer. Bad news....

Let's summarize the above findings:
    \begin{itemize}
    \item  Local objects are thrown as copied objects;
    \item  Don't throw pointers to local objects;
    \item  It is possible to throw pointers to \emph{dynamically} generated
objects. In this case one must take care that the generated object is properly
deleted by the exception handler to prevent a \index{memory leak}memory leak.
    \end{itemize}
    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:
        \begin{verbatim}
    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";
\end{verbatim}
Where these \texttt{throw} statements are located is irrelevant: they may be
found deeply nested inside the program, or at a more superficial level.
Furthermore, \emph{functions} may be used to generate the exception to be
thrown. An \texttt{Exception} object might support stream-like insertion operations
allowing us to do, e.g.,
        \begin{verbatim}
    if (!lookup(variableName))
        throw Exception() << "Undefined variable '" << variableName << "';
\end{verbatim}
\subsection{The empty `throw' statement}\label{EMPTYTHROW}
    \typeout{Original Yodl file: exceptions/emptythrow}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 \index{throw: empty} \emph{empty} \texttt{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 \emph{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
        \begin{verbatim}
    initialExceptionHandler(string &exception)
\end{verbatim}
could be designed to handle the \texttt{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 \texttt{initialExceptionHandler}'s
implementation the empty \texttt{throw} statement is used:
        \begin{verbatim}
    void initialExceptionHandler(string &exception)
    {
        if (!plainMessage(exception))
            throw;

        handleTheMessage(exception);
    }
\end{verbatim}
Below (section \ref{EXCEPTIONCATCH}), the empty \texttt{throw} statement is used
to pass on the exception received by a \texttt{catch}-block. Therefore, a function
like \texttt{initialExceptionHandler} can be used for a variety of thrown
exceptions, as long as their types match \texttt{initialExceptionHandler}'s
parameter, which is a string.

The next example jumps slightly ahead, using some of the topics covered in
chapter \ref{POLYMORPHISM}. 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 \texttt{Exception}, having a
member function \texttt{ExceptionType Exception::severity}.  This member function
tells us (little wonder!) the severity of a thrown exception. It might be
\texttt{Info, Notice, Warning, Error} or \texttt{Fatal}.  The information contained in
the exception depends on its severity and is processed by a function
\texttt{handle}. In addition, all exceptions support a member function like
\index{textMsg}\texttt{textMsg}, returning textual information about the exception in a
\texttt{string}.

By defining a polymorphic function \texttt{handle} it can be made to behave
differently, depending on the nature of a thrown exception, when called
from a basic \texttt{Exception} pointer or reference.

In this case, a program may throw any of these five exception types.  Assuming
that the classes \texttt{Message} and \texttt{Warning} were derived from the class
\texttt{Exception}, then the \texttt{handle} function matching the exception type will
automatically be called by the following exception catcher:
        \begin{verbatim}
    //
    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
    }
\end{verbatim}
Now anywhere in the \texttt{try} block preceding the exception handler
\texttt{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.,
        \begin{verbatim}
    throw Info{};
    throw Warning{};
    throw Notice{};
    throw Error{};
    throw Fatal{};
\end{verbatim}
\section{The try block}
\typeout{Original Yodl file: exceptions/try}The \index{try}\texttt{try}-block surrounds \texttt{throw} statements. Remember that a program is
always surrounded by a global \texttt{try} block, so \texttt{throw} statements may
appear anywhere in your code. More often, though, \texttt{throw} statements are
used in function bodies and such functions may be called from within \texttt{try}
blocks.

A \texttt{try} block is defined by the keyword \texttt{try} followed by a compound
statement. This block, in turn,  \emph{must} be followed by at least one
\texttt{catch} handler:
        \begin{verbatim}
    try
    {
                // any statements here
    }
    catch (...)  // at least one catch clause here
    {}
\end{verbatim}
\texttt{Try}-blocks are commonly nested, creating exception \emph{levels}. For
example, \texttt{main}'s code is surrounded by a \texttt{try}-block, forming an outer
level handling exceptions.  Within \texttt{main}'s \texttt{try}-block functions are
called which may also contain \texttt{try}-blocks, forming the next exception
level. As we have seen (section \ref{EMPTYTHROW}), exceptions thrown in
inner level \texttt{try}-blocks may or may not be processed at that level. By
placing an empty \texttt{throw} statement in an exception handler, the
thrown exception is passed on to the next (outer) level.

\section{Catching exceptions}\label{EXCEPTIONCATCH}
\typeout{Original Yodl file: exceptions/catch}A \index{catch}\texttt{catch} clause consists of the keyword \texttt{catch} followed by a parameter
list defining one parameter specifying type and (parameter) name of the
exception caught by that particular \texttt{catch} handler. This name may then be
used as a variable in the compound statement following the \texttt{catch} clause.
Example:
        \begin{verbatim}
    catch (string &message)
    {
        // code to handle the message
    }
\end{verbatim}
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
\emph{dynamically} allocated object may be thrown if the exception handler
deletes the allocated memory to prevent a \index{memory leak}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:
        \begin{verbatim}
    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?
    }
\end{verbatim}
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 \texttt{unique\_ptr} or
\texttt{shared\_ptr} (cf. sections \ref{UNIQUEPTR} and \ref{SHAREDPTR}).

Multiple \texttt{catch} handlers may follow a \texttt{try} block, each handler
defining its own exception type.  The \emph{order} \index{exception handler: 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 \texttt{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 \texttt{char $*$}s and \index{void *}\texttt{void $*$}s
then NTBSs are caught by the former handler. Note that a \texttt{char
$*$} can also be considered a \texttt{void $*$}, but the exception type matching
procedure is smart enough to use the \texttt{char $*$} handler with the thrown
NTBS. Handlers should be designed very type specific to catch the
correspondingly typed exception. For example, \texttt{int}-exceptions are not
caught by \texttt{double}-catchers, \texttt{char}-exceptions are not caught by
\texttt{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., \texttt{int} is not derived from \texttt{double}; \texttt{string} is not
derived from an NTBS):
        \begin{verbatim}
#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";
        }
    }
}
\end{verbatim}
    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 \ref{EMPTYTHROW}. Using this
approach, there's only one handler required, since we \emph{know} we don't throw
other types of exceptions:
        \begin{verbatim}
    try
    {
        // code throws only Exception objects
    }
    catch (Exception &ex)
    {
        ex.handle();
    }
\end{verbatim}
When the code of an exception handler has been processed, execution continues
beyond the last exception handler directly following the matching
\texttt{try}-block (assuming the handler doesn't itself use flow control statements
(like \texttt{return} or \texttt{throw}) to break the default flow of execution). The
following cases can be distinguished:
    \begin{itemize}
    \item  If \emph{no} exception was thrown within the \texttt{try}-block no exception
handler is activated, and execution continues from the last statement in
the \texttt{try}-block to the first statement beyond the last \texttt{catch}-block.
    \item  If an exception \emph{was} thrown within the \texttt{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.
    \item  If an exception was thrown from the \texttt{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 \texttt{catch}-block.
    \end{itemize}
    All statements in a \texttt{try} block following an executed
\texttt{throw}-statement are ignored. However, objects that were successfully
constructed within the \texttt{try} block before executing the \texttt{throw} statement
\emph{are} destroyed before any exception handler's code is executed.

\subsection{The default catcher}
    \typeout{Original Yodl file: exceptions/defaultcatch}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
\texttt{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 \ref{EXCEPTIONCATCH}) 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
\texttt{throw} statement (see section \ref{EMPTYTHROW}) 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:
    \begin{verbatim}
    #include <iostream>
    using namespace std;

    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
    */
\end{verbatim}
    The program's output illustrates that an empty \texttt{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 \ref{THREADING}), thrown exceptions can be
transferred between threads after converting \texttt{std::exception} objects to
\texttt{std::exception\_ptr} objects. This proceduce can even be used from inside
the default catcher. Refer to section \ref{EXCPTR} for further coverage of the
class \texttt{std::exception\_ptr}.

\section{Functions unable to throw exceptions: the `noexcept' keyword}
\typeout{Original Yodl file: exceptions/noexcept}Once a function has been defined it's often called from other functions. If
called functions are not defined in the same source file as calling functions
the called functions must be declared, for which header files are often
used. Those called functions might throw exceptions, which might be
unacceptible to the function calling those other functions. E.g., functions
like \texttt{swap} and destructors may not throw exceptions. 

Functions that may not throw exceptions can be declared and defined by
specifying the \index{noexcept}\texttt{noexcept} keyword (see section \ref{SYSTEMERROR} for examples
of function declarations specifying \texttt{noexcept}).

When using \texttt{noexept} there's a slight run-time overhead penalty because the
function needs an over-all \texttt{try-catch} block catching any exception that
might be thrown by its (called) code. When an exception is caught (violating
the \texttt{noexcept} specification) then the \texttt{catch} clause calls
\texttt{std::terminate}, ending the program.

In addition to using a plain \texttt{noexcept}, it can also be given an argument
that is evaluated compile-time (e.g., \texttt{void fun() noexcept(sizeof(int) ==
4)}): if the evaluation returns \texttt{true} then the \texttt{noexcept} requirement is
used; if the evaluation returns \texttt{false}, then the \texttt{noexcept} requirement
is ignored. Examples of this advanced use of \texttt{noexcept} are provided in
section \ref{NOEXCEPT}.

\section{Iostreams and exceptions}\label{IOEXCEPTIONS}
\typeout{Original Yodl file: exceptions/iostreams}The \textbf{C++} I/O library was used well before exceptions were available in
\textbf{C++}. Hence, normally the classes of the iostream library do not throw
exceptions. However, it is possible to modify that behavior using the
 \index{ios::exceptions}\texttt{ios::exceptions} member function. This function has two overloaded
versions:
    \begin{itemize}
    \item \index{exceptions (function)}\texttt{ios::iostate exceptions()}:\ \\ \index{iostate}this member returns the \index{state flags}state flags for which the
         stream will throw exceptions;
    \item \texttt{void exceptions(ios::iostate state)}\ \\ 
        \index{iostate}this member causes the stream to throw an exception
            when state \texttt{state} is observed.
    \end{itemize}

In the I/O library, exceptions are objects of the class
 \index{failure class} \texttt{ios::failure}, derived from \index{exception class}
\texttt{ios::exception}. A \texttt{std::string const \&message} may be specified when
defining a \texttt{failure} object. Its message may then be  retrieved using its
 \index{what} \texttt{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 \texttt{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:
        \begin{verbatim}
    #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';
                cin.clear();
                cin.ignore(INT_MAX, '\n');  // ignore the faulty line
            }
        }
    }
\end{verbatim}
By default, exceptions raised from within \texttt{ostream} objects are caught by
these objects, which set their \texttt{ios::badbit} as a result. See also the
paragraph on this issue in section \ref{STREAMBUF}.

\section{Standard exceptions}\label{STDEXC}
\typeout{Original Yodl file: exceptions/standard}All data types may be thrown as exceptions. Several additional exception
classes are now defined by the \textbf{C++} standard. Before using those additional
exception classes the \index{stdexcept: header file}\texttt{$<$stdexcept$>$} header file must be included.

All of these \index{standard exceptions}\emph{standard exceptions}
  \index{exception: standard} are class types by themselves, but also offer
all facilities of the \index{exception class} \texttt{std::exception} class and objects
of the standard exception classes may also be considered objects of the
\texttt{std::exception} class.

The \texttt{std::exception} class offers the member
        \begin{verbatim}
    char const *what() const;
\end{verbatim}
\index{what} describing in a short textual message the nature of the
exception.

\textbf{C++} defines the following standard exception classes:
    \begin{itemize}
    \item \index{bad\_alloc}\texttt{std::bad\_alloc} (this requires the \index{new: header file}\texttt{$<$new$>$} header file):
        thrown when \index{operator new}\texttt{operator new} fails;
    \item \index{bad\_array\_new\_length}\texttt{std::bad\_array\_new\_length} (this requires the 
        \index{new: header file}\texttt{$<$new$>$} header file): thrown when an illegal array size is requested
        when using \texttt{new Type{[}...{]}}. Illegal sizes are negative values,
        values that exceed an implementation defined maximum, the number of
        initializer clauses exceeds the specified number of array elements
        (e.g., \texttt{new int{[}2{]}\{ 1, 2, 3 \}});
    \item \index{bad\_cast}\texttt{std::bad\_cast} (this requires the \index{typeinfo: header file}\texttt{$<$typeinfo$>$} header
        file): thrown in the context of \emph{polymorphism}
        (see section \ref{DYNAMICCAST});
    \item \index{bad\_exception}\texttt{std::bad\_exception} (this requires the 
        \index{exception: header file}\texttt{$<$exception$>$} header file): thrown when a function tries to
        generate another type of exception than declared in its
        \index{throw list}\index{function throw list}function throw list;
    \item \index{bad\_typeid}\texttt{std::bad\_typeid} (this requires the \index{typeinfo: header file}\texttt{$<$typeinfo$>$} header
        file): also thrown in the context of
        \emph{polymorphism} (see section \ref{TYPEID});
    \end{itemize}

All additional exception classes were derived from \texttt{std::exception}. The
constructors of all these additional classes accept \texttt{std::string const \&}
arguments summarizing the reason for the exception (retrieved by the
\texttt{exception::what} member).  The additionally defined exception classes are:
    \begin{itemize}
    \item \index{domain\_error}\texttt{std::domain\_error}: a (mathematical) domain error is
detected;
    \item \index{invalid\_argument}\texttt{std::invalid\_argument}: the argument of a function
has an invalid value;
    \item \index{length\_error}\texttt{std::length\_error}: thrown when an object would have
exceeded its maximum permitted length;
    \item \index{logic\_error}\texttt{std::logic\_error}: a logic error should be thrown when a
problem is detected in the internal logic of the program. Example: a function
like \textbf{C}'s \texttt{printf} is called with more arguments than there are format
specifiers in its format string;
    \item \index{out\_of\_range}\texttt{std::out\_of\_range}: thrown when an argument exceeds its
permitted range. Example: thrown by \texttt{at} members when their arguments exceed
the range of admissible index values;
    \item \index{overflow\_error}\texttt{std::overflow\_error}: an overflow error should be
thrown when an arithmetic overflow is detected. Example: dividing a
value by a very small value;
    \item \index{range\_error}\texttt{std::range\_error}: a range error should be thrown when
an internal computation results in a value exceeding a permissible range;
    \item \index{runtime\_error}\texttt{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.
    \item \index{underflow\_error}\texttt{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.
    \item \index{tx\_exception}\texttt{std::tx\_exception$<$Type$>$}: derived from
\texttt{std::runtime\_error}. This exception can be thrown from an \texttt{atomic\_cancel}
compound statement (cf. section \ref{TRANSMEM}) to undo statements executed so
far. 
    \end{itemize}

\subsection{Standard exceptions: to use or not to use?}
    \typeout{Original Yodl file: exceptions/usestandard.yo}Since values of any type may be thrown as exceptions, you may wonder when to
throw values of standard exception types and (if ever) when to throw values of
other types.

Current practice in the C++ community is to throw exceptions only in
exceptional situations. In that respect C++'s philosophy about using
exceptions differs markedly from the way exceptions are used in, e.g., Java,
where exceptions are often encountered in situations C++ doesn't consider
exceptional. Another common practice is to follow a `conceptual' style when
designing software. A nice characteristic of exceptions is that exceptions can
be thrown at a point where your source shows what's happening: throwing an
\texttt{std::out\_of\_range} exception is nice for the software maintainer, as
the reason for the exception is immediately recognized.

At the catch-clause the semantical context usually isn't very relevant anymore
and by catching a std::exception and showing its \texttt{what()} content the
program's \emph{user} is informed about what happened.

But throwing values of other types can also be useful. What about a situation
where you want to throw an exception and catch it at some shallow level?  In
between there may be various levels of software provided by external software
libraries over which the software engineer has no control.  At those levels
exceptions (std::exceptions) could be generated too, and those exceptions
might also be caught by the library's code. When throwing a standard exception
type it may be hard to convince yourself that that exception isn't caught by
the externally provided software. Assuming that no catch-alls are used (i.e.,
\texttt{catch (...)})  then throwing an exception from the \texttt{std::exception}
family might not be a very good idea. In such cases throwing a value from a
simple, maybe empty, \texttt{enum} works fine:
        \begin{verbatim}
    enum HorribleEvent 
    {};      

    ... at some deep level:
        throw HorribleEvent{};

    ... at some shallow level:
    catch (HorribleEvent hs)
    {
        ...
    }
\end{verbatim}
Other examples can easily be found: design a class holding a message and
an error (exit) code: where necessary throw an object of that class, catch it
in the catch clause of main's try block and you can be sure that all objects
defined at intermediate levels are neatly destroyed, and at the end you show
the error message and return the exit code embedded in your non-exception
object.

So, the advice is to use \texttt{std::exception} types when available, and
clearly do the required job. But if an exception is used to simply bail out
of an unpleasant situation, or if there's a chance that externally provided
code might catch \texttt{std:exceptions} then consider throwing objects or values
of other types.

\section{System error, error\_category, and error\_condition}\label{SYSTEMERROR}
\typeout{Original Yodl file: exceptions/systemerror}The class \texttt{std::system\_error}\index{system\_error} is derived from
\texttt{std::runtime\_error}, which in turn is derived from \texttt{std::exception}

\index{error\_category: required header}
    \index{error\_condition: required header}
Before using the class \texttt{system\_error} or related classes the
\index{system\_error: header file}\texttt{$<$system\_error$>$} header file must be included.

\texttt{System\_error} exceptions can be thrown when errors occur having
associated (system) \emph{error values}. Such errors are typically associated
with low-level (like operating system) functions, but other types of errors
(e.g., bad user input, non-existing requests) can also be handled. 

In addition to error codes (cf. section \ref{ERRORCODE}) and error categories
(covered below) error \emph{conditions} are distinguished. Error
conditions specify platform independent types of errors like syntax errors or
non-existing requests.

When constructing \texttt{system\_error} objects error codes and error categories
may be specified. First we'll look at the classes \texttt{error\_condition} and
\texttt{error\_category}, then \texttt{system\_error} itself is covered in more detail.

Figure \ref{SYSERRFIG} illustrates how the various components interact.

\begin{figure}[tbp]
\centerline{\epsffile{exceptions/systemerror.eps}}
\caption{\label{SYSERRFIG}System\_error: associated components}
\end{figure}

As shown in figure \ref{SYSERRFIG} the class \texttt{error\_category} uses the class
\texttt{error\_condition} and the class \texttt{error\_condition} uses the class
\texttt{error\_category}. As a consequence of this circular dependency between these
two classes these classes should be approached as one single class:
when covering \texttt{error\_category} the class \texttt{error\_condition} should be known
and vice versa. This circular dependency among these classes is unfortunate
and an example of bad class design.

As \texttt{system\_error} is eventually derived from \texttt{exception} it offers the
standard \texttt{what} member. It also contains an \texttt{error\_code}.

In POSIX systems the \texttt{errno} variable is associated with many, often rather
cryptic, symbols. The predefined \texttt{enum class errc} attempts to provide
intuitively more appealing symbols. Since its symbols are defined in a
strongly typed enumeration, they cannot directly be used when defining a
matching \texttt{error\_code}. Instead, a \texttt{make\_error\_code} function converts
    \index{errc (enum)}\texttt{enum class errc} values and values of newly defined
error code enumerations (called \index{ErrorCodeEnum}\texttt{ErrorCodeEnum} below) to \texttt{error\_code}
objects.

The \index{enum class errc}\texttt{enum class errc} defined in the \texttt{std} namespace defines symbols whose
values are equal to the traditional error code values used by \textbf{C} but 
describe the errors in a less cryptic way. E.g.,
        \begin{verbatim}
    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
        ...
    };
\end{verbatim}
Values of \texttt{ErrorCodeEnums} can be passed to matching \texttt{make\_error\_code}
functions. Defining your own \texttt{ErrorCodeEnum} enumeration is covered in
section \ref{ERRCODEENUM}.

Now that the general outline has been presented, it's time to have a closer
look at the various components shown in figure \ref{SYSERRFIG}.

\subsection{The class `std::error\_category'}\label{EXCERRCAT}
    \typeout{Original Yodl file: exceptions/errorcategory}Objects of the class \texttt{std::error\_category} identify sources of sets of error
codes. New error categories for new error code enumerations can also be
defined (cf. section \ref{ERRCODEENUM}).

Error categories are designed as \emph{singletons}: only one object of each class
can exist. Because of this \texttt{error\_categories} are equal when the addresses
of \texttt{error\_category} objects are equal. Error category objects are returned
by functions (see below) or by static \texttt{instance()} members of error category
classes.

Error category classes define several members. Most are declared \emph{virtual}
(cf. chapter \ref{POLYMORPHISM}), meaning that those members may be redefined
in error category classes we ourselves design:
    \begin{itemize}
    \item \index{default\_error\_condition}\texttt{virtual error\_condition
        default\_error\_condition(int ev) const noexcept}:\ \\ returns an \texttt{error\_condition} object (cf. section \ref{ERRCOND})
        initialized with error value \texttt{ev} and the current 
        (i.e., \texttt{$*$this}) \texttt{error\_category};

\item \texttt{virtual bool equivalent(error\_code const \&code, int condition) const
        noexcept}:\ \\ returns \texttt{true} if the equivalence between 
        the error condition that is associated with the \texttt{error\_code} object
        and the \texttt{error\_condition\_enum} value that is specified (as an
        \texttt{int} value) as the function's second argument could be
        establisted;

\item \index{equivalent}\texttt{virtual bool equivalent(int ev, error\_condition const \&condition)
        const noexcept}:\ \\ returns \texttt{true} if the equivalence of an \texttt{error\_condition} object
        that is constructed from the \texttt{ErrorConditionEnum} value that is
        associated with the \texttt{ErrorCategoryEnum} value that was passed (as
        \texttt{int}) to the function and the \texttt{error\_condition} object that was
        passed to the function as its second argument could be established;


    \item \index{message}\texttt{virtual string message(int ev) const}:\ \\ This member returns a string describing the error condition denoted by
        \texttt{ev}, which should be a (cast to \texttt{int}) value of the category's
        error condition enumeration;


    \item \index{name}\texttt{virtual char const $*$name() const noexcept}:\ \\ This member returns the name of the error category as NTBS (like
        \texttt{generic}); 

\item \texttt{bool operator$<$(error\_category const \&rhs) const noexcept}:\ \\ returns \texttt{less$<$const error\_category$*$$>$()(this, \&rhs)}.

\item  Error category objects can be compared for (in)equality.
    \end{itemize}

The functions returning predefined error categories are:
    \begin{itemize}
    \item \index{generic\_category}\texttt{error\_category const \&generic\_category() noexcept}:\ \\ returns a reference to the \emph{generic} \texttt{error\_category} object.
        The returned object's \texttt{name} member returns a pointer to the string
        \texttt{"generic"};

\item \index{system\_category}\texttt{error\_category const \&system\_category() noexcept}:\ \\ returns a reference to the \emph{operating system} \texttt{error\_category}
        object: it is used for errors reported by the operating system. The
        object's \texttt{name} member returns a pointer to the string
        \texttt{"system"};

\item \index{iostream\_category}\texttt{error\_category const \&iostream\_category() noexcept}:\ \\ returns a reference to the \emph{iostream} \texttt{error\_category}
        object: it is used for errors reported by stream objects. The
        object's \texttt{name} member returns a pointer to the string
        \texttt{"iostream"};

\item \index{future\_category}\texttt{error\_category const \&future\_category() noexcept}:\ \\ returns a reference to the \emph{future} \texttt{error\_category} object: it is
        used for errors reported by `future' objects (cf. section
        \ref{FUTURE}). The object's \texttt{name} member returns a pointer to the
        string \texttt{"future"};
    \end{itemize}

\subsection{The class `std::error\_condition'}\label{ERRCOND}
    \typeout{Original Yodl file: exceptions/errorcondition}\texttt{Error\_condition}\index{error\_condition} objects contain information about
`higher level' types of errors. They are supposed to be platform independent
like syntax errors or non-existing requests.

Error condition objects are returned by the member \texttt{default\_error\_condition}
of the classes \texttt{error\_code} and \texttt{error\_category}, and they are returned by
the function \index{make\_error\_condition}\texttt{std::error\_condition
make\_error\_condition(ErrorConditionEnum ec)}. The type name
\texttt{ErrorConditionEnum} is a formal name for an \texttt{enum class} that enumerates
the `higher level' error types. The \texttt{error\_condition} objects returned by
\texttt{make\_error\_condition} are initialized with \texttt{ec} and the
\texttt{error\_category} that uses the \texttt{ErrorConditionEnum}.  Defining your own
\texttt{ErrorConditionEnum} is covered in section \ref{ERRCODEENUM}.

\textbf{Constructors}:
    \begin{itemize}
    \item \texttt{error\_condition() noexcept}:\ \\ the object's value is initialized to `no error' (i.e., 0) and
        a \texttt{system\_category} error category;

\item  The copy constructor is available;

\item \texttt{error\_condition(int ec, error\_category const \&cat) noexcept}:\ \\ the object's value is initialized to \texttt{ec} and error category
        \texttt{cat}. It is the responsibility of the caller to ensure that \texttt{ec}
        represents a (cast to \texttt{int}) value of \texttt{cat's} error condition
        enumeration;

\item \texttt{error\_condition(ErrorConditionEnum value) noexcept}:\ \\ this is a member template (cf. section \ref{MEMTEMP}), using template
        header \texttt{template $<$class ErrorConditionEnum$>$}. It initializes the
        object with the return value of
        \texttt{make\_error\_condition(value)};
    \end{itemize}

\textbf{Members}:
    \begin{itemize}
    \item  The copy assignment operator and an assignment operator accepting an
        \texttt{ErrorConditionEnum} are available;

\item \texttt{void assign(int val, error\_category const \&cat)}:\ \\ assigns new values to the current object's \emph{value} and
        \emph{category} data members;

\item \texttt{error\_category const \&category() const noexcept}:\ \\ returns a reference to the object's error category (note that this is
        a reference to the category's singleton object);

\item \texttt{void clear() noexcept}:\ \\ after calling this member \emph{value} is set to 0 and the object's error
        \emph{category} set to \texttt{generic\_category};

\item \texttt{string message() const}:\ \\ returns \texttt{category().message(value())};

\item \texttt{explicit operator bool() const noexcept}:\ \\ returns \texttt{true} if \texttt{value()} returns a non-zero value (so its
        semantic meaning is `the object represents an error');

\item \texttt{int value() const noexcept}:\ \\ returns the object's error value.
    \end{itemize}

Two \texttt{error\_condition} objects can be compared for (in)equality, and can be
ordered using \texttt{operator$<$}. Ordering is pointless if the two objects refer to
different error categories. If the categories of two objects are different 
they are considered different.

\subsection{The class system\_error}
    \typeout{Original Yodl file: exceptions/systemerroruse}\texttt{System\_error} objects can be constructed from \texttt{error\_codes} or from 
error values (\texttt{ints}) and matching error category objects, optionally
followed by a standard textual description of the nature of the encountered
error. 

Here is the class's public interface:
        \begin{verbatim}
   class system_error: public runtime_error 
    {
        public:
            system_error(error_code ec);
            system_error(error_code ec, string const &what_arg);
            system_error(error_code ec, char const *what_arg);
    
            system_error(int ev, error_category const &ecat);
            system_error(int ev, error_category const &ecat,
                             char const *what_arg);
            system_error(int ev, error_category const &ecat,
                             string const &what_arg);
    
            error_code const &code() const noexcept;
            char const *what() const noexcept;
    }
\end{verbatim}
The \texttt{ev} values often are the values of the \texttt{errno} variable as set
upon failure by system level functions like \textbf{chmod}(2).

Note that the first three constructors shown in the interface receive an
\texttt{error\_code} object as their first arguments. As one of the \texttt{error\_code}
constructors also expects an \texttt{int} and and \texttt{error\_category} argument,
the second set of three constructors could also be used instead of the first
set of three constructors. E.g.,
        \begin{verbatim}
    system_error(errno, system_category(), "context of the error");
    // identical to:
    system_error(error_code(errno, system_category()), 
                                            "context of the error");
\end{verbatim}
The second set of three constructors are primarily used when an existing
function already returns an \texttt{error\_code}. E.g.,
        \begin{verbatim}
    system_error(make_error_code(errc::bad_address), 
                                            "context of the error");
    // or maybe:
    system_error(make_error_code(static_cast<errc>(errno)), 
                                            "context of the error");
\end{verbatim}
In addition to the standard \texttt{what} member, the \texttt{system\_error} class also
offers a member \texttt{code} returning a const reference to the exception's error
code. 

The NTBS returned by \texttt{system\_error's what} member may be formatted by a
\texttt{system\_error} object:
        \begin{verbatim}
    what_arg + ": " + code().message()
\end{verbatim}
Note that, although \texttt{system\_error} was derived from \texttt{runtime\_error},
you'll lose the \texttt{code} member when catching a \texttt{std::exception} object. Of
course, downcasting is possible, but that's a stopgap. Therefore, if a
\texttt{system\_error} is thrown, a matching \texttt{catch (system\_error const \&)} clause
must be provided to retrieve the value returned by the \texttt{code} member. This,
and the rather complex organization of the classes that are involved when
using \texttt{system\_error} result in a very complex, and hard to generalize
exception handling. In essence, what you obtain at the cost of high
complexity is a facility for categorizing \texttt{int} or \texttt{enum} error
values. Additional coverage of the involved complexities is provided in
chapter \ref{ADVANCEDTEMPL}, in particular section \ref{ERRCODEENUM}
(for a flexible alternative, see the class 
    \index{Exception (Bobcat)} \texttt{FBB::Exception} in the author's 
        \texttt{Bobcat library}\footnote{http://fbb-git.gitlab.io/bobcat/}\index{Bobcat library}\index{http://fbb-git.gitlab.io/bobcat/}).

\subsection{Exception propagation: std::exception\_ptr}\label{EXCPTR}
    \typeout{Original Yodl file: exceptions/exceptionptr}In practice almost everything can be used as an exception. But at the same
time any exception that is thrown can be reached using the function
\index{current\_exception}(\texttt{std::current\_exception}), and access to any exception
can be standardized using \index{make\_exception\_ptr}\texttt{std::make\_exception\_ptr}.
These functions expect or use objects of the class
\index{exception\_ptr}\texttt{std::exception\_ptr}, and in this section we take a closer
look at tha class.

The class \texttt{exception\_ptr's} default constructor initializes it to a
null-pointer. In the following code snippet the variable \texttt{isNull} is set to
true:
        \begin{verbatim}
    std::exception_ptr obj;
    bool isNull =  obj == nullptr && obj == 0;
\end{verbatim}
The class \texttt{exception\_ptr} provides copy and move constructors as well as
copy and move assignment operators.

Two \texttt{exception\_ptr} objects can be compared for equality. They are equal
if they refer to the same exception. Move assignment transfers the exception
referred to by the right-hand side operand to the left-hand side operand, and
turns the right-hand side operand into a null pointer.

There is no published method directly retrieving the exception to which an
\texttt{exception\_ptr} object refers. However, there are some free functions
constructing or handling \texttt{exception\_ptr} objects:
    \begin{itemize}
    \item \index{current\_exception}\texttt{std::exception\_ptr std::current\_exception() noexcept}:\ \\ An \texttt{exception\_ptr} object is returned referring to the currently
        handled exception (or a copy of the currently handled exception, or a
        default constructed \texttt{exception\_ptr} object if no current exception
        is available). This function can also be called when a default
        exception catcher is used. 


The exception referred to by \texttt{current\_exception} does not have to
        be an object of the class \texttt{std::exception}. Any type of object or
        value thrown as an exception is retrieved as an \texttt{exception\_ptr} by
        \texttt{current\_exception}. The exception referred to by an
        \texttt{exception\_ptr} object remains valid for at least as long as there
        exists an \texttt{exception\_ptr} object that refers to it. Calling
        \texttt{current\_exception} twice in a row then the two returned
        \texttt{exception\_ptr} objects may or may not refer to the same exception
        object.

\item \index{make\_exception\_ptr}\texttt{std::exception\_ptr make\_exception\_ptr(Type
        value) noexcept}:\ \\ This function template constructs an \texttt{exception\_ptr} from a value of
        any type which is passed as its argument. \texttt{Type} does not
        necessarily have to be a \texttt{std::exception} but can be anything that
        can be thrown as an exception: an \texttt{int}, a \texttt{std::string}, a
        \texttt{std::exception}, you name it.


        Here are
        some examples, showing how values of different types can be passed as
        arguments to \texttt{make\_exception\_ptr}

       \begin{verbatim}
    auto ptr = make_exception_ptr(exception());
    ptr = make_exception("hello world"s);
    ptr = make_exception(12);
\end{verbatim}
\item \index{rethrow\_exception}\texttt{void std::rethrow\_exception(exception\_ptr obj)}:\ \\ The exception to which \texttt{obj} refers is thrown. Note: \texttt{obj}
        cannot be a \texttt{nullptr}.

\end{itemize}

\section{Exception guarantees}
\typeout{Original Yodl file: exceptions/guarantees}Software should be \index{exception safe}\emph{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 \textbf{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:
        \begin{verbatim}
    void fun()
    {
        X x;
        cout << x;
        X *xp = new X{ x };
        cout << (x + *xp);
        delete xp;
    }
\end{verbatim}
If it can be assumed that \texttt{cout} as used above does not throw an
exception there are at least 13 opportunities for exceptions to be thrown:
    \begin{itemize}
    \item  \texttt{X x}: the default constructor could throw an exception (\#1)
    \item  \texttt{cout $<$$<$ x}: the overloaded insertion operator could throw an
exception (\#2), but its rhs argument might not be an \texttt{X} but, e.g., an
\texttt{int}, and so \texttt{X::operator int() const} could be called which offers yet
another opportunity for an exception (\#3).
    \item  \texttt{$*$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 \texttt{::new}, but from, e.g., \texttt{X}'s own
overload of \texttt{operator new}? (\#5b)
    \item  \texttt{cout $<$$<$ (x + $*$xp)}: we might be seduced into thinking that two
\texttt{X} objects are added. But it doesn't have to be that way. A separate class
Y might exist and \texttt{X} may have a conversion operator \texttt{operator Y() const},
and \texttt{operator+(Y const \&lhs, X const \&rhs), operator+(X const \&lhs, Y const
\&rhs)}, and \texttt{operator+(X const \&lhs, X const \&rhs)} might all exist. So, if
the conversion operator exists, then depending on the kind of overload of
\texttt{operator+} that is defined either the addition's left-hand side operand
(\#6), right-hand side operand (\#7), or \texttt{operator+} itself (\#8) may throw an
exception. The resulting value may again be of any type and so the overloaded
\texttt{cout $<$$<$ return-type-of-operator+} operator may throw an exception
(\#9). Since \texttt{operator+} returns a temporary object it is destroyed shortly
after its use. \texttt{X}'s destructor \emph{could} throw an exception (\#10).
    \item  \texttt{delete xp}: whenever \texttt{operator new} is overloaded \texttt{operator
delete} should be overloaded as well and may throw an exception (\#11). And of
course, \texttt{X}'s destructor might again throw an exception (\#12).
    \item  \texttt{\}}: when the function terminates the local \texttt{x} object is
destroyed: again an exception could be thrown (\#13).
        \end{itemize}
 It is stressed here (and further discussed in section \ref{CONSEXCEPTIONS})
that although it is possible for exceptions to leave
destructors this would violate the \textbf{C++} standard and so it must be
prevented in well-behaving \textbf{C++} programs.

How can we expect to create working programs when exceptions might be thrown
in so 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 \index{exception guarantees}exception guarantees:
    \begin{itemize}
    \item  The \emph{basic guarantee}: no resources are leaked. In practice this
means: all allocated memory is properly returned when exceptions are thrown.
    \item  The \emph{strong guarantee}: the program's state remains unaltered when
an exception is thrown (as an example: the canonical form of the overloaded
assignment operator provides this guarantee)
    \item  The \emph{nothrow} guarantee: this applies to code for which it can be
proven that no exception can be thrown from it.
    \end{itemize}

\subsection{The basic guarantee}
    \typeout{Original Yodl file: exceptions/basic}The \index{basic guarantee}\emph{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.
        \begin{verbatim}
    void allocator(X **xDest, Y **yDest)
    {
        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;
    }
\end{verbatim}
In the pre-try code the pointers to receive the addresses returned by the
operator \texttt{new} calls are initialized to 0. Since the catch handler must be
able to return allocated memory they must be available outside of the \texttt{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 \texttt{new}
throws a \index{bad\_alloc}\texttt{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
    \index{new: and exceptions}\index{exception: and new} \emph{guaranteed} to happen:
    \begin{itemize}
    \item  The destructors of all successfully allocated objects are called;
    \item  The dynamically allocated memory to contain the objects is returned
    \end{itemize}

Consequently, there is no memory leak when \texttt{new} fails. Inside the above
\texttt{try} block \texttt{new X} may fail: this does not affect the 0-pointers
and so the catch handler merely deletes 0 pointers. When \texttt{new Y} fails
\texttt{xp} points to allocated memory and so it must be returned. This happens
inside the catch handler. The final pointer (here: \texttt{yp}) will only be
unequal zero when \texttt{new Y} properly completes, so there's no need for the
catch handler to return the memory pointed at by \texttt{yp}.

\subsection{The strong guarantee}
    \typeout{Original Yodl file: exceptions/strong}The \index{strong guarantee}\emph{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:
        \begin{verbatim}
    Class &operator=(Class const &other)
    {
        Class tmp(other);
        swap(tmp);
        return *this;
    }
\end{verbatim}
The copy construction might throw an exception, but this keeps the current
object's state intact. If the copy construction succeeds \texttt{swap} swaps the
current object's content with \texttt{tmp}'s content and returns a reference to
the current object. For this to succeed it must be guaranteed that \texttt{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 \index{rule of thumb} rules of thumb were formulated that relate to the
strong guarantee
 (cf. \index{Sutter, H.}Sutter, H., \index{Exceptional C++}\emph{Exceptional C++}, Addison-Wesley, 2000). E.g.,
    \begin{itemize}
    \item  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.
    \item  Member functions modifying their object's data should not return
original (contained) objects by value.
    \end{itemize}

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
\texttt{PersonDb} storing multiple \texttt{Person} objects. Such a class might offer a
member \texttt{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:
        \begin{verbatim}
    Person *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;
            return tmp;
        }
        catch (...)
        {
            delete[] tmp;
            throw;
        }
    }

    void PersonDb::add(Person const &next)
    {
        Person *tmp = newAppend(next);
        delete[] d_data;
        d_data = tmp;
        ++d_size;
    }
\end{verbatim}
The (private) \texttt{newAppend} member's task is to create a copy of the
currently allocated \texttt{Person} objects, including the data of the next
\texttt{Person} object. Its \texttt{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
 \index{exception neutral}\emph{exception neutral} as it propagates all its exceptions to its caller. The
function also doesn't modify the \texttt{PersonDb} object's data, so it meets the
strong exception guarantee. Returning from \texttt{newAppend} the member \texttt{add}
may now modify its data. Its existing data are returned and its \texttt{d\_data}
pointer is made to point to the newly created array of \texttt{Person}
objects. Finally its \texttt{d\_size} is incremented. As these three steps don't
throw exceptions \texttt{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 \texttt{PersonDb::erase(size\_t idx)}. Here is an implementation
attempting to return the original \texttt{d\_data{[}idx{]}} object:
        \begin{verbatim}
    Person PersonData::erase(size_t idx)
    {
        if (idx >= d_size)
            throw "Array bounds exceeded"s;
        Person ret(d_data[idx]);
        Person *tmp = copyAllBut(idx);
        delete[] d_data;
        d_data = tmp;
        --d_size;
        return ret;
    }
\end{verbatim}
Although copy elision usually prevents the use of the copy constructor
when returning \texttt{ret}, this is not guaranteed to happen. Furthermore, a copy
constructor \emph{may} throw an exception. If that happens the function has
irrevocably mutated the \texttt{PersonDb}'s data, thus losing the strong guarantee.

Rather than returning \texttt{d\_data{[}idx{]}} by value it might be assigned to an
external \texttt{Person} object before mutating \texttt{PersonDb}'s data:
        \begin{verbatim}
    void PersonData::erase(Person *dest, size_t idx)
    {
        if (idx >= d_size)
            throw "Array bounds exceeded"s;
        *dest = d_data[idx];
        Person *tmp = copyAllBut(idx);
        delete[] d_data;
        d_data = tmp;
        --d_size;
    }
\end{verbatim}
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 \texttt{PersonDb}'s data and also return an original
object. In situations like these the \emph{one-function-one-responsibility}
\index{rule of thumb}rule of thumb should be kept in mind: a function should have a single, well
defined responsibility.

The preferred approach is to retrieve \texttt{PersonDb}'s objects using a member
like \texttt{Person const \&at(size\_t idx) const} and to erase an object using a
member like \texttt{void PersonData::erase(size\_t idx)}.

\subsection{The nothrow guarantee}
    \typeout{Original Yodl file: exceptions/nothrow}Exception safety can only be realized if some functions and operations are
guaranteed \emph{not} to throw exceptions. This is called the
 \index{nothrow guarantee}\emph{nothrow guarantee}. An example of a function that must offer the nothrow
guarantee is the \texttt{swap} function. Consider once again the canonical
overloaded assignment operator:
        \begin{verbatim}
    Class &operator=(Class const &other)
    {
        Class tmp(other);
        swap(tmp);
        return *this;
    }
\end{verbatim}
If \texttt{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 \texttt{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 \index{swap}\texttt{swap} function must therefore offer the nothrow guarantee. It must
have been designed as if using the following prototype (see also section
\ref{NOEXCEPT}): 
        \begin{verbatim}
    void Class::swap(Class &other) noexcept;
\end{verbatim}
Likewise, \texttt{operator delete} and \texttt{operator delete{[}{]}} offer the nothrow
guarantee, and according to the \textbf{C++} standard destructors may themselves
not throw exceptions (if they do their behavior is formally undefined, see
also section \ref{CONSEXCEPTIONS} below).

Since the \textbf{C} programming language does not define the exception concept
functions from the standard \textbf{C} library offer the nothrow guarantee
by implication. This allowed us to define the generic \texttt{swap} function in
section \ref{CopyDestroy} using \index{memcpy}\texttt{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.

\section{Function try blocks}\label{FUNTRY}
\typeout{Original Yodl file: exceptions/function}    Exceptions may be generated from inside constructors. 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 \texttt{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 \texttt{try} block is illustrated in the next example, where
\texttt{main} defines an object of class \texttt{PersonDb}. Assuming that
\texttt{PersonDb}'s constructor throws an exception, there is no way we can access
the resources that might have been allocated by \texttt{PersonDb}'s constructor
from the catch handler as the \texttt{pdb} object is out of scope:
        \begin{verbatim}
    int main(int argc, char **argv)
    {
        try
        {
            PersonDb pdb{ argc, argv }; // may throw exceptions
            ...                         // main()'s other code
        }
        catch (...)                      // and/or other handlers
        {
            ...                         // pdb is inaccessible from here
        }
    }
\end{verbatim}
Although all objects and variables defined inside a \texttt{try} block are
inaccessible from its associated catch handlers, object data members were
available before starting the \texttt{try} block and so they may be accessed from a
catch handler. In the following example the catch handler in
\texttt{PersonDb}'s constructor is able to access its \texttt{d\_data} member:
        \begin{verbatim}
    PersonDb::PersonDb(int argc, char **argv)
    :
        d_data(0),
        d_size(0)
    {
        try
        {
            initialize(argc, argv);
        }
        catch (...)
        {
            // d_data, d_size: accessible
        }
    }
\end{verbatim}
Unfortunately, this does not help us much. The \texttt{initialize} member is
unable to reassign \texttt{d\_data} and \texttt{d\_size} if \texttt{PersonDb const pdb}
was defined; the \texttt{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 \texttt{d\_data} and \texttt{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 \texttt{PersonDb} assume that constructor
receives a pointer to an already allocated block of \texttt{Person} objects. The
\texttt{PersonDb} object takes ownership of the allocated memory and it is
therefore responsible for the allocated memory's eventual destruction.
Moreover, \texttt{d\_data} and \texttt{d\_size} are also used by a composed object
\texttt{PersonDbSupport}, having a constructor expecting a \texttt{Person const $*$} and
\texttt{size\_t} argument. Our next implementation may then look something like
this:
        \begin{verbatim}
    PersonDb::PersonDb(Person *pData, size_t size)
    :
        d_data(pData),
        d_size(size),
        d_support(d_data, d_size)
    {
        // no further actions
    }
\end{verbatim}
This setup allows us to define a \texttt{PersonDb const \&pdb}. Unfortunately,
\texttt{PersonDb} cannot offer the basic guarantee. If \texttt{PersonDbSupport}'s
constructor throws an exception it isn't caught although \texttt{d\_data} already
points to allocated memory.

The \index{function try block}\emph{function try block} offers a solution for this problem. A function
try block consists of a \texttt{try} block and its associated handlers. The
function \texttt{try} block starts \emph{immediately} after the function header, and
its block defines the function body. With constructors base class and data
member initializers may be placed between the \texttt{try} keyword and the opening
curly brace. Here is our final implementation of \texttt{PersonDb}, now offering
the basic guarantee:
        \begin{verbatim}
    PersonDb::PersonDb(Person *pData, size_t size)
    try
    :
        d_data(pData),
        d_size(size),
        d_support(d_data, d_size)
    {}
    catch (...)
    {
        delete[] d_data;
    }
\end{verbatim}
Let's have a look at a stripped-down example. A constructor defines a
function try block. The exception thrown by the \texttt{Throw} object is initially
caught by the object itself. Then it is rethrown. The surrounding
\texttt{Composer}'s constructor also defines a function try block, \texttt{Throw}'s
rethrown exception is properly caught by \texttt{Composer}'s exception handler,
even though the exception was generated from within its member initializer
list:
        \begin{verbatim}
    #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";
            }
    };

    int main()
    {
        Composer c;
    }
\end{verbatim}
When running this example, we're in for a nasty surprise: the program runs
and then breaks with an \index{abort exception}\emph{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:
        \begin{verbatim}
    Throw's exception handled locally by Throw()
    Composer() caught exception as well
    terminate called after throwing an instance of 'int'
    Abort
\end{verbatim}
The reason for this is documented in the \textbf{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
 \index{exception: replace} 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 \texttt{main} with its own function try
block:
        \begin{verbatim}
    int main()
    try
    {
        Composer c;
    }
    catch (...)
    {}
\end{verbatim}
Now the program runs as planned, producing the following output:
        \begin{verbatim}
    Throw's exception handled locally by Throw()
    Composer() caught exception as well
\end{verbatim}
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.

\section{Exceptions in constructors}\label{CONSEXCEPTIONS}
\typeout{Original Yodl file: exceptions/constructors}    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 \emph{not} called when
the object goes out of scope. This could happen if an exception that is
 \index{exception: and constructors}\index{constructor: and exceptions}
    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.

The following example illustrates this situation in its prototypical
form. The constructor of the class \texttt{Incomplete} first displays a message
and then throws an exception. Its destructor also displays a message:
        \begin{verbatim}
    class Incomplete
    {
        public:
            Incomplete()
            {
                cerr << "Allocated some memory\n";
                throw 0;
            }
            ~Incomplete()
            {
                cerr << "Destroying the allocated memory\n";
            }
    };
\end{verbatim}
    Next, \texttt{main()} creates an \texttt{Incomplete} object inside a \texttt{try}
block. Any exception that may be generated is subsequently caught:
        \begin{verbatim}
    int main()
    {
        try
        {
            cerr << "Creating `Incomplete' object\n";
            Incomplete{};
            cerr << "Object constructed\n";
        }
        catch (...)
        {
            cerr << "Caught exception\n";
        }
    }
\end{verbatim}
    When this program is run, it produces the following output:
        \begin{verbatim}
    Creating `Incomplete' object
    Allocated some memory
    Caught exception
\end{verbatim}
Thus, if \texttt{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:
    \begin{itemize}
    \item  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 \texttt{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.
    \item  If an exception is generated by a base class constructor or by a
member initializing constructor then a \texttt{try} block within the constructor's
 body won't be able to catch the thrown exception. This \emph{always} results in
the exception leaving the constructor and the object is not considered to have
been properly constructed. A \texttt{try} block may include the member
initializers, and the \texttt{try} block's compound statement becomes the
constructor's body as in the following example:
    \begin{verbatim}
class Incomplete2
{
    Composed d_composed;
    public:
        Incomplete2()
        try
        :
            d_composed(/* arguments */)
        {
            // body
        }
        catch (...)
        {}
};
\end{verbatim}
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.
    \end{itemize}

The catch clause of a constructor's function \texttt{try} block behaves
slightly different than a catch clause of an ordinary function \texttt{try}
block. An exception reaching a constructor's function \texttt{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 \emph{always} propagates
to a more shallow block and in that case the object's construction is always
considered incomplete.

Therefore, if incompletely constructed objects throw exceptions then
the constructor \emph{remains responsible} for preventing memory
(generally: resource) leaks. There are several ways to realize this:
    \begin{itemize}
    \item  If the constructor defines a function try block, then the
constructor's catch clause \emph{cannot} use \emph{any} of its data members
anymore. By implication: if the constructor has allocated memory pointed to by
one of its data members, then the catch-clause cannot delete that
memory. Instead, the constructor's body itself must ensure that the memory is
properly deleted;
    \item  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)
    \item  When composition is used: already constructed composed objects are
automatically destroyed (as they are fully constructed objects)
    \item  Instead of using plain pointers \emph{smart pointers} (cf. section
\ref{SHAREDPTR}) 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 \texttt{shared\_ptr}
objects are, after all, objects.
    \item  If plain pointer data members \emph{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 data members. In these cases the
pointer-handling must be embedded in a try-block, allowing the constructor to
free the allocated memory before a final exception is thrown, possibly 
reaching the catch clause of the constructor's function try block. That final
catch clause can complete whatever actions are required (e.g., write a
log-file entry). Example:
    \begin{verbatim}
class Incomplete2
{
    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)
        {
            try
            {
                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;
                throw;                          // retrow the exception
            }
        }
        catch (...)
        {
            // maybe write a log-entry, but also throws 
            // the original exception
        }
};
\end{verbatim}
\end{itemize}

On the other hand, \textbf{C++} supports constructor delegation, so an object
may have been completely constructed according to the \textbf{C++} run-time system,
but yet its (delegating) constructor may throw an exception, as illustrated by
the next example:
        \begin{verbatim}
     1: #include <iostream>
     2: using namespace std;
     3: 
     4: class Delegate
     5: {
     6:     char *d_p1;
     7:     char *d_p2;
     8: 
     9:     public:
    10:         Delegate()      // succeeds -> object constructed
    11:         :
    12:             Delegate(0)
    13:         {
    14:             d_p2 = new char[10];
    15:             cout << "default, throws...\n";
    16:             throw 12;   // but considered constructed
    17:         }
    18:         ~Delegate()
    19:         {
    20:             delete[] d_p1;
    21:             delete[] d_p2;
    22:             cout << "destructor\n";
    23:         }
    24: 
    25:     private:
    26:         Delegate(int x)         // completes OK
    27:         :
    28:             d_p1(0),
    29:             d_p2(0)
    30:         {
    31:             cout << "delegated\n";
    32:         }
    33: };
    34: 
    35: int main()
    36: try
    37: {
    38:     Delegate del;           // throws
    39: 
    40:     cout << "never reached\n";
    41: } // del's destructor is called here
    42: catch (...)
    43: {
    44:     cout << "main's catch clause\n";
    45: }
\end{verbatim}
Here it is the responsibility of \texttt{Delegate}'s designer to ensure that
the throwing default constructor does not invalidate the actions performed by
the \texttt{Delegate(int x)} constructor. The latter constructor is called (line
12) by the default constructor, and merely initializes (lines 28, 29) the data
members at lines 6 and 7. Next, the default constructor, after allocating some
memory, throws an exception (line 16). In fact, an exception may be called at
any point, since the destructor (line 18) will be called automatically anyway
(line 41). If multiple exceptions could be thrown then \texttt{Delegate} can define
an enumeration and a data member of that enumeration type, which is set to the
enum value indication the nature of the next exception (if it is thrown), so
the destructor can handle the exception according to its type.

\section{Exceptions in destructors}
\typeout{Original Yodl file: exceptions/destructors}    According to the \textbf{C++} standard exceptions thrown by destructors may
\emph{not} leave their bodies. Providing a destructor with a function \texttt{try}
block is therefore a violation of the standard: exceptions caught by a
function \texttt{try} block's catch clause have already left the destructor's body.
If -{}-{}in violation of the standard-{}-{} the destructor \emph{is} provided with a
function \texttt{try} block and an exception is caught by the \texttt{try} block then
that exception is rethrown, similar to what happens in catch clauses of
constructor functions' \texttt{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 \emph{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:
        \begin{verbatim}
    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";
        }
    }
\end{verbatim}
    When this program is run it produces the following output:
        \begin{verbatim}
    Creating Cupboard1
    Drawer 1 used
    Cupboard1 behaves as expected
    Creating Cupboard2
    Drawer 2 used
    Drawer 1 used
    terminate called after throwing an instance of 'int'
    Abort
\end{verbatim}
The final \texttt{Abort} indicates that the program has aborted instead of
displaying a message like \texttt{Cupboard2 behaves as expected}.

Let's have a look at the three classes involved. The class \texttt{Drawer} has no
particular characteristics, except that its destructor throws an exception:
        \begin{verbatim}
    class Drawer
    {
        size_t d_nr;
        public:
            Drawer(size_t nr)
            :
                d_nr(nr)
            {}
            ~Drawer()
            {
                cerr << "Drawer " << d_nr << " used\n";
                throw 0;
            }
    };
\end{verbatim}
    The class \texttt{Cupboard1} has no special characteristics at all. It merely
has a single composed \texttt{Drawer} object:
        \begin{verbatim}
    class Cupboard1
    {
        Drawer left;
        public:
            Cupboard1()
            :
                left(1)
            {}
    };
\end{verbatim}
    The class \texttt{Cupboard2} is constructed comparably, but it has two
composed \texttt{Drawer} objects:
        \begin{verbatim}
    class Cupboard2
    {
        Drawer left;
        Drawer right;
        public:
            Cupboard2()
            :
                left(1),
                right(2)
            {}
    };
\end{verbatim}
When \texttt{Cupboard1}'s destructor is called \texttt{Drawer}'s destructor is
eventually called to destroy its composed object. This destructor throws an
exception, which is caught beyond the program's first \texttt{try} block. This
behavior is completely as expected.

A subtlety here is that \texttt{Cupboard1}'s destructor (and hence \texttt{Drawer}'s
destructor) is activated \emph{immediately} subsequent to its construction. Its
destructor is called immediately subsequent to its construction as
\texttt{Cupboard1()} defines an anonymous object. As a result the \texttt{Beyond
Cupboard1 object} text is never inserted into \texttt{std::cerr}.

Because of \texttt{Drawer}'s destructor throwing an exception a problem occurs
when \texttt{Cupboard2}'s destructor is called. Of its two composed objects, the
second \texttt{Drawer}'s destructor is called first.  This destructor throws an
exception, which ought to be caught beyond the program's second \texttt{try}
block. However, although the flow of control by then has left the context of
\texttt{Cupboard2}'s destructor, that object hasn't completely been destroyed yet
as the destructor of its other (left) \texttt{Drawer} still has to be called.

Normally that would not be a big problem: once an exception is thrown from
\texttt{Cupboard2}'s destructor any remaining actions would simply be ignored,
albeit that (as both drawers are properly constructed objects) \texttt{left}'s
destructor would still have to be called.

This happens here too and \texttt{left}'s destructor \emph{also} needs to throw an
exception. But as we've already left the context of the second \texttt{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 \texttt{terminate()}, which in
turn calls \texttt{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 \textbf{C++} standard therefore understandably stipulates that exceptions
may \emph{never} leave destructors. Here is the skeleton of a destructor whose
 \index{destructor: and exceptions}\index{exception: and destructors} code might throw
exceptions. No function \texttt{try} block but all the destructor's actions are
encapsulated in a \texttt{try} block nested under the destructor's body.
        \begin{verbatim}
    Class::~Class()
    {
        try
        {
            maybe_throw_exceptions();
        }
        catch (...)
        {}
    }
\end{verbatim}
\cleardoublepage\chapter{More Operator Overloading}\label{OVERLOADING}
\typeout{Original Yodl file: overloading}\typeout{Original Yodl file: overloading/more}Having covered the overloaded assignment operator in chapter \ref{MEMORY}, and
having shown several examples of other overloaded operators as well (i.e., the
insertion and extraction operators in chapters \ref{FirstImpression} and
\ref{IOStreams}), we now take a look at \index{operator overloading}operator overloading in general.

\section{Overloading `operator{[}{]}()'}\label{OPERATORINDEX}
\typeout{Original Yodl file: overloading/array}As our next example of operator overloading, we introduce a class \texttt{IntArray}
encapsulating an array of \texttt{int}s. Indexing the array elements is possible
using the standard array index operator \texttt{{[}{]}}, but additionally checks for
 \index{array bounds overflow}array bounds overflow are performed (note, however, that index checking is
not normally done by index operators. Since it's good practice to avoid
surprises array bound checks should normally not be performed by overloaded
index operators). The
 \index{index operator}index operator (\index{operator[]}\texttt{operator{[}{]}}) is interesting because it can be used  in
expressions as both \index{lvalue}lvalue and as \index{rvalue}rvalue.

Here is an example illustrating the basic use of the class:
        \begin{verbatim}
    int main()
    {
        IntArray x{ 20 };               // 20 ints

        for (int idx = 0; idx < 20; ++idx)
            x[idx] = 2 * idx;                   // assign the elements

        for (int idx = 0; idx <= 20; ++idx)     // result: boundary overflow
            cout << "At index " << idx << ": value is " << x[idx] << '\n';
    }
\end{verbatim}
    First, the constructor is used to create an object containing 20
\texttt{int}s. The elements stored in the object can be assigned or retrieved. The
first \texttt{for}-loop assigns values to the elements using the index operator,
the second \texttt{for}-loop retrieves the values but also results in a run-time
error once the non-existing value \texttt{x{[}20{]}} is addressed. The \texttt{IntArray}
class interface is:
        \begin{verbatim}
    #include <cstddef>

    class IntArray
    {
        size_t d_size;
        int     *d_data;

         public:
            IntArray(size_t size = 1);
            IntArray(IntArray const &other);
            ~IntArray();
            IntArray &operator=(IntArray const &other);

                                                // overloaded index operators:
            int &operator[](size_t index);              // first
            int const &operator[](size_t index) const;  // second

            void swap(IntArray &other);         // trivial

        private:
            void boundary(size_t index) const;
            int &operatorIndex(size_t index) const;
    };
\end{verbatim}
    This class has the following characteristics:
    \begin{itemize}
    \item  One of its constructors has a \texttt{size\_t} parameter having a
default argument value, specifying the number of \texttt{int} elements in the
object.
    \item  The class internally uses a pointer to reach allocated memory.
Hence, the necessary tools are provided: a copy constructor, an overloaded
assignment operator and a destructor.
    \item  That there are two overloaded index operators. Why are there
two?

The first overloaded index operator allows us to reach and modify the
elements of non-constant \texttt{IntArray} objects.  This overloaded operator's
prototype is a function returning a reference to an \texttt{int}, allowing
us to use an expression like \texttt{x{[}10{]}} as rvalue \emph{or} lvalue.

With non-const \texttt{IntArray} objects \texttt{operator{[}{]}} can therefore be used
to retrieve and to assign values.  Therefore, the return value of the
non-const \texttt{operator{[}{]}} member is an \texttt{int \&}, to allow modification of the
elements when used as lvalue, whereas the return value of the const
\texttt{operator{[}{]}} member is preferably an \texttt{int const \&}, rather than a mere
\texttt{int}. In this situation we prefer the use of a \texttt{const \&} return value to
allow immediate writing of the return value to, e.g., a binary file, as in:
    \begin{verbatim}
    void writeValue(Intarray const &iarr, size_t idx)
    {
        cout.write(reinterpret_cast<char const *>(&iarr[idx]));
    }
\end{verbatim}
This whole scheme fails if there's nothing to assign. Consider the
situation where we have an \texttt{IntArray const stable(5)}. Such an object is an
immutable \emph{const} object. The compiler detects this and refuses to compile
this object definition if only the non-const \texttt{operator{[}{]}} is
available. Hence the second overloaded index operator is added to the class's
interface. This second form of the overloaded index operator is automatically
used by the compiler with \texttt{const} objects. It is used for value
\emph{retrieval} instead of value assignment. That, of course, is precisely what
we want when using \texttt{const} objects. In this situation members are overloaded
only by their \texttt{const} attribute. This form of function overloading was
introduced earlier in the \textbf{C++} Annotations (sections \ref{FunctionOverloading} and
\ref{ConstFunctions}).

\item  As there is only one pointer data member, the destruction of the
memory allocated by the object is a simple \texttt{delete{[}{]} data}.
    \end{itemize}

Now, the implementation of the members (omitting the trivial
implementation of \texttt{swap}, cf. chapter \ref{MEMORY}) are:
        \begin{verbatim}
    #include "intarray.ih"

    IntArray::IntArray(size_t size)
    :
        d_size(size)
    {
        if (d_size < 1)
            throw "IntArray: size of array must be >= 1"s;

        d_data = new int[d_size];
    }

    IntArray::IntArray(IntArray const &other)
    :
        d_size(other.d_size),
        d_data(new int[d_size])
    {
        memcpy(d_data, other.d_data, d_size * sizeof(int));
    }

    IntArray::~IntArray()
    {
        delete[] d_data;
    }

    IntArray &IntArray::operator=(IntArray const &other)
    {
        IntArray tmp(other);
        swap(tmp);
        return *this;
    }

    int &IntArray::operatorIndex(size_t index) const
    {
        boundary(index);
        return d_data[index];
    }

    int &IntArray::operator[](size_t index)
    {
        return operatorIndex(index);
    }

    int const &IntArray::operator[](size_t index) const
    {
        return operatorIndex(index);
    }

    void IntArray::swap(IntArray &other)
    {
        // swaps the d_size and d_data data members
        // of *this and other
    }


    void IntArray::boundary(size_t index) const
    {
        if (index < d_size)
            return;
        ostringstream out;
        out  << "IntArray: boundary overflow, index = " <<
                index << ", should be < " << d_size << '\n';
        throw out.str();
    }
\end{verbatim}
    Note how the \texttt{operator{[}{]}} members were implemented: as non-const members
may call const member functions and as the implementation of the \texttt{const}
member function is identical to the non-const member function's implementation
both \texttt{operator{[}{]}} members could be defined inline using an auxiliary
function \texttt{int \&operatorIndex(size\_t index) const}.  A \texttt{const} member
function may return a non-const reference (or pointer) return value, referring
to one of the data members of its object. Of course, this is a potentially
dangerous backdoor that may break data hiding. However, the members in the
public interface prevent this breach and so the two public \texttt{operator{[}{]}}
members may themselves safely call the same \texttt{int \&operatorIndex() const}
member, that defines a
 \index{private backdoor}\emph{private backdoor}.

\subsection{Multi-argument `operator{[}{]}()'}
    \typeout{Original Yodl file: overloading/multiindex}Consider a standard two-dimensional array. It has \texttt{nRows} rows and \texttt{nCols}
columns. Such an array is a generalization of a one-dimensional array: each
row consists of an array of \texttt{nCols} elements. If a type \texttt{DoubleArray} is
available, defined like the \texttt{IntArray} of the previous section, but
containing \texttt{double} values instead of \texttt{int} values, then designing a class
\texttt{Matrix} could start as follows:
        \begin{verbatim}
    class Matrix
    {
        size_t d_nRows;
        size_t d_nCols;
        DoubleArray *d_row;

        public:
            Matrix(size_t nRows, size_t nCols);
        ...
    };
\end{verbatim}
    and its constructor allocates \texttt{nRows DoubleArrays}, each having
\texttt{nCols} columns, with each \texttt{DoubleArray} being initialized to a \texttt{nCols}
elements, initialized to 0 by the \texttt{DoubleArray's} default constructor:
        \begin{verbatim}
    Matrix::Matrix(size_t nRows, size_t nCols)
    :
        d_nRows(nRows),
        d_nCols(nCols),
        d_row(new DoubleArray[nRows])
    {}
\end{verbatim}
Traditionally accessing elements of a \texttt{Matrix} could be realized in three
ways (plus optionally corresponding \texttt{const} variants):
    \begin{itemize}
    \item  A member \texttt{double \&element(size\_t row, size\_t col)}, returning the
        value of element \texttt{{[}row, col{]}};
    \item  A member \texttt{DoubleArray \&row(size\_t row)}, returning \texttt{row's
        DoubleArray};
    \item  A member \texttt{DoubleArray \&operator{[}{]}(size\_t row)}, also returning
        \texttt{row's DoubleArray};
    \end{itemize}

The members \texttt{element} and \texttt{row} work fine, but at the disadvantage that
the standard syntax for referring to matrix elements is not used. E.g, to
access element \texttt{matrix{[}3, 4{]}} we would write \texttt{matrix.element(3, 4)} or
\texttt{matrix.row(3){[}4{]}}, whereas the third element requires us to use two index
operators: \texttt{matrix{[}3{]}{[}4{]}}. Moreover, with the second and third members data
hiding of \texttt{DoubleArray row} is abandoned if the only reason for these
members is to access \texttt{Matrix} elements.

\index{index operator: multiple arguments}\index{operator[]}\texttt{operator{[}{]}}
The overloaded index operator, however, can also be defined having multiple
arguments, allowing the use of the (standard mathematical) syntax
\texttt{matrix{[}row, col{]}} (and in general: the overloaded index operator can also
have more arguments, which might come in useful when defining, e.g., arrays of
arrays). 

Providing \texttt{Matrix} with an index operator accepting two arguments is simple:
just add a member \texttt{double \&operator{[}{]}(size\_t row, size\_t col)} (and
optionally a comparable \texttt{const} member) to the class's interface. Its
implementation may then directly return the requested array element:
        \begin{verbatim}
    double &Matrix::operator[](size_t row, size_t col)
    {
        return d_row[row][col];
    }
\end{verbatim}
As an aside: note that this implementation does not check whether the provided
indices are valid. Traditionally index operators don't perform such checks,
improving the efficiency of programs when it's \emph{known} that indices
cannot be invalid. E.g., to initialize all elements of a \texttt{Matrix} with
subsequent integral values the following function could be used:
        \begin{verbatim}
    void init(Matrix &matrix, size_t value)
    {
        for (size_t row = 0; row != matrix.nRows(); ++row)
            for (size_t col = 0; col != matrix.nCols(); ++col)
                matrix[row, col] = value++;
    }
\end{verbatim}
\index{at: multiple arguments}
If, on the other hand, checking the validity of the indices \emph{is} necessary
then a multi-argument \texttt{at} member like the following can be defined:
        \begin{verbatim}
    double &Matrix::at(size_t row, size_t col)
    {
        if (row >= d_nrows or col >= d_nCols)
            throw runtime_error("Matrix::at: invalid indices");
        return d_row[row][col];
    }
\end{verbatim}
\section{Overloading insertion and extraction operators}\label{EXTRACTORS}
\typeout{Original Yodl file: overloading/insertextract}    Classes may be adapted in such a way that their objects may be inserted
into and extracted from, respectively, a \texttt{std::ostream} and
\texttt{std::istream}.

The class \texttt{std::ostream} defines insertion operators for primitive
types, such as \texttt{int}, \texttt{char $*$}, etc.. In this section we learn how to
extend the existing functionality of classes (in particular \texttt{std::istream}
and \texttt{std::ostream}) in such a way that they can be used also in combination
with classes developed much later in history.

In particular we will show how the
 \index{insertion operator}insertion operator can be overloaded allowing the insertion of any type of
object, say \texttt{Person} (see chapter \ref{MEMORY}), into an \texttt{ostream}. Having
defined such an overloaded operator we're able to use the following code:
        \begin{verbatim}
    Person kr("Kernighan and Ritchie", "unknown", "unknown");

    cout << "Name, address and phone number of Person kr:\n" << kr << '\n';
\end{verbatim}
The statement \texttt{cout} $<<$ \texttt{kr} uses \texttt{operator}$<<$.  This member
function has two operands: an \texttt{ostream \&} and a \texttt{Person \&}. The required
action is defined in an overloaded \index{free function}\emph{free function} \texttt{operator}$<<$ expecting two
arguments:
        \begin{verbatim}
                                // declared in `person.h'
    std::ostream &operator<<(std::ostream &out, Person const &person);

                                // defined in some source file
    ostream &operator<<(ostream &out, Person const &person)
    {
        return
            out <<
                "Name:    " << person.name() << ", "
                "Address: " << person.address() << ", "
                "Phone:   " << person.phone();
    }
\end{verbatim}
The free function \texttt{operator}$<<$ has the following noteworthy characteristics:
    \begin{itemize}
    \item  The function returns a reference to an \texttt{ostream} object,
to enable `chaining' of the insertion operator.
    \item  The two operands of \texttt{operator}$<<$ are passed to the free function as its
arguments. In the example, the parameter \texttt{out} was initialized by \texttt{cout},
the parameter \texttt{person} by \texttt{kr}.
    \end{itemize}

In order to overload the \emph{extraction} operator for, e.g., the \texttt{Person}
class, members are needed modifying the class's private data members. Such
 \index{modifier}\emph{modifiers} are normally offered by the class interface. For
the \texttt{Person} class these members could be the following:
        \begin{verbatim}
    void setName(char const *name);
    void setAddress(char const *address);
    void setPhone(char const *phone);
\end{verbatim}
These members may easily be implemented: the memory
pointed to by the corresponding data member must be deleted, and the data
member should point to a copy of the text pointed to by the parameter. E.g.,
        \begin{verbatim}
    void Person::setAddress(char const *address)
    {
        delete[] d_address;
        d_address = strdupnew(address);
    }
\end{verbatim}
A more elaborate function should check the reasonableness of the new
address (\texttt{address} also shouldn't be a 0-pointer). This
however, is not further pursued here. Instead, let's have a look at the final
 \index{\textgreater{}\textgreater{}}\index{operator\textgreater{}\textgreater{}}\texttt{operator}$>>$. A simple implementation is:
        \begin{verbatim}
    istream &operator>>(istream &in, Person &person)
    {
        string name;
        string address;
        string phone;

        if (in >> name >> address >> phone)    // extract three strings
        {
            person.setName(name.c_str());
            person.setAddress(address.c_str());
            person.setPhone(phone.c_str());
        }
        return in;
    }
\end{verbatim}
Note the stepwise approach that is followed here. First, the required
information is extracted using available extraction operators. Then, if that
succeeds, \emph{modifiers} are used to modify the data members of the object to
be extracted. Finally, the stream object itself is returned as a reference.

\section{Conversion operators}\label{ConversionOperators}
\typeout{Original Yodl file: overloading/conversion}    A class may be constructed around a built-in type. E.g., a class
\texttt{String}, constructed around the \index{char *}\texttt{char $*$} type. Such a class may define
all kinds of operations, like assignments. Take a look at the following class
interface, designed after the \texttt{string} class:
        \begin{verbatim}
    class String
    {
        char *d_string;

        public:
            String();
            String(char const *arg);
            ~String();
            String(String const &other);
            String &operator=(String const &rvalue);
            String &operator=(char const *rvalue);
    };
\end{verbatim}
Objects of this class can be initialized from a \texttt{char const $*$}, and also
from a \texttt{String} itself. There is an overloaded assignment operator, allowing
the assignment from a \texttt{String} object and from a \texttt{char const
$*$}\footnote{Note that the assignment from a \texttt{char const $*$} also allows the
null-pointer. An assignment like \texttt{stringObject = 0} is perfectly in order.}.

Usually, in classes that are less directly linked to their data than this
\texttt{String} class, there will be an \index{accessor}\emph{accessor member function},
like a member \texttt{char const $*$String::c\_str() const}. However, the need to use
this latter member doesn't appeal to our intuition when an array of \texttt{String}
objects is defined by, e.g., a class \texttt{StringArray}. If this latter class
provides the \index{operator[]}\texttt{operator{[}{]}} to access individual \texttt{String} members, it would
most likely offer at least the following class interface:
        \begin{verbatim}
    class StringArray
    {
        String *d_store;
        size_t d_n;

        public:
            StringArray(size_t size);
            StringArray(StringArray const &other);
            StringArray &operator=(StringArray const &rvalue);
            ~StringArray();

            String &operator[](size_t index);
    };
\end{verbatim}
This interface allows us to assign \texttt{String} elements to each other:
        \begin{verbatim}
    StringArray sa{ 10 };

    sa[4] = sa[3];  // String to String assignment
\end{verbatim}
But it is also possible to assign a \texttt{char const $*$} to an element of
\texttt{sa}:
        \begin{verbatim}
    sa[3] = "hello world";
\end{verbatim}
Here, the following steps are taken:
    \begin{itemize}
    \item  First, \texttt{sa{[}3{]}} is evaluated. This results in a \texttt{String} reference.
    \item  Next, the \texttt{String} class is inspected for an overloaded assignment,
        expecting a \texttt{char const $*$} to its right-hand side. This operator is
        found, and the string object \texttt{sa{[}3{]}} receives its new value.
    \end{itemize}
    Now we try to do it the other way around: how to \emph{access} the
\texttt{char const $*$} that's stored in \texttt{sa{[}3{]}}? The following attempt fails:
        \begin{verbatim}
    char const *cp = sa[3];
\end{verbatim}
It fails since we would need an overloaded assignment operator for the
'class' \texttt{char const $*$}. Unfortunately, there isn't such a class, and
therefore we can't build that overloaded assignment operator (see also section
\ref{OverloadableOperators}). Furthermore, \emph{casting} won't work as the
compiler doesn't know how to cast a \texttt{String} to a \texttt{char const $*$}.  How
to proceed?

One possibility is to define an accessor member function \texttt{c\_str()}:
        \begin{verbatim}
    char const *cp = sa[3].c_str()
\end{verbatim}
This compiles fine but looks clumsy.... A far better approach would be to
use a \index{conversion operator}\emph{conversion operator}.

A \emph{conversion operator} is a kind of overloaded operator, but this time
the overloading is used to cast the object to another type.
In class interfaces, the general form of a
conversion operator is:
        \begin{verbatim}
    operator <type>() const;
\end{verbatim}
Conversion operators usually are \texttt{const} member functions: they are
automatically called when their objects are used as \emph{rvalues} in expressions
having a \texttt{type} \emph{lvalue}.  Using a conversion operator a \texttt{String}
object may be interpreted as a \texttt{char const $*$} rvalue, allowing us to perform
the above assignment.

Conversion operators are somewhat dangerous. The conversion is automatically
performed by the compiler and unless its use is perfectly transparent it may
confuse those who read code in which conversion operators are used. E.g.,
novice \textbf{C++} programmers are frequently confused by statements like `\texttt{if
(cin) ...}'.

As a \index{rule of thumb}rule of thumb: classes should define at most one conversion
operator. Multiple conversion operators may be defined but frequently result
in ambiguous code. E.g., if a class defines \texttt{operator bool() const} and
\texttt{operator int() const} then passing an object of this class to a function
expecting a \texttt{size\_t} argument results in an ambiguity as an \texttt{int} and a
\texttt{bool} may both be used to initialize a \texttt{size\_t}.

In the current example, the class \texttt{String} could define the following
conversion operator for \texttt{char const $*$}:
        \begin{verbatim}
    String::operator char const *() const
    {
        return d_string;
    }
\end{verbatim}
Notes:
    \begin{itemize}
    \item  Conversion operators do not define return types. The conversion
operator returns a value of the type specified beyond the \texttt{operator}
keyword.
    \item  In certain situations (e.g., when a \texttt{String} argument is passed to
a function specifying an \index{ellipsis}ellipsis parameter) the compiler needs a hand to
disambiguate our intentions. A \texttt{static\_cast} solves the problem.
    \item  With \emph{template functions} conversion operators may not work
immediately as expected. For example, when defining a conversion operator
\texttt{X::operator std::string const() const} then \texttt{cout $<$$<$ X()} won't
compile. The reason for this is explained in section \ref{SPECIALIZING}, but a
shortcut allowing the conversion operator to work is to define the following
overloaded \texttt{operator$<$$<$} function:
    \begin{verbatim}
std::ostream &operator<<(std::ostream &out, std::string const &str)
{
    return out.write(str.data(), str.length());
}
\end{verbatim}
\end{itemize}
    Conversion operators are also used when objects of classes defining
conversion operators are inserted into streams. Realize that the right hand
sides of insertion operators are function parameters that are initialized by
the operator's right hand side arguments. The rules are simple:
    \begin{itemize}
    \item  If a class \texttt{X} defining a conversion operator also defines an
insertion operator accepting an \texttt{X} object the insertion operator is used;
    \item  Otherwise, if the type returned by the conversion operator is
insertable then the conversion operator is used;
    \item  Otherwise, a compilation error results. Note that this happens if the
type returned by the conversion operator itself defines a conversion operator
to a type that may be inserted into a stream.
    \end{itemize}
    In the following example an object of class \texttt{Insertable} is directly
inserted; an object of the class \texttt{Convertor} uses the conversion operator;
an object of the class \texttt{Error} cannot be inserted since it does not define
an insertion operator and the type returned by its conversion operator cannot
be inserted either (\texttt{Text} \emph{does} define an \texttt{operator int() const}, but
the fact that a \texttt{Text} itself cannot be inserted causes the error):
        \begin{verbatim}
    #include <iostream>
    #include <string>
    using namespace std;

    struct Insertable
    {
        operator int() const
        {
            cout << "op int()\n";
            return 0;
        }
    };
    ostream &operator<<(ostream &out, Insertable const &ins)
    {
        return out << "insertion operator";
    }
    struct Convertor
    {
        operator Insertable() const
        {
            return Insertable();
        }
    };
    struct Text
    {
        operator int() const
        {
            return 1;
        }
    };
    struct Error
    {
        operator Text() const
        {
            return Text{};
        }
    };

    int main()
    {
        Insertable insertable;
        cout << insertable << '\n';
        Convertor convertor;
        cout << convertor << '\n';
        Error error;
        cout << error << '\n';
    }
\end{verbatim}
Some final remarks regarding conversion operators:
    \begin{itemize}
    \item  A conversion operator should be a `natural extension' of the
facilities of the object. For example, the stream classes define \texttt{operator
bool()}, allowing constructions like \texttt{if (cin)}.
    \item  A conversion operator usually returns an \emph{rvalue}. It does so
to enforce data-hiding and because it is the intended use of the conversion
operator. Defining a conversion operator as an \emph{lvalue} (e.g., defining an
\texttt{operator int \&()} conversion operator) opens up a back door, and the
operator can only be used as \emph{lvalue} when explicitly called (as in:
\texttt{x.operator int\&() = 5}). Don't normally use it, although there are
exceptions to this rule (cf. section \ref{BYTE}).
    \item  Conversion operators are normally defined as \texttt{const} member
functions as they normally don't modify their object's data members (but
again: see section \ref{BYTE}).
    \item  Conversion operators returning composed objects should return const
references to these objects whenever possible to avoid calling the composed
object's copy constructor.
    \end{itemize}

\section{An alternative implementation of the `byte' type}\label{BYTE}
\typeout{Original Yodl file: overloading/byte}In chapter \ref{FirstImpression} the \texttt{std::byte} type was introduced. It
offers bit-wise and comparison operators but lacks other arithmetic operators
as well as insertion and extraction operators, which may render it less
useful. Fortunately, using the facilities provided by operator overloading a
more generically useful byte-type can be developed.

In this section we develop a class \texttt{Byte} offering all facilities of numeric
types, as well as insertion and extraction operators, while the size of a
\texttt{Byte} object equals the size of an \texttt{unsigned char}: 1 byte.

A size 1 \texttt{Byte} type is realized by defining a class \texttt{Byte} having a
single \texttt{uint8\_t} data member. Insertion and extraction operators are
provided by free functions. The class \texttt{Byte}, therefore, starts as follows:
    \begin{verbatim}
    #include <iostream>
    #include <cstdint>          // uint8_t
    
    class Byte
    {
        uint8_t d_byte;
\end{verbatim}
All the class's member functions are public: \texttt{Byte} objects can be defined
using the default constructor, the copy constructor, and a constructor
accepting any argument that can be converted to a \texttt{uint8\_t}:
    \begin{verbatim}
            Byte();                     // CC available by default
            Byte(uint8_t byte);
\end{verbatim}
\texttt{Byte} objects can be used as lvalues, so assignment operators must be
provided. The first (default) assignment operator handles assignment of
\texttt{Byte} objects, while the second assignment operator handles assignment of
numeric types which can be converted to \texttt{uint8\_t} values:
    \begin{verbatim}
            Byte &operator=(Byte const &rhs) = default;
            Byte &operator=(uint8_t rhs);
\end{verbatim}
Conversion operators are provided so \texttt{Byte} objects can be used in
situations where \texttt{uint8\_t} values are used:
    \begin{verbatim}
            operator uint8_t &();
            operator uint8_t() const;
\end{verbatim}
Athough conversion operators usually return const references, an excption
is made for \texttt{Byte} because of its semantics: as a \texttt{Byte} is essentially a
wrapper around a \texttt{uint8\_t} a non-const conversion operator is provided
allowing the use of arithmetic assignment operators. A statement like \texttt{byte
+= 13} (having defined \texttt{Byte byte}) is compiled as \texttt{byte.operator() = 13},
which requires the non-const conversion operator.

Most members require a single statement and can very well be implemented
inline. Here are their implementations:
    \begin{verbatim}
    inline Byte::Byte()
    :
        d_byte(0)
    {}
    
    inline Byte::Byte(uint8_t byte)
    :
        d_byte(byte)
    {}
    
    Byte &Byte::operator=(uint8_t rhs)
    {
        d_byte = rhs;
        return *this;
    }
    
    inline Byte::operator uint8_t &()
    {
        return d_byte;
    }
    
    inline Byte::operator uint8_t () const // 16_t
    {
        return d_byte;
    }
\end{verbatim}
The insertion and extraction operators act identically to the standard
insertion and extraction operators for \texttt{uint8\_t} type values: they insert
and extract the \texttt{char} representation of the \texttt{Byte}'s value, because
that's what insertion and extraction operators do: they process text. Here are
their one-line implementations, using the conversion operators to insert or
assign the \texttt{Byte's d\_byte} value:
    \begin{verbatim}
    inline std::ostream &operator<<(std::ostream &out, Byte const &byte)
    {
        return out << byte.operator uint8_t();
    }
    
    inline std::istream &operator>>(std::istream &in, Byte &byte)
    {
        return in >> byte.operator uint8_t &();
    }
\end{verbatim}
To write the \texttt{d\_byte's} binary value the stream's \texttt{write} member
should be used in the way it's always used: reinterpret a \texttt{Byte} as a
\texttt{char const $*$} and write a single byte. Reading a \texttt{Byte}'s binary value is
implemented analogously, using the stream's \texttt{read} member.

Finally, here are some examples of how \texttt{Byte} variables can be used in
practice: 
    \begin{verbatim}
    using namespace std;
    
    int main()
    {
        Byte b1;            // default: d_byte = 0
        Byte b2{ 12 };      // construct from an int
        Byte b3{ b2 };      // copy-construct
    
        b1 = 65;            // direct assignment
        b1 += 20;           // arithmetic assignment
    
        b1 <<= 1;           // shift-assignments
        b1 >>= 1;
    
        b1 |= 1;            // bit-or assignment
    
        uint8_t u8 = b1;    // assign Byte to an uint8_t
    
                            // some stream insertions
        cout << sizeof(Byte) << ',' << (b1 < b2) << ',' <<
                b1 << ',' << b3 << ',' << u8 << '\n';
    
                            // using 'write'
        cout.write(reinterpret_cast<char const *>(&b1), 1) << '\n';
    }
    
    // output:
    //  hex values                                 text ( . : not printable)
    //  31 2C 30 2C 55 2C 0C 2C 55 0A 55 0A        1,0,U,.,U.U.
\end{verbatim}
\section{The keyword `explicit'}\label{EXPLICIT}
\typeout{Original Yodl file: overloading/explicit.yo}    Conversions are not only performed by conversion operators, but also by
constructors accepting one argument (i.e., constructors having one or multiple
parameters, specifying default argument values for all parameters or for all
but the first parameter).

Assume a data base class \texttt{DataBase} is defined in which \texttt{Person}
objects can be stored. It defines a \texttt{Person $*$d\_data} pointer, and so it
offers a copy constructor and an overloaded assignment operator.

In addition to the copy constructor \texttt{DataBase} offers a default
constructor and several additional constructors:
    \begin{itemize}
    \item \texttt{DataBase(Person const \&)}: the \texttt{DataBase} initially contains a
single \texttt{Person} object;
    \item \texttt{DataBase(istream \&in)}: the data about multiple persons are read from
\texttt{in}.
    \item \texttt{DataBase(size\_t count, istream \&in = cin)}: the data of \texttt{count}
persons are read from \texttt{in}, by default the standard input stream.
    \end{itemize}

The above constructors all are perfectly reasonable. But they also allow
the compiler to compile the following code without producing any warning at
all:
        \begin{verbatim}
    DataBase db;
    DataBase db2;
    Person person;

    db2 = db;           // 1
    db2 = person;       // 2
    db2 = 10;           // 3
    db2 = cin;          // 4
\end{verbatim}
Statement 1 is perfectly reasonable: \texttt{db} is used to redefine
\texttt{db2}. Statement 2 might be understandable since we designed \texttt{DataBase} to
contain \texttt{Person} objects. Nevertheless, we might question the logic that's
used here as a \texttt{Person} is not some kind of \texttt{DataBase}. The logic becomes
even more opaque when looking at statements 3 and 4. Statement 3 in effect
waits for the data of 10 persons to appear at the standard input
stream. Nothing like that is suggested by \texttt{db2 = 10}.

Implicit \index{promotion}promotions are used with statements 2 through 4. Since
constructors accepting, respectively a \texttt{Person}, an \texttt{istream}, and a
\texttt{size\_t} and an \texttt{istream} have been defined for \texttt{DataBase} and since the
assignment operator expects a \texttt{DataBase} right-hand side (rhs) argument the
compiler first converts the rhs arguments to anonymous \texttt{DataBase} objects
which are then assigned to \texttt{db2}.

It is good practice to prevent implicit promotions by using the
 \index{explicit}\texttt{explicit} modifier when declaring a constructor. Constructors using the
\texttt{explicit} modifier can only be used to construct objects
explicitly. Statements 2-4 would not have compiled if the constructors
expecting one argument would have been declared using \texttt{explicit}. E.g.,
        \begin{verbatim}
    explicit DataBase(Person const &person);
    explicit DataBase(size_t count, std:istream &in);
\end{verbatim}
Having declared all constructors accepting one argument as \texttt{explicit}
the above assignments would have required the explicit specification of
the appropriate constructors, thus clarifying the programmer's intent:
        \begin{verbatim}
    DataBase db;
    DataBase db2;
    Person person;

    db2 = db;                   // 1
    db2 = DataBase{ person };   // 2
    db2 = DataBase{ 10 };       // 3
    db2 = DataBase{ cin };      // 4
\end{verbatim}
As a \index{rule of thumb}rule of thumb prefix one argument constructors with the
\texttt{explicit} keyword unless implicit promotions are perfectly natural
(\texttt{string}'s \texttt{char const $*$} accepting constructor is a case in point).

\subsection{Explicit conversion operators}
    \typeout{Original Yodl file: overloading/explicitconversion}In addition to explicit constructors, \textbf{C++} supports
 \index{explicit: conversion operator}\index{conversion operator: explicit}
\emph{explicit conversion operators}.

For example, a class might define \texttt{operator bool() const} returning \texttt{true}
if an object of that class is in a usable state and \texttt{false} if not.
Since the type \texttt{bool} is an arithmetic type this could result in unexpected
or unintended behavior. Consider:
        \begin{verbatim}
    void process(bool value);

    class StreamHandler
    {
        public:
            operator bool() const;      // true: object is fit for use
            ...
    };

    int fun(StreamHandler &sh)
    {
        int sx;

        if (sh)                         // intended use of operator bool()
            ... use sh as usual; also use `sx'

        process(sh);                    // typo: `sx' was intended
    }
\end{verbatim}
In this example \texttt{process} unintentionally receives the value returned by
\texttt{operator bool} using the implicit conversion from \texttt{bool} to \texttt{int}.

When defining \texttt{explicit} conversion operators implicit conversions like the
one shown in the example are prevented. Such conversion operators can only be
used in situations where the converted type is explicitly required (as in the
condition clauses of \texttt{if} or \texttt{while} statements), or is explicitly
requested using a \texttt{static\_cast}. To declare an explicit bool conversion
operator in class \texttt{StreamHandler}'s interface replace the above declaration
by:
    \begin{verbatim}
        explicit operator bool() const;
\end{verbatim}
Since the C++14 standard \texttt{istreams} define an 
    \texttt{explicit operator bool() const}. As a consequence:
    \begin{verbatim}
    while (cin.get(ch)) // compiles OK
        ;

    bool fun1()
    {
        return cin;     // 'bool = istream' won't compile as 
    }                   // istream defines 'explicit operator bool'

    bool fun1()
    {
        return static_cast<bool>(cin); // compiles OK
    }
\end{verbatim}
\section{Overloading increment and decrement operators}\label{OVERLOADINCR}
\typeout{Original Yodl file: overloading/increment.yo}Overloading the 
    \index{increment operator}increment operator \index{operator++}(\texttt{operator++}) and
    \index{decrement operator}decrement operator (\index{operator-{}-{}} \texttt{operator-{}-{}}) introduces a
small problem: there are two versions of each operator, as they may be used as
\emph{postfix operator} (e.g., \texttt{x++}) or as \emph{prefix operator} (e.g.,
\texttt{++x}).

Used as \emph{postfix} operator, the value's object is returned as an
\index{rvalue}\emph{rvalue}, temporary const object and the post-incremented variable itself
disappears from view. Used as \emph{prefix} operator, the variable is
incremented, and its value is returned as \index{lvalue}\emph{lvalue} and it may be altered
again by modifying the prefix operator's return value. Whereas these
characteristics are not \emph{required} when the operator is overloaded, it is
strongly advised to implement these characteristics in any overloaded
increment or decrement operator.

Suppose we define a \index{wrapper class}\emph{wrapper class} around the \texttt{size\_t} value
type. Such a class could offer the following (partially shown) interface:
        \begin{verbatim}
    class Unsigned
    {
        size_t d_value;

        public:
            Unsigned();
            explicit Unsigned(size_t init);

            Unsigned &operator++();
    }
\end{verbatim}
The class's last member declares the \emph{prefix} overloaded increment
operator. The returned \emph{lvalue} is \texttt{Unsigned \&}. The member is easily
implemented:
        \begin{verbatim}
    Unsigned &Unsigned::operator++()
    {
        ++d_value;
        return *this;
    }
\end{verbatim}
To define the \emph{postfix} operator, an overloaded version of the operator
is defined, expecting a (dummy) \texttt{int} argument. This might be considered a
\index{kludge}\emph{kludge}, or an acceptable application of function overloading. Whatever
your opinion in this matter, the following can be concluded:
    \begin{itemize}
    \item  Overloaded increment and decrement operators \emph{without parameters}
are \emph{prefix} operators, and should return \emph{references} to the current
object.
    \item  Overloaded increment and decrement operators \emph{having an int
parameter} are \emph{postfix} operators, and should return a value which
is a copy of the object at the point where its postfix operator is used.
    \end{itemize}
    The postfix increment operator is declared as follows in the class
\texttt{Unsigned}'s interface:
        \begin{verbatim}
    Unsigned operator++(int);
\end{verbatim}
It may be implemented as follows:
        \begin{verbatim}
    Unsigned Unsigned::operator++(int)
    {
        Unsigned tmp{ *this };
        ++d_value;
        return tmp;
    }
\end{verbatim}
Note that the operator's parameter is not used. It is only part of the
implementation to \emph{disambiguate} the prefix- and postfix operators in
implementations and declarations.

In the above example the statement incrementing the current object offers
the \emph{nothrow} guarantee as it only involves an operation on a
primitive type. If the initial copy construction throws then the original
object is not modified, if the return statement throws the object has safely
been modified. But incrementing an object could itself throw exceptions. How
to implement the increment operators in that case? Once again, \texttt{swap} is our
friend. Here are the pre- and postfix operators offering the strong guarantee
when the member \texttt{increment} performing the increment operation may throw:
        \begin{verbatim}
    Unsigned &Unsigned::operator++()
    {
        Unsigned tmp{ *this };
        tmp.increment();
        swap(tmp);
        return *this;
    }
    Unsigned Unsigned::operator++(int)
    {
        Unsigned tmp{ *this };
        tmp.increment();
        swap(tmp);
        return tmp;
    }
\end{verbatim}
Both operators first create copies of the current objects. These copies
are incremented and then swapped with the current objects. If \texttt{increment}
throws the current objects remain unaltered; the swap operations ensure that
the correct objects are returned (the incremented object for the prefix
operator, the original object for the postfix operator) and that the current
objects become the incremented objects.

When calling the increment or decrement operator using its full member
function name then any \texttt{int} argument passed to the function results in
calling the postfix operator. Omitting the argument results in calling the
prefix operator. Example:
        \begin{verbatim}
    Unsigned uns{ 13 };

    uns.operator++();     // prefix-incrementing uns
    uns.operator++(0);    // postfix-incrementing uns
\end{verbatim}
Both the prefix and postfix increment and decrement operators are deprecated
when applied to \texttt{bool} type of variables. In situations where a postfix
increment operator could be useful the \texttt{std::exchange} (cf. section
\ref{EXCHANGE}) should be used.

\section{Overloading binary operators}\label{OVERLOADBINARY}
\typeout{Original Yodl file: overloading/binary.yo}    In various classes overloading binary operators (like \index{operator+}\texttt{operator+}) can
be a very natural extension of the class's functionality. For example, the
\texttt{std::string} class has various overloaded \texttt{operator+} members.

Most binary operators come in two flavors: the plain binary operator (like
the \texttt{+} operator) and the compound binary assignment operator (like
\texttt{operator+=}). Whereas the plain binary operators return values, the
compound binary assignment operators usually return references to the objects
for which the operators were called. For example, with \texttt{std::string} objects
the following code (annotations below the example) may be used:
        \begin{verbatim}
    std::string s1;
    std::string s2;
    std::string s3;

    s1 = s2 += s3;                  // 1
    (s2 += s3) + " postfix";        // 2
    s1 = "prefix " + s3;            // 3
    "prefix " + s3 + "postfix";     // 4
\end{verbatim}
    \begin{itemize}
    \item  at \texttt{// 1} the content of \texttt{s3} is added to \texttt{s2}. Next, \texttt{s2}
is returned, and its new content is assigned to \texttt{s1}. Note that \texttt{+=}
returns \texttt{s2}.
    \item  at \texttt{// 2} the content of \texttt{s3} is also added to \texttt{s2}, but as
\texttt{+=} returns \texttt{s2} itself, it's possible to add some more to \texttt{s2}
    \item  at \texttt{// 3} the \texttt{+} operator returns a \texttt{std::string} containing
the concatenation of the text \texttt{prefix} and the content of \texttt{s3}. This
string returned by the \texttt{+} operator is thereupon assigned to \texttt{s1}.
    \item  at \texttt{// 4} the \texttt{+} operator is applied twice. The effect is:
        \begin{enumerate}
        \item  The first \texttt{+} returns a \texttt{std::string} containing
the concatenation of the text \texttt{prefix} and the content of \texttt{s3}.
        \item  The second \texttt{+} operator takes this returned string as its left
hand value, and returns a string containing the concatenated text of its left
and right hand operands.
        \item  The string returned by the second \texttt{+} operator represents the
value of the expression.
        \end{enumerate}
    \end{itemize}

Now consider the following code, in which a class \texttt{Binary} supports an
overloaded \texttt{operator+}:
        \begin{verbatim}
    class Binary
    {
        public:
            Binary();
            Binary(int value);
            Binary operator+(Binary const &rhs);
    };

    int main()
    {
        Binary b1;
        Binary b2{ 5 };

        b1 = b2 + 3;            // 1
        b1 = 3 + b2;            // 2
    }
\end{verbatim}
    Compilation of this little program fails for statement \texttt{// 2}, with the
compiler reporting an error like:
        \begin{verbatim}
    error: no match for 'operator+' in '3 + b2'
\end{verbatim}
Why is statement \texttt{// 1} compiled correctly whereas statement \texttt{// 2}
won't compile?

In order to understand this remember \emph{promotions}. As we have seen in
section \ref{EXPLICIT}, constructors expecting single arguments may implicitly
be activated when an argument of an appropriate type is provided. We've
already encountered this with \texttt{std::string} objects, where NTBSs may be used
to initialize \texttt{std::string} objects.

Analogously, in statement \texttt{// 1}, \texttt{operator+} is called, using \texttt{b2}
as its left-hand side operand. This operator expects another \texttt{Binary} object
as its right-hand side operand. However, an \texttt{int} is provided. But as a
constructor \texttt{Binary(int)} exists, the \texttt{int} value can be promoted to a
\texttt{Binary} object. Next, this \texttt{Binary} object is passed as argument to the
\texttt{operator+} member.

Unfortunately, in statement \texttt{// 2} promotions are not available: here
the \texttt{+} operator is applied to an \texttt{int}-type lvalue. An \texttt{int} is a
primitive type and primitive types have no knowledge of `constructors',
`member functions' or `promotions'.

How, then, are promotions of left-hand operands implemented in statements
like \texttt{"prefix " + s3}? Since promotions can be applied to function
arguments, we must make sure that both operands of binary operators are
arguments. This implies that plain binary operators supporting promotions for
either their left-hand side operand or right-hand side operand should be
declared as
        \index{operator: free}\index{function: free}\emph{free operators},
    also called \emph{free functions}.

Functions like the plain binary operators conceptually belong to the class
for which they implement these operators. Consequently they should be
declared in the class's header file. We cover their implementations
shortly, but here is our first revision of the declaration of the class
\texttt{Binary}, declaring an overloaded \texttt{+} operator as a free function:
        \begin{verbatim}
    class Binary
    {
        public:
            Binary();
            Binary(int value);
    };

    Binary operator+(Binary const &lhs, Binary const &rhs);
\end{verbatim}
After defining binary operators as free functions, several promotions are
available:
    \begin{itemize}
    \item  If the left-hand operand is of the intended class type, the right
hand argument is promoted whenever possible;
    \item  If the right-hand operand is of the intended class type, the left
hand argument is promoted whenever possible;
    \item  No promotions occur when neither operand is of the intended
class type;
    \item  An ambiguity occurs when promotions to different classes are possible
for the two operands. For example:
        \begin{verbatim}
    class A;

    class B
    {
        public:
            B(A const &a);
    };

    class A
    {
        public:
            A();
            A(B const &b);
    };

    A operator+(A const &a, B const &b);
    B operator+(B const &b, A const &a);

    int main()
    {
        A a;

        a + a;
    };
\end{verbatim}
    Here, both overloaded \texttt{+} operators are possible candidates when
compiling the statement \texttt{a + a}. The ambiguity must be solved by explicitly
promoting one of the arguments, e.g., \texttt{a + B\{a\}}, which enables the compiler
to resolve the ambiguity to the first overloaded \texttt{+} operator.
    \end{itemize}

The next step consists of implementing the required overloaded binary
compound assignment operators, having the form \texttt{@=}, where \texttt{@} represents
a binary operator. As these operators \emph{always} have left-hand side operands
which are object of their own classes, they are implemented as genuine member
functions. Compound assignment operators usually return references to the
objects for which the binary compound assignment operators were requested, as
these objects might be modified in the same statement. E.g.,
    \texttt{(s2 += s3) + " postfix"}. 

Here is our second revision of the class \texttt{Binary}, showing the
declaration of the plain binary operator as well as the corresponding compound
assignment operator:
        \begin{verbatim}
    class Binary
    {
        public:
            Binary();
            Binary(int value);

            Binary &operator+=(Binary const &rhs);
    };

    Binary operator+(Binary const &lhs, Binary const &rhs);
\end{verbatim}
How should the compound addition assignment operator be implemented?  When
implementing compound binary assignment operators the strong guarantee should
always be kept in mind: if the operation might throw use a temporary object
and swap. Here is our implementation of the compound assignment operator:
        \begin{verbatim}
    Binary &Binary::operator+=(Binary const &rhs)
    {
        Binary tmp{ *this };
        tmp.add(rhs);           // this might throw
        swap(tmp);
        return *this;
    }
\end{verbatim}
It's easy to implement the free binary operator: the \texttt{lhs} argument is
copied into a \texttt{Binary tmp} to which the \texttt{rhs} operand is added. Then
\texttt{tmp} is returned, using copy elision. The class \texttt{Binary} declares the
free binary operator as a friend (cf. chapter \ref{Friends}), so it can call
\texttt{Binary's add} member:
        \begin{verbatim}
    class Binary
    {
        friend Binary operator+(Binary const &lhs, Binary const &rhs);

        public:
            Binary();
            Binary(int value);

            Binary &operator+=(Binary const &other);

        private:
            void add(Binary const &other);
    };
\end{verbatim}
The binary operator's implementation becomes:
        \begin{verbatim}
    Binary operator+(Binary const &lhs, Binary const &rhs)
    {
        Binary tmp{ lhs };
        tmp.add(rhs);
        return tmp;
    }
\end{verbatim}
If the class \texttt{Binary} is move-aware then it's attractive to add move-aware
binary operators. In this case we also need operators whose left-hand side
operands are rvalue references. When a class is move aware various interesting
implementations are suddenly possible, which we encounter below, and in
the next (sub)section. First have a look at the signature of such a binary
operator (which should also be declared as a friend in the class interface):
        \begin{verbatim}
    Binary operator+(Binary &&lhs, Binary const &rhs);
\end{verbatim}
Since the lhs operand is an rvalue reference, we can modify it \emph{ad lib}. 
Binary operators are commonly designed as factory functions, returning objects
created by those operators. However, the (modified) object referred to by 
\texttt{lhs} should itself \emph{not} be returned. As stated in the C++ standard,
    \begin{quote} 
    A temporary object bound to a reference parameter in a function call
    persists until the completion of the full-expression containing the call.
    \end{quote}
and furthermore: 
    \begin{quote} 
    The lifetime of a temporary bound to the returned value in a function
    return statement is not extended; the temporary is destroyed at the end of
    the full-expression in the return statement.
    \end{quote}
    In other words, a temporary object cannot itself be returned as the
function's return value: a \texttt{Binary \&\&} return type should therefore not be
used. Therefore functions implementing binary operators are factory functions
(note, however, that the returned object may be constructed using the class's
move constructor whenever a temporary object has to be returned).

Alternatively, the binary operator can first create an object by move
constructing it from the operator's lhs operand, performing the binary
operation on that object and the operator's rhs operand, and then return the
modified object (allowing the compiler to apply copy elision). It's a matter
of taste which one is preferred.

Here are the two implementations. Because of copy elision the explicitly
defined \texttt{ret} object is created in the location of the return value. Both
implementations, although they appear to be different, show identical run-time
behavior:
        \begin{verbatim}
                // first implementation: modify lhs
    Binary operator+(Binary &&lhs, Binary const &rhs)   
    {
        lhs.add(rhs);
        return std::move(lhs);
    }
                // second implementation: move construct ret from lhs
    Binary operator+(Binary &&lhs, Binary const &rhs)   
    {
        Binary ret{ std::move(lhs) };
        ret.add(rhs);
        return ret;
    }
\end{verbatim}
Now, when executing expressions like (all \texttt{Binary} objects) 
\texttt{b1 + b2 + b3} the following functions are called:
        \begin{verbatim}
    copy operator+          = b1 + b2 
    Copy constructor        = tmp(b1) 
        adding              = tmp.add(b2)
    copy elision            : tmp is returned from b1 + b2
        
    move operator+          = tmp + b3 
    adding                  = tmp.add(b3)
    Move construction       = tmp2(move(tmp)) is returned
\end{verbatim}
But we're not there yet: in the next section we encounter possibilities
for several more interesting implementations, in the context of compound
assignment operators.

\subsection{Member function reference bindings (\& and \&\&)}\label{REFBIND}
    \typeout{Original Yodl file: overloading/reference.yo}We've seen that binary operators (like \texttt{operator+}) can be implemented very
efficiently, but require at least move constructors.

An expression like
        \begin{verbatim}
    Binary{} + varB + varC + varD
\end{verbatim}
therefore returns a move constructed object representing \texttt{Binary\{\} +
varB}, then another move constructed object receiving the first return value
and \texttt{varC}, and finally yet another move constructed object receiving the
second returned object and \texttt{varD} as its arguments.

Now consider the situation where we have a function defining a \texttt{Binary \&\&}
parameter, and a second \texttt{Binary const \&} parameter. Inside that function
these values need to be added, and their sum is then passed as argument to two
other functions. We \emph{could} do this:
        \begin{verbatim}
    void fun1(Binary &&lhs, Binary const &rhs)
    {
        lhs += rhs;
        fun2(lhs);
        fun3(lhs);
    }
\end{verbatim}
But realize that when using \texttt{operator+=} we first construct a copy of
the current object, so a temporary object is available to perform the addition
on, and then swap the temporary object with the current object to commit the
results. But wait! Our lhs operand already \emph{is} a temporary object. So why
create another?

In this example another temporary object is indeed not required: \texttt{lhs}
remains in existence until \texttt{fun1} ends. But different from the binary
operators the binary compound assignment operators don't have explicitly
defined left-hand side operands. But we still can inform the compiler that a
particular \emph{member} (so, not merely compound assignment operators) should
only be used when the objects calling those members is an anonymous temporary
object, or a non-anonymous (modifiable or non-modifiable) object. For this
we use
    \emph{reference bindings}\index{reference binding} a.k.a.  
    \emph{reference qualifiers}\index{reference qualifier}. 

Reference bindings consist of a reference token (\texttt{\&}), optionally
preceded by \texttt{const}, or an rvalue reference token (\texttt{\&\&}). Such reference
qualifiers are immediately affixed to the function's head (this applies to the
declaration and the implementation alike). Functions provided with rvalue
reference bindings are selected by the compiler when used by anonymous
temporary objects, whereas functions provided with lvalue reference bindings
are selected by the compiler when used by other types of objects.

Reference qualifiers allow us to fine-tune our implementations of compound
assignment operators like \texttt{operator+=}. If we know that the object calling
the compound assignment operator is itself a temporary, then there's no need
for a separate temporary object. The operator may directly perform its
operation and could then return itself as an rvalue reference. Here is the
implementation of \texttt{operator+=} tailored to being used by temporary objects:
        \begin{verbatim}
    Binary &&Binary::operator+=(Binary const &rhs) &&
    {
        add(rhs);                   // directly add rhs to *this, 
        return std::move(*this);    // return the temporary object itself
    }
\end{verbatim}
This implementation is about as fast as it gets. But be careful: in the
previous section we learned that a temporary is destroyed at the end of the
full expression of a return stattement. In this case, however, the temporary
already exists, and so (also see the previous section) it should persist until
the expression containing the (\texttt{operator+=}) function call is completed. As
a consequence,
            \begin{verbatim}
    cout << (Binary{} += existingBinary) << '\n';
\end{verbatim}
is OK, but
            \begin{verbatim}
    Binary &&rref = (Binary{} += existingBinary);
    cout << rref << '\n';
\end{verbatim}
is not, since \texttt{rref} becomes a dangling reference immediately after its
initialization. 

A full-proof alternative implementation of the rvalue-reference bound
\texttt{operator+=} returns a move-constructed copy:
        \begin{verbatim}
    Binary Binary::operator+=(Binary const &rhs) &&
    {
        add(rhs);                   // directly add rhs to *this, 
        return std::move(*this);    // return a move constructed copy
    }
\end{verbatim}
The price to pay for this full-proof implementation is an extra move
construction. Now, using the previous example (using \texttt{rref}), \texttt{operator+=}
returns a copy of the \texttt{Binary\{\}} temporary, which is still a temporary
object which can safely be referred to by \texttt{rref}.

Which implementation to use may be a matter of choice: if users of
\texttt{Binary} know what they're doing then the former implementation can be used,
since these users will never use the above \texttt{rref} initialization. If you're
not so sure about your users, use the latter implementation: formally your
users will do something they shouldn't do, but there's no penalty for that.

For the compound assignment operator called by an lvalue reference (i.e.,
a named object) we use the implementation for \texttt{operator+=} from the previous
section (note the reference qualifier):
        \begin{verbatim}
    Binary &Binary::operator+=(Binary const &rhs) &
    {
        Binary tmp(*this);
        tmp.add(rhs);           // this might throw
        swap(tmp);
        return *this;
    }
\end{verbatim}
With this implementation adding \texttt{Binary} objects to each other
(e.g., \texttt{b1 += b2 += b3}) boils down to
        \begin{verbatim}
    operator+=    (&)       = b2 += b3
    Copy constructor        = tmp(b2) 
        adding              = tmp.add(b3)
        swap                = b2 <-> tmp
    return                  = b2

    operator+=    (&)       = b1 += b2
    Copy constructor        = tmp(b1) 
        adding              = tmp.add(b2)
        swap                = b1 <-> tmp
    return                  = b1
\end{verbatim}
When the leftmost object is a temporary then a copy construction and swap
call are replaced by the construction of an anonymous object. E.g.,
with \texttt{Binary\{\} += b2 += b3} we observe:
        \begin{verbatim}
    operator+=    (&)       = b2 += b3
    Copy constructor        = tmp(b2) 
        adding              = tmp.add(b3)
        swap                = b2 <-> tmp
    
    Anonymous object        = Binary{}

    operator+=    (&&)      = Binary{} += b2
        adding              = add(b2)

    return                  = move(Binary{})
\end{verbatim}
For \texttt{Binary \&Binary::operator+=(Binary const \&rhs) \&} an alternative
implementation exists, merely using a single return statement, but in fact
requiring two extra function calls. It's a matter of taste whether you prefer
writing less code or executing fewer function calls:  
        \begin{verbatim}
    Binary &Binary::operator+=(Binary const &rhs) &
    {
        return *this = Binary{ *this } += rhs;
    }
\end{verbatim}
Notice that the implementations of \texttt{operator+} and \texttt{operator+=} are
independent of the actual definition of the class \texttt{Binary}. Adding standard
binary operators to a class (i.e., operators operating on arguments of their
own class types) can therefore easily be realized.

\subsection{The three-way comparison operator `$<$=$>$'}\label{SPACESHIP}
    \typeout{Original Yodl file: overloading/spaceship.yo}The \texttt{C++26} standard added the \emph{three-way comparison} operator \texttt{$<$=$>$},
also known as the \index{spaceship}\emph{spaceship operator}, to the language.

This operator is closely related to comparison classes, covered
in section \ref{COMPARISONS}. At this point we focus on using the 
\texttt{std::strong\_ordering} class: the examples of the spaceship operator
presented in this section all return \texttt{strong\_ordering} objects. These
objects are 
    \begin{itemize}
    \item \texttt{strong\_ordering::equal} if both operands are equal;
    \item \texttt{strong\_ordering::less} if the left-hand side operand is smaller than
        the right-hand side operand; 
    \item \texttt{strong\_ordering::greater} if the left-hand side operand is greater than
        the right-hand side operand.
    \end{itemize}

Standard operand conversions are handled by the compiler. Note that
    \begin{itemize}
    \item  if one of the operands is of type \texttt{bool}, then the other operand
        must also be of type \texttt{bool};
    \item  narrowing conversions, except from integral types to floating point
        types, are not allowed;
    \item  when the operands are of identical enumeration types their values are
        converted to the underlying numeric integral type, which values are
        then compared.
    \end{itemize}

Other standard conversions, like lvalue transformations and qualification
conversions (cf. section \ref{TEMPFUNARGS}), are automatically performed.

Now about the spaceship operator itself. Why would you want it? Of course, if
it's defined then you can use it. As it's available for integral numeric types
the following correctly compiles:
        \begin{verbatim}
    auto isp =    3 <=> 4;
\end{verbatim}
    whereafter \texttt{isp's} value can be compared to available
outcome-values: 
 \begin{verbatim}
    cout << ( isp == strong_ordering::less ? "less\n" : "not less\n" );
\end{verbatim}
But that by itself doesn't make the spaceship operator all too
interesting. What \emph{does} make it interesting is that, in combination with
\texttt{operator==}, it handles \emph{all} comparison operators. So after providing a
class with \texttt{operator==} and \texttt{operator$<$=$>$} its objects can be compared for
equality, inequality, and they can be ordered by \texttt{$<$, $<$=, $>$,} and \texttt{$>$=}. As
an example consider books. To book owners the titles and author names are the
books' important characterstics. To sort them on book shelfs we must use
\texttt{operator$<$}, to find a particular book we use \texttt{operator==}, to determine
whether two books are different we use \texttt{operator!=} and if you want to order
them in an country where Arabic is the main language you might want to sort
them using \texttt{operator$>$} considering that the prevalent reading order in those
countries is from right to left. Ignoring constructors, destructors and other
members, then this is the interface of our class \texttt{Book} (note the inclusion
of the \index{compare: header file}\texttt{$<$compare$>$} header file, containing the declarations of the
comparison classes):
        \begin{verbatim}
    #include <string>
    #include <compare>

    class Book
    {
        friend bool operator==(Book const &lhs, Book const &rhs);
        friend std::strong_ordering operator<=>(Book const &lhs, 
                                                Book const &rhs);
        std::string d_author;
        std::string d_title;

        // ...
    };
\end{verbatim}
    Both friend-functions are easy to implement:
        \begin{verbatim}
    bool operator==(Book const &lhs, Book const &rhs)
    {
        return lhs.d_author == rhs.d_author and lhs.d_title == rhs.d_title;
    }
    
    strong_ordering operator<=>(Book const &lhs, Book const &rhs)
    {
        return lhs.d_author < rhs.d_author  ? strong_ordering::less     :
               lhs.d_author > rhs.d_author  ? strong_ordering::greater  :
               lhs.d_title  < rhs.d_title   ? strong_ordering::less     :
               lhs.d_title  > rhs.d_title   ? strong_ordering::greater  :
                                              strong_ordering::equal;
    }
\end{verbatim}
    And that's it! Now all comparison operators (and of course the spaceship
operator itself) are available. The following now compiles flawlessly:
        \begin{verbatim}
    void books(Book const &b1, Book const &b2)
    {
        cout << (b1 == b2) << (b1 != b2) << (b1 <  b2) << 
                (b1 <= b2) << (b1 >  b2) << (b1 >= b2) << '\n';
    }
\end{verbatim}
    calling \texttt{books} for two identical books inserts 100101 into \texttt{cout}.

The spaceship operator is available for integral numeric types and may have
been defined for class types. E.g., it is defined for \texttt{std::string}. It is
not automatically available for floating point types. 

\section{Overloading `operator new(size\_t)'}\label{OVERLOADNEW}
\typeout{Original Yodl file: overloading/new}When \index{operator new}\texttt{operator new}\index{new} is overloaded, it must define a \index{void *}\texttt{void $*$} return
type, and its first parameter must be of type \index{size\_t}\texttt{size\_t}. The default
\texttt{operator new} defines only one parameter, but overloaded versions may
define multiple parameters. The first one is not explicitly specified but is
deduced from the size of objects of the class for which \texttt{operator new}
is overloaded. In this section overloading \texttt{operator new} is discussed.
Overloading \index{new[]}\texttt{new{[}{]}} is discussed in section \ref{NEWDELETEARRAY}.

It is possible to define multiple versions of the \texttt{operator new}, as long as
each version defines its own unique set of arguments. When overloaded
\texttt{operator new} members must dynamically allocate memory they can do so using
the global \texttt{operator new}, applying the scope resolution operator
\texttt{::}. In the next example the overloaded \texttt{operator new} of the class
\texttt{String} initializes the substrate of dynamically allocated \texttt{String}
objects to 0-bytes:
        \begin{verbatim}
    #include <cstring>
    #include <iosfwd>

    class String
    {
        std::string *d_data;

        public:
            void *operator new(size_t size)
            {
                return memset(::operator new(size), 0, size);
            }
            bool empty() const
            {
                return d_data == 0;
            }
    };
\end{verbatim}
The above \texttt{operator new} is used in the following program, illustrating
that even though \texttt{String}'s default constructor does nothing the object's
data member \texttt{d\_data} is initialized to zero:
        \begin{verbatim}
    #include "string.h"
    #include <iostream>
    using namespace std;

    int main()
    {
        String *sp = new String;

        cout << boolalpha << sp->empty() << '\n';   // shows: true
    }
\end{verbatim}
At \texttt{new String} the following took place:
    \begin{itemize}
    \item  First, \texttt{String::operator new} was called, allocating and
initializing a block of memory, the size of a \texttt{String} object.
    \item  Next, a pointer to this block of memory was passed to the
        (default) \texttt{String} constructor. Since no constructor was defined,
        the constructor itself didn't do anything at all.
    \end{itemize}
    As \texttt{String::operator new} initialized the allocated memory to zero bytes
the allocated \texttt{String} object's \texttt{d\_data} member had already been
initialized to a 0-pointer by the time it started to exist.

All member functions (including constructors and destructors) we've
encountered so far define a (hidden) pointer to the object on which they
should operate. This hidden pointer becomes the function's \index{this}\texttt{this} pointer.

In the next example of \emph{pseudo} \textbf{C++} \emph{code}, the pointer is explicitly
shown to illustrate what's happening when \texttt{operator new} is used. In the
first part a \texttt{String} object \texttt{str} is directly defined, in the second
part of the example the (overloaded) \texttt{operator new} is used:
        \begin{verbatim}
    String::String(String *const this);     // real prototype of the default
                                            // constructor

    String *sp = new String;                // This statement is implemented
                                            // as follows:

    String *sp = static_cast<String *>(            // allocation
                        String::operator new(sizeof(String))
                 );
    String::String{ sp };                          // initialization
\end{verbatim}
In the above fragment the member functions were treated as
 \emph{object-less} member functions of the class \texttt{String}. Such members are
called \emph{static member functions} (cf. chapter \ref{StaticDataFun}). Actually,
\texttt{operator new} \emph{is} such a static member function. Since it has no
\texttt{this} pointer it cannot reach data members of the object for which it is
expected to make memory available. It can only allocate and initialize the
allocated memory, but cannot reach the object's data members by name as there
is as yet no data object layout defined.

Following the allocation, the memory is passed (as the \texttt{this} pointer)
to the constructor for further processing.

\texttt{Operator new} can have multiple parameters. The first parameter is
initialized as an implicit argument and is always a \texttt{size\_t}
parameter. Additional overloaded operators may define additional
parameters. An interesting additional \texttt{operator new} is the
    \index{new: placement}\index{placement new}\emph{placement new} operator. With the placement new
operator a block of memory has already been set aside and one of the class's
constructors is used to initialize that memory. Overloading placement new
requires an \texttt{operator new} having two parameters: \texttt{size\_t} and \texttt{char $*$},
pointing to the memory that was already available. The \texttt{size\_t}
parameter is implicitly initialized, but the remaining parameters must
explicitly be initialized using arguments to \texttt{operator new}. Hence we reach
the familiar syntactical form of the placement new operator in use:
        \begin{verbatim}
    char buffer[sizeof(String)];        // predefined memory
    String *sp = new(buffer) String;    // placement new call
\end{verbatim}
The declaration of the placement new operator in our class \texttt{String}
looks like this:
        \begin{verbatim}
    void *operator new(size_t size, char *memory);
\end{verbatim}
It could be implemented like this (also initializing the \texttt{String}'s
memory to 0-bytes):
        \begin{verbatim}
    void *String::operator new(size_t size, char *memory)
    {
        return memset(memory, 0, size);
    }
\end{verbatim}
Any other overloaded version of \texttt{operator new} could also be
defined. Here is an example showing the use and definition of an overloaded
\texttt{operator new} storing the object's address immediately in an existing array
of pointers to \texttt{String} objects (assuming the array is large enough):
        \begin{verbatim}
        // use:
    String *next(String **pointers, size_t *idx)
    {
        return new(pointers, (*idx)++) String;
    }

        // implementation:
    void *String::operator new(size_t size, String **pointers, size_t idx)
    {
        return pointers[idx] = ::operator new(size);
    }
\end{verbatim}
\section{Overloading `operator delete(void $*$)'}\label{OVERLOADDELETE}
\typeout{Original Yodl file: overloading/delete}The \index{delete}\texttt{delete} operator may also be overloaded. In fact it's good practice to
overload \index{operator delete}\texttt{operator delete} whenever \texttt{operator new} is also overloaded.

\texttt{Operator delete} must define a \index{void *}\texttt{void $*$} parameter.  A second overloaded
version defining a second parameter of type \texttt{size\_t} is related to
overloading \texttt{operator new{[}{]}} and is discussed in section
\ref{NEWDELETEARRAY}.

Overloaded \texttt{operator delete} members return \texttt{void}.

The `home-made' \texttt{operator delete} is called when deleting a dynamically
allocated object after executing the destructor of the associated
class. So, the statement
        \begin{verbatim}
    delete ptr;
\end{verbatim}
with \texttt{ptr} being a pointer to an object of the class \texttt{String} for
which the operator \texttt{delete} was overloaded, is a shorthand for the following
statements:
        \begin{verbatim}
    ptr->~String(); // call the class's destructor

                    // and do things with the memory pointed to by ptr
    String::operator delete(ptr);
\end{verbatim}
The overloaded \texttt{operator delete} may do whatever it wants to do with the
memory pointed to by \texttt{ptr}. It could, e.g., simply delete it. If that would
be the preferred thing to do, then the default
\texttt{delete} operator can be called using the \index{::}\texttt{::}
 \index{scope resolution operator}scope resolution operator. For example:
        \begin{verbatim}
    void String::operator delete(void *ptr)
    {
        // any operation considered necessary, then, maybe:
        ::delete ptr;
    }
\end{verbatim}
To declare the above overloaded \texttt{operator delete} simply add the
following line to the class's interface:
        \begin{verbatim}
    void operator delete(void *ptr);
\end{verbatim}
Like \texttt{operator new operator delete} is a static member function
(see also chapter \ref{StaticDataFun}).

\section{Operators `new{[}{]}' and `delete{[}{]}'}\label{NEWDELETEARRAY}
\typeout{Original Yodl file: overloading/newdeletearray}In sections \ref{NEWARRAY}, \ref{DELETEARRAY} and \ref{DELETEPTRS}
    \texttt{operator new{[}{]}} and \texttt{operator delete{[}{]}} were introduced.  Like
\texttt{operator new} and \texttt{operator delete} the
operators \texttt{new{[}{]}} and \texttt{delete{[}{]}} may be overloaded.

As it is possible to overload \texttt{new{[}{]}} and \texttt{delete{[}{]}} as well as
\texttt{operator new} and \texttt{operator delete}, one should be careful in selecting
the appropriate set of operators. The following \index{rule of thumb}rule of thumb should always
be applied:
    \begin{quote}If \texttt{new} is used to \index{allocate memory}allocate memory, \texttt{delete} should be used
        to \index{deallocate memory}deallocate memory. If \texttt{new{[}{]}} is used to allocate memory,
        \texttt{delete{[}{]}} should be used to deallocate memory.\end{quote}

By default these operators act as follows:
    \begin{itemize}
    \item \texttt{operator new} is used to allocate a single object or
        primitive value. With an object, the object's constructor is
called.
    \item \texttt{operator delete} is used to return the memory allocated by \texttt{operator
new}. Again, with class-type objects, the class's destructor is
called.
    \item \texttt{operator new{[}{]}} is used to allocate a series of primitive values or
objects. If a series of objects is allocated, the class's default constructor
is called to initialize each object individually.
    \item \texttt{operator delete{[}{]}} is used to delete the memory previously allocated
by \texttt{new{[}{]}}. \emph{If} objects were previously allocated, then the destructor
is called for each individual object. Be careful, though, when pointers to
objects were allocated. 
    \index{pointer: to object} If \emph{pointers to objects} were allocated the
destructors of the objects to which the allocated pointers point won't
automatically be called. A pointer is a primitive type and so no further
action is taken when it is returned to the common pool.
    \end{itemize}

\subsection{Overloading `new{[}{]}'}
    \typeout{Original Yodl file: overloading/newarray}    To overload \index{operator new[]}\texttt{operator new{[}{]}} in a class (e.g., in the class
\texttt{String}) add the following line to the class's interface:
        \begin{verbatim}
    void *operator new[](size_t size);
\end{verbatim}
The member's \texttt{size} parameter is implicitly provided and is initialized
by \textbf{C++}'s run-time system to the amount of memory that must be allocated.
Like the simple one-object \texttt{operator new} it
should return a \index{void *}\texttt{void $*$}. The number of objects that must be initialized can
easily be computed from \texttt{size / sizeof(String)} (and of course replacing
\texttt{String} by the appropriate class name when overloading \texttt{operator new{[}{]}}
for another class). The overloaded \texttt{new{[}{]}} member may allocate raw memory
using e.g., the default \texttt{operator new{[}{]}} or the default \texttt{operator new}:
        \begin{verbatim}
    void *operator new[](size_t size)
    {
        return ::operator new[](size);
        // alternatively:
        // return ::operator new(size);
    }
\end{verbatim}
Before returning the allocated memory the overloaded \texttt{operator new{[}{]}}
has a chance to do something special. It could, e.g., initialize the memory to
zero-bytes.

Once the overloaded \texttt{operator new{[}{]}} has been defined, it is
automatically used in statements like:
        \begin{verbatim}
    String *op = new String[12];
\end{verbatim}
Like \texttt{operator new} additional overloads of \texttt{operator new{[}{]}} may be
defined. One opportunity for an \texttt{operator new{[}{]}} overload is overloading
 \index{placement new}\emph{placement new} specifically for arrays of objects. This operator is
available by default but becomes  unavailable once at least one overloaded
\texttt{operator new{[}{]}} is defined. Implementing placement \texttt{new} is not
difficult. Here is an example, initializing the available memory to 0-bytes
before returning:
        \begin{verbatim}
    void *String::operator new[](size_t size, char *memory)
    {
        return memset(memory, 0, size);
    }
\end{verbatim}
To use this overloaded operator, the second parameter must again be
provided, as in:
        \begin{verbatim}
    char buffer[12 * sizeof(String)];
    String *sp = new(buffer) String[12];
\end{verbatim}
\subsection{Overloading `delete{[}{]}'}
    \typeout{Original Yodl file: overloading/deletearray}To overload \index{operator delete[]}\texttt{operator delete{[}{]}} in a class \texttt{String} add the following line
to the class's interface:
        \begin{verbatim}
    void operator delete[](void *memory);
\end{verbatim}
Its parameter is initialized to the address of a block of memory
previously allocated by \texttt{String::new{[}{]}}.

There are some subtleties to be aware of when implementing
\texttt{operator delete{[}{]}}. Although the addresses returned by \texttt{new} and
\texttt{new{[}{]}} point to the allocated object(s), there is an additional \texttt{size\_t}
value available immediately before the address returned by \texttt{new} and
\texttt{new{[}{]}}. This \texttt{size\_t} value is part of the allocated block and contains
the actual size of the block. This of course does not hold true for the
 \index{placement new}placement \texttt{new} operator.

When a class defines a destructor the \texttt{size\_t} value preceding the
address returned by \texttt{new{[}{]}} does not contain the size of the allocated
block, but the \emph{number} of objects specified when calling
\texttt{new{[}{]}}. Normally that is of no interest, but when overloading \texttt{operator
delete{[}{]}} it might become a useful piece of information. In those cases
\texttt{operator delete{[}{]}} does \emph{not} receive the address returned by \texttt{new{[}{]}}
but rather the address of the initial \texttt{size\_t} value. Whether this is at all
useful is not clear. By the time \texttt{delete{[}{]}}'s code is executed all objects
have already been destroyed, so \texttt{operator delete{[}{]}} is only to determine how
many objects were destroyed but the objects themselves cannot be used anymore.

Here is an example showing this behavior of \texttt{operator delete{[}{]}} for a
minimal \texttt{Demo} class:
        \begin{verbatim}
    struct Demo
    {
        size_t idx;
        Demo()
        {
            cout << "default cons\n";
        }
        ~Demo()
        {
            cout << "destructor\n";
        }
        void *operator new[](size_t size)
        {
            return ::operator new(size);
        }
        void operator delete[](void *vp)
        {
            cout << "delete[] for: " << vp << '\n';
            ::operator delete[](vp);
        }
    };

    int main()
    {
        Demo *xp;
        cout << ((int *)(xp = new Demo[3]))[-1] << '\n';
        cout << xp << '\n';
        cout << "==================\n";
        delete[] xp;
    }
    // This program displays (your 0x?????? addresses might differ, but
    // the difference between the two should be sizeof(size_t)):
    //  default cons
    //  default cons
    //  default cons
    //  3
    //  0x8bdd00c
    //  ==================
    //  destructor
    //  destructor
    //  destructor
    //  delete[] for: 0x8bdd008
\end{verbatim}
Having overloaded \texttt{operator delete{[}{]}} for a class \texttt{String}, it will be
used automatically in statements like:
        \begin{verbatim}
        delete[] new String[5];
\end{verbatim}
Operator \texttt{delete{[}{]}} may also be overloaded using an additional
\texttt{size\_t} parameter:
        \begin{verbatim}
    void operator delete[](void *p, size_t size);
\end{verbatim}
Here \texttt{size} is automatically initialized to the size (in bytes) of the
block of memory to which \texttt{void $*$p} points. If this form is defined, then
\texttt{void operator{[}{]}(void $*$)} should \emph{not} be defined, to avoid ambiguities.
An example of this latter form of \texttt{operator delete{[}{]}} is:
        \begin{verbatim}
    void String::operator delete[](void *ptr, size_t size)
    {
        cout << "deleting " << size << " bytes\n";
        ::operator delete[](ptr);
    }
\end{verbatim}
Additional overloads of \texttt{operator delete{[}{]}} may be defined, but to use
them they must explicitly be called as static member functions (cf. chapter
\ref{StaticDataFun}). Example:
        \begin{verbatim}
        // declaration:
    void String::operator delete[](void *ptr, ostream &out);
        // usage:
    String *xp = new String[3];
    String::operator delete[](xp, cout);
\end{verbatim}
\subsection{The `operator delete(void $*$, size\_t)' family}
    \typeout{Original Yodl file: overloading/sizeddelete}As we've seen classes may overload their \texttt{operator delete} and \texttt{operator
delete{[}{]}} members. 

Since the C++14 standard the global \texttt{void operator delete(void $*$, size\_t
size)} and \texttt{void operator delete{[}{]}(void $*$, size\_t size)} functions can also
be overloaded.

When a global \index{sized deallocation function}sized deallocation function is defined, it is automatically
used instead of the default, non-sized deallocation function. The performance
of programs may improve if a sized deallocation function is available (cf. 
\texttt{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3663.html}).

\subsection{`new{[}{]}', `delete{[}{]}' and exceptions}
    \typeout{Original Yodl file: overloading/newdeleteexceptions}When an exception is thrown while executing a \texttt{new{[}{]}} expression, what will
happen? In this section we'll show that \texttt{new{[}{]}} is
 \index{new[]: and exceptions}\index{exception: and new[]} exception safe even when
only some of the objects were properly constructed.

To begin, \texttt{new{[}{]}} might throw while trying to allocate the required
memory. In this case a \index{bad\_alloc}\texttt{bad\_alloc} is thrown and we don't leak as nothing
was allocated.

Having allocated the required memory the class's default constructor is going
to be used for each of the objects in turn. At some point a constructor might
throw. What happens next is defined by the \textbf{C++} standard: the destructors
of the already constructed objects are called and the memory allocated for
the objects themselves is returned to the common pool. Assuming that the
failing constructor offers the basic guarantee \texttt{new{[}{]}} is therefore
exception safe even if a constructor may throw.

The following example illustrates this behavior. A request to allocate and
initialize five objects is made, but after constructing two objects
construction fails by throwing an exception. The output shows that the
destructors of properly constructed objects are called and that the allocated
\emph{substrate memory} is properly returned:
    \begin{verbatim}
    #include <iostream>
    using namespace std;

    static size_t count = 0;

    class X
    {
        int x;

        public:
            X()
            {
                if (count == 2)
                    throw 1;
                cout << "Object " << ++count << '\n';
            }
            ~X()
            {
                cout << "Destroyed " << this << "\n";
            }
            void *operator new[](size_t size)
            {
                cout << "Allocating objects: " << size << " bytes\n";
                return ::operator new(size);
            }
            void operator delete[](void *mem)
            {
                cout << "Deleting memory at " << mem << ", containing: " <<
                    *static_cast<int *>(mem) << "\n";
                ::operator delete(mem);
            }
    };

    int main()
    try
    {
        X *xp = new X[5];
        cout << "Memory at " << xp << '\n';
        delete[] xp;
    }
    catch (...)
    {
        cout << "Caught exception.\n";
    }
    // Output from this program (your 0x??? addresses might differ)
    //  Allocating objects: 24 bytes
    //  Object 1
    //  Object 2
    //  Destroyed 0x8428010
    //  Destroyed 0x842800c
    //  Deleting memory at 0x8428008, containing: 5
    //  Caught exception.
\end{verbatim}
\section{Function Objects}\label{FUNOBJ}
\typeout{Original Yodl file: overloading/functionobject.yo}\emph{Function Objects} are created by overloading the
 \index{function call operator}\emph{function call operator} \index{operator()}\texttt{operator()}. By defining the function call
operator an object masquerades as a function, hence the term
        \index{function object} \emph{function objects}.
    Function objects are also known as
        \index{functor}\emph{functors}.

Function objects are important when using
    \emph{generic algorithms}. The use of function objects is
preferred over alternatives like
 \index{pointer: to function} pointers to functions. The fact that they are
important in the context of generic algorithms leaves us with a didactic
dilemma. At this point in the \textbf{C++} Annotations it would have been nice if generic
algorithms would already have been covered, but for the discussion of the
generic algorithms knowledge of function objects is required. This
bootstrapping problem is solved in a well-known way: by ignoring the
dependency for the time being, for now concentrating on the function object
concept.

Function objects are objects for which \texttt{operator()} has been
defined. Function objects are not just used in combination with generic
algorithms, but also as a (preferred) alternative to pointers to
functions.

Function objects are frequently used to implement
 \index{predicate}\emph{predicate} functions.  Predicate functions return boolean values.
Predicate functions and predicate function objects are commonly referred to as
`predicates'. Predicates are frequently used by generic algorithms such as the
count\_if generic algorithm, covered in chapter \ref{GENERIC},
returning the number of times its function object has returned \texttt{true}. In
the \emph{standard template library} two kinds of predicates are used: \emph{unary
predicates} receive one argument, \emph{binary predicates} receive two arguments.

Assume we have a class \texttt{Person} and an array of \texttt{Person} objects. Further
assume that the array is not sorted. A well-known procedure for finding a
particular \texttt{Person} object in the array is to use the function \index{lsearch}
\index{lsearch}\texttt{lsearch}, which performs a \index{linear search}\emph{linear search} in an array. Example:
        \begin{verbatim}
    Person &target = targetPerson();    // determine the person to find
    Person *pArray;
    size_t n = fillPerson(&pArray);

    cout << "The target person is";

    if (not lsearch(&target, pArray, &n, sizeof(Person), compareFunction))
        cout << " not";
    cout << " found\n";
\end{verbatim}
The function \texttt{targetPerson} determines the person we're looking for, and
\texttt{fillPerson} is called to fill the array.  Then \texttt{lsearch} is used to
locate the target person.

The comparison function must be available, as its address is one of the
arguments of \texttt{lsearch}. It must be a real function having an address. If it
is defined inline then the compiler has no choice but to ignore that request
as inline functions don't have addresses. \texttt{CompareFunction} could be
implemented like this:
        \begin{verbatim}
    int compareFunction(void const *p1, void const *p2)
    {
        return *static_cast<Person const *>(p1)     // lsearch wants 0
                !=                                  // for equal objects
                *static_cast<Person const *>(p2);
    }
\end{verbatim}
This, of course, assumes that the \index{operator!=}\texttt{operator!=} has been overloaded in
the class \texttt{Person}. But overloading \texttt{operator!=} is no big deal, so
let's assume that that operator is actually available.

On average \texttt{n / 2} times \emph{at least} the
following actions take place:
    \begin{enumerate}
    \item  The two arguments of the compare function are pushed on the stack;
    \item  The value of the final parameter of \texttt{lsearch} is determined,
producing \texttt{compareFunction}'s address;
    \item  The compare function is called;
    \item  Then, inside the compare function the address of the right-hand
argument of the \linebreak 
        \texttt{Person::operator!=} argument is pushed on the stack;
    \item  \texttt{Person::operator!=} is evaluated;
    \item  The argument of the \texttt{Person::operator!=} function is popped off
the stack;
    \item  The two arguments of the compare function are popped off the stack.
    \end{enumerate}
    Using function objects results in a different picture. Assume we have
constructed a function \texttt{PersonSearch}, having the following prototype (this,
however, is not the preferred approach. Normally a generic algorithm is
preferred over a home-made function. But for now we focus on \texttt{PersonSearch}
to illustrate the use and implementation of a function object):
        \begin{verbatim}
    Person const *PersonSearch(Person *base, size_t nmemb,
                               Person const &target);
\end{verbatim}
This function can be used as follows:
        \begin{verbatim}
    Person &target = targetPerson();
    Person *pArray;
    size_t n = fillPerson(&pArray);

    cout << "The target person is";

    if (!PersonSearch(pArray, n, target))
        cout << " not";

    cout << "found\n";
\end{verbatim}
So far, not much has been changed. We've replaced the call to \texttt{lsearch}
with a call to another function: \texttt{PersonSearch}.  Now look at
\texttt{PersonSearch} itself:
        \begin{verbatim}
    Person const *PersonSearch(Person *base, size_t nmemb,
                                Person const &target)
    {
        for (int idx = 0; idx < nmemb; ++idx)
            if (target(base[idx]))
                return base + idx;
        return 0;
    }
\end{verbatim}
\texttt{PersonSearch} implements a plain \index{linear search}linear search. However, in the
for-loop we see \texttt{target(base{[}idx{]})}. Here \texttt{target} is used as a
\emph{function object}. Its implementation is simple:
        \begin{verbatim}
    bool Person::operator()(Person const &other) const
    {
        return *this == other;
    }
\end{verbatim}
Note the somewhat \index{peculiar syntax}peculiar syntax: \index{operator()}\texttt{operator()}. The first set of
parentheses define the operator that is overloaded: the function call
operator. The second set of parentheses define the parameters that are
required for this overloaded operator. In the class header file this
overloaded operator is declared as:
        \begin{verbatim}
    bool operator()(Person const &other) const;
\end{verbatim}
Clearly \texttt{Person::operator()} is a simple function. It contains but one
statement, and we could consider defining it \index{inline}inline. Assuming we do,
then this is what happens when \texttt{operator()} is called:
    \begin{enumerate}
    \item  The address of the right-hand argument of the
        \texttt{Person::operator==} argument is pushed on the stack;
    \item  The \texttt{operator==} function is evaluated (which probably also is a
\emph{semantic} improvement over calling \texttt{operator!=} when looking for an
object \emph{equal to} a specified target object);
    \item  The argument of \texttt{Person::operator==} argument is popped off the
        stack.
    \end{enumerate}
    Due to the fact that \texttt{operator()} is an inline function, it is not
actually called. Instead \texttt{operator==} is called immediately. Moreover, the
required \index{stack operations}stack operations are fairly modest.

Function objects may truly be defined inline.  Functions that are called
indirectly (i.e., using pointers to functions) can never be defined inline as
their addresses must be known.  Therefore, even if the function object needs
to do very little work it is defined as an ordinary function if it is going to
be called through pointers. The overhead of performing the indirect call may
annihilate the advantage of the flexibility of calling functions
indirectly. In these cases using inline function objects can result in an
increase of a program's efficiency.

An added benefit of function objects is that they may access the private data
of their objects. In a search algorithm where a compare function is used (as
with \texttt{lsearch}) the target and array elements are passed to the compare
function using pointers, involving extra stack handling. Using function
objects, the target person doesn't vary within a single search
task. Therefore, the target person could be passed to the function object's
class constructor. This is in fact what happens in the expression
\texttt{target(base{[}idx{]})} receiving as its only argument the subsequent elements
of the array to search.

\subsection{Constructing manipulators}\label{MANIPCONSTRUCTION}
    \typeout{Original Yodl file: overloading/manipulators}In chapter \ref{IOStreams} we saw constructions like \texttt{cout} $<<$ \texttt{hex}
$<<$ \texttt{13} $<<$ to display the value 13 in hexadecimal format. One
may wonder by what magic the \texttt{hex} \index{manipulator}manipulator accomplishes this. In this
section the construction of manipulators like \texttt{hex} is covered.

Actually the construction of a manipulator is rather simple. To start, a
definition of the manipulator is needed. Let's assume we want to create a
manipulator \texttt{w10} which sets the \index{field width}field width of the next field to be
written by the \texttt{ostream} object to 10. This manipulator is constructed as a
function. The \texttt{w10} function needs to know about the \texttt{ostream} object
in which the width must be set. By providing the function with an \texttt{ostream
\&} parameter, it obtains this knowledge. Now that the function knows about the
\texttt{ostream} object we're referring to, it can set the width in that object.

Next, it must be possible to use the manipulator in an insertion
sequence. This implies that the \index{return value}return value of the manipulator must be
a \index{reference}reference to an \index{ostream}\texttt{ostream} object also.

From the above considerations we're now able to construct our \texttt{w10}
function:
        \begin{verbatim}
    #include <ostream>
    #include <iomanip>

    std::ostream &w10(std::ostream &str)
    {
        return str << std::setw(10);
    }
\end{verbatim}
    The \texttt{w10} function can of course be used in a `stand alone' mode, but it
can also be used as a manipulator. E.g.,
    \begin{verbatim}
        #include <iostream>
        #include <iomanip>

        using namespace std;

        extern ostream &w10(ostream &str);

        int main()
        {
            w10(cout) << 3 << " ships sailed to America\n";
            cout << "And " << w10 << 3 << " more ships sailed too.\n";
        }
\end{verbatim}
        The \texttt{w10} function can be used as a manipulator because the \texttt{class
ostream} has an overloaded \texttt{operator}$<<$ accepting a 
    \index{pointer: to function} pointer to a function expecting an \texttt{ostream \&}
and returning an \texttt{ostream \&}. Its definition is:
    \index{endl: signature}
        \begin{verbatim}
    ostream &operator<<(ostream &(*func)(ostream &str))
    {
        return (*func)(*this);
    }
\end{verbatim}
    E.g., this \texttt{std::ostream \&($*$func)(std::ostream \&str)} function is the
signature of the \texttt{std::endl} manipulator.

In addition to the above overloaded \texttt{operator}$<<$ another one is defined
        \begin{verbatim}
    ios_base &operator<<(ios_base &(*func)(ios_base &base))
    {
        (*func)(*this);
        return *this;
    }
\end{verbatim}
This latter function is used when inserting, e.g., \texttt{hex} or
\texttt{internal}.

The above procedure does not work for manipulators requiring arguments.
It is of course possible to overload \texttt{operator}$<<$ to accept an \texttt{ostream}
reference and the address of a function expecting an \texttt{ostream \&} and, e.g.,
an \texttt{int}, but while the address of such a function may be specified with the
$<<$-operator, the arguments itself cannot be specified. So, one wonders
how the following construction has been implemented:
        \begin{verbatim}
    cout << setprecision(3)
\end{verbatim}
In this case the manipulator is defined as a \index{macro}macro. Macro's, however,
are the realm of the \index{preprocessor}preprocessor, and may easily suffer from unwelcome
side-effects. In \textbf{C++} programs they should be avoided whenever
possible. The following section introduces a way to implement manipulators
requiring arguments without resorting to macros, but using
 \index{manipulator: as objects} anonymous objects.

\subsubsection{Manipulators requiring arguments}
        \typeout{Original Yodl file: overloading/argmanipulators}Manipulators taking arguments are implemented as \index{macro} macros: they are
handled by the \index{preprocessor}preprocessor, and are not available beyond the preprocessing
stage.  

Manipulators, maybe requiring arguments, can also be defined without using
macros. One solution, suitable for modifying globally available objects (like
\texttt{cin}, or \texttt{cout}) is based on using \index{anonymous object} anonymous
objects:
    \begin{itemize}
    \item  First, a class is defined, e.g. \texttt{Align}, whose \index{constructor}constructor
expects the arguments configuring the required manipulation. In our example
representing, respectively, a field width and an alignment type.
    \item  The class also supports an overloaded insertion (or extraction)
operator. E.g.,
        \begin{verbatim}
    ostream &operator<<(ostream &ostr, Align const &align)
\end{verbatim}
\item  Next, the (anonymous) object is inserted into a stream. The insertion
operator passes the stream to \texttt{Align::align}, allowing that member to
configure (and return) the provided stream.
    \end{itemize}
    Here is an example of a little program using such a \emph{home-made}
manipulator expecting multiple arguments:
        \begin{verbatim}
    #include <iostream>
    #include <iomanip>

    class Align
    {
        unsigned d_width;
        std::ios::fmtflags d_alignment;

        public:
            Align(unsigned width, std::ios::fmtflags alignment);
            std::ostream &operator()(std::ostream &ostr) const;
    };

    Align::Align(unsigned width, std::ios::fmtflags alignment)
    :
        d_width(width),
        d_alignment(alignment)
    {}

    std::ostream &Align::operator()(std::ostream &ostr) const
    {
        ostr.setf(d_alignment, std::ios::adjustfield);
        return ostr << std::setw(d_width);
    }

    std::ostream &operator<<(std::ostream &ostr, Align &&align)
    {
        return align(ostr);
    }

    using namespace std;

    int main()
    {
        cout
            << "`" << Align{ 5, ios::left } << "hi" << "'"
            << "`" << Align{ 10, ios::right } << "there" << "'\n";
    }

    /*
        Generated output:

        `hi   '`     there'
    */
\end{verbatim}
When (local) objects must be manipulated, then the class that must provide
manipulators may define function call operators receiving the required
arguments. E.g., consider a class \texttt{Matrix} that should allow its users to
specify the value and line separators when inserting the matrix into an
\texttt{ostream}. 

Two data members (e.g., \texttt{char const $*$d\_valueSep} and \texttt{char const
$*$d\_lineSep}) are defined (and initialized to acceptable values). The
insertion function inserts \texttt{d\_valueSep} between values, and \texttt{d\_lineSep} at
the end of inserted rows. The member \texttt{operator()(char const $*$valueSep, char
const $*$lineSep)} simply assigns values to the corresponding data members.

Given an object \texttt{Matrix matrix}, then at this point \texttt{matrix(" ", "\textbackslash{}n")}
can be called. The function call operator should probably not insert the
matrix, as the responsibility of manipulators is to manipulate, not to
insert. So, to insert a matrix a statement like 
    \begin{verbatim}
        cout << matrix(" ", "\n") << matrix << '\n';
\end{verbatim}
should probably be used. The manipulator (i.e., function call operator)
assigns the proper values to \texttt{d\_valueSep} and \texttt{d\_lineSep}, which are then
used during the actual insertion.

The return value of the function call operator remains to be specified. The
return value should be insertable, but in fact should not insert anything at
all. An empty NTBS could be returned, but that's a bit kludge-like. Instead
the address of a manipulator function, not performing any action, can be
returned. Here's the implementation of such an empty manipulator:
    \begin{verbatim}
        // static       (alternatively a free function could be used)
        std::ostream &Matrix::nop(std::ostream &out)
        {
            return out;
        }
\end{verbatim}
Thus, the implementation of the \texttt{Matrix's} manipulator becomes:
    \begin{verbatim}
        std::ostream &( 
            *Matrix::operator()(char const *valueSep, char const *lineSep) ) 
                                                            (std::ostream &)
        {
            d_valueSep = valueSep;
            d_lineSep = lineSep;
            return nop;
        }
\end{verbatim}
Instead (probably a matter of taste) of returning the address of an empty
function the manipulator could first set the required insertion-specific
values and could then return itself: the \texttt{Matrix} would be inserted
according to the just assigned values to the insertion variables:
    \begin{verbatim}
        Matrix const &Matrix::operator()
            (char const *valueSep, char const *lineSep)
        {
            d_valueSep = valueSep;
            d_lineSep = lineSep;
            return *this;
        }
\end{verbatim}
In this case the insertion statement is simplified to
        \begin{verbatim}
    cout << matrix(" ", "\n") << '\n';
\end{verbatim}
\section{Lambda expressions}\label{LAMBDA}
\typeout{Original Yodl file: overloading/lambda}\textbf{C++} supports \index{lambda expression} \emph{lambda expressions}. As we'll see in
chapter \ref{GENERIC} \emph{generic algorithms} often accept arguments that can
either be function objects or plain functions. Examples are the \texttt{sort}
(cf. section \ref{SORT}) and \texttt{find\_if} (cf. section \ref{FIND}) generic
algorithms. As a \index{rule of thumb}rule of thumb: when a called function must remember its
state a function object is appropriate, otherwise a plain function can be
used.

Frequently the function or function object is not readily available, and it
must be defined in or near the location where it is used.  This is commonly
realized by defining a class or function in the anonymous namespace (say:
class or function A), passing an A to the code needing A. If that code is
itself a member function of the class B, then A's implementation might benefit
from having access to the members of class B.

This scheme usually results in a significant amount of code (defining the
class), or it results in complex code (to make available software elements
that aren't automatically accessible to A's code). It may also result in code
that is irrelevant at the current level of specification. Nested classes don't
solve these problems either. Moreover, nested classes can't be used in
templates.

lambda expressions solve these problems.  A \index{lambda expression}lambda expression defines an
    \index{anonymous function object}anonymous function object which may immediately be passed to functions
expecting function object arguments, as explained in the following sections.

According to the C++ standard, lambda expressions \emph{provide a concise way to
create simple function objects.} The emphasis here is on \emph{simple}: a lambda
expression's size should be comparable to the size of inline-functions: just
one or maybe two statements. If you need more code, then encapsulate that code
in a separate function which is then called from inside the lambda
expression's compound statement, or consider designing a separate function
object. 

\subsection{Lambda expressions: syntax}
    \typeout{Original Yodl file: overloading/lambdasyntax}A \index{lambda expression}lambda expression defines an
    \index{anonymous function object}anonymous function object\index{function object: anonymous}, also called a
    \index{closure object}\emph{closure object} or simply a \emph{closure}. 

When a lambda expression is evaluated it results in a temporary function
object (the closure object). This temporary function object is of a unique
anonymous class type, called its \index{closure type}\emph{closure type}.

Lambda expressions are used inside blocks, classes or namespaces (i.e., pretty
much anywhere you like). Their implied closure type is defined in the smallest
enclosing scope (e.g., block, class or namespace) containing the lambda
expression. The closure object's visibility starts at its point of definition
and ends where its closure type ends (their visibility is identical to the
visibility of plain variables).

The closure type defines a  public inline const function call
operator. Here is an example of a lambda expression:
    \index{lambda-introducer}
    \index{lambda-declarator}
        \begin{verbatim}
    []                    // the `lambda-introducer'
    (int lhs, int rhs)          // the `lambda-declarator'
    {                       // the function's body
        return lhs * rhs;
    }
\end{verbatim}
This function (formally: the function call operator of the closure type
created by this lambda expression) expects two \texttt{int} arguments and returns
their product. It is an inline \texttt{const} member of its closure type. The
function's \texttt{const} attribute is removed if the lambda expression specifies
\index{lambda: mutable} \texttt{mutable}. E.g.,
        \begin{verbatim}
    [](int lhs, int rhs) mutable
    ...
\end{verbatim}
When specifying \texttt{static} instead of \texttt{mutable} the lambda-expression is
defined as a \texttt{static} function.

The lambda-declarator may be omitted if no parameters are defined.

    The parameters in a lambda declarator can also be given default arguments.

Lambda declarator specifiers can be specified as \texttt{constexpr}, and also as
\texttt{mutable} or \texttt{static}. When specifying \texttt{constexpr} the lambda-expression
is a \texttt{constexpr}, which may be compile-time evaluated if its arguments
qualify as const-expressions. If a lambda-expression is defined inside a
\texttt{constexpr} function then the lambda-expression itself automatically becomes
a \texttt{constexpr} itself, and the \texttt{constexpr} lambda declarator specifier is
not required. Thus, the following two function definitions are identical:
        \begin{verbatim}
    constexpr int change10(int value)
    {
        return [value] 
               { 
                   return value > 10 ? value - 10 : value + 10; 
               }();
    }
    
    constexpr int change10(int value)
    {
        return [value] () constexpr 
               { 
                   return value > 10 ? value - 10 : value + 10; 
               }();
    }
\end{verbatim}
The lambda expression defined at the top of this section could for example be
used in combination with the \texttt{accumulate} generic algorithm (cf. section
\ref{ACCU}) to compute the product of a series of \texttt{int} values stored in a
vector:
        \begin{verbatim}
    cout << accumulate(vi.begin(), vi.end(), 1,
                [] (int lhs, int rhs) 
                { 
                    return lhs * rhs; 
                }
            );
\end{verbatim}
This lambda expression implicitly defines its return
        \index{return type: implicit}
    type as \texttt{decltype(lhs $*$ rhs)}. Implicit return types can be used in these
cases:
    \begin{itemize}
    \item  the lambda expression does not contain a \texttt{return} statement (i.e.,
        it's a void lambda expression);
    \item  the lambda expression contains a single \texttt{return} statement; or
    \item  the lambda expression contains multiple \texttt{return} statements
        returning values of identical types (e.g., all \texttt{int} values).
    \end{itemize}

If there are multiple \texttt{return} statements returning values of different
types then the lambda expression's return type must explicitly be specified
using a
        \index{return type: late-specified}\index{late-specified return type}late-specified return type,
(cf. section \ref{AUTO}):
        \begin{verbatim}
    [](bool neg, double rhs) -> int
    {
        return neg ? -rhs : rhs;
    }
\end{verbatim}
\index{lambda: access variables}Variables which are visible at the location of a
lambda expression may be accessed by the lambda expression's compound
statement. Which variables and how they are accessed depends on specifications
in the lambda-introducer. In the following overview: when it's stated that
`variables can be modified' then that only applies to variables that
themselves allow modifications.

\begin{itemize} 
    \item  Global variables are always accessible, and can be modified if their
        definitions allow modifications;
    \item  If the lambda expression is defined inside a function then that
        function's local variables may be accessed by the lambda expression's
        compound statement \emph{if} their names are listed inside the
        lambda-introducer.\ \\ 
       The specification \texttt{local} is used below as a shorthand for a
        (comma-separated) list of names of local variables of the surrounding
        function that are visible in the lambda expression's compound
        statement;
    \item  Local variables specified in the lambda introducer are in fact data
        members of the lambda expression which are initialized by the
        corresponding local variables of the function surrounding the lambda
        expression. This is illustrated by the following example showing
        different addresses for \texttt{var} (however, copying can be prevented as
        covered below):
       \begin{verbatim}
    #include <iostream>

    int main()
    {
        int var = 12;
        std::cout << &var << '\n';
        [var]               // lambda expr. using 'var'
        {
            std::cout << &var << '\n';
        }();                // directly call the lambda expr.
    }
\end{verbatim}
    \item  When the lambda expression is defined inside a class member function
        the lambda-introducer may specify \texttt{this} or \texttt{$*$this} allowing the
        lambda function to access/use the class's members (not defining copies
        as when accessing local variables). When \texttt{this} is specified the
        class's members can be accessed and the class's (non-const) data
        members can be modified. When \texttt{$*$this} is specified the lambda
        expression uses a copy of the class's object. 
    \end{itemize}

By default lambda expressions define constant (immutable) function objects,
but by appending \texttt{mutable} to the lambda declarator they are defined as
mutable function objects.  Sometimes using \texttt{mutable} or not is
irrelevant. In those cases `\texttt{mutable\_opt}' is specified below. If
\texttt{mutable\_opt} is not specified then specifying \texttt{mutable} indicates that
the lambda expression's function isn't a \texttt{const} member function anymore, so
it may modify its (modifiable) data members.

Below specifications \texttt{(...)} refer to the lambda expression's declarator,
and lambda introducers ending in  \texttt{, ...{]}} indicate that they may
specify \texttt{, this} or \texttt{, $*$this}.\ \\ 
    There is no required ordering of the \texttt{this, $*$this} and \texttt{local}
specifications. 

\begin{itemize}
    \item \texttt{{[}...{]} (...) mutable\_opt}:
       only global variables can be accessed;

\item \texttt{{[}local, ...{]} (...)}:
       like the previous specification, with \texttt{local} being defined as the
        lambda expression's data member(s) initialized by copying
        the surrounding function's local variable(s).  When \texttt{mutable} is
        specified the (copied) \texttt{local} variable(s) can be modified;

\item \texttt{{[}\&local, ...{]} (...)}:
       like the previous specification, but the local variable(s) specified
        using \texttt{\&}-prefixes are available as references to the class's data
        members. They can be modified if those members are non-const;

\item \texttt{{[}\&d\_local = std::as\_const(local), ...{]} (...)} 
       defines the lambda expression's \texttt{d\_local} data member as a reference
        to the (immutable) \texttt{local} variable of the surrounding function. The
        \texttt{d\_local} data members remains a reference to an immutable \texttt{local}
        variable whether or not \texttt{mutable} is specified.\ \\ 
       To use \texttt{std::as\_const} the \index{utility: header file}\texttt{$<$utility$>$} header file must be
        included;

\item \texttt{{[}\&, ...{]} (...)  mutable\_opt}:
       the `local reference specifier': local variables are visible as
        modifiable references. If some of those references should not be able
        to modify their local variables then use specifications like
        \texttt{\&d\_local = std::as\_const(local)} for those variables.

\item \texttt{{[}vars, ...{]} (...)}: 
       in addition to the above specifications lambda expressions may define
        their own data members. E.g., to define a lambda expression having its
        own \texttt{int count} and \texttt{double value} data members, also allowing it
        to access the caller's local variables its lambda-introducers can be
        specified as \texttt{{[}\&, count = int(0), value = double(0){]}}.\ \\ 
       Such local variables are defined by specifying their names, followed by
        their type-specifying initializations;

\item \texttt{{[}=, ...{]} (...)}: 
       if the lambda introducer starts with \texttt{=} then all local variables are
        available as copies of the surrounding function's local variables;

\item \texttt{{[}=, \&local, ...{]}}: 
       like the previous specification, but the local variable(s) prefixed by
        \texttt{\&} are available as references. If those local variables are
        non-const they can be modified. If some of those references should not
        be able to modify their local variables then use specifications like
        \texttt{\&d\_local = std::as\_const(local)};
    \end{itemize}

Even when not specified, lambda expressions defined inside class member
functions implicitly capture
    \index{lambda: capture =, this} their \texttt{this}
pointers, and class members are always accessed relative to \texttt{this}. 

Although lambda expressions are anonymous function objects, they \emph{can} be
assigned to variables. Often, the variable is defined using the keyword
\texttt{auto}. E.g.,
        \begin{verbatim}
    auto sqr = [](int value)
               {
                   return value * value;
               };
\end{verbatim}
The lifetime of such a lambda expression is equal to the lifetime of \texttt{sqr},
which is the variable receiving the lambda expression as its value.

Defining a lambda expression is different from calling its function
operator. The function \texttt{S2::f()} returns what the lamba expression (1)'s
function call operator returns: its function call operator is called by using
\texttt{()} (at (3)). What it in fact returns is another anonymous function object
(defined at \texttt{(2)}). As that's just a function object, to retrieve its value
it must still be called from \texttt{f's} return value using something like this:
        \begin{verbatim}
    S2 s2;      // define the object
    s2.f()();   // call the function call operator (see below)
\end{verbatim}
Here, the second set of parentheses activates the returned function
object's function call operator. Had the parentheses been omitted at (3) then
\texttt{S2::f()} would have returned a mere anonymous function object (defined at
(1)), in which case it would require three sets of parentheses to retrieve
\texttt{ohseven's} value: \texttt{s2.f()()()}.

\subsection{Using lambda expressions}
    \typeout{Original Yodl file: overloading/lambdause}    Now that the syntax of lambda expressions has been covered let's see how
they can be used in various situations.

First we consider named lambda expressions. Named lambda expressions nicely
fit in the niche of \index{function:local}
        \index{local function}
    local functions: when a function needs to perform computations which are
at a conceptually lower level than the function's task itself, then it's
attractive to encapsulate these computations in a separate support function
and call the support function where needed.  Although support functions can be
defined in anonymous namespaces, that quickly becomes awkward when the
requiring function is a class member and the support function also must access
the class's members.

In that case a named lambda expression can be used: it can be defined inside
a requiring function, and it may be given full access to the surrounding
class. The name to which the lambda expression is assigned becomes the name of
a function which can be called from the surrounding function. Here is an
example, converting a numeric IP address to a dotted decimal string, which can
also be accessed directly from an \texttt{Dotted} object (all implementations
in-class to conserve space):
        \begin{verbatim}
    class Dotted
    {
        std::string d_dotted;
        
        public:
            std::string const &dotted() const
            {
                return d_dotted;
            }
            std::string const &dotted(size_t ip)
            {
                auto octet = 
                    [](size_t idx, size_t numeric)
                    {
                        return to_string(numeric >> idx * 8 & 0xff);
                    };

                d_dotted = 
                        octet(3, ip) + '.' + octet(2, ip) + '.' +
                        octet(1, ip) + '.' + octet(0, ip);

                return d_dotted;
            }
    };
\end{verbatim}
Next we consider the use of generic algorithms, like 
the \texttt{for\_each} (cf. section \ref{FOREACH}):
        \begin{verbatim}
    void showSum(vector<int> const &vi)
    {
        int total = 0;
        for_each(
            vi.begin(), vi.end(),
            [&](int x)
            {
                total += x;
            }
        );
        std::cout << total << '\n';
    }
\end{verbatim}
Here the variable \texttt{int total} is passed to the lambda expression by
reference and is directly accessed by the function. Its parameter list merely
defines an \texttt{int x}, which is initialized in sequence by each of the values
stored in \texttt{vi}. Once the generic algorithm has completed \texttt{showSum}'s
variable \texttt{total} has received a value that is equal to the sum of all the
vector's values. It has outlived the lambda expression and its value is
displayed.

But although generic algorithms are extremely useful, there may not always be
one that fits the task at hand. Furthermore, an algorithm like \texttt{for\_each}
looks a bit unwieldy, now that the language offers range-based for-loops. So
let's try this, instead of the above implementation:
        \begin{verbatim}
    void showSum(vector<int> const &vi)
    {
        int total = 0;
        for (auto el: vi)
            [&](int x)
            {
                total += x;
            };

        std::cout << total << '\n';
    }
\end{verbatim}
But when \texttt{showSum} is now called, its \texttt{cout} statement consistently
reports 0. What's happening here?

When a generic algorithm is given a lambda function, its implementation
instantiates a reference to a function. The referenced function is thereupon
called from within the generic algorithm. But, in the above example the
range-based for-loop's nested statement merely represents the \emph{definition}
of a lambda function. Nothing is actually called, and hence \texttt{total} remains
equal to 0. 

Thus, to make the above example work we not only must \emph{define} the
lambda expression, but we must also \emph{call} the lambda function. We can do
this by  giving the lambda function a \emph{name}, and then call the
lambda function by its given name:
        \begin{verbatim}
    void showSum(vector<int> const &vi)
    {
        int total = 0;
        for (auto el: vi)
        {
            auto lambda = [&](int x)
                            {
                                total += x;
                            };

            lambda(el);
        }
        std::cout << total << '\n';
    }
\end{verbatim}
In fact, there is no need to give the lambda function a name: the \texttt{auto
lambda} definition represents the lambda function, which could also
directly be called. The syntax for doing this may look a
bit weird, but there's nothing wrong with it, and it allows us to drop the
compound statement, required in the last example, completely. Here goes:
        \begin{verbatim}
    void showSum(vector<int> const &vi)
    {
        int total = 0;
        for (auto el: vi)
            [&](int x)
            {
                total += x;
            }(el);          // immediately append the 
                            // argument list to the lambda
                            // function's definition
        std::cout << total << '\n';
    }
\end{verbatim}
Lambda expressions can also be used to prevent spurious returns from
\texttt{condition\_variable's wait} calls (cf. section \ref{CONDEX}). 

The class \texttt{condition\_variable} allows us to do so by offering \texttt{wait}
members expecting a lock \emph{and} a predicate. The predicate checks the data's
state, and returns \texttt{true} if the data's state allows the data's
processing. Here is an alternative implementation of the \texttt{down} member shown
in section \ref{CONDEX}, checking for the data's actual availability:
        \begin{verbatim}
    void down()
    {
        unique_lock<mutex> lock(sem_mutex);
        condition.wait(lock, 
            [&]()
            {
                return semaphore != 0
            }
        );
        --semaphore;
    }
\end{verbatim}
The lambda expression ensures that \texttt{wait} only returns once
\texttt{semaphore} has been incremented.

Lambda expression are primarily used to obtain functors that are used in a
very localized section of a program. Since they are used inside an existing
function we should realize that once we use lambda functions multiple
aggregation levels are mixed. Normally a function implements a task which can
be described at its own aggregation level using just a few sentences. E.g.,
``the function \texttt{std::sort} sorts a data structure by comparing its elements
in a way that is appropriate to the context where \texttt{sort} is called''. By
using an existing comparison method the aggregation level is kept, and the
statement is clear by itself. E.g.,
        \begin{verbatim}
    sort(data.begin(), data.end(), greater<DataType>());
\end{verbatim}
If an existing comparison method is not available, a tailor-made function
object must be created. This could be realized using a lambda
expression. E.g.,
        \begin{verbatim}
    sort(data.begin(), data.end(), 
        [&](DataType const &lhs, DataType const &rhs)
        {
            return lhs.greater(rhs);
        }
    );
\end{verbatim}
Looking at the latter example, we should realize that here two different
aggregation levels are mixed: at the top level the intent is to sort the
elements in \texttt{data}, but at the nested level (inside the lambda expression)
something completely different happens. Inside the lambda expression we define
how a the decision is made about which of the two objects is the greater. Code
exhibiting such mixed aggregation levels is hard to read, and should be
avoided. 

On the other hand: lambda expressions also simplify code because the overhead
of defining tailor-made functors is avoided. The advice, therefore, is to use
lambda expressions sparingly. \emph{When} they are used make sure that their
sizes remain small. As a \index{rule of thumb}rule of thumb: lambda expressions should be
treated like in-line functions, and should merely consist of one, or maybe
occasionally two expressions.

A special group of lambda expressions is known as \emph{generic lambda
expressions}. As generic lambda expressions are in fact \emph{class templates},
their coverage is postponed until chapter \ref{TEMPCLASS}.

\section{The case of {[}io{]}fstream::open()}\label{EnumOverload}
\typeout{Original Yodl file: overloading/iofstreamopen}Earlier, in section \ref{OUTPUTMODES}, it was noted that the
\texttt{{[}io{]}fstream::open} members expect an \texttt{ios::openmode} value as their
final argument. E.g., to open an \texttt{fstream} object for writing you could do
as follows:
        \begin{verbatim}
    fstream out;
    out.open("/tmp/out", ios::out);
\end{verbatim}
Combinations are also possible. To open an \texttt{fstream} object for
\emph{both} reading and writing the following stanza is often seen:
        \begin{verbatim}
    fstream out;
    out.open("/tmp/out", ios::in | ios::out);
\end{verbatim}
When trying to combine enum values using a `home made' \texttt{enum} we may run
into problems. Consider the following:
        \begin{verbatim}
    enum Permission
    {
        READ =      1 << 0,
        WRITE =     1 << 1,
        EXECUTE =   1 << 2
    };

    void setPermission(Permission permission);

    int main()
    {
        setPermission(READ | WRITE);
    }
\end{verbatim}
When offering this little program to the compiler it replies with an
error message like this:
    \begin{center}\texttt{invalid conversion from 'int' to 'Permission'}\end{center}

The question is of course: why is it OK to combine \texttt{ios::openmode}
values passing these combined values to the stream's \texttt{open} member, but
not OK to combine \texttt{Permission} values.

\index{enum values: and arithmetic operators}
    Combining enum values using arithmetic operators results in \texttt{int}-typed
values. \emph{Conceptually} this never was our intention. Conceptually it can be
considered correct to combine enum values if the resulting value conceptually
makes sense as a value that is still within the original enumeration
domain. Note that after adding a value \texttt{READWRITE = READ \textbar{} WRITE} to the
above \texttt{enum} we're still not allowed to specify \texttt{READ \textbar{} WRITE} as an
argument to \texttt{setPermission}.

To answer the question about combining enumeration values and yet stay
within the enumeration's domain we turn to operator overloading. Up to this
point operator overloading has been applied to class types. Free functions
like \texttt{operator$<$$<$} have been overloaded, and those overloads are conceptually
within the domain of their class.

As \textbf{C++} is a strongly typed language realize that defining an \texttt{enum} is
really something beyond the mere association of \texttt{int}-values with symbolic
names. An enumeration type is really a type of its own, and as with any type
its operators can be overloaded. When writing \texttt{READ \textbar{} WRITE} the compiler
performs the default conversion from enum values to \texttt{int} values and
applies the operator to \texttt{ints}. It does so when it has no alternative.

But it is also possible to overload the enum type's operators. Thus we may
ensure that we'll remain within the enum's domain even though the resulting
value wasn't defined by the enum. The advantage of type-safety and conceptual
clarity is considered to outweigh the somewhat peculiar introduction of values
hitherto not defined by the enum.

Here is an example of such an overloaded operator:
        \begin{verbatim}
    Permission operator|(Permission left, Permission right)
    {
        return static_cast<Permission>(static_cast<int>(left) | right);
    }
\end{verbatim}
Other operators can easily and analogously be constructed.

Operators like the above were defined for the  \texttt{ios::openmode}
enumeration type, allowing us to specify \texttt{ios::in \textbar{} ios::out} as argument to
\texttt{open} while specifying the corresponding parameter as \texttt{ios::openmode}
as well. Clearly, operator overloading can be used in many situations, not
necessarily only involving class-types.

\section{User-defined literals}\label{UDLITERALS}
\typeout{Original Yodl file: overloading/userdefined}In addition to the well-known literals, like numerical constants (with or
without suffixes), character constants and string (textual) literals, \textbf{C++}
also supports
    \index{user-defined literals}\emph{user-defined literals}, also known as \index{extensible literals}\emph{extensible literals}. 

A user-defined literal is defined by a function (see also section \ref{UDL})
that must be defined at namespace scope. Such a function is called a
        \index{literal operator}literal operator.
    A literal operator cannot be a class member function.  The names of a
literal operator must start with an
    \index{identifier: initial underscore} underscore, and a literal operator is
used (called) by \emph{suffixing} its name (including the underscore) to the
argument that must be passed to it . Assuming \texttt{\_NM2km} (nautical mile to km)
is the name of a literal operator, then it could be called as \texttt{100\_NM2km},
producing, e.g., the value 185.2.

Using \texttt{Type} to represent the return type of the literal operator
its generic declaration looks like this:
        \begin{verbatim}
    Type operator "" _identifier(parameter-list);
\end{verbatim}
The blank space trailing the empty string is required. The parameter lists
of literal operators can be:
    \begin{itemize}
    \item \texttt{unsigned long long int}. It is used as, e.g., \texttt{123\_identifier}. The
        argument to this literal operator can be decimal constants,
        binary constants (initial \index{0b}0b), octal constants (initial 0) and
        hexadecimal constants (initial 0x);
    \item \texttt{long double}. It is used as, e.g., \texttt{12.25\_NM2km};
    \item \texttt{char const $*$text}. The \texttt{text} argument is an NTBS. It is
        used as, e.g., \texttt{1234\_pental}. The argument must \emph{not} be given
        double quotes, and must represent a numeric constant, as also expected
        by literal operators defining  \texttt{unsigned long long int}
        parameters.
    \item \texttt{char const $*$text, size\_t len}. Here, the compiler determines \texttt{len}
        as if it had called \texttt{strlen(text)}. It is used as, e.g.,
        \texttt{"hello"\_nVowels};
    \item \texttt{wchar\_t const $*$text, size\_t len}, same as the previous one, but
        accepting a string of \texttt{wchar\_t} characters. It is used as, e.g.,
        \texttt{L"1234"\_charSum};
    \item \texttt{char16\_t const $*$text, size\_t len}, same as the previous one, but
        accepting a string of \texttt{char16\_t} characters. It is used as, e.g.,
        \texttt{u"utf 16"\_uc};
    \item \texttt{char32\_t const $*$text, size\_t len}, same as the previous one, but
        accepting a string of \texttt{char32\_t} characters. It is used as, e.g.,
        \texttt{U"UTF 32"\_lc};
    \end{itemize}
    If literal operators are overloaded the compiler will pick the literal
operator requiring the least `effort'. E.g., 120 is processed by a literal
operator defining an \texttt{unsigned long long int} parameter and not by its
overloaded version, defining a \texttt{char const $*$} parameter. But if overloaded
literal operators exist defining \texttt{char const $*$} and \texttt{long double}
parameters then the operator defining a \texttt{char const $*$} parameter is used
when the argument 120 is provided, while the operator defining a \texttt{long
double} parameter is used with the argument 120.3.

A literator operator can define any return type. Here is
an example of a definition of the \texttt{\_NM2km} literal operator:
        \begin{verbatim}
    double operator "" _NM2km(char const *nm)
    {
        return std::stod(nm) * 1.852;
    }

    double value = 120_NM2km;   // example of use
\end{verbatim}
Of course, the argument could also have been a \texttt{long double}
constant. Here's an alternative implementation, explicitly expecting a \texttt{long
double}:

\begin{verbatim}
    constexpr double operator "" _NM2km(long double nm)
    {
        return nm * 1.852;
    }

    double value = 450.5_NM2km;   // example of use
\end{verbatim}
A numeric constant can also be processed completely at compile-time.
Section \ref{UDL} provides the details of this type of literal operator.

Arguments to literal operators are themselves always constants. A literal
operator like \texttt{\_NM2km} cannot be used to convert, e.g., the value of a
variable. A literal operator, although it is defined as a function, cannot be
called like a function. The following examples therefore
result in compilation errors:
        \begin{verbatim}
    double speed;

    speed_NM2km;        // no identifier 'speed_NM2km'
    _NM2km(speed);      // no function _NM2km
    _NM2km(120.3);      // no function _NM2km
\end{verbatim}
\section{Overloadable operators}\label{OverloadableOperators}
\typeout{Original Yodl file: overloading/overloadable}The following \index{overloadable operators} operators can be overloaded:
        \begin{verbatim}
    +       -       *       /       %       ^       &       |
    ~       !       ,       =       <=>     <       >       <=
    >=      ++      --      <<      >>      ==      !=      &&
    ||      +=      -=      *=      /=      %=      ^=      &=
    |=      <<=     >>=     []      ()      ->      ->*     new
    new[]   delete  delete[]
\end{verbatim}
Several operators have \emph{textual alternatives}:

\begin{center}
    
        \index{operators: textual alternatives}
    \begin{tabular}{cl}

    \hline

    
textual alternative &                operator \\

    \hline

    
  \index{and}\texttt{and}\index{operator and} &        \texttt{ \&\& } \\

    
  \index{and\_eq}\texttt{and\_eq}\index{operator and\_eq} &  \texttt{ \&= } \\

    
  \index{bitand}\texttt{bitand}\index{operator bitand} &  \texttt{ \&  } \\

    
  \index{bitor}\texttt{bitor}\index{operator bitor} &    \texttt{ \textbar{}  } \\

    
  \index{compl}\texttt{compl}\index{operator compl} &    \texttt{ \textasciitilde{}  } \\

    
  \index{not}\texttt{not}\index{operator not} &        \texttt{ !  } \\

    
  \index{not\_eq}\texttt{not\_eq}\index{operator not\_eq} &  \texttt{ != } \\

    
  \index{or}\texttt{or}\index{operator or} &          \texttt{ \textbar{}\textbar{} } \\

    
  \index{or\_eq}\texttt{or\_eq}\index{operator or\_eq} &    \texttt{ \textbar{}= } \\

    
  \index{xor}\texttt{xor}\index{operator xor} &        \texttt{ \textasciicircum{}  } \\

    
  \index{xor\_eq}\texttt{xor\_eq}\index{operator xor\_eq} &  \texttt{ \textasciicircum{}= } \\

    \hline

    
\end{tabular}
    \end{center}

`Textual' alternatives of operators are also overloadable (e.g.,
\texttt{operator and}). However, note that textual alternatives are not
\emph{additional} operators. So, within the same context \texttt{operator\&\&} and
\texttt{operator and} can not \emph{both} be overloaded.

Several of these operators may only be overloaded as member functions
    \index{operator overloading: within classes only} \emph{within} a class. This
holds true for the \texttt{'='}, the \texttt{'{[}{]}'}, the \texttt{'()'} and the \texttt{'-$>$'}
operators. Consequently, it isn't possible to redefine, e.g., the assignment
operator globally in such a way that it accepts a \texttt{char const $*$} as an
\texttt{lvalue} and a \texttt{String \&} as an \emph{rvalue}. Fortunately, that isn't
necessary either, as we have seen in section \ref{ConversionOperators}.

Finally, the following operators cannot be  overloaded:
        \begin{verbatim}
    .       .*      ::      ?:      sizeof  typeid
\end{verbatim}
\cleardoublepage\chapter{Abstract Containers}\label{CONTAINERS}
\typeout{Original Yodl file: containers}\typeout{Original Yodl file: containers/container}\textbf{C++} offers several predefined datatypes, all part of the
 Standard Template Library,
which can be used to implement solutions to frequently occurring problems. The
datatypes discussed in this chapter are all
 \index{container} \emph{containers}: you can put stuff inside them, and you can
retrieve the stored information from them.

The interesting part is that the kind of data that can be stored inside these
containers has been left unspecified at the time the containers were
constructed. That's why they are spoken of as \emph{abstract} containers.

Abstract containers rely heavily on \emph{templates}, covered in chapter
\ref{TEMPLATES} and beyond. To use abstract containers, only a minimal grasp of
the template concept is required. In \textbf{C++} a template is in fact a recipe
for constructing a function or a complete class. The recipe tries to abstract
the functionality of the class or function as much as possible from the data
on which the class or function operates. As the data types on which the
templates operate were not known when the template was implemented, the
datatypes are either inferred from the context in which a function template is
used, or they are mentioned explicitly when a class template is used (the term
that's used here is \emph{instantiated}). In situations where the types are
explicitly mentioned, the \emph{angle bracket notation} is used to indicate
which data types are required. For example, below (in section \ref{PAIR}) we'll
encounter the \index{pair container}\texttt{pair} container, which requires the
explicit mentioning of two data types. Here is a \texttt{pair} object
containing both an \texttt{int} and a \texttt{string}:
        \begin{verbatim}
    pair<int, string> myPair;
\end{verbatim}
The object \texttt{myPair} is defined as an object holding both an \texttt{int} and
a \texttt{string}.

The angle bracket notation is used intensively in the upcoming
discussion of abstract containers. Actually, understanding this part of
templates is the only real requirement for using abstract containers. Now
that we've introduced this notation, we can postpone the more thorough
discussion of templates to chapter \ref{TEMPLATES}, and concentrate on
their use in this chapter.

Most abstract containers are \emph{sequential} containers: they contain
data that can be stored and retrieved in some sequential
way. Examples are the \texttt{array}, implementing a fixed-sized array; a 
\texttt{vector}, implementing an extendable array; the
\texttt{list}, implementing a data structure that allows for the easy insertion or
deletion of  data; the \texttt{queue}, also called a \index{FIFO}\emph{FIFO}
    (\index{first in, first out}first in, first out) structure, in which the first element that is
entered is the first element to be retrieved again; and the \texttt{stack},
which is a
    \index{first in, last out}\emph{first in, last out} (\index{FILO}FILO or \index{LIFO}LIFO) structure.

In addition to sequential containers several special containers are
available. The \texttt{pair} is a basic container in which a pair of values (of
types that are left open for further specification) can be stored, like two
strings, two ints, a string and a double, etc.. Pairs are often used to return
data elements that naturally come in pairs. For example, the \texttt{map} is an
abstract container storing keys and their associated values. Elements
of these maps are returned as \texttt{pairs}.

A variant of the \texttt{pair} is the \texttt{complex} container, implementing
operations that are defined on complex numbers.

A \texttt{tuple} (cf. section \ref{TUPLES}) generalizes the \texttt{pair} container to a
data structure accommodating any number of different data types.

All abstract containers described in this chapter as well as the \texttt{string}
and stream datatypes (cf. chapters \ref{String} and \ref{IOStreams}) are part of
the Standard Template Library.

All but the unordered containers support
        \index{basic operators of containers}
        \index{container: basic operators}
        \index{operators of containers}
    the following basic set of operators:
    \begin{itemize}
    \item  The \index{overloaded assignment}overloaded assignment operator, so we can assign two
containers of the same types to each other. If the container's data type
supports move assignment, then assignment of an anonymous temporary container
to a destination container will use move assignment when assigning new values
to the destination container's element. Overloaded assignment is \emph{also}
supported by the unordered containers;
    \item  \index{container: equality tests} Tests for equality: \index{==}\texttt{==} and \index{!=}\texttt{!=}
The \index{equality operator}equality operator applied to two containers returns \texttt{true} if the two
containers have the same number of elements, which are pairwise equal
according to the equality operator of the contained data type. The
\index{inequality operator}inequality operator does the opposite;
    \item  \index{container: ordering} Ordering operators: \index{\textless{}}\texttt{$<$}, \index{\textless{}=}\texttt{$<$=}, \index{\textgreater{}}\texttt{$>$} and
\index{\textgreater{}=}\texttt{$>$=}.  The \texttt{$<$} operator returns \texttt{true} if each element in the
\index{left-hand}left-hand side container is less than each corresponding element in the
\index{right-hand}right-hand side container. Additional elements in either the left-hand side
container or the right-hand side container are ignored.
    \begin{verbatim}
container left;
container right;

left = {0, 2, 4};
right = {1, 3};             // left < right

right = {1, 3, 6, 1, 2};    // left < right
\end{verbatim}
\end{itemize}
    Note that \index{container: data type requirements} before a
user-defined type (usually a \texttt{class}-type) can be stored in a container, the
user-defined type should at least support:
    \begin{itemize}
    \item  A default value (e.g., a \index{default constructor}default constructor)
    \item  The \index{equality operator}equality operator (\index{==}\texttt{==})
    \item  The \index{less-than operator}less-than operator (\index{\textless{}}\texttt{$<$})
    \end{itemize}
    Sequential containers can also be initialized using \emph{initializer lists}.

Most containers (exceptions are the stack (section
\ref{STACK}), priority\_queue (section
\ref{PRIQUEUE}), and queue (section
\ref{QUEUE}) containers) support members to determine their maximum sizes
(through their member function \index{max\_size}max\_size).

Virtually all containers support copy construction.  If the container
supports copy construction and the container's data type supports move
construction, then move construction is automatically used for the container's
data elements when a container is initialized with an anonymous temporary
container.

Closely linked to the standard template library are the
    \index{generic algorithms}\emph{generic algorithms}. These algorithms may be used to perform
frequently occurring tasks or more complex tasks than is possible with the
containers themselves, like counting, filling, merging, filtering etc.. An
\index{overview of generic algorithms}overview of generic algorithms and their applications is given in chapter
\ref{GENERIC}. Generic algorithms usually rely on the availability of
    \index{iterator}\emph{iterators}, representing begin and
end-points for processing data stored inside containers. The abstract
containers usually support constructors and members expecting iterators, and
they often have members returning iterators (comparable to the
\texttt{string::begin} and \texttt{string::end} members). In this chapter the
iterator concept is not further investigated. Refer to chapter \ref{STL} for
this.

Containers often collect data during their lifetimes. When a container
goes out of scope, its destructor tries to destroy its data elements. This
only succeeds if the data elements themselves are stored inside the
container. If the \index{container: storing pointers} data elements of containers
are pointers to dynamically allocated memory then the memory pointed to by
these pointers is not destroyed, resulting in a \index{memory leak}memory leak. A consequence
of this scheme is that the data stored in a container should often be
considered the `property' of the container: the container should be able to
destroy its data elements when the container's destructor is called. So,
normally containers should not contain pointers to data. Also, a container
should not be required \index{containter: storing const data}
    \index{const data and containers} to contain \texttt{const} data, as \texttt{const} data
prevent the use of many of the container's members, like the assignment
operator.

\section{Notations used in this chapter}
\typeout{Original Yodl file: containers/notations}    In this chapter about containers, the following notational conventions are
used:
    \begin{itemize}
    \item  Containers live in the standard namespace. In code examples this will
be clearly visible, but in the text \texttt{std::} is usually omitted.
    \item  A \index{container without angle brackets}container without angle brackets represents any container of
that type. Mentally add the required type in
    \index{angle bracket notation}angle bracket notation. E.g., \texttt{pair} may represent \texttt{pair$<$string,
int$>$}.
    \item  The notation \index{Type}\texttt{Type} represents the \index{generic type}generic type. \texttt{Type} could
be \texttt{int}, \texttt{string}, etc.
    \item  Identifiers \texttt{object} and \texttt{container} represent objects of the
container type under discussion.
    \item  The identifier \texttt{value} represents a value of the type that is
stored in the container.
    \item  Simple, one-letter identifiers, like \texttt{n} represent unsigned
values.
    \item  Longer identifiers represent \index{iterator}iterators. Examples
are \texttt{pos}, \texttt{from}, \texttt{beyond}
    \end{itemize}
    Some containers, e.g., the \texttt{map} container, contain pairs of
values, usually called `keys' and `values'. For such containers the following
notational convention is used in addition:
    \begin{itemize}
    \item  The identifier \texttt{key} indicates a value of the used key-type
    \item  The identifier \texttt{keyvalue} indicates a value of the `\texttt{value\_type}'
used with the particular container.
    \end{itemize}

\section{The `pair' container}\label{PAIR}
\typeout{Original Yodl file: containers/pair}The \index{pair container} \index{pair}\texttt{pair} container is a rather basic container. It is
used to store two elements, called \index{first}\texttt{first} and \index{second}\texttt{second}, and that's about
it. Before using \texttt{pair} containers the header file \index{utility: header file}\texttt{$<$utility$>$} must be
included.

The \texttt{pair}'s data types are specified when the \texttt{pair} object is
defined (or declared) using the template's angle bracket notation (cf. chapter
\ref{TEMPLATES}). Examples:
        \begin{verbatim}
    pair<string, string> piper("PA28", "PH-ANI");
    pair<string, string> cessna("C172", "PH-ANG");
\end{verbatim}
here, the variables \texttt{piper} and \texttt{cessna} are defined as \texttt{pair}
variables containing two \texttt{strings}. Both strings can be retrieved using the
\texttt{first} and \texttt{second} fields of the \texttt{pair} type:
        \begin{verbatim}
    cout << piper.first << '\n' <<      // shows 'PA28'
            cessna.second << '\n';      // shows 'PH-ANG'
\end{verbatim}
The \texttt{first} and \texttt{second} members can also be used to reassign values:
        \begin{verbatim}
    cessna.first = "C152";
    cessna.second = "PH-ANW";
\end{verbatim}
If a \texttt{pair} object must be completely reassigned, an \emph{anonymous}
\index{anonymous pair} pair object can be used as the \index{right-hand}right-hand operand of
the assignment. An anonymous variable defines a temporary variable (which
receives no name) solely for the purpose of (re)assigning another variable of
the same type. Its \index{anonymous variable: generic form} generic form is
        \begin{verbatim}
    type(initializer list)
\end{verbatim}
Note that when a \texttt{pair} object is used the type specification is not
completed by just mentioning the containername \texttt{pair}. It also requires the
specification of the data types which are stored within the pair. For this the
(template) \index{angle bracket notation}angle bracket notation is used again. E.g., the reassignment
of the \texttt{cessna} pair variable could have been accomplished as follows:
        \begin{verbatim}
    cessna = pair<string, string>("C152", "PH-ANW");
\end{verbatim}
In cases like these, the \texttt{type} specification can become quite
elaborate, in which case \texttt{using} declarations can be used to improve
readability. If many \index{pair\textless{}type1, type2\textgreater{}}\texttt{pair$<$type1, type2$>$} clauses are
used in a source, the typing effort may be reduced and readability might be
improved by first defining a name for the clause, and then using the defined
name later. E.g.,
        \begin{verbatim}
    using pairStrStr = pair<string, string>;

    cessna = pairStrStr("C152", "PH-ANW");
\end{verbatim}
All abstract containers are class templates, and the
types for which class templates are initialized are commonly specified between
pointed brackets following the class template's name. However, the compiler
may be able to 
    \index{class templates: deducing parameters} deduce the container's types from
the types of arguments that are specified when constructing the
container. E.g., when defining
        \begin{verbatim}
    pair values{ 1, 1.5 };
\end{verbatim}
the compiler deduces that \texttt{values.first} is an \texttt{int} and
\texttt{values.second} is a \texttt{double}. Sometimes the class template's types cannot
be deduced. In those cases the intended types must explicitly be specified:
        \begin{verbatim}
    pair<int, double> values;
\end{verbatim}
Although the compiler will deduce types whenever it can, it might not
deduce the types we had in mind. Had we defined
        \begin{verbatim}
    pair cessna{ "C172", "PH-BVL" };
\end{verbatim}
then the compilation would succeed, but an expression  like 
        \texttt{cout $<$$<$ cessna.first.length()} would not compile, as \texttt{"C172"} is
a NTBS, and hence \texttt{cessna.first} is a \texttt{char $*$}. In this case simply
appending an \texttt{s} to the NTBSs fixes the problem, but such a simple fix might
not always be available. Section \ref{VECTOR} provides more information about
deducing template parameter types.

Apart from this (and the basic set of operations (assignment and
comparisons)) the \texttt{pair} offers no further \index{functionality}functionality. It is, however,
a basic ingredient of the upcoming abstract containers \texttt{map, multimap} and
\texttt{hash\_map}.

\textbf{C++} also offers a \index{generalized pair}\emph{generalized pair} container: the \emph{tuple}, covered
in section \ref{TUPLES}.

\section{Available Containers}

\subsection{The `array' container}
    \typeout{Original Yodl file: containers/array}The \index{array}\texttt{array} class implements a 
    \index{array: fixed size} \index{fixed-size array}fixed-size array.  Before using the \texttt{array}
container the \index{array: header file}\texttt{$<$array$>$} header file must be included.

To define a \texttt{std::array} both the data type of its elements and its size
must be specified: the data type is given after an opening angle bracket,
immediately following the `\texttt{array}' container name. The array's size is
provided after the data type specification. Finally, a closing angle bracket
completes the array's type. Specifications like this are common practice with
containers.  The combination of \texttt{array}, type and size defines a
\emph{type}. As a result, \texttt{array$<$string, 4$>$} defines another type than
\texttt{array$<$string, 5$>$}, and a function explicitly defining an \texttt{array$<$Type, N$>$}
parameter will not accept an \texttt{array$<$Type, M$>$} argument if \texttt{N} and \texttt{M}
are unequal.

The array's size may may be defined as 0 (although such an array probably has
little use as it cannot store any element). The elements of an array are
stored contiguously. If \texttt{array$<$Type, N$>$ arr} has been defined, then
\texttt{\&arr{[}n{]} + m == \&arr{[}n + m{]}}, assuming than \texttt{0 $<$= n $<$ N} and \texttt{0 $<$= n + m
$<$ N}.

The following constructors, operators, and member functions are available:
    \begin{itemize}
    \item  \index{array constructors} Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  An \texttt{array} may be constructed with a fixed number \texttt{N} of
default elements:
        \begin{verbatim}
array<string, N> object;
\end{verbatim}
\item  An initial subset of the elements of an array may be 
initialized using a brace delimited initializer list:
    \begin{verbatim}
array<double, 4> dArr = {1.2, 2.4};
\end{verbatim}
Here \texttt{dArr} is defined as an array of 4 element, with \texttt{dArr{[}0{]}} and
\texttt{dArr{[}1{]}} initialized to, respectively 1.2 and 2.4, and \texttt{dArr{[}2{]}} and
\texttt{dArr{[}3{]}} initialized to 0.  An attractive characteristic of arrays (and
other containers) is that containers initialize \index{container: initialization}
their data elements to the data type's default value. The data type's
\emph{default constructor} is used for this \index{initialization}initialization. With non-class
data types the value 0 is used.  So, for an \texttt{array$<$double, 4$>$} array we know
that all but its explicitly initialized elements are initialized to
zero. 
        \end{itemize}
    \item  In addition to the standard operators for containers, the \texttt{array}
supports the \index{index operator}index operator, which can be used to retrieve or reassign
individual elements of the array. Note that the elements which are indexed
must exist. For example, having defined an empty array a statement like
\texttt{iarr{[}0{]} = 18} produces an error, as the array is empty. Note that 
\texttt{operator{[}{]}} does \emph{not} respect its
 \index{array bounds}array bounds. If you want run-time array bound checking, use the array's
\texttt{at} member.
    \item  The \texttt{array} class offers the following
 \index{array: member functions} member functions:
        \begin{itemize}
        \item \index{at}\texttt{Type \&at(size\_t idx)}:\ \\ returns a reference to the array's element at index position
            \texttt{idx}. If \texttt{idx} exceeds the array's size a
            \texttt{std::out\_of\_range} exception is thrown.
        \item \index{back}\texttt{Type \&back()}:\ \\ returns a reference to the last element in the array. It is the
            \index{responsibility of the programmer}responsibility of the programmer to use the member only if the
            array is not empty.
        \item \index{begin}\texttt{array::iterator begin()}:\ \\ returns an \index{iterator}iterator pointing to the first
            element in the array, returning \texttt{end} if the array is empty.
        \item \index{cbegin}\texttt{array::const\_iterator cbegin()}:\ \\ returns a \index{const\_iterator}const\_iterator pointing to the first element in the
            array, returning \texttt{cend} if the array is empty.
        \item \index{cend}\texttt{array::const\_iterator cend()}:\ \\ returns a \index{const\_iterator}const\_iterator pointing just beyond the array's last
            element.
        \item \index{crbegin}\texttt{array::const\_reverse\_iterator crbegin()}:\ \\ returns a \index{const\_reverse\_iterator}const\_reverse\_iterator pointing to the last element
            in the array, returning \texttt{crend} if the array is empty.
        \item \index{crend}\texttt{array::const\_reverse\_iterator crend()}:\ \\ returns a \index{const\_reverse\_iterator}const\_reverse\_iterator pointing just before the
            array's first element.
        \item \index{data}\texttt{value\_type $*$data()}:\ \\ returns a pointer to the array's first data element. With a const
            array a \texttt{value\_type const $*$} is returned.
        \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if the array contains no elements.
        \item \index{end}\texttt{array::iterator end()}:\ \\ returns an iterator pointing beyond the last element in the
            array.
        \item \index{fill}\texttt{void fill(Type const \&item)}:\ \\ fills all the array's elements with a copy of \texttt{item}
        \item \index{front}\texttt{Type \&front()}:\ \\ returns a reference to the first element in the array. It is the
            responsibility of the programmer to use the member only if
            the array is not empty.
        \item \index{rbegin}\texttt{array::reverse\_iterator rbegin()}:\ \\ \index{reverse\_iterator} this member returns a reverse\_iterator
            pointing to the last element in the array.
        \item \index{rend}\texttt{array::reverse\_iterator rend()}:\ \\ returns a reverse\_iterator pointing before the first element in
            the array.
        \item \index{size}\texttt{constexpr size\_t size()}:\ \\ returns the number of elements the array contains.
        \item \index{swap}\texttt{void swap(array$<$Type, N$>$ \&other)}:\ \\ swaps the content of the current and other array. The array
            other's data type and size must be equal to the data type and size
            of the object calling \texttt{swap}.
        \end{itemize}
    \end{itemize}
    Using an \texttt{array} rather than a standard \textbf{C} style array offers several
advantages:
    \begin{itemize}
    \item  All its elements are immediately initialized;
    \item  Introspection is possible (e.g., \texttt{size} can be used);
    \item  The \texttt{array} container can be used in the context of templates,
        there code is developed that operates on data types that become
        available only after the code itself has been developed;
    \item  Since \texttt{array} supports reverse iterators, it can immediately be
        used with generic algorithms performing `reversed' operations (e.g.,
        to perform a descending rather than ascending sort (cf. section
        \ref{SORT}))
    \end{itemize}
    In general, when looking for a sequential data structure, the \texttt{array} or
\texttt{vector} (introduced in the next section) should be your `weapon of
choice'. Only if these containers demonstrably do not fit the problem at hand
you should use another type of container.

\subsection{The `vector' container}\label{VECTOR}
    \typeout{Original Yodl file: containers/vector}The \index{vector}\texttt{vector} class implements an 
    \index{array: expandable}\index{expandable array}expandable array.  Before using the \texttt{vector}
container the \index{vector: header file}\texttt{$<$vector$>$} header file must be included.

The following constructors, operators, and member functions are available:
\begin{itemize}
\item  \index{vector constructors} Constructors:
    \begin{itemize}
    \item  The copy and move constructors are available;

\item  A \texttt{vector} may be constructed empty:
    \begin{verbatim}
vector<string> object;
\end{verbatim}
\item  A vector may be initialized to a certain number of elements:
    \begin{verbatim}
vector<string> object(5, "Hello"s); // initialize to 5 Hello's,
vector<string> container(10);       // and to 10 empty strings
vector<string> names = {"george", "frank", "tony", "karel"};
\end{verbatim}
Note the difference between \texttt{vector$<$int$>$ first(5)} and \texttt{vector$<$int$>$
second\{ 5 \}}. The vector \texttt{first} contains five elements, initialized to 0,
while the vector \texttt{second} contains one element, initialized to 5. Referring
back to section \ref{PAIR}: with the latter definition the compiler is able to
deduce 
    \index{class templates: deducing parameters} the vector's template parameter
type (\texttt{int}), so the latter definition could also have been written as
\texttt{vector second\{ 5 \}}. 

An ambiguity might be observed when looking at 
        \begin{verbatim}
vector object{ vector{ 1 } };
\end{verbatim}
Did we define a \texttt{vector$<$int$>$} or a \texttt{vector$<$vector$<$int$>$$>$}? The standard
considers this a \texttt{vector$<$int$>$}: it is initialized using the vector's move
constructor from an abstract \texttt{vector$<$int$>$}.
        \end{itemize}
        \item  A vector may be initialized using iterators. To
initialize a vector with elements 5 until 10 (including the last one) of an
existing \texttt{vector$<$string$>$} the following construction may be used:
    \begin{verbatim}
extern vector<string> container;
vector<string> object(&container[5], &container[11]);
\end{verbatim}
Note here that the last element pointed to by the second iterator
(\texttt{\&container{[}11{]}}) is \emph{not} stored in \texttt{object}.  This is a simple
example of the use of \emph{iterators}, in which the used
    \index{range of values}range of values starts at the first value, and includes all elements up
to but not including the element to which the second iterator refers. The
standard notation for this is \index{[begin, end)}\texttt{[begin, end)}.

\item  In addition to the standard operators for containers, the \texttt{vector}
supports the index operator, which can be used to retrieve or reassign
individual elements of the vector. Note that the elements which are indexed
must exist. For example, having defined an empty vector a statement like
\texttt{ivect{[}0{]} = 18} produces an error, as the vector is empty.  So, the vector
is \emph{not} automatically
 \index{automatic expansion} expanded, and \texttt{operator{[}{]}} does \emph{not} respect its
 \index{array bounds}array bounds. In this case the vector should be resized first, or
\texttt{ivect.push\_back(18)} should be used (see below). If you need run-time array
bound checking, use the vector's \texttt{at} member.
    \item  The \texttt{vector} class offers the following
 \index{vector: member functions} member functions:
        \begin{itemize}
        \item \index{assign}\texttt{void assign(...)}:\ \\ assigns new content to the vector:
            \begin{itemize}
            \item \texttt{assign(iterator begin, iterator end)} assigns the values at
the iterator range \texttt{[begin, end)} to the vector;
            \item \texttt{assign(size\_type n, value\_type const \&val)} assigns \texttt{n}
copies of \texttt{val} to the vector;
            \item \texttt{assign(initializer\_list$<$value\_type$>$ values)} assigns the
values in the initializer list to the vector.
                \end{itemize}

\item \index{at}\texttt{Type \&at(size\_t idx)}:\ \\ returns a reference to the vector's element at
index position \texttt{idx}. If \texttt{idx} exceeds the vector's size a
\texttt{std::out\_of\_range} exception is thrown.
        \item \index{back}\texttt{Type \&back()}:\ \\ returns a reference to the last element in the
vector. It is the \index{responsibility of the programmer}responsibility of the programmer to use the member only
if the vector is not empty.
        \item \index{begin}\texttt{vector::iterator begin()}:\ \\ returns an iterator pointing to the first
element in the vector, returning \texttt{end} if the vector is empty.
        \item \index{capacity}\texttt{size\_t capacity()}:\ \\ Number of elements for which memory has been
allocated. It returns at least the value returned by \texttt{size}
        \item \index{cbegin}\texttt{vector::const\_iterator cbegin()}:\ \\ returns a const\_iterator pointing to the first
element in the vector, returning \texttt{cend} if the vector is empty.
        \item \index{cend}\texttt{vector::const\_iterator cend()}:\ \\ returns a const\_iterator pointing just beyond the
vector's last element.
        \item \index{clear}\texttt{void clear()}:\ \\ erases all the vector's elements.
        \item \index{crbegin}\texttt{vector::const\_reverse\_iterator crbegin()}:\ \\ returns a const\_reverse\_iterator pointing to the last
element in the vector, returning \texttt{crend} if the vector is empty.
        \item \index{crend}\texttt{vector::const\_reverse\_iterator crend()}:\ \\ returns a const\_reverse\_iterator pointing just before the
vector's first element.
        \item \index{data}\texttt{value\_type $*$data()}:\ \\ returns a pointer to the vector's first data element.
        \item \index{emplace}\texttt{iterator emplace(const\_iterator position, Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the arguments
specified after \texttt{position}, and the newly created element is inserted at
\texttt{position}. Different from \texttt{insert}, which expects an existing object of
the container's value type (and inserts 
the provided argument into the container) using copy or move construction or
assignment, \texttt{emplace} uses its arguments to 
\emph{construct} such an object immediately at the intended location of the
container, without requiring copy or move construction or assignment.
        \item \index{emplace\_back}\texttt{constexpr \&emplace\_back(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted beyond the vector's last
element, returning a reference to the newly added element.
        \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if the vector contains no
elements.
        \item \index{end}\texttt{vector::iterator end()}:\ \\ returns an iterator pointing beyond the last
element in the vector.
        \item \index{erase}\texttt{vector::iterator erase()}:\ \\ erases a specific range of elements in the vector:
            \begin{itemize}
            \item \texttt{erase(pos)} erases the element pointed to by the iterator
\texttt{pos}. The iterator \texttt{++pos} is returned.
            \item \texttt{erase(first, beyond)} erases elements indicated by the iterator
range \texttt{[first, beyond)}, returning \texttt{beyond}.
            \end{itemize}

\item \index{front}\texttt{Type \&front()}:\ \\ returns a reference to the first element in the
vector. It is the responsibility of the programmer to use the member only if
the vector is not empty.
        \item \index{get\_allocator}\texttt{allocator\_type get\_allocator() const}:\ \\ returns a
copy of the allocator object used by the \texttt{vector} object.
        \item \index{insert}\texttt{... insert()}:\ \\ elements may be inserted starting at a certain position. The
return value depends on the version of \texttt{insert()} that is called:
            \begin{itemize}
            \item \texttt{vector::iterator insert(pos)} inserts a default value of type
\texttt{Type} at \texttt{pos}, \texttt{pos} is returned.
            \item \texttt{vector::iterator insert(pos, value)} inserts \texttt{value} at
\texttt{pos}, \texttt{pos} is returned.
            \item \texttt{void insert(pos, first, beyond)} inserts the elements in the
                iterator range \texttt{[first, beyond)}.
            \item \texttt{void insert(pos, n, value)} inserts \texttt{n} elements having value
\texttt{value} at position \texttt{pos}.
            \end{itemize}

\item \index{max\_size}\texttt{size\_t max\_size()}:\ \\ returns the maximum number of
elements this \texttt{vector} may contain.
        \item \index{pop\_back}\texttt{void pop\_back()}:\ \\ removes the last element from the vector. Avoid calling this
member on an empty vector: although nothing is returned its internally
maintained count of number of available elements is reduced, causing the
vector's \texttt{size()} member to return the (when cast to \texttt{int}) value -1, and
then -2, etc., etc.
        \item \index{push\_back}\texttt{void push\_back(value)}:\ \\ adds \texttt{value} to the end of the vector.
        \item \index{rbegin}\texttt{vector::reverse\_iterator rbegin()}:\ \\ this member returns a reverse\_iterator pointing to the last
element in the vector.
        \item \index{rend}\texttt{vector::reverse\_iterator rend()}:\ \\ returns an iterator pointing before the first element in the
vector. 
        \item \index{reserve}\texttt{void reserve(size\_t request)}:\ \\ if \texttt{request} is less than or equal to \texttt{capacity}, this
call has no effect. Otherwise, it is a request to allocate additional
memory. If the call is successful, then \texttt{capacity} returns a value of at
least \texttt{request}. Otherwise, \texttt{capacity} is unchanged. In either case,
\texttt{size}'s return value won't change, until a function like \texttt{resize} is
called, actually changing the number of accessible elements.
        \item \index{resize}\texttt{void resize()}:\ \\ can be used to alter the number of elements that
are currently stored in the vector:
            \begin{itemize}
            \item \texttt{resize(n, value)} may be used to resize the vector to a size
of \texttt{n}. \texttt{Value} is optional. If the vector is expanded and \texttt{value} is
not provided, the additional elements are initialized to the \index{default value}default value
of the used data type, otherwise \texttt{value} is used to initialize extra
elements.
            \end{itemize}

\item \index{shrink\_to\_fit}\texttt{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
    \begin{verbatim}
vector<Type>(vectorObject).swap(vectorObject)
\end{verbatim}
idiom can be used.
        \item \index{size}\texttt{size\_t size()}:\ \\ returns the number of elements in the vector.
        \item \index{swap}\texttt{void swap(vector$<$Type$>$ \&other)}:\ \\ swaps two vectors using identical data types. Example:
    \begin{verbatim}
#include <iostream>
#include <vector>
using namespace std;

int main()
{
    vector<int> v1(7);
    vector<int> v2(10);

    v1.swap(v2);
    cout << v1.size() << " " << v2.size() << '\n';
}
/*
    Produced output:
10 7
*/
\end{verbatim}
\end{itemize}\end{itemize}

\subsection{The `list' container}
    \typeout{Original Yodl file: containers/list}The \index{list}\texttt{list} container \index{list container} implements a list data structure.
Before using a \texttt{list} container the header file \index{list: header file}\texttt{$<$list$>$} must be included.

The organization of a \texttt{list} is shown  in figure \ref{listFig}.
        \begin{figure}[tbp]
\centerline{\epsffile{containers/list.eps}}
\caption{\label{listFig}A list data-structure}
\end{figure}
    Figure \ref{listFig}  shows that a list consists of separate
list-elements, connected by pointers. The list can be
    \index{list: traversal} traversed in two directions: starting at \emph{Front} the
list may be traversed from left to right, until the 0-pointer is reached at
the end of the rightmost list-element. The list can also be traversed from
right to left: starting at \emph{Back}, the list is traversed from right to left,
until eventually the 0-pointer emanating from the leftmost list-element is
reached.

As a subtlety note that the representation given in figure \ref{listFig} is not
necessarily used in actual implementations of the list. For example, consider
the following little program:
        \begin{verbatim}
    int main()
    {
        list<int> l;
        cout << "size: " << l.size() << ", first element: " <<
                l.front() << '\n';
    }
\end{verbatim}
When this program is run it might actually produce the output:
        \begin{verbatim}
    size: 0, first element: 0
\end{verbatim}
Its front element can even be assigned a value. In this case the
implementor has chosen to provide the list with a hidden element. The list
actually is a \emph{circular}
 \index{list: circular} list, where the hidden element serves as terminating
element, replacing the 0-pointers in figure \ref{listFig}. As noted, this is a
subtlety, which doesn't affect the conceptual notion of a list as a data
structure ending in 0-pointers. Note also that it is well known that various
implementations of list-structures are possible (cf.
    \index{Aho, A.V.}Aho, A.V., \index{Hopcroft J.E.}Hopcroft J.E. and \index{Ullman, J.D.}Ullman, J.D., (1983)
    \index{Data Structures and Algorithms}\emph{Data Structures and Algorithms} (Addison-Wesley)).

Both lists and vectors are often appropriate data structures in situations
where an \index{storing data} unknown number of data elements must be
stored. However, there are some \index{rule of thumb} rules of thumb to follow
when selecting the appropriate  data structure.
    \begin{itemize}
    \item  When most accesses are \index{random}random, a \texttt{vector} is the preferred data
            structure. Example: in a program counting character frequencies in
            a textfile, a \texttt{vector$<$int$>$ frequencies(256)} is the
            datastructure of choice, as the values of the received characters
            can be used as indices into the \texttt{frequencies} vector.
    \item  The previous example illustrates a second rule of thumb, also
            favoring the \texttt{vector}: if the number of elements is known in
            advance (and does not notably change during the lifetime of the
            program), the vector is also preferred over the list.
    \item  In cases where \index{insertions}insertions or \index{deletions}deletions prevail and the data
            structure is large the list is generally preferred.
    \end{itemize}
    At present lists aren't as useful anymore as they used to be (when
computers were much slower and more memory-constrained).  Except maybe for
some rare cases, a \texttt{vector} should be the preferred container; even when
implementing algorithms traditionally using lists.

Other considerations related to the choice between lists and vectors
should also be given some thought. Although it is true that the vector is able
to grow dynamically, the \index{dynamic growth}dynamic growth requires data-copying.
Clearly, copying a million large data structures takes a considerable amount
of time, even on fast computers. On the other hand, inserting a large number
of elements in a list doesn't require us to
    \index{copy non-involved data}copy non-involved data. Inserting a new element in a list merely
requires us to juggle some pointers. In figure \ref{listAdd} this is shown: a
new element is inserted between the second and third element, creating a new
list of four elements.
        \begin{figure}[tbp]
\centerline{\epsffile{containers/insertlist.eps}}
\caption{\label{listAdd}Adding a new element to a list}
\end{figure}
    Removing an element from a list is also fairly easy. Starting again
from the situation shown in figure \ref{listFig}, figure \ref{listDel} shows
what happens if element two is removed from our list. Again: only pointers
need to be juggled. In this case it's even simpler than adding an element:
only two pointers need to be rerouted.
        \begin{figure}[tbp]
\centerline{\epsffile{containers/dellist.eps}}
\caption{\label{listDel}Removing an element from a list}
\end{figure}
    To summarize the comparison between lists and vectors: it's probably best
to conclude that there is no clear-cut answer to the question what data
structure to prefer. There are rules of thumb, which may be adhered to. But if
worse comes to worst, a \index{profiler}profiler may be required to find out what's best.

The \texttt{list} container offers the following constructors, operators, and
member functions:
    \begin{itemize}
    \item  \index{list constructors} Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  A \texttt{list} may be constructed empty:
    \begin{verbatim}
list<string> object;
\end{verbatim}
As with the \texttt{vector}, it is an error to refer to an element of an
empty list.
        \item  A list may be initialized to a certain number of elements. By
            default, if the initialization value is not explicitly mentioned,
            the default value or default constructor for the actual data type
            is used. For example:
    \begin{verbatim}
list<string> object(5, "Hello"s); // initialize to 5 Hello's
list<string> container(10);       // and to 10 empty strings
\end{verbatim}
\item  A list may be initialized using a two iterators. To initialize a
            list with elements 5 until 10 (including the last one) of a
            \texttt{vector$<$string$>$} the following construction may be used:
    \begin{verbatim}
extern vector<string> container;
list<string> object(&container[5], &container[11]);
\end{verbatim}
\end{itemize}
    \item  The \texttt{list} does not offer specialized operators, apart from the
            standard operators for containers.
    \item  The following \index{member function}member functions are available:
        \begin{itemize}
        \item \index{assign}\texttt{void assign(...)}:
            \begin{quote}assigns new content to the list:\end{quote}
            \begin{itemize}
            \item \texttt{assign(iterator begin, iterator end)} assigns the values at
                the iterator range \texttt{[begin, end)} to the list;
            \item \texttt{assign(size\_type n, value\_type const \&val)} assigns \texttt{n}
                copies of \texttt{val} to the list;
            \end{itemize}
        \item \index{back}\texttt{Type \&back()}:\ \\ returns a reference to the last element in
            the list. It is the \index{responsibility of the programmer}responsibility of the programmer to use
            this member only if the list is not empty.
        \item \index{begin}\texttt{list::iterator begin()}:\ \\ returns an iterator pointing to
            the first element in the list, returning \texttt{end} if the list is
            empty.
        \item \index{clear}\texttt{void clear()}:\ \\ erases all elements from the list.
        \item \index{emplace\_back}\texttt{value\_type \&emplace\_back(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
            arguments, and the newly created element is inserted beyond the
            last element of the list, returning a reference to the newly added
            element. 
        \item \index{emplace\_front}\texttt{value\_type \&emplace\_front(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
            arguments, and the newly created element is inserted before the
            first element of the list, returning a reference to the newly added
            element. 
        \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if the list contains no
            elements.
        \item \index{end}\texttt{list::iterator end()}:\ \\ returns an iterator pointing beyond
            the last element in the list.
        \item \index{erase}\texttt{list::iterator erase()}:\ \\ erases a specific range of
            elements in the list:
            \begin{itemize}
            \item \texttt{erase(pos)} erases the element pointed to by \texttt{pos}. The
                iterator \texttt{++pos} is returned.
            \item \texttt{erase(first, beyond)} erases elements indicated by the iterator
                range \texttt{[first, beyond)}. \texttt{Beyond} is returned.
            \end{itemize}
        \item \index{front}\texttt{Type \&front()}:\ \\ returns a reference to the first element
            in the list. It is the responsibility of the programmer to use
            this member only if the list is not empty.
        \item \index{get\_allocator}\texttt{allocator\_type get\_allocator() const}:\ \\ returns a
            copy of the allocator object used by the \texttt{list} object.
        \item \index{insert}\texttt{... insert()}:\ \\ inserts elements into the list. The return
            value depends on the version of \texttt{insert} that is called:
            \begin{itemize}
            \item \texttt{list::iterator insert(pos)} inserts a default value of type
                \texttt{Type} at \texttt{pos}, \texttt{pos} is returned.
            \item \texttt{list::iterator insert(pos, value)} inserts \texttt{value} at
                \texttt{pos}, \texttt{pos} is returned.
            \item \texttt{void insert(pos, first, beyond)} inserts the elements in the
                iterator range \texttt{[first, beyond)}.
            \item \texttt{void insert(pos, n, value)} inserts \texttt{n} elements having value
                \texttt{value} at position \texttt{pos}.
            \end{itemize}
        \item \index{max\_size}\texttt{size\_t max\_size()}:\ \\ returns the maximum number of
            elements this \texttt{list} may contain.
        \item \index{merge}\texttt{void merge(list$<$Type$>$ other)}:\ \\ this member function
            assumes that the current and other lists are sorted (see below,
            the member \texttt{sort}). Based on that assumption, it inserts the
            elements of \texttt{other} into the current list in such a way that the
            modified list remains sorted.  If both list are not sorted, the
            resulting list will be ordered `as much as possible', given the
            initial ordering of the elements in the two
            lists. \texttt{list$<$Type$>$::merge} uses \texttt{Type::operator$<$} to sort the
            data in the list, which operator must therefore be available.  The
            next example illustrates the use of the \texttt{merge} member: the list
            `\texttt{object}' is not sorted, so the resulting list is ordered 'as
            much as possible'.  
           \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <list>
    using namespace std;

    void showlist(list<string> &target)
    {
        for
        (
            list<string>::iterator from = target.begin();
            from != target.end();
            ++from
        )
            cout << *from << " ";

        cout << '\n';
    }

    int main()
    {
        list<string> first;
        list<string> second;

        first.push_back("alpha"s);
        first.push_back("bravo"s);
        first.push_back("golf"s);
        first.push_back("quebec"s);

        second.push_back("oscar"s);
        second.push_back("mike"s);
        second.push_back("november"s);
        second.push_back("zulu"s);

        first.merge(second);
        showlist(first);
    }
    // shows:
    // alpha bravo golf oscar mike november quebec zulu
\end{verbatim}
           A subtlety is that \texttt{merge} doesn't alter the list if the list
            itself is used as argument: \texttt{object.merge(object)} won't change
            the list `\texttt{object}'.
        \item \index{pop\_back}\texttt{void pop\_back()}:\ \\ removes the last element from the
            list. The program aborts when called on an \index{empty list}empty list.
        \item \index{pop\_front}\texttt{void pop\_front()}:\ \\ removes the first element from the
            list. The program aborts when called on an \index{empty list}empty list.
        \item \index{push\_back}\texttt{void push\_back(value)}:\ \\ adds \texttt{value} to the end of
            the list.
        \item \index{push\_front}\texttt{void push\_front(value)}:\ \\ adds \texttt{value} before the
            first element of the list.
        \item \index{rbegin}\texttt{list::reverse\_iterator rbegin()}:\ \\  returns a
            reverse\_iterator pointing to the last element in the list.
        \item \index{remove}\texttt{void remove(value)}:\ \\ removes all occurrences of \texttt{value}
            from the list. In the following example, the two strings
            `\texttt{Hello}' are removed from the list \texttt{object}:
           \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <list>
    using namespace std;

    int main()
    {
        list<string> object;

        object.push_back("Hello"s);
        object.push_back("World"s);
        object.push_back("Hello"s);
        object.push_back("World"s);

        object.remove("Hello"s);

        while (object.size())
        {
            cout << object.front() << '\n';
            object.pop_front();
        }
    }
    /*
            Generated output:
        World
        World
    */
\end{verbatim}
        \item \index{remove\_if}\texttt{void remove\_if(Predicate pred)}:\ \\ removes all
            occurrences from the list for which the predicate function or
            function object \texttt{pred} returns \texttt{true}. For each of the objects
            stored in the list the predicate is called as \texttt{pred($*$iter)},
            where \texttt{iter} represents the iterator used internally by
            \texttt{remove\_if}. If a function \texttt{pred} is used, its prototype
            should be \texttt{bool pred(value\_type const \&object)}.
        \item \index{rend}\texttt{list::reverse\_iterator rend()}:\ \\ this member returns a
            reverse\_iterator pointing before the first element in the list.
        \item \index{resize}\texttt{void resize()}:\ \\ alters the number of elements that are
            currently stored in the list: \begin{itemize} \item \texttt{resize(n, value)}
            may be used to resize the list to a size of \texttt{n}. \texttt{Value} is
            optional. If the list is expanded and \texttt{value} is not provided,
            the extra elements are initialized to the \index{default value}default value of the
            used data type, otherwise \texttt{value} is used to initialize extra
            elements.\end{itemize}
        \item \index{reverse}\texttt{void reverse()}:\ \\ reverses the order of the elements in
            the list. The element \texttt{back} becomes \texttt{front} and \emph{vice
            versa}.
        \item \index{size}\texttt{size\_t size()}:\ \\ returns the number of elements in the
            list.
        \item \index{sort}\texttt{void sort()}:\ \\ sorts the list. An example of its use is
            given at the description of the \texttt{unique} member function
            below. \texttt{list$<$Type$>$::sort} uses \texttt{Type::operator$<$} to sort the
            data in the list, which must therefore be available.
        \item \index{splice}\texttt{void splice(pos, object)}:\ \\ transfers the content of
            \texttt{object} to the current list, starting the insertion at the
            iterator position \texttt{pos} of the object using the \texttt{splice}
            member. Following \texttt{splice}, \texttt{object} is empty. For example:
         \begin{verbatim}
#include <iostream>
#include <string>
#include <list>
using namespace std;

int main()
{
    list<string> object;

    object.push_front("Hello"s);
    object.push_back("World"s);

    list<string> argument(object);

    object.splice(++object.begin(), argument);

    cout << "Object contains " << object.size() << " elements, " <<
            "Argument contains " << argument.size() <<
            " elements,\n";

    while (object.size())
    {
        cout << object.front() << '\n';
        object.pop_front();
    }
}
\end{verbatim}
           Alternatively, \texttt{argument} may be followed by an iterator of
            \texttt{argument}, indicating the first element of \texttt{argument} that
            should be spliced, or by two iterators \texttt{begin} and \texttt{end}
            defining the iterator-range \texttt{[begin, end)} on \texttt{argument}
            that should be spliced into \texttt{object}.
        \item \index{swap}\texttt{void swap()}:\ \\ swaps two lists using identical data types.
        \item \index{unique}\texttt{void unique()}:\ \\ operating on a sorted list, this member
            function removes all consecutively identical elements from the
            list. \texttt{list$<$Type$>$::unique} uses \texttt{Type::operator==} to identify
            identical data elements, which operator must therefore be
            available.  Here's an example removing all multiply occurring
            words from the list: \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <list>
    using namespace std;
                            // see the merge() example
    void showlist(list<string> &target)
    {
        for
        (
            list<string>::iterator from = target.begin();
            from != target.end();
            ++from
        )
            cout << *from << " ";

        cout << '\n';
    }


    int main()
    {
        string
            array[] =
            {
                "charlie",
                "alpha",
                "bravo",
                "alpha"
            };

        list<string>
            target
            (
                array, array + sizeof(array)
                / sizeof(string)
            );

        cout << "Initially we have:\n";
        showlist(target);

        target.sort();
        cout << "After sort() we have:\n";
        showlist(target);

        target.unique();
        cout << "After unique() we have:\n";
        showlist(target);
    }
    /*
        Generated output:

        Initially we have:
        charlie alpha bravo alpha
        After sort() we have:
        alpha alpha bravo charlie
        After unique() we have:
        alpha bravo charlie
    */
\end{verbatim}
        \end{itemize}
\end{itemize}

\subsection{The `queue' container}\label{QUEUE}
    \typeout{Original Yodl file: containers/queue}The \index{queue}\texttt{queue} class implements a \index{queue data structure}queue data structure.  Before using a
\texttt{queue} container the header file \index{queue: header file}\texttt{$<$queue$>$} must be included.

A queue is depicted in figure \ref{queueFig}.
        \begin{figure}[tbp]
\centerline{\epsffile{containers/queue.eps}}
\caption{\label{queueFig}A queue data-structure}
\end{figure}
    In figure \ref{queueFig} it is shown that a queue has one point (the
\emph{back}) where items can be added to the queue, and one point (the \emph{front})
where items can be removed (read) from the queue. A \texttt{queue} is therefore
also called a \index{FIFO}\emph{FIFO} data structure, for \index{first in, first out}\emph{first in, first out}. It is
most often used in situations where events should be handled in the same order
as they are generated.

The following constructors, operators, and member functions are available
for the \texttt{queue} container:
    \begin{itemize}
    \item  \index{queue} Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  A \texttt{queue} may be constructed empty:
        \begin{verbatim}
    queue<string> object;
\end{verbatim}
As with the \texttt{vector}, it is an error to refer to an element of an
empty queue.
    \end{itemize}
    \item  The \texttt{queue} container only supports the basic container operators.
    \item  The following \index{member function}member functions are available for
queues:
        \begin{itemize}
        \item \index{back}\texttt{Type \&back()}:\ \\ returns a
reference to the last element in the queue. It is the
    \index{responsibility of the programmer}responsibility of the programmer to use the member only if the queue is
not empty.

\item \index{emplace}\texttt{value\_type \&emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
            arguments, and the newly created element is inserted beyond the
            end of the queue, returning a reference to (or copy of) the newly
            added element. 
        \item \index{empty}\texttt{bool empty()}:\ \\ returns
\texttt{true} if the queue contains no elements.
        \item \index{front}\texttt{Type \&front()}:\ \\ returns a
reference to the first element in the queue. It is the responsibility of the
programmer to use the member only if the queue is not empty.
        
        \item \index{pop}\texttt{void pop()}:\ \\ removes the element at the front of
the queue. Note that the element is \emph{not} returned by this member. 
Avoid calling this member on an empty queue: although nothing is returned its
internally maintained count of number of available elements is reduced,
causing the queue's \texttt{size()} member to return the (when cast to \texttt{int})
value -1, and then -2, etc., etc.  One might wonder why
\texttt{pop} returns \texttt{void}, instead of a value of type \texttt{Type}
(cf. \texttt{front}). One reason is found in the principles of good software
design: functions should perform one task. Combining the removal and return of
the removed element breaks this principle. Moreover, when this principle is
abandoned \texttt{pop}'s implementation is always flawed. Consider the
prototypical implementation of a \texttt{pop} member that is expected to return the
queue's front-value:
    \begin{verbatim}
        Type queue::pop()
        {
            Type ret{ front() };
            erase_front();
            return ret;
        }
\end{verbatim}
   Since \texttt{queue} has no control over \texttt{Type}'s behavior the first statement
(\texttt{Type ret\{ front() \}}) might throw. Although this still supports the
'commit or roll-back' principle, \texttt{queue} cannot guarantee that \texttt{Type}
offers copy-construction. Hence, \texttt{pop} does not return the queue's
front-value, but simply erases that element: 
    \begin{verbatim}
        Type queue::pop()
        {
            erase_front();
        }
\end{verbatim}
    Note that \texttt{push} doesn't require copy construction: \texttt{push} can also be
implemented when move-construction is supported. E.g.,
    \begin{verbatim}
        void queue::push(Type &&tmp)
        {
            d_data.push_back(std::move(tmp));   // uses move construction
        }
\end{verbatim}
    Because of all this, we must first use \texttt{front} and then \texttt{pop} to
obtain and remove the queue's front element.
        \item \index{push}\texttt{void push(value)}:\ \\ this member
adds \texttt{value} to the back of the queue.
        \item \index{size}\texttt{size\_t size()}:\ \\ returns the
number of elements in the queue.
        \end{itemize}
    \end{itemize}
    Note that the queue does not support iterators or an index operator. The
only elements that can be accessed are its front and back element.  A queue
can be emptied by:
    \begin{itemize}
    \item  repeatedly removing its front element;
    \item  assigning an empty queue using the same data type to it;
    \item  having its destructor called.
    \end{itemize}

\subsection{The `priority\_queue' container}\label{PRIQUEUE}
    \typeout{Original Yodl file: containers/priority}The \index{priority\_queue}\texttt{priority\_queue} class implements a \index{priority queue data structure}priority queue data structure.
Before using a \texttt{priority\_queue} container the \index{queue: header file}\texttt{$<$queue$>$} header file must
have been included.

A priority queue is identical to a \texttt{queue}, but allows the entry of data
elements according to \index{priority rules}\emph{priority rules}. A real-life priority queue is
found, e.g., at airport check-in terminals. At a terminal the passengers
normally stand in line to wait for their turn to check in, but late passengers
are usually allowed to jump the queue: they receive a higher priority than
other passengers.

The priority queue uses \texttt{operator$<$} of the data type stored in the
priority queue to decide about the priority of the data elements. The
\emph{smaller} the value, the \emph{lower} the priority. So, the priority queue
\emph{could} be used to sort values while they arrive.  A simple example of such
a priority queue application is the following program: it reads words from
\texttt{cin} and writes a sorted list of words to \texttt{cout}:
        \begin{verbatim}
#include <iostream>
#include <string>
#include <queue>
using namespace std;

int main()
{
    priority_queue<string> q;
    string word;

    while (cin >> word)
        q.push(word);

    while (q.size())
    {
        cout << q.top() << '\n';
        q.pop();
    }
}
\end{verbatim}
Unfortunately, the words are listed in reversed order: because of the
underlying \texttt{$<$}-operator the words appearing later in the \index{ASCII}ASCII-sequence
appear first in the priority queue. A solution to that problem is to define a
\emph{wrapper class} around the \texttt{string} datatype, reversing \texttt{string}'s
\texttt{operator$<$}. Here is the modified program:
        \begin{verbatim}
#include <iostream>
#include <string>
#include <queue>

class Text
{
    std::string d_s;

    public:
        Text(std::string const &str)
        :
            d_s(str)
        {}
        operator std::string const &() const
        {
            return d_s;
        }
        bool operator<(Text const &right) const
        {
            return d_s > right.d_s;
        }
};

using namespace std;

int main()
{
    priority_queue<Text> q;
    string word;

    while (cin >> word)
        q.push(word);

    while (q.size())
    {
        word = q.top();
        cout << word << '\n';
        q.pop();
    }
}
\end{verbatim}
Other possibilities to achieve the same exist. One would be to store the
content of the priority queue in, e.g., a vector, from which the elements can
be read in reversed order.

The following constructors, operators, and member functions are available
for the \texttt{priority\_queue} container:
    \begin{itemize}
    \item  \index{priority\_queue} Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  A \texttt{priority\_queue} may be constructed empty:
    \begin{verbatim}
priority_queue<string> object;
\end{verbatim}
        \end{itemize}

\item  The \texttt{priority\_queue} only supports the basic operators of
containers.
    \item  The following \index{member functions}member functions are available for priority queues:
        \begin{itemize}
        \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if the
priority queue contains no elements.
        \item \index{pop}\texttt{void pop()}:\ \\ removes the element at the top of the priority
queue. Note that the element is \emph{not} returned by this member. As with the
\texttt{queue} avoid calling this member on an empty priority queue (cf. section
\ref{QUEUE}.)
        \item \index{push}\texttt{void push(value)}:\ \\ inserts \texttt{value} at the
appropriate position in the priority queue.
        \item \index{size}\texttt{size\_t size()}:\ \\ returns the number of elements
in the priority queue.
        \item \index{top}\texttt{Type \&top()}:\ \\ returns a reference to the first
element of the priority queue. It is the
    responsibility of the programmer to use the member only if the priority
queue is not empty.
        \end{itemize}
    \end{itemize}

Note that the priority queue does not support iterators or an index
operator. The only element that can be accessed is its top element.  A
priority queue can be emptied by:
    \begin{itemize}
    \item  repeatedly removing its top element;
    \item  assigning an empty queue using the same data type to it;
    \item  having its destructor called.
    \end{itemize}

\subsection{The `deque' container}
    \typeout{Original Yodl file: containers/deque}The \index{deque}\texttt{deque} (pronounce: `deck') class implements a
    \index{doubly ended queue}doubly ended queue data structure (deque).  Before using a \texttt{deque}
container the header file \index{deque: header file}\texttt{$<$deque$>$} must be included.

A \texttt{deque} is comparable to a queue, but it allows for reading and
writing at both ends. Actually, the \texttt{deque} data type supports a lot more
functionality than the \texttt{queue}, as illustrated by the following overview of
available member functions. A \texttt{deque} is a combination of a \texttt{vector} and
two queues, operating at both ends of the vector. In situations where random
insertions and the addition and/or removal of elements at one or both sides of
the vector occurs frequently using a \texttt{deque} should be considered.

The following constructors, operators, and member functions are available for
deques:
    \begin{itemize}
    \item  \index{deque constructors} Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  A \texttt{deque} may be constructed empty:
    \begin{verbatim}
deque<string> object;
\end{verbatim}
As with the \texttt{vector}, it is an error to refer to an element of an
empty deque.
        \item  A deque may be initialized to  a certain number of
elements. By default, if the initialization value is not explicitly mentioned,
the default value or default constructor for the actual data type is used. For
example:
    \begin{verbatim}
deque<string> object(5, "Hello"s), // initialize to 5 Hello's
deque<string> container(10);       // and to 10 empty strings
\end{verbatim}
\item  A deque may be initialized using two iterators. To
initialize a deque with elements 5 until 10 (including the last one) of a
\texttt{vector$<$string$>$} the following construction may be used:
    \begin{verbatim}
extern vector<string> container;
deque<string> object(&container[5], &container[11]);
\end{verbatim}
\end{itemize}
    \item  In addition to the standard operators for containers, the deque
supports the index operator, which may be used to retrieve or reassign
random elements of the deque. Note that the indexed elements must exist.
    \item  The following member functions are available for deques:
        \begin{itemize}
        \item \index{assign}\texttt{void assign(...)}:
            \begin{quote}assigns new content to the deque:\end{quote}
            \begin{itemize}
            \item \texttt{assign(iterator begin, iterator end)} assigns the values at
the iterator range \texttt{[begin, end)} to the deque;
            \item \texttt{assign(size\_type n, value\_type const \&val)} assigns \texttt{n}
copies of \texttt{val} to the deque;
            \end{itemize}

\item \index{at}\texttt{Type \&at(size\_t idx)}:
            \begin{quote}returns a reference to the deque's element at index position
\texttt{idx}. If \texttt{idx} exceeds the deque's size a \texttt{std::out\_of\_range} exception
is thrown.\end{quote}
        \item \index{back}\texttt{Type \&back()}:\ \\ returns a
reference to the last element in the deque. It is the
    \index{responsibility of the programmer}responsibility of the programmer to use the member only if the deque is
not empty.
        \item \index{begin}\texttt{deque::iterator begin()}:\ \\ returns an iterator pointing
to the first element in the deque. 
        \item \index{cbegin}\texttt{deque::const\_iterator cbegin()}:
            \begin{quote}returns a const\_iterator pointing to the first
element in the deque, returning \texttt{cend} if the deque is empty.\end{quote}
        \item \index{cend}\texttt{deque::const\_iterator cend()}:
            \begin{quote}returns a const\_iterator pointing just beyond the
deque's last element.\end{quote}
        \item \index{clear}\texttt{void clear()}:\ \\ erases all
elements in the deque.
        \item \index{crbegin}\texttt{deque::const\_reverse\_iterator crbegin()}:
            \begin{quote}returns a const\_reverse\_iterator pointing to the last
element in the deque, returning \texttt{crend} if the deque is empty.\end{quote}
        \item \index{crend}\texttt{deque::const\_reverse\_iterator crend()}:
            \begin{quote}returns a const\_reverse\_iterator pointing just before the
deque's first element.\end{quote}
        \item \index{emplace}\texttt{iterator emplace(const\_iterator position, Args \&\&...args)}
            \begin{quote}a \texttt{value\_type} object is constructed from the arguments
specified after \texttt{position}, and the newly created element is inserted at
\texttt{position}.\end{quote}
        \item \index{emplace\_back}\texttt{void emplace\_back(Args \&\&...args)}
            \begin{quote}a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted beyond the deque's last
element.\end{quote}
        \item \index{emplace\_front}\texttt{void emplace\_front(Args \&\&...args)}
            \begin{quote}a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted before the deque's first
element.\end{quote}
        \item \index{empty}\texttt{bool empty()}:\ \\ returns
\texttt{true} if the deque contains no elements.
        \item \index{end}\texttt{deque::iterator end()}:\ \\ returns an iterator pointing beyond
the last element in the deque. 
        \item \index{erase}\texttt{deque::iterator erase()}:\ \\ the member can
be used to erase a specific range of elements in the deque:
            \begin{itemize}
            \item \texttt{erase(pos)} erases the element pointed to by \texttt{pos}. The
iterator \texttt{++pos} is returned.
            \item \texttt{erase(first, beyond)} erases elements indicated by the iterator
range \texttt{[first, beyond)}. \texttt{Beyond} is returned.
            \end{itemize}
        \item \index{front}\texttt{Type \&front()}:\ \\ returns a
reference to the first element in the deque. It is the responsibility of the
programmer to use the member only if the deque is not empty.
        \item \index{get\_allocator}\texttt{allocator\_type get\_allocator() const}:\ \\ returns a
copy of the allocator object used by the \texttt{deque} object.

\item \index{insert}\texttt{... insert()}:\ \\ inserts elements starting at a certain
position. The return value depends on the version of \texttt{insert} that is
called:
            \begin{itemize}
            \item \texttt{deque::iterator insert(pos)} inserts a default value of type
\texttt{Type} at \texttt{pos}, \texttt{pos} is returned.
            \item \texttt{deque::iterator insert(pos, value)} inserts \texttt{value} at
\texttt{pos}, \texttt{pos} is returned.
            \item \texttt{void insert(pos, first, beyond)} inserts the elements in the
                iterator range \texttt{[first, beyond)}.
            \item \texttt{void insert(pos, n, value)} inserts \texttt{n} elements having value
\texttt{value} starting at iterator position \texttt{pos}.
            \end{itemize}
        \item \index{max\_size}\texttt{size\_t max\_size()}:\ \\ returns the maximum number of
elements this \texttt{deque} may contain.
        \item \index{pop\_back}\texttt{void pop\_back()}:\ \\ removes the last element from the
deque. Avoid calling this member on an empty deque: although nothing is
returned its internally maintained count of number of available elements is
reduced, causing the deque's \texttt{size()} member to return the (when cast to
\texttt{int}) value -1, and then -2, etc., etc.
        \item \index{pop\_front}\texttt{void pop\_front()}:\ \\ removes the first element from the
deque. Avoid calling this member on an empty deque: as with \texttt{pop\_back()} its
internally maintained count of number of available elements is reduced
        \item \index{push\_back}\texttt{void push\_back(value)}:\ \\ adds \texttt{value} to the end of
the deque.
        \item \index{push\_front}\texttt{void push\_front(value)}:\ \\ adds \texttt{value} before the
first element of the deque.
        \item \index{rbegin}\texttt{deque::reverse\_iterator rbegin()}:\ \\ 
            returns a reverse\_iterator pointing to the last element in the
deque.
        \item \index{rend}\texttt{deque::reverse\_iterator rend()}:\ \\ this member returns a
reverse\_iterator pointing before the first element in the deque.
        \item \index{resize}\texttt{void resize()}:\ \\ alters the number of elements that are
currently stored in the deque:
            \begin{itemize}
            \item \texttt{resize(n, value)} may be used to resize the deque to a size of
\texttt{n}. \texttt{Value} is optional. If the deque is expanded and \texttt{value} is not
provided, the additional elements are initialized to the default value of the
used data type, otherwise \texttt{value} is used to initialize extra elements.
            \end{itemize}
        \item \index{shrink\_to\_fit}\texttt{void shrink\_to\_fit()}:\ \\ optionally reduces the
amount of memory allocated by a deque to its current size. The implementor is
free to ignore or otherwise optimize this request. In order to guarantee a
`shrink to fit' operation \texttt{deque$<$Type$>$(dequeObject).swap(dequeObject)} idiom
can be used.
        \item \index{size}\texttt{size\_t size()}:\ \\ returns the
number of elements in the deque.
        \item \index{swap}\texttt{void swap(argument)}:\ \\ swaps two deques using identical data
types.

\end{itemize}
\end{itemize}

\subsection{The `map' container}\label{MAP}
    \typeout{Original Yodl file: containers/map}The \index{map}\texttt{map} class offers a (sorted) \index{associative array}associative array. Before using a
\texttt{map} container the \index{map: header file}\texttt{$<$map$>$} header file must be included.

A \texttt{map} is filled with \index{key, value}\emph{key, value} pairs, which may be of any
container-accepted type. Since types are associated with both the key and the
value, we must specify \emph{two types} in the angle bracket notation, comparable
to the specification we've seen with the \texttt{pair} container (cf. section
\ref{PAIR}). The first type represents the key's type, the second type
represents the value's type. The \index{key}\emph{key} is used to access its associated
information. The \texttt{map} sorts the keys using their \texttt{operator$<$}, where the
smallest key values appears as first element in the map.  For example, a
\texttt{map} in which the key is a \texttt{string} and the value is a \texttt{double} can be
defined as follows:
        \begin{verbatim}
    map<string, double> object;
\end{verbatim}
That information is called the \index{value}\emph{value}. For example, a phone book uses the
names of people as the key, and uses the telephone number and maybe other
information (e.g., the zip-code, the address, the profession) as value. Since
a \texttt{map} sorts its keys, the \texttt{key}'s \index{operator\textless{}}\texttt{operator$<$} must be defined, and it
must be sensible to use it. For example, it is generally a bad idea to use
pointers for keys, as sorting pointers is something different than sorting the
values pointed at by those pointers. In addition to the \emph{key, value} types,
a third type defines the comparison class, used to compare two keys. By
default, the comparison class is \texttt{std::less$<$KeyType$>$} (cf. section
\ref{RELATIONAL}), using the key type's \texttt{operator$<$} to compare two key
values. For key type \texttt{KeyType} and value type \texttt{ValueType} the map's type
definition, therefore, looks like this:
        \begin{verbatim}
    map<KeyType, ValueType, std::less<KeyType>>
\end{verbatim}
The two fundamental operations on maps are the storage of \emph{key, value}
combinations, and the retrieval of values, given their keys. The index
operator using a key as the index, can be used for both. If the index operator
is used as \emph{lvalue}, the expression's \texttt{rvalue} is inserted into the
map. If it is used as \emph{rvalue}, the key's associated value is retrieved.
Each key can be stored only once in a \texttt{map}. If the same key is entered
again, the new value replaces the formerly stored value, which is lost.

A specific \emph{key, value} combination can implicitly or explicitly be inserted
into a \texttt{map}. If explicit insertion is required, the \emph{key, value}
combination must be constructed first. For this, every \texttt{map} defines a
\index{value\_type}\texttt{value\_type} which may be used to create values that can be stored in the
\texttt{map}. For example, a value for a \texttt{map$<$string, int$>$} can be constructed as
follows:
        \begin{verbatim}
    map<string, int>::value_type siValue{ "Hello", 1 };
\end{verbatim}
The \texttt{value\_type} is associated with the \texttt{map$<$string, int$>$}: the
type of the key is \texttt{string}, the type of the value is \texttt{int}. Anonymous
\texttt{value\_type} objects are also often used. E.g.,
        \begin{verbatim}
    map<string, int>::value_type{ "Hello", 1 };
\end{verbatim}
Instead of using the line \texttt{map$<$string, int$>$::value\_type(...)} over and
over again, a using declaration is frequently used to reduce typing and to
improve readability:
        \begin{verbatim}
    using StringIntValue = map<string, int>::value_type;
\end{verbatim}
Now values for the \texttt{map$<$string, int$>$} may be specified this way:
        \begin{verbatim}
    StringIntValue{ "Hello", 1 };
\end{verbatim}
Alternatively, \texttt{pairs} may be used to represent \emph{key, value}
combinations used by maps:
        \begin{verbatim}
    pair<string, int>{ "Hello", 1 };
\end{verbatim}
\subsubsection{The `map' constructors}
        \typeout{Original Yodl file: containers/mapconstructors}    The following \index{map constructors} constructors are available for the
\texttt{map} container:
    \begin{itemize}
    \item  The copy and move constructors are available;
    \item  A \texttt{map} may be constructed empty:
    \begin{verbatim}
map<string, int> object;
\end{verbatim}
Note that the values stored in maps may be containers themselves. For
example, the following defines a \texttt{map} in which the value is a \texttt{pair}: a
container
 \index{nested container} \index{container: nested} nested under another container:
        \begin{verbatim}
    map<string, pair<string, string>> object;
\end{verbatim}
Note the use of the two
 \index{\textgreater{}\textgreater{}: with templates}\index{angle brackets: consecutive}
 \index{consecutive closing angle brackets}consecutive closing angle brackets, which does not result in ambiguities
as their syntactical context differs from their use as binary operators in
expressions.
    \item  A map may be initialized using two iterators.  The iterators may
either point to \texttt{value\_type} values for the map to be constructed, or to
plain \index{pair}\texttt{pair} objects. If pairs are used, their \texttt{first} element represents
the type of the keys, and their \texttt{second} element represents the type of the
values. Example:
    \begin{verbatim}
pair<string, int> pa[] =
{
    pair<string,int>("one", 1),
    pair<string,int>("two", 2),
    pair<string,int>("three", 3),
};

map<string, int> object(&pa[0], &pa[3]);
\end{verbatim}
In this example, \texttt{map$<$string, int$>$::value\_type} could have been written
instead of \texttt{pair$<$string, int$>$} as well.

If \texttt{begin} represents the first iterator that is used to construct a map
and if \texttt{end} represents the second iterator, \texttt{[begin, end)} will be
used to initialize the map. Maybe contrary to intuition, the \texttt{map}
constructor only enters \emph{new} keys.  If the last element of \texttt{pa} would
have been \texttt{"one", 3}, only \emph{two} elements would have entered the \texttt{map}:
\texttt{"one", 1} and \texttt{"two", 2}. The value \texttt{"one", 3} would silently have been
ignored.

The \texttt{map} receives its own copies of the data to which the iterators
point as illustrated by the following example:
        \begin{verbatim}
    #include <iostream>
    #include <map>
    using namespace std;

    class MyClass
    {
        public:
            MyClass()
            {
                cout << "MyClass constructor\n";
            }
            MyClass(MyClass const &other)
            {
                cout << "MyClass copy constructor\n";
            }
            ~MyClass()
            {
                cout << "MyClass destructor\n";
            }
    };

    int main()
    {
        pair<string, MyClass> pairs[] =
        {
            pair<string, MyClass>{ "one", MyClass{} }
        };
        cout << "pairs constructed\n";

        map<string, MyClass> mapsm{ &pairs[0], &pairs[1] };
        cout << "mapsm constructed\n";
    }
    /*
        Generated output:
    MyClass constructor
    MyClass copy constructor
    MyClass destructor
    pairs constructed
    MyClass copy constructor
    mapsm constructed
    MyClass destructor
    MyClass destructor
    */
\end{verbatim}
When tracing the output of this program, we see that, first, the
constructor of a \texttt{MyClass} object is called to initialize the anonymous
element of the array \texttt{pairs}. This object is then copied into the first
element of the array \texttt{pairs} by the copy constructor. Next, the original
element is not required anymore and is destroyed. At that point the array
\texttt{pairs} has been constructed. Thereupon, the \texttt{map} constructs a temporary
\texttt{pair} object, which is used to construct the map element. Having
constructed the map element, the temporary \texttt{pair} object is
destroyed. Eventually, when the program terminates, the \texttt{pair} element
stored in the \texttt{map} is destroyed too.
    \end{itemize}

\subsubsection{The `map' operators}
        \typeout{Original Yodl file: containers/mapoperators}    The map supports, in addition to the standard operators for containers,
the \index{index operator}index operator.

The index operator may be used to retrieve or reassign individual elements of
the map. The argument of the index operator is called a \emph{key}.

If the provided key is not available in the \texttt{map}, a new data element is
automatically added to the \texttt{map} using the default value or default
constructor to initialize the value part of the new element. This default
value is returned if the index operator is used as an rvalue.

When initializing a new or reassigning another element of the map, the type of
the right-hand side of the assignment operator must be equal to (or promotable
to) the type of the map's value part. E.g., to add or change the value of
element \texttt{"two"} in a map, the following statement can be used:
        \begin{verbatim}
    mapsm["two"] = MyClass{};
\end{verbatim}
\subsubsection{The `map' public members}
        \typeout{Original Yodl file: containers/mapmembers}The following member functions are available for the \texttt{map} container:
    \begin{itemize}
        \item \index{at}\texttt{mapped\_type \&at(key\_type const \&key)}:\ \\ returns a reference to the map's \texttt{mapped\_type}
associated with \texttt{key}. If the key is not stored in the \texttt{map} an
\texttt{std::out\_of\_range} exception is thrown.
    \item \index{begin}\texttt{map::iterator begin()}:\ \\ returns an iterator pointing to the
first element of the map. 
        \item \index{cbegin}\texttt{map::const\_iterator cbegin()}:\ \\ returns a const\_iterator pointing to the first
element in the map, returning \texttt{cend} if the map is empty.
        \item \index{cend}\texttt{map::const\_iterator cend()}:\ \\ returns a const\_iterator pointing just beyond the
map's last element.
    \item \index{clear}\texttt{void clear()}:\ \\ erases all elements from
the map.
    \item \index{count}\texttt{size\_t count(key)}:\ \\ returns 1 if
the provided key is available in the \texttt{map}, otherwise 0 is returned.
    \item \index{crbegin}\texttt{map::reverse\_iterator crbegin() const}:\ \\ 
    reverse\_iterator returns a reverse\_iterator pointing to the last
element of the map.
    \item \index{rend}\texttt{map::reverse\_iterator crend()}:\ \\ returns an iterator pointing
before the first element of the map.
        \item \index{emplace}\texttt{pair$<$iterator, bool$>$ emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from \texttt{emplace}'s
arguments. If the \texttt{map} already contained an object using the same
\texttt{key\_type} value, then a \texttt{std::pair} is returned containing an iterator
pointing to the object using the same \texttt{key\_type} value and the value
\texttt{false}. If no such \texttt{key\_type} value was found, the newly constructed
object is inserted into the \texttt{map}, and the returned \texttt{std::pair}
contains an iterator pointing to the newly inserted \texttt{value\_type}
as well as the value \texttt{true}.
        \item \index{emplace\_hint}\texttt{iterator emplace\_hint(const\_iterator position,
                            Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted into the
\texttt{map}, unless the (at \texttt{args}) provided key already exists. The
implementation may or may not use \texttt{position} as a \emph{hint} to start looking
for an insertion point. The returned \texttt{iterator} points to the \texttt{value\_type}
using the provided key. It may refer to an already existing \texttt{value\_type} or
to a newly added \texttt{value\_type}; an existing \texttt{value\_type} is not
replaced. If a new value \emph{was} added, then the container's size has been
incremented when \texttt{emplace\_hint} returns.
    \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if
the map contains no elements.
    \item \index{end}\texttt{map::iterator end()}:\ \\ returns an iterator pointing beyond the
last element of the map.
    \item \index{equal\_range}\texttt{pair$<$map::iterator, map::iterator$>$ equal\_range(key)}:\ \\ this
member returns a pair of iterators, being respectively the return values of
the member functions \texttt{lower\_bound} and \texttt{upper\_bound}, introduced below.
An example illustrating these member functions is given at the
discussion of the member function \texttt{upper\_bound}.
    \item \index{erase}\texttt{... erase()}:\ \\ erases a specific element or range of elements
from the map:
        \begin{itemize}
        \item \texttt{bool erase(key)} erases the element having the
given \texttt{key} from the \texttt{map}. \texttt{True} is returned if the value was removed,
\texttt{false} if the map did not contain an element using the given \texttt{key}.
        \item \texttt{void erase(pos)} erases the element pointed to by the iterator
\texttt{pos}.
        \item \texttt{void erase(first, beyond)} erases all elements indicated by
the iterator range \texttt{[first, beyond)}.
        \end{itemize}

\item \index{find}\texttt{map::iterator find(key)}:\ \\ returns
an iterator to the element having the given key. If the element isn't
available, \texttt{end} is returned. The following example illustrates the use of
the \texttt{find} member function:
        \begin{verbatim}
    #include <iostream>
    #include <map>
    using namespace std;

    int main()
    {
        map<string, int> object;

        object["one"] = 1;

        map<string, int>::iterator it = object.find("one");

        cout << "`one' " <<
                (it == object.end() ? "not " : "") << "found\n";

        it = object.find("three");

        cout << "`three' " <<
                (it == object.end() ? "not " : "") << "found\n";
    }
    /*
        Generated output:
    `one' found
    `three' not found
    */
\end{verbatim}
        \item \index{get\_allocator}\texttt{allocator\_type get\_allocator() const}:\ \\ returns a
copy of the allocator object used by the \texttt{map} object.
    \item \index{insert}\texttt{... insert()}:\ \\ inserts elements into the map. Values
associated with already existing keys, however, are not replaced by new
values. Its return value depends on the version of \texttt{insert} that is called:
        \begin{itemize}
        \item \texttt{pair$<$map::iterator, bool$>$ insert(keyvalue)} inserts
a new \texttt{value\_type} into the map. The return value is a
\index{pair\textless{}map::iterator, bool\textgreater{}}\texttt{pair$<$map::iterator, bool$>$}.  If the returned \index{bool}\texttt{bool} field is \texttt{true},
\texttt{keyvalue} was inserted into the map. The value \texttt{false} indicates that the
key that was specified in \texttt{keyvalue} was already available in the map, and
so \texttt{keyvalue} was not inserted into the map.  In both cases the
\texttt{map::iterator} field points to the data element having the
\texttt{key} that was specified in \texttt{keyvalue}. The use of this variant of
\texttt{insert} is illustrated by the following example:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <map>
    using namespace std;

    int main()
    {
        pair<string, int> pa[] =
        {
            pair<string,int>("one", 10),
            pair<string,int>("two", 20),
            pair<string,int>("three", 30),
        };
        map<string, int> object(&pa[0], &pa[3]);

                // {four, 40} and `true' is returned
        pair<map<string, int>::iterator, bool>
            ret = object.insert
                    (
                        map<string, int>::value_type
                        ("four", 40)
                    );

        cout << boolalpha;

        cout << ret.first->first << " " <<
            ret.first->second << " " <<
            ret.second << " " << object["four"] << '\n';

                // {four, 40} and `false' is returned
        ret = object.insert
                    (
                        map<string, int>::value_type
                        ("four", 0)
                    );

        cout << ret.first->first << " " <<
            ret.first->second << " " <<
            ret.second << " " << object["four"] << '\n';
    }
    /*
        Generated output:

        four 40 true 40
        four 40 false 40
    */
\end{verbatim}
    Note the somewhat peculiar constructions like
        \begin{verbatim}
    cout << ret.first->first << " " << ret.first->second << ...
\end{verbatim}
Note that `\texttt{ret}' is equal to the \texttt{pair} returned by the
\texttt{insert} member function. Its `\texttt{first}' field is an iterator into the
\texttt{map$<$string, int$>$}, so it can be considered a pointer to a \texttt{map$<$string,
int$>$::value\_type}. These value types themselves are pairs too, having
`\texttt{first}' and `\texttt{second}' fields. Consequently, `\texttt{ret.first-$>$first}' is
the \emph{key} of the map value (a \texttt{string}), and `\texttt{ret.first-$>$second}' is
the \emph{value} (an \texttt{int}).
        \item \texttt{map::iterator insert(pos, keyvalue)}. This way a
\texttt{map::value\_type} may also be inserted into the map. \texttt{pos} is ignored, and
an iterator to the inserted element is returned.
        \item \texttt{void insert(first, beyond)} inserts the (\texttt{map::value\_type})
elements pointed to by the iterator range \texttt{[first, beyond)}. Values that
were already present are not replaced.
        \end{itemize}

\item \index{key\_comp}\texttt{key\_compare key\_comp()}:\ \\ returns a copy of the object used by the \texttt{map} to compare keys. The
        type \texttt{map$<$KeyType, ValueType$>$::key\_compare} is defined by the map
        container and \texttt{key\_compare}'s parameters have types \texttt{KeyType const
        \&}. The comparison function returns \texttt{true} if the first key
        argument should be ordered before the second key argument. To compare
        keys \emph{and} values, use \texttt{value\_comp}, listed below.
    \item \index{lower\_bound}\texttt{map::iterator lower\_bound(key)}:\ \\ returns an iterator pointing to the first
\texttt{keyvalue} element of which the \texttt{key} is at least equal to the specified
\texttt{key}.  If no such element exists, the function returns \texttt{end}.
    \item \index{max\_size}\texttt{size\_t max\_size()}:\ \\ returns the maximum number of
elements this \texttt{map} may contain.
    \item \index{rbegin}\texttt{map::reverse\_iterator rbegin()}:\ \\ 
    returns a reverse\_iterator pointing to the last element of the map.
    \item \index{rend}\texttt{map::reverse\_iterator rend()}:\ \\ returns an iterator pointing
before the first element of the map.
    \item \index{size}\texttt{size\_t size()}:\ \\ returns the
number of elements in the map.
    \item \index{swap}\texttt{void swap(argument)}:\ \\ swaps two maps using identical key/value
types.
    \item \index{upper\_bound}\texttt{map::iterator upper\_bound(key)}:\ \\ returns an iterator pointing to the first
\texttt{keyvalue} element having a \texttt{key} exceeding the specified \texttt{key}.  If no
such element exists, the function returns \texttt{end}.  The following
example illustrates the member functions \texttt{equal\_range}, \texttt{lower\_bound}
and \texttt{upper\_bound}:
        \begin{verbatim}
    #include <iostream>
    #include <map>
    using namespace std;

    int main()
    {
        pair<string, int> pa[] =
        {
            pair<string,int>("one", 10),
            pair<string,int>("two", 20),
            pair<string,int>("three", 30),
        };
        map<string, int> object(&pa[0], &pa[3]);
        map<string, int>::iterator it;

        if ((it = object.lower_bound("tw")) != object.end())
            cout << "lower-bound `tw' is available, it is: " <<
                    it->first << '\n';

        if (object.lower_bound("twoo") == object.end())
            cout << "lower-bound `twoo' not available" << '\n';

        cout << "lower-bound two: " <<
                object.lower_bound("two")->first <<
                " is available\n";

        if ((it = object.upper_bound("tw")) != object.end())
            cout << "upper-bound `tw' is available, it is: " <<
                    it->first << '\n';

        if (object.upper_bound("twoo") == object.end())
            cout << "upper-bound `twoo' not available" << '\n';

        if (object.upper_bound("two") == object.end())
            cout << "upper-bound `two' not available" << '\n';

        pair
        <
            map<string, int>::iterator,
            map<string, int>::iterator
        >
            p = object.equal_range("two");

        cout << "equal range: `first' points to " <<
                    p.first->first << ", `second' is " <<
            (
                p.second == object.end() ?
                    "not available"
                :
                    p.second->first
            ) <<
            '\n';
    }
    /*
        Generated output:

            lower-bound `tw' is available, it is: two
            lower-bound `twoo' not available
            lower-bound two: two is available
            upper-bound `tw' is available, it is: two
            upper-bound `twoo' not available
            upper-bound `two' not available
            equal range: `first' points to two, `second' is not available
    */
\end{verbatim}
\item \index{value\_comp}\texttt{value\_compare value\_comp()}:\ \\ returns a copy of the object used by the \texttt{map} to compare keys. The
        type \texttt{map$<$KeyType, ValueType$>$::value\_compare} is defined by the map
        container and \texttt{value\_compare}'s parameters have types \texttt{value\_type
        const \&}. The comparison function returns \texttt{true} if the first
        key argument should be ordered before the second key argument. The
        \texttt{Value\_Type} elements of the \texttt{value\_type} objects passed to this
        member are not used by the returned function.
    \end{itemize}

\subsubsection{The `map': a simple example}
        \typeout{Original Yodl file: containers/mapexample}    As mentioned at the beginning of section \ref{MAP}, the \texttt{map} represents
a sorted associative array. In a \texttt{map} the keys are sorted. If an
application must visit all elements in a map the \texttt{begin} and \texttt{end}
iterators must be used.

The following example illustrates how to make a simple table listing all keys
and values found in a map:
        \begin{verbatim}
    #include <iostream>
    #include <iomanip>
    #include <map>

    using namespace std;

    int main()
    {
        pair<string, int>
            pa[] =
            {
                pair<string,int>("one", 10),
                pair<string,int>("two", 20),
                pair<string,int>("three", 30),
            };
        map<string, int>
            object(&pa[0], &pa[3]);

        for
        (
            map<string, int>::iterator it = object.begin();
                it != object.end();
                    ++it
        )
            cout << setw(5) << it->first.c_str() <<
                    setw(5) << it->second << '\n';
    }
    /*
        Generated output:
      one   10
    three   30
      two   20
    */
\end{verbatim}
\subsection{The `multimap' container}\label{MULTIMAP}
    \typeout{Original Yodl file: containers/multimap}Like the \texttt{map}, the \index{multimap}\texttt{multimap} class implements a (sorted)
    \index{associative array}associative array. Before using a \texttt{multimap} container the header
file \index{map: header file}\texttt{$<$map$>$} must be included.

The main difference between the \texttt{map} and the \texttt{multimap} is that the
multimap supports multiple values associated with the same key, whereas the
map contains single-valued keys. Note that the multimap also accepts multiple
identical values associated with identical keys.

The \texttt{map} and the \texttt{multimap} have the same set of constructors and member
functions, with the exception of the \index{index operator}index operator which is not supported
 \index{multimap: no operator[]} with the multimap. This is understandable: if
multiple entries of the same key are allowed, which of the possible values
should be returned for \texttt{object{[}key{]}}?

Refer to section \ref{MAP} for an overview of
the \texttt{multimap} member functions. Some member functions, however, deserve
additional attention when used in the context of the \texttt{multimap}
container. These members are discussed below.
    \begin{itemize}
        \item \index{count}\texttt{size\_t map::count(key)}:\ \\ returns the
number of entries in the multimap associated with the given \texttt{key}.
        \item \index{erase}\texttt{... erase()}:\ \\ erases elements from the map:
            \begin{itemize}
            \item \texttt{size\_t erase(key)} erases all elements having the
given \texttt{key}. The number of erased elements is returned.
            \item \texttt{void erase(pos)} erases the single element pointed to by
\texttt{pos}. Other elements possibly having the same keys are not erased.
            \item \texttt{void erase(first, beyond)} erases all elements indicated by
the iterator range \texttt{[first, beyond)}.
            \end{itemize}

\item \index{equal\_range}\texttt{pair$<$multimap::iterator, multimap::iterator$>$ equal\_range(key)}:\ \\ returns a pair of iterators, being respectively the return values of
\texttt{lower\_bound} and \texttt{upper\_bound}, introduced below.  The function provides
a simple means to determine all elements in the \texttt{multimap} that have the
same \texttt{keys}. An example illustrating the use of these member functions is
given at the end of this section.
        \item \index{find}\texttt{multimap::iterator find(key)}:\ \\ this
member returns an iterator pointing to the first value whose key is
\texttt{key}. If the element isn't available, \texttt{end} is returned. The
iterator could be incremented to visit all elements having the same \texttt{key}
until it is either \texttt{end}, or the iterator's \texttt{first} member is
not equal to \texttt{key} anymore.
        \item \index{insert}\texttt{multimap::iterator insert()}:\ \\ this
member function normally succeeds, and so a \emph{multimap::iterator} is
returned, instead of a \texttt{pair$<$multimap::iterator, bool$>$} as returned with the
\texttt{map} container. The returned iterator points to the newly added element.
    \end{itemize}
    Although the functions \texttt{lower\_bound} and \texttt{upper\_bound} act
identically in the \texttt{map} and \texttt{multimap} containers, their operation in a
\texttt{multimap} deserves some additional attention. The next example illustrates
\texttt{lower\_bound}, \texttt{upper\_bound} and
\texttt{equal\_range} applied to a \texttt{multimap}:
        \begin{verbatim}
    #include <iostream>
    #include <map>
    using namespace std;

    int main()
    {
        pair<string, int> pa[] =
        {
            pair<string,int>("alpha", 1),
            pair<string,int>("bravo", 2),
            pair<string,int>("charlie", 3),
            pair<string,int>("bravo", 6),   // unordered `bravo' values
            pair<string,int>("delta", 5),
            pair<string,int>("bravo", 4),
        };
        multimap<string, int> object(&pa[0], &pa[6]);

        using msiIterator = multimap<string, int>::iterator;

        msiIterator it = object.lower_bound("brava");

        cout << "Lower bound for `brava': " <<
                it->first << ", " << it->second << '\n';

        it = object.upper_bound("bravu");

        cout << "Upper bound for `bravu': " <<
                it->first << ", " << it->second << '\n';

        pair<msiIterator, msiIterator>
            itPair = object.equal_range("bravo");

        cout << "Equal range for `bravo':\n";
        for (it = itPair.first; it != itPair.second; ++it)
            cout << it->first << ", " << it->second << '\n';
        cout << "Upper bound: " << it->first << ", " << it->second << '\n';

        cout << "Equal range for `brav':\n";
        itPair = object.equal_range("brav");
        for (it = itPair.first; it != itPair.second; ++it)
            cout << it->first << ", " << it->second << '\n';
        cout << "Upper bound: " << it->first << ", " << it->second << '\n';
    }
    /*
        Generated output:

        Lower bound for `brava': bravo, 2
        Upper bound for `bravu': charlie, 3
        Equal range for `bravo':
        bravo, 2
        bravo, 6
        bravo, 4
        Upper bound: charlie, 3
        Equal range for `brav':
        Upper bound: bravo, 2
    */
\end{verbatim}
    In particular note the following characteristics:
    \begin{itemize}
    \item \texttt{lower\_bound} and \texttt{upper\_bound} produce the same result for
non-existing keys: they both return the first element having a key that
exceeds the provided key.
    \item  Although the keys are ordered in the \texttt{multimap}, the values for
equal keys are not ordered: they are retrieved in the order in which they were
entered.
    \end{itemize}

\subsection{The `set' container}\label{SET}
    \typeout{Original Yodl file: containers/set}The \index{set}\texttt{set} class implements a \index{sorted collection of values}sorted collection of values. Before using
\texttt{set} containers the \index{set: header file}\texttt{$<$set$>$} header file must be included.

A set contains unique values (of a container-acceptable type). Each value
is stored only once, and the \texttt{set} sorts its values using their
\texttt{operator$<$}, where the smallest values appears as first element in the set.

A specific value can be explicitly created: Every \texttt{set} defines a
\index{value\_type}\texttt{value\_type} which may be used to create values that can be stored in the
\texttt{set}. For example, a value for a \texttt{set$<$string$>$} can be constructed as
follows:
        \begin{verbatim}
    set<string>::value_type setValue{ "Hello" };
\end{verbatim}
Like the \texttt{std::map} container, the \texttt{std::set} also has an additional
parameter declaring the class that is used for comparing values in the set.
For value type \texttt{ValueType} the set's type definition, therefore, looks like
this:
        \begin{verbatim}
    set<ValueType, std::less<ValueType>>
\end{verbatim}
The \texttt{value\_type} is associated with the \texttt{set$<$string$>$}. Anonymous
\texttt{value\_type} objects are also often used. E.g.,
        \begin{verbatim}
    set<string>::value_type{ "Hello" };
\end{verbatim}
Instead of using the line \texttt{set$<$string$>$::value\_type(...)} over
and over again, a using declaration is often used to reduce typing and to
improve readability:
        \begin{verbatim}
    using StringSetValue = set<string>::value_type;
\end{verbatim}
Now values for the \texttt{set$<$string$>$} may be constructed as follows:
        \begin{verbatim}
    StringSetValue{ "Hello" };
\end{verbatim}
Alternatively, values of the set's type may be used
immediately. In that case the value of type \texttt{Type} is implicitly
converted  to a \texttt{set$<$Type$>$::value\_type}.

The following constructors, operators, and member functions are available
for the \texttt{set} container:
    \begin{itemize}
    \item  Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  A \texttt{set} may be constructed empty:
        \begin{verbatim}
    set<int> object;
\end{verbatim}
\item  A set may be initialized using two iterators. For example:
            \begin{verbatim}
    int intarr[] = {1, 2, 3, 4, 5};

    set<int> object{ &intarr[0], &intarr[5] };
\end{verbatim}
\end{itemize}

Note that all values in the set must be different: it is not possible to
store the same value repeatedly when the set is constructed. If the same value
occurs repeatedly, only the first instance of the value is entered into the
set; the remaining values are silently ignored.

Like the map, the \texttt{set} receives its own copy of the data it
contains.
    \item  The \texttt{set} container only supports the standard set of operators
that are available for containers.
    \item  The \texttt{set} class has the following member functions:
        \begin{itemize}
        \item \index{begin}\texttt{set::iterator begin()}:\ \\ returns an iterator pointing to
the first element of the set. If the set is empty \texttt{end} is returned.
        \item \index{clear}\texttt{void clear()}:\ \\ erases all elements from the set.
        \item \index{count}\texttt{size\_t count(value)}:\ \\ returns 1 if
the specified value is available in the \texttt{set}, otherwise 0 is returned.
        \item \index{emplace}\texttt{pair$<$iterator, bool$>$ emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
            arguments, and the newly created element is inserted into the
            set. The return value's \texttt{second} member is \texttt{true} if the
            element is inserted, and \texttt{false} if the element was already
            available. The pair's \texttt{first} element is an iterator referring
            to the set's eement. 
        \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if
the set contains no elements.
        \item \index{end}\texttt{set::iterator end()}:\ \\ returns an iterator pointing beyond
the last element of the set.
        \item \index{equal\_range}\texttt{pair$<$set::iterator, set::iterator$>$ equal\_range(value)}:\ \\ this
member returns a pair of iterators, being respectively the return values of
the member functions \texttt{lower\_bound} and \texttt{upper\_bound}, introduced
below.
        \item \index{erase}\texttt{... erase()}:\ \\ erases a specific element or range of
elements from the set:
            \begin{itemize}
            \item \texttt{bool erase(value)} erases the element having the given
\texttt{value} from the \texttt{set}. \texttt{True} is returned if the value was removed,
\texttt{false} if the set did not contain an element `\texttt{value}'.
            \item \texttt{void erase(pos)} erases the element pointed to by the iterator
\texttt{pos}.
            \item \texttt{void erase(first, beyond)} erases all elements
indicated by the iterator range \texttt{[first, beyond)}.
            \end{itemize}

\item \index{find}\texttt{set::iterator find(value)}:\ \\ returns
an iterator to the element having the given value. If the element isn't
available, \texttt{end} is returned.
        \item \index{get\_allocator}\texttt{allocator\_type get\_allocator() const}:\ \\ returns a
copy of the allocator object used by the \texttt{set} object.
        \item \index{insert}\texttt{... insert()}:\ \\ inserts elements into the \texttt{set}. If the
element already exists, the existing element is left untouched and the element
to be inserted is ignored.  The return value depends on the version of
\texttt{insert} that is called:
            \begin{itemize}
            \item \texttt{pair$<$set::iterator, bool$>$ insert(value)} inserts
a new \texttt{set::value\_type} into the set. The return value is a
\index{pair\textless{}set::iterator, bool\textgreater{}}\texttt{pair$<$set::iterator, bool$>$}.  If the returned \index{bool}\texttt{bool} field is \texttt{true},
\texttt{value} was inserted into the set. The value \texttt{false} indicates that the
value that was specified was already available in the set, and
so the provided \texttt{value} was not inserted into the set.  In both cases the
\texttt{set::iterator} field points to the data element in the \texttt{set} having the
specified \texttt{value}.
            \item \texttt{set::iterator insert(pos, value)}. This way a
\texttt{set::value\_type} may also be inserted into the set. \texttt{pos} is ignored, and
an iterator to the inserted element is returned.
            \item \texttt{void insert(first, beyond)} inserts the (\texttt{set::value\_type})
elements pointed to by the iterator range \texttt{[first, beyond)} into the
set. Values that were already present are not replaced.
            \end{itemize}

\item \index{key\_comp}\texttt{key\_compare key\_comp()}:\ \\ returns a copy of the object used by the \texttt{set} to compare keys. The
        type \ \\ 
        \texttt{set$<$ValueType$>$::key\_compare} is defined by the set container
        and \texttt{key\_compare}'s parameters have types \texttt{ValueType const \&}. The
        comparison function returns \texttt{true} if its first argument should
        be ordered before its second argument.
    \item \index{lower\_bound}\texttt{set::iterator lower\_bound(value)}:\ \\ returns an iterator pointing to the first \texttt{value} element of
        which the \texttt{value} is at least equal to the specified \texttt{value}.  If no
        such element exists, the function returns \texttt{end}.
    \item \index{max\_size}\texttt{size\_t max\_size()}:\ \\ returns the maximum number of
        elements this \texttt{set} may contain.
    \item \index{rbegin}\texttt{set::reverse\_iterator rbegin()}:\ \\ 
        returns a reverse\_iterator pointing to the last element of the set.
    \item \index{rend}\texttt{set::reverse\_iterator rend}:\ \\ returns a reverse\_iterator
        pointing before the first element of the set.
    \item \index{size}\texttt{size\_t size()}:\ \\ returns the number of elements in the set.
    \item \index{swap}\texttt{void swap(argument)}:\ \\ swaps two sets (\texttt{argument} being
the second set) that use identical data types.
    \item \index{upper\_bound}\texttt{set::iterator upper\_bound(value)}:\ \\ returns an iterator pointing to the first
\texttt{value} element having a \texttt{value} exceeding the specified \texttt{value}.  If no
such element exists, the function returns \texttt{end}.
    \item \index{value\_comp}\texttt{value\_compare value\_comp()}:\ \\ returns a copy of the object used by the \texttt{set} to compare values. The
        type \ \\ 
       \texttt{set$<$ValueType$>$::value\_compare} is defined by the set container and
        \texttt{value\_compare}'s parameters have types \texttt{ValueType const \&}. The
        comparison function returns \texttt{true} if its first argument should be
        ordered before its second argument. Its operation is identical to that
        of a \texttt{key\_compare} object, returned by \texttt{key\_comp}.
    \end{itemize}
  \end{itemize}

\subsection{The `multiset' container}\label{MULTISET}
    \typeout{Original Yodl file: containers/multiset}Like the \texttt{set}, the \index{multiset}\texttt{multiset} class implements a
    \index{sorted collection of value} sorted collection of values. Before
using \texttt{multiset} containers the header file \index{set: header file}\texttt{$<$set$>$} must be included.

The main difference between the \texttt{set} and the \texttt{multiset} is that the
\texttt{multiset} supports multiple entries of the same value, whereas the \texttt{set}
contains unique values.

The \texttt{set} and the \texttt{multiset} have the same set of constructors and member
functions.  Refer to section \ref{SET} for an overview of the member functions
that can be used with the \texttt{multiset}.  Some member functions, however,
behave slightly different than their counterparts of the \texttt{set}
container. Those members are:
    \begin{itemize}
        \item \index{count}\texttt{size\_t count(value)}:\ \\ returns the number of
entries in the multiset associated with the given \texttt{value}.
        \item \index{erase}\texttt{... erase()}:\ \\ erases elements from the set:
            \begin{itemize}
            \item \texttt{size\_t erase(value)} erases all elements having the given
\texttt{value}. The number of erased elements is returned.
            \item \texttt{void erase(pos)} erases the element pointed to by the iterator
\texttt{pos}. Other elements possibly having the same values are not erased.
            \item \texttt{void erase(first, beyond)} erases all elements indicated by
the iterator range \texttt{[first, beyond)}.
            \end{itemize}

\item \index{equal\_range}\texttt{pair$<$multiset::iterator, multiset::iterator$>$ equal\_range(value)}:\ \\ returns a pair of iterators, being respectively the return values of
\texttt{lower\_bound} and \texttt{upper\_bound}, introduced below.  The function provides
a simple means to determine all elements in the \texttt{multiset} that have the
same \texttt{values}.
        \item \index{find}\texttt{multiset::iterator find(value)}:\ \\ returns an
iterator pointing to the first element having the specified value. If the
element isn't available, \texttt{end} is returned. The iterator could be
incremented to visit all elements having the given \texttt{value} until it is
either \texttt{end}, or the iterator doesn't point to `\texttt{value}' anymore.
        \item \index{insert}\texttt{... insert()}:\ \\ this member function normally succeeds and
returns a \index{multiset::iterator}\emph{multiset::iterator} rather than a \texttt{pair$<$multiset::iterator,
bool$>$} as returned with the \texttt{set} container. The returned iterator points to
the newly added element.
    \end{itemize}
    Although the functions \texttt{lower\_bound} and \texttt{upper\_bound} act identically
in the \texttt{set} and \texttt{multiset} containers, their operation in a \texttt{multiset}
deserves some additional attention. With a \texttt{multiset} container
\texttt{lower\_bound} and \texttt{upper\_bound} produce the same result for non-existing
keys: they both return the first element having a key exceeding the provided
key.

Here is an example showing the use of various member functions of a
multiset:
    \begin{verbatim}
    #include <iostream>
    #include <set>

    using namespace std;

    int main()
    {
        string
            sa[] =
            {
                "alpha",
                "echo",
                "hotel",
                "mike",
                "romeo"
            };

        multiset<string>
            object(&sa[0], &sa[5]);

        object.insert("echo");
        object.insert("echo");

        multiset<string>::iterator
            it = object.find("echo");

        for (; it != object.end(); ++it)
            cout << *it << " ";
        cout << '\n';

        cout << "Multiset::equal_range(\"ech\")\n";
        pair
        <
            multiset<string>::iterator,
            multiset<string>::iterator
        >
            itpair = object.equal_range("ech");

        if (itpair.first != object.end())
            cout << "lower_bound() points at " << *itpair.first << '\n';
        for (; itpair.first != itpair.second; ++itpair.first)
            cout << *itpair.first << " ";

        cout << '\n' <<
                object.count("ech") << " occurrences of 'ech'" << '\n';

        cout << "Multiset::equal_range(\"echo\")\n";
        itpair = object.equal_range("echo");

        for (; itpair.first != itpair.second; ++itpair.first)
            cout << *itpair.first << " ";

        cout << '\n' <<
                object.count("echo") << " occurrences of 'echo'" << '\n';

        cout << "Multiset::equal_range(\"echoo\")\n";
        itpair = object.equal_range("echoo");

        for (; itpair.first != itpair.second; ++itpair.first)
            cout << *itpair.first << " ";

        cout << '\n' <<
                object.count("echoo") << " occurrences of 'echoo'" << '\n';
    }
    /*
        Generated output:

        echo echo echo hotel mike romeo
        Multiset::equal_range("ech")
        lower_bound() points at echo

        0 occurrences of 'ech'
        Multiset::equal_range("echo")
        echo echo echo
        3 occurrences of 'echo'
        Multiset::equal_range("echoo")

        0 occurrences of 'echoo'
    */
\end{verbatim}
\subsection{The `stack' container}\label{STACK}
    \typeout{Original Yodl file: containers/stack}The \index{stack}\texttt{stack} class implements a \index{stack data structure}stack data structure.  Before using
\texttt{stack} containers the header file \index{stack: header file}\texttt{$<$stack$>$} must be included.

A stack is also called a \index{first in, last out}first in, last out (\index{FILO}FILO or \index{LIFO}LIFO) data
structure as the first item to enter the stack is the last item to leave.  A
stack is an extremely useful data structure in situations where data must
temporarily remain available. For example, programs maintain a stack to store
local variables of functions: the lifetime of these variables is determined by
the time these functions are active, contrary to global (or static local)
variables, which live for as long as the program itself lives. Another example
is found in calculators using the
 \index{Reverse Polish Notation}\emph{Reverse Polish Notation} (\index{RPN}RPN), in which the operands of operators are
kept  in a stack, whereas operators pop their operands off the stack and
push the results of their work back onto the stack.

As an example of the use of a stack, consider figure \ref{StackFig}, in which
the content of the stack is shown while the expression \texttt{(3 + 4) $*$ 2} is
evaluated. In the RPN this expression becomes \texttt{3 4 + 2 $*$}, and figure
\ref{StackFig} shows the stack content after each \index{token}\emph{token} (i.e., the
operands and the operators) is read from the input. Notice that each operand
is indeed pushed on the stack, while each operator changes the content of the
stack.
    \begin{figure}[tbp]
\centerline{\epsffile{containers/stack/stack.eps}}
\caption{\label{StackFig}The content of a stack while evaluating \texttt{3 4 + 2 $*$}}
\end{figure}
    The expression is evaluated in five steps. The caret between the tokens
in the expressions shown on the first line of figure \ref{StackFig} shows what
token has just been read. The next line shows the actual stack-content, and
the final line shows the steps for referential purposes. Note that at step 2,
two numbers have been pushed on the stack. The first number (\texttt{3}) is now at
the bottom of the stack. Next, in step 3, the \texttt{+} operator is read. The
operator pops two operands (so that the stack is empty at that moment),
calculates their sum, and pushes the resulting value (\texttt{7}) on the
stack. Then, in step 4, the number \texttt{2} is read, which is dutifully pushed on
the stack again. Finally, in step 5 the final operator \texttt{$*$} is read, which
pops the values \texttt{2} and \texttt{7} from the stack, computes their product, and
pushes the result back on the stack. This result (\texttt{14}) could then be popped
to be displayed on some medium.

From figure \ref{StackFig} we see that a stack has one location (the \index{top}\emph{top})
where items can be pushed onto and popped off the stack. This top element is
the stack's only immediately visible element. It may be accessed and modified
directly.

Bearing this model of the stack in mind, let's see what we formally can do
with the \texttt{stack} container. For the \texttt{stack}, the following constructors,
operators, and member functions are available:
    \begin{itemize}
    \item  \index{stack constructors} Constructors:
        \begin{itemize}
        \item  The copy and move constructors are available;
        \item  A \texttt{stack} may be constructed empty:
    \begin{verbatim}
stack<string> object;
\end{verbatim}
\end{itemize}

\item  Only the basic set of container operators are supported by the
\texttt{stack}
    \item  The following member functions are available for stacks:
        \begin{itemize}
        \item \index{emplace}\texttt{value\_type \&emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
            arguments, and the newly created element is pushed on the stack.
            The return value is a reference to (or copy of) the newly pushed
            value. 
        \item \index{empty}\texttt{bool empty()}:\ \\ this
member returns \texttt{true} if the stack contains no elements.
        \item \index{pop}\texttt{void pop()}:\ \\ removes the element at the top of the
stack. Note that the popped element is \emph{not} returned by this member.
Refer to section \ref{QUEUE} for a discussion about the reason why \texttt{pop} has
return type \texttt{void} and why \texttt{pop} should not be called on an empty
\texttt{stack}.
        \item \index{push}\texttt{void push(value)}:\ \\ places
\texttt{value} at the top of the stack, hiding the other elements from view.
        \item \index{size}\texttt{size\_t size()}:\ \\ this
member returns the number of elements in the stack.
        \item \index{top}\texttt{Type \&top()}:\ \\ this member
returns a reference to the stack's top (and only visible) element. It is the
    \index{responsibility of the programmer}responsibility of the programmer to use this member only if the stack
is not empty.
        \end{itemize}
    \end{itemize}

The stack does not support iterators or an index
operator. The only elements that can be accessed is its top element.
  To empty a stack:
    \begin{itemize}
    \item  repeatedly remove its front element;
    \item  assign an empty stack to it;
    \item  have its destructor called (e.g., by ending its lifetime).
    \end{itemize}

\subsection{Intermezzo: hashing and unordered containers}\label{HASH}
    \typeout{Original Yodl file: containers/hash}\index{hashing}Hashing is a very attractive way to find an element in a
container. For example, to find an element in an unsorted \texttt{std::vector} of
\texttt{N} elements takes (on average) \texttt{N / 2} tests before the element is
found. If the elements in the vector are sorted a binary search algorithm
(cf. section \ref{BINSRCH}) can be used, requiring about \texttt{2 log N} tests
before the element is found. But hashing usually requires just one test, and
occasionally one or two additional tests.

Hashing is used by some of the standard containers, like the \texttt{unordered\_set}
(section \ref{USET}) and the \texttt{unordered\_map} (section \ref{UMAP})
containers. For example, when using the \texttt{unordered\_set} container four types
must be specified: a \emph{key} type, a \emph{hash} type, a \emph{predicate} type, and
an \emph{allocator} type. In practice, the default provided allocator type 
can be used (section \ref{TEMPTEMPPAR} covers the construction of your
own allocator class). The \emph{key} is used by the hash type to determine the
location of the key in the container, and the predicate type doesn't have to
be specified if the key type itself supports the equality operator
(i.e., \texttt{operator==}).

\index{hashing: default available}
 For all built-in types and many standard (\texttt{std::}) types hashing is already
available, e.g., \texttt{std::bitset}, \texttt{std::chrono}, \texttt{std::error\_code},
\texttt{std::optional, std::string}, \texttt{std::string\_view}, \texttt{std::unique\_ptr},
\texttt{std::vector$<$bool$>$}
 (a complete overview is provided by
\texttt{cppreference.com}\footnote{https://en.cppreference.com/w/cpp/utility/hash.html}).
When using those key types \texttt{unordered\_sets} can be constructed by merely
specifying the key type. E.g.,
    \begin{verbatim}
    std::unordered_set<double>
    std::unordered_set<std::string>
\end{verbatim}
When a hash value cannot already be computed for a \texttt{Key} type then a hash
class, and (if not already provided by the key type itself) a predicator type
must be defined.

\index{hash} 
 Consider the situation where an \texttt{unordered\_set} for a \texttt{Key} class type
containing two \texttt{std::string} data members must be constructed. To define and
use such an \texttt{unordered\_set} the following must be available:
    \index{operator== (default)}
    \begin{itemize}
    \item  The \texttt{Key} class. In this case, where the class's data members can
        all be compared for equality, a default \texttt{operator==} can be used. If
        not all its data members can be compared for equality the \texttt{Key}
        class can implement its own \texttt{operator==} member. If, when using an
        unordered container, a special \texttt{operator==} is required, then a
        separate predicate class must be defined which is then specified when
        defining the unordered container.\ \\ 
       Such a predicate class defines a \texttt{bool operator()(Key const \&lhs, Key
        const \&rhs)}, performing the special comparison of two \texttt{Key}
        objects, which apparently could not be defined that way by the \texttt{Key}
        class itself.\ \\ 
       In the example used in this section the \texttt{Key} class's data members
        all can be compared for equality, and thus the compiler can provide a
        \emph{default} implementation for its \texttt{operator==} member. Here is the
        class's interface, note the \texttt{= default} in the declaration of its
        \texttt{operator==} member:
       \begin{verbatim}
    class Key
    {
        std::string d_name;
        std::string d_phone;
    
        public:
            Key(std::string const &name, std::string const &phone);
            bool operator==(Key const &other) const = default;
    
            std::string const &name() const;
            std::string const &phone() const;
    };
\end{verbatim}
\item  Hash values (also known as \index{bucket numbers}\emph{bucket numbers}) are computed and
        returned either by a \texttt{KeyHash} class defining a function call
        operator (also known as the \index{hash function}\emph{hash function}), or by a specialization
        for the \texttt{Key} type of the \texttt{std::hash} template.\ \\ 
       \emph{Collisions} \index{collision} occur when a computed hash value happens
        to be equal to the hash value computed for another key which is
        already available in the container.  Those cases are seldom
        encountered and are solved by the container, hence the on average
        slightly more than one required test to retrieve a key.  A simple
        solution consists of using \index{linear chaining}\emph{linear chaining}, using linked list to
        store colliding elements.
    \end{itemize}

A \texttt{KeyHash} class only needs a \texttt{size\_t operator()(Key const \&key) const}
member function (optionally \texttt{noexcept} can be added to its declaration). For
example:
    \begin{verbatim}
    struct KeyHash
    {
        size_t operator()(Key const &key) const;        // noexcept;
    };
    
    size_t KeyHash::operator()(Key const &key) const    // noexcept
    {
        std::hash<std::string> hashObj;
    
        return hashObj(key.name()) ^ (hashObj(key.phone()) << 1);
    }
\end{verbatim}
Using \texttt{Key} and \texttt{KeyHash} an \texttt{unordered\_set} can be defined as, e.g.,
    \begin{verbatim}
    std::unordered_set<Key, KeyHash> keySet;
\end{verbatim}
Alternatively a specialization of the \texttt{std::hash} class template
(cf. chapter \ref{TEMPCLASS}) can be defined.  Interestingly, when the
\texttt{std::hash} specialization is defined it's OK to define it as \texttt{std::hash},
so inside the \texttt{std} namespace, which normally is off-limits for user-defined
software. it's easy to define this specialization. Here are its class and
member function:
            \begin{verbatim}
    template<>
    struct std::hash<Key>
    {
        std::size_t operator()(Key const &key) const;           // noexcept;
    };
    
    size_t std::hash<Key>::operator()(Key const &key) const     // noexcept
    {
        std::hash<std::string> hashObj;
    
        return hashObj(key.name()) ^ (hashObj(key.phone()) << 1);
    }
\end{verbatim}
When this specialization is available the \texttt{unordered\_set} can be defined by
merely specifying the \texttt{Key} class:
    \begin{verbatim}
    std::unordered_set<Key> keySet;
\end{verbatim}
The \texttt{std::hash} class is included by quite a few standard header files:
    \begin{quote}\texttt{bitset}, \texttt{chrono}, \texttt{coroutine}, \texttt{filesystem}, \texttt{
        functional}, \texttt{memory}, \texttt{optional}, \texttt{stacktrace}, \texttt{string},
        \texttt{string\_view}, \texttt{system\_error}, \texttt{text\_encoding}, \texttt{thread},
        \texttt{typeindex}, \texttt{utility}, \texttt{variant}, \texttt{vector}.
    \end{quote}
 Include the \index{functional: header file}\texttt{$<$functional$>$} header file when \texttt{std::hash} is required but
none of the other header files are included.

Key values frequently consists of text. Be careful not to use a plain \texttt{char
const $*$} key type as two \texttt{char const $*$} values pointing to equal
\textbf{C}-strings stored at different locations are different \texttt{char const $*$}
keys, as their pointer values rather than their textual content are compared.

\subsection{The `unordered\_set' container}\label{USET}
    \typeout{Original Yodl file: containers/unorderedset}The \emph{set} container, like the \texttt{map} container, orders its elements. If
ordering is not an issue, but fast lookups is, then a hash-based set and/or
multi-set may be used (cf. section \ref{HASH}). \textbf{C++} offers such
hash-based sets and multi-sets: the \index{unordered\_set}\texttt{unordered\_set} and
\texttt{unordered\_multiset}.\ \\ 
    Before using a hash-based set container the header file
\index{unordered\_set: header file}\texttt{$<$unordered\_set$>$} must be included.

Elements stored in the \texttt{unordered\_set} are immutable, but they can be
inserted and removed from the container. The set merely stores elements, and
the stored element itself acts as its key.

\subsubsection{The `unordered\_set' constructors}
        \typeout{Original Yodl file: containers/unorderedsetconstructors}When defining an \index{unordered\_set}\texttt{unordered\_set} four template arguments must be specified
(often, except for the first template argument default arguments can be used):
    \index{unordered\_set: sub-types}
    \begin{itemize}
    \item  a Key type: the type of the values storing in the set (becoming
        the sub-types \texttt{unordered\_set::key\_type} and
         \texttt{unordered\_set::value\_types});
    \item  a Hash type: the type of an object computing a hash value from a key
        value (becoming the sub-type \texttt{unordered\_set::hasher});
    \item  a Predicator type: the type of an object that can compare two keys
        for equality (becoming the sub-type \index{unordered\_set::key\_equal}\texttt{unordered\_set::key\_equal}).
    \item  an Allocator type: the type of its allocator. This is usually left
        unspecified, using the allocator provided by default by the
        implementor.
    \end{itemize}

The generic definition of an \texttt{unordered\_set} container looks like this:
        \begin{verbatim}
    std::unordered_set <Key type, Hash type, Predicate type, Allocator type>
\end{verbatim}
For all built-in types and many standard (\texttt{std::}) types hashing and the
predicator are already available (cf. section \ref{HASH}).  In these cases an
\texttt{unordered\_set} object can be defined by merely specifying the key
type. E.g.,
        \begin{verbatim}
    std::unordered_set<std::string> strSet;
\end{verbatim}
When necessary the set's size is automatically enlarged, in which case the
container \emph{rehashes} all its elements.

The \texttt{unordered\_set} supports the following constructors:
    \begin{itemize}
    \item  Copy and move constructors (and corresponding assignment operators)
        are available; 
    \item \texttt{explicit unordered\_set(size\_type size = implSize,
             hasher const \&hf = hasher(),}
             \texttt{key\_equal const \&eql = key\_equal(),}
             \texttt{allocator\_type const \&alloc = allocator\_type())}:\ \\ 
        this constructor can also be used as default constructor.
        Here, \texttt{implSize} is the container's default initial size, which is
        specified by the implementor. In practice the default \texttt{size}
        argument provided by the implementor is completely satisfactory;
    \item \texttt{unordered\_set(const\_iterator begin, const\_iterator end,
                    size\_type n = implSize, hasher const \&hf = hasher()),}
            \texttt{key\_equal const \&eql = key\_equal()},
            \texttt{allocator\_type const \&alloc = allocator\_type()}:\ \\ 
        this constructor expects two iterators specifying
        a range of \texttt{unordered\_set::value\_type const} objects;
    \item \texttt{unordered\_set(initializer\_list$<$value\_type$>$ initList,
                    size\_type n = implSize, hasher const \&hf = hasher())},
            \texttt{key\_equal const \&eql = key\_equal()},
            \texttt{allocator\_type const \&alloc = allocator\_type()}:\ \\ 
        a constructor expecting an \texttt{initializer\_list} of
            \texttt{unordered\_set::value\_type} values.
    \end{itemize}

\subsubsection{The `unordered\_set' public members}\label{USETMEMBERS}
        \typeout{Original Yodl file: containers/unorderedsetmembers}The \texttt{unordered\_set} provides the following
 \index{unordered\_set: member functions} member functions:

\begin{itemize}
    \item \index{begin}\texttt{unordered\_set::iterator begin()}:\ \\ returns an \index{iterator}iterator pointing to the first element in the
        unordered set, returning \texttt{end} if the unordered set is empty;
    \item \index{bucket}\texttt{size\_t bucket(key\_type const \&key)}:\ \\ returns the hash value where \texttt{key} is stored. If \texttt{key} wasn't
        stored yet \texttt{bucket} adds \texttt{value\_type(key, Value())} before
        returning its index position;
    \item \index{bucket\_count}\texttt{size\_t bucket\_count()}:\ \\ returns the number of slots used by the container. Each slot may
        contain one (or more, in case of collisions) \texttt{value\_type} objects;
    \item \index{bucket\_size}\texttt{size\_t bucket\_size(size\_t index)}:\ \\ returns the number of \texttt{value\_type} objects stored at bucket position
        \texttt{index};
    \item \index{cbegin}\texttt{unordered\_set::const\_iterator cbegin()}:\ \\ returns a \index{const\_iterator}const\_iterator pointing to the first element in the
        unordered set, returning \texttt{cend} if the unordered set is empty;
    \item \index{cend}\texttt{unordered\_set::const\_iterator cend()}:\ \\ returns a \index{const\_iterator}const\_iterator pointing just beyond the unordered set's
        last element;
    \item \index{clear}\texttt{void clear()}:\ \\ erases all the unordered set's elements;
    \item \index{count}\texttt{size\_t count(key\_type const \&key)}:\ \\ returns the number of times a \texttt{value\_type} object using \texttt{key\_type}
        \texttt{key} is stored in the \texttt{unordered\_set} (which is either one or
        zero);
    \item \index{emplace}\texttt{iterator emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from \texttt{emplace}'s
        arguments. It is added to the set if it is unique, and an iterator to
        the \texttt{value\_type} is returned;
    \item \index{emplace\_hint}\texttt{iterator emplace\_hint(const\_iterator position,
                        Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's arguments,
        and if the newly created element is unique it is inserted into the
        \texttt{unordered\_set}. The implementation may or may not use \texttt{position}
        as a \emph{hint} to start looking for an insertion point. The returned
        \texttt{iterator} points to the \texttt{value\_type};
    \item \index{empty}\texttt{bool empty()}:\ \\ returns \texttt{true} if the unordered set contains no elements;
    \item \index{end}\texttt{unordered\_set::iterator end()}:\ \\ returns an iterator pointing beyond the last element in the
        unordered set;
    \item \index{equal\_range}\texttt{pair$<$iterator, iterator$>$ equal\_range(key)}:\ \\ this member returns a pair
        of iterators defining the range of elements having a key that is equal
        to \texttt{key};
    \item \index{erase}\texttt{unordered\_set::iterator erase()}:\ \\ erases a specific range of elements in the unordered set:
        \begin{itemize}
        \item \texttt{erase(key\_type const \&key)} erases \texttt{key} from the set. It
           returns \texttt{true} if the \texttt{key} was removed and \texttt{false} if the
            \texttt{key} wasn't available in the set.
        \item \texttt{erase(pos)} erases the element pointed to by the iterator
            \texttt{pos}. The iterator \texttt{++pos} is returned.
        \item \texttt{erase(first, beyond)} erases elements indicated by the
            iterator range \texttt{[first, beyond)}, returning \texttt{beyond}.
        \end{itemize}
    \item \index{find}\texttt{iterator find(key)}:\ \\ returns an iterator to the element having the given key. If the
        element isn't available, \texttt{end} is returned;
    \item \index{get\_allocator}\texttt{allocator\_type get\_allocator() const}:\ \\ returns a copy of the allocator object used by the \texttt{unordered\_set}
        object;
    \item \index{hash\_function}\texttt{hasher hash\_function() const}:\ \\ returns a copy of the hash function object used by the
        \texttt{unordered\_set} object;
    \item \index{insert}\texttt{... insert()}:
       \begin{quote}elements may be inserted starting at a certain position. No
        insertion is performed if the provided key is already in use. The
        return value depends on the version of \texttt{insert()} that is
        called. When a \texttt{pair$<$iterator, bool$>$} is returned, then the
        \texttt{pair's first} member is an iterator pointing to the element having
        a key that is equal to the key of the provided \texttt{value\_type}, the
        \texttt{pair's second} member is \texttt{true} if \texttt{value} was actually
        inserted into the container, and \texttt{false} if not;\end{quote}
       \begin{itemize}
        \item \texttt{pair$<$iterator, bool$>$ insert(value\_type const \&value)}
            attempts to insert \texttt{value}.
        \item \texttt{pair$<$iterator, bool$>$ insert(value\_type \&\&tmp)}
           attempts to insert \texttt{value} using \texttt{value\_type}'s move
            constructor.
        \item \texttt{pair$<$iterator, bool$>$ insert(const\_iterator hint, value\_type
            const \&value)}
           attempts to insert \texttt{value}, possibly using \texttt{hint} as a starting
            point when trying to insert \texttt{value}.
        \item \texttt{pair$<$iterator, bool$>$ insert(const\_iterator hint, value\_type \&\&tmp)}
           attempts to insert a \texttt{value} using \texttt{value\_type}'s move
            constructor, and possibly using \texttt{hint} as a starting point when
            trying to insert \texttt{value}.
        \item \texttt{void insert(first, beyond)}
           tries to insert the elements in the iterator range \texttt{[first,
            beyond)}.
        \item \texttt{void insert(initializer\_list $<$value\_type$>$ iniList)}
           attempts to insert the elements in \texttt{iniList} into the container.
        \end{itemize}
    \item \index{key\_equal}\texttt{hasher key\_eq() const}:\ \\ returns a copy of the \texttt{key\_equal} function object used by the
        \texttt{unordered\_set} object;
    \item \index{load\_factor}\texttt{float load\_factor() const}:\ \\ returns the container's current load factor, i.e. \texttt{size /
        bucket\_count};
    \item \index{max\_bucket\_count}\texttt{size\_t max\_bucket\_count()}:\ \\ returns the maximum number of buckets this \texttt{unordered\_set} may
        contain;
    \item \index{max\_load\_factor}\texttt{float max\_load\_factor() const}:\ \\ identical to \texttt{load\_factor};
    \item \index{max\_load\_factor}\texttt{void max\_load\_factor(float max)}:\ \\ changes the current maximum load factor to \texttt{max}. When a load factor
        of \texttt{max} is reached, the container will enlarge its
        \texttt{bucket\_count}, followed by a rehash of its elements. Note that the
        container's default maximum load factor equals 1.0
    \item \index{max\_size}\texttt{size\_t max\_size()}:\ \\ returns the maximum number of elements this \texttt{unordered\_set} may
        contain;
    \item \index{rehash}\texttt{void rehash(size\_t size)}:\ \\ if \texttt{size} exceeds the current bucket count, then the bucket count is
        increased to \texttt{size}, followed by a rehash of its elements;
    \item \index{reserve}\texttt{void reserve(size\_t request)}:\ \\ if \texttt{request} is less than or equal to the current bucket count, this
        call has no effect. Otherwise, the bucket count is increased to a
        value of at least \texttt{request}, followed by a rehash of the container's
        elements;
    \item \index{size}\texttt{size\_t size()}:\ \\ returns the number of elements in the unordered set;
    \item \index{swap}\texttt{void swap(unordered\_set \&other)}:\ \\ swaps the content of the current and the other \texttt{unordered\_set}.  
    \end{itemize}

\subsubsection{The `unordered\_multiset' container}
        \typeout{Original Yodl file: containers/unorderedmultiset}The \index{unordered\_multiset}\texttt{unordered\_multiset} allows multiple objects using the same keys to be
stored in an unordered set. The \texttt{unordered\_multiset} container offers the
same set of members and constructors as the \texttt{unordered\_set}, but without the
unique-key restriction imposed upon the \texttt{unordered\_set}.

Below all members are described whose behavior differs from the behavior of
the corresponding \texttt{unordered\_set} members:

\begin{itemize}
        \item \index{count}\texttt{size\_t count(key\_type const \&key)}:\ \\ returns the number of times a \texttt{value\_type} object using
\texttt{key\_type} \texttt{key} is stored in the \texttt{unordered\_set}. This member is
commonly used to verify whether \texttt{key} is available in the
\texttt{unordered\_multiset};
        \item \index{emplace}\texttt{iterator emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from \texttt{emplace}'s
arguments. The returned \texttt{iterator} points to the newly inserted inserted
\texttt{value\_type};
        \item \index{emplace\_hint}\texttt{iterator emplace\_hint(const\_iterator position,
                            Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted into the
\texttt{unordered\_multiset}. The
implementation may or may not use \texttt{position} as a \emph{hint} to start looking
for an insertion point. The returned \texttt{iterator} points to the \texttt{value\_type}
using the provided key;
    \item \index{equal\_range}\texttt{pair$<$iterator, iterator$>$ equal\_range(key)}:\ \\ this
member returns a pair of iterators  defining the range of elements having a
key that is equal to \texttt{key};
    \item \index{find}\texttt{iterator find(key)}:\ \\ returns an iterator to an element having the given key. If no
such element is available, \texttt{end} is returned;
        \item \index{insert}\texttt{... insert()}:
            \begin{quote}elements may be inserted starting at a certain position. The
return value depends on the version of \texttt{insert()} that is called. When an
\texttt{iterator} is returned, then it points to the element that was inserted:\end{quote}
            \begin{itemize}
            \item \texttt{iterator insert(value\_type const \&value)}
                inserts \texttt{value}.
            \item \texttt{iterator insert(value\_type \&\&tmp)}
                inserts \texttt{value} using \texttt{value\_type}'s move
                constructor.
            \item \texttt{iterator insert(const\_iterator hint, value\_type const \&value)}
                inserts \texttt{value}, possibly using \texttt{hint} as a
starting point when trying to insert \texttt{value}.
            \item \texttt{iterator insert(const\_iterator hint, value\_type \&\&tmp)}
                inserts \texttt{value} using \texttt{value\_type}'s move
constructor, and possibly using \texttt{hint} as a starting point when trying to
insert \texttt{value}.
            \item \texttt{void insert(first, beyond)} inserts the elements in
the iterator range \texttt{[first, beyond)}.
            \item \texttt{void insert(initializer\_list $<$value\_type$>$ iniList)}
                inserts the elements in \texttt{iniList} into the container.
            \end{itemize}
        \end{itemize}

\subsection{The `unordered\_map' container (`hash table')}\label{UMAP}
    \typeout{Original Yodl file: containers/unorderedmap}In \textbf{C++} hash tables are available as objects of the class
\texttt{std::unordered\_map}\index{unordered\_map}. 

Before using \texttt{unordered\_map} or \texttt{unordered\_multimap} containers the header
file \index{unordered\_map: header file}\texttt{$<$unordered\_map$>$} must be included.

The class \texttt{unordered\_map} implements an \emph{associative array} in which the
elements are stored according to some \emph{hashing} scheme.  While the \emph{map}
container defines a sorted data structure whose keys are sorted using the key
class's \index{operator\textless{}}\texttt{operator$<$}, the \texttt{unordered\_map} uses \emph{hashing} to located its
elements (cf. section \ref{HASH}). Hashing is a by far faster way to store and
retrieve data than using a sorted data structure.

Retrieval of a key/value pair is as simple as computing the key's
 \index{hash value}hash value, and locating it in the table at the computed index location:
if the key is present, the key/value combination is retrieved. If the key
isn't available then the key/value pair may automatically be stored in the
table at the computed bucket location, returning the value.

The term \emph{unordered\_map} is used rather than \emph{hash} to avoid name
collisions with hash tables developed before they were added to the language.

The \texttt{unordered\_map} supports the index operator operating identically to the
\texttt{map}'s index operator: a (const) reference to the \texttt{ValueType} associated
with the provided \texttt{KeyType}'s value is returned. If not yet available, the
key is added to the \texttt{unordered\_map}, and a default \texttt{ValueType} value is
returned. In addition, it supports \texttt{operator==}.

The \texttt{unordered\_map} also offers the \index{at} \texttt{ValueType \&at(KeyType const
\&key)} member returning a reference to the \texttt{unordered\_map's ValueType}
associated with \texttt{key}. If \texttt{key} is not stored in the \texttt{unordered\_map} a
\texttt{std::out\_of\_range} exception is thrown.

Other than those, it offers the same members as the \texttt{unordered\_set}
(cf. section \ref{USET}), but some of these members show different behavior.
Those members are listed below. For a description of the
remaining members, please refer to section \ref{USETMEMBERS}.

\begin{itemize}
        \item \index{emplace}\texttt{pair$<$iterator, bool$>$ emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from \texttt{emplace}'s
arguments. If the \texttt{unordered\_map} already contained an object using the same
\texttt{key\_type} value, then a \texttt{std::pair} is returned containing an iterator
pointing to the object using the same \texttt{key\_type} value and the value
\texttt{false}. If no such \texttt{key\_type} value was found, the newly constructed
object is inserted into the \texttt{unordered\_map}, and the returned \texttt{std::pair}
contains an iterator pointing to the newly inserted inserted \texttt{value\_type}
as well as the value \texttt{true};

\item \index{emplace\_hint}\texttt{iterator emplace\_hint(const\_iterator position,
                            Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted into the
\texttt{unordered\_map}, unless the (at \texttt{args}) provided key already exists. The
implementation may or may not use \texttt{position} as a \emph{hint} to start looking
for an insertion point. The returned \texttt{iterator} points to the \texttt{value\_type}
using the provided key. It may refer to an already existing \texttt{value\_type} or
to a newly added \texttt{value\_type}; an existing \texttt{value\_type} is not
replaced. If a new value \emph{was} added, then the container's size has been
incremented when \texttt{emplace\_hint} returns;
        \end{itemize}

\subsubsection{The `unordered\_map' constructors}
        \typeout{Original Yodl file: containers/unorderedmapconstructors}When defining an \index{unordered\_map}\texttt{unordered\_map} type five template arguments must be
specified :
    \index{unordered\_map: sub-types}
    \begin{itemize}
    \item  a \index{Key type}Key type: the type of the values storing in the set (becoming
        the sub-type \texttt{unordered\_map::key\_type});
    \item  a Value type: the value associated with a key (becoming the sub-type
        \texttt{unordered\_map::mapped\_type});
    \item  a Hash type: the type of an object computing a hash value from a key
        value (becoming the sub-type \texttt{unordered\_map::hasher});
    \item  a Predicator type: the type of an object that can compare two keys
        for equality (becoming the sub-type \texttt{unordered\_map::key\_equal});
    \item  an Allocator type: the type of its allocator. This is usually left
        unspecified, using the allocator provided by default by the
        implementor.
    \end{itemize}

The generic definition of an \texttt{unordered\_map} container type looks like this:
    \begin{verbatim}
    std::unordered_map <Key type, Value type, Hash type, 
                        Predicate type, Allocator type>
\end{verbatim}
For all built-in types and many standard (\texttt{std::}) types hashing and the
predicator are already available. In practice the allocator type is not
specified, as the default allocator suffices.  In these cases an
\texttt{unordered\_map} object can be defined by merely specifying its key- and
value types, like this:
        \begin{verbatim}
    std::unordered_map<std::string, ValueType> hash;
\end{verbatim}
The \texttt{unordered\_map} supports the following constructors:
    \begin{itemize}
    \item  Copy and move constructors (and corresponding assignment operators)
        are available; 
    \item \texttt{explicit unordered\_map(size\_type n = implSize,
             hasher const \&hf = hasher(),}
             \texttt{key\_equal const \&eql = key\_equal()},
             \texttt{allocator\_type const \&alloc = allocator\_type()}):\ \\ 
       this constructor can also be used as default constructor.  Here,
        \texttt{implSize} is the container's default initial size, which is
        specified by the implementor. In practice the default \texttt{size}
        argument provided by the implementor is completely satisfactory;
    \item \texttt{explicit unordered\_map(const\_iterator begin, const\_iterator
        end,size\_type n = implSize,}
             \texttt{hasher const \&hf = hasher()},
             \texttt{key\_equal const \&eql = key\_equal()},
             \texttt{allocator\_type const \&alloc = allocator\_type())}:\ \\ 
            this constructor expects two iterators providing
        a range of \texttt{unordered\_map::value\_type const} objects;
    \item \texttt{unordered\_map(initializer\_list$<$value\_type$>$ initList,
            size\_type n = implSize,}
            \texttt{hasher const \&hf = hasher()},
            \texttt{key\_equal const \&eql = key\_equal()},
            \texttt{allocator\_type const \&alloc = allocator\_type()}):\ \\ 
        a constructor expecting an \texttt{initializer\_list} of
        \texttt{unordered\_map::value\_type} values.
    \end{itemize}

The following example shows a program using an \texttt{unordered\_map}
containing the names of the months of the year and the number of days these
months (usually) have. Then, using the subscript operator the days in several
months are displayed (the predicate used here is the generic algorithm
\texttt{equal\_to$<$string$>$}, which is provided by the compiler as the default fourth
argument of the \texttt{unordered\_map} constructor):
        \begin{verbatim}
    #include <unordered_map>
    #include <iostream>
    #include <string>
    using namespace std;

    int main()
    {
        unordered_map<string, int> months;

        months["january"] = 31;
        months["february"] = 28;
        months["march"] = 31;
        months["april"] = 30;
        months["may"] = 31;
        months["june"] = 30;
        months["july"] = 31;
        months["august"] = 31;
        months["september"] = 30;
        months["october"] = 31;
        months["november"] = 30;
        months["december"] = 31;

        cout << "september -> " << months["september"] << '\n' <<
                "april     -> " << months["april"] << '\n' <<
                "june      -> " << months["june"] << '\n' <<
                "november  -> " << months["november"] << '\n';
    }
    /*
        Generated output:
    september -> 30
    april     -> 30
    june      -> 30
    november  -> 30
    */
\end{verbatim}
        \subsubsection{The `unordered\_multimap' container}
        \typeout{Original Yodl file: containers/unorderedmultimap}The \index{unordered\_multimap}\texttt{unordered\_multimap} allows multiple objects using the same keys to be
stored in an unordered map. The \texttt{unordered\_multimap} container offers the
same set of members and constructors as the \texttt{unordered\_map}, but without the
unique-key restriction imposed upon the \texttt{unordered\_map}.

The \texttt{unordered\_multimap} does not offer \texttt{operator{[}{]}} and does not offer
\texttt{at} members.

Below all members are described whose behavior differs from the behavior of
the corresponding \texttt{unordered\_map} members:

\begin{itemize}
        \item \texttt{at(key\_type const \&key)}\ \\ 
            not supported by the \texttt{unordered\_multimap} container;
        \item \index{count}\texttt{size\_t count(key\_type const \&key)}:\ \\ returns the number of times a \texttt{value\_type} object using
            \texttt{key\_type} \texttt{key} is stored in the \texttt{unordered\_map}. This
            member is commonly used to verify whether \texttt{key} is available in
            the \texttt{unordered\_multimap};
        \item \index{emplace}\texttt{iterator emplace(Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from \texttt{emplace}'s
arguments. The returned \texttt{iterator} points to the newly inserted inserted
\texttt{value\_type};
        \item \index{emplace\_hint}\texttt{iterator emplace\_hint(const\_iterator position,
                            Args \&\&...args)}:\ \\ a \texttt{value\_type} object is constructed from the member's
arguments, and the newly created element is inserted into the
\texttt{unordered\_multimap}. The
implementation may or may not use \texttt{position} as a \emph{hint} to start looking
for an insertion point. The returned \texttt{iterator} points to the \texttt{value\_type}
using the provided key;
    \item \index{equal\_range}\texttt{pair$<$iterator, iterator$>$ equal\_range(key)}:\ \\ this
member returns a pair of iterators  defining the range of elements having a
key that is equal to \texttt{key};
    \item \index{find}\texttt{iterator find(key)}:\ \\ returns an iterator to an element having the given key. If no
such element is available, \texttt{end} is returned;
        \item \index{insert}\texttt{... insert()}:
            \begin{quote}elements may be inserted starting at a certain position. The
return value depends on the version of \texttt{insert()} that is called. When an
\texttt{iterator} is returned, then it points to the element that was inserted.\end{quote}
            \begin{itemize}
            \item \texttt{iterator insert(value\_type const \&value)}
                inserts \texttt{value}.
            \item \texttt{iterator insert(value\_type \&\&tmp)}
                inserts \texttt{value} using \texttt{value\_type}'s move
                constructor.
            \item \texttt{iterator insert(const\_iterator hint, value\_type const \&value)}
                inserts \texttt{value}, possibly using \texttt{hint} as a
starting point when trying to insert \texttt{value}.
            \item \texttt{iterator insert(const\_iterator hint, value\_type \&\&tmp)}
                inserts \texttt{value} using \texttt{value\_type}'s move
constructor, and possibly using \texttt{hint} as a starting point when trying to
insert \texttt{value}.
            \item \texttt{void insert(first, beyond)} inserts the elements in
the iterator range \texttt{[first, beyond)}.
            \item \texttt{void insert(initializer\_list $<$value\_type$>$ iniList)}
                inserts the elements in \texttt{iniList} into the container.
            \end{itemize}
        \end{itemize}

\subsection{Heterogeneous lookup}
    \typeout{Original Yodl file: containers/heterogeneous}The associative containers offered by \textbf{C++} allow us to find a value (or
values) matching a given key. Traditionally, the type of the key used for the
lookup must match the container's key type. 

Arbitrary lookup key types can be used provided a comparison operator is
available to compare that type with the container's key type.  Thus, a \texttt{char
const $*$} key (or any other type for which an \texttt{operator$<$} overload for
\texttt{std::string} is available) can be used to lookup values in a
\texttt{map$<$std::string, ValueType$>$}. This is called
    \index{heterogeneous lookup}\emph{heterogeneous lookup}.

Heterogeneous lookup is allowed when the comparator given to the associative
container does allow this. The standard library classes \texttt{std::less} and
\texttt{std::greater} were augmented to allow heterogeneous lookup.

\section{The `complex' container}\label{COMPLEX}
\typeout{Original Yodl file: containers/complex}The \index{complex}\texttt{complex} container defines the standard operations that can be
performed on \index{complex numbers}complex numbers. Before using \texttt{complex} containers the
header file \index{complex: header file}\texttt{$<$complex$>$} must be included.

The complex number's real and imaginary types are specified as the container's
data type. Examples:
        \begin{verbatim}
    complex<double>
    complex<int>
    complex<float>
\end{verbatim}
Note that the real and imaginary parts of complex numbers have the same
datatypes.

When initializing (or assigning) a complex object, the \index{imaginary part}imaginary part
may be omitted from the initialization or assignment resulting in its value
being 0 (zero). By default, both parts are zero.

Below it is silently assumed that the used \texttt{complex} type is
\texttt{complex$<$double$>$}. Given this assumption, complex numbers may be initialized
as follows:
    \begin{itemize}
    \item \texttt{target}:   A default initialization: real and imaginary parts are 0.
    \item \texttt{target(1)}: The \index{real part}real part is 1, imaginary part is 0
    \item \texttt{target(0, 3.5)}: The real part is 0, imaginary part is 3.5
    \item \texttt{target(source)}: \texttt{target} is initialized with the values of
\texttt{source}.
    \end{itemize}
    Anonymous complex values may also be used. In the next example two
anonymous complex values are pushed on a stack of complex numbers, to be
popped again thereafter:
        \begin{verbatim}
    #include <iostream>
    #include <complex>
    #include <stack>

    using namespace std;

    int main()
    {
        stack<complex<double>>
            cstack;

        cstack.push(complex<double>(3.14, 2.71));
        cstack.push(complex<double>(-3.14, -2.71));

        while (cstack.size())
        {
            cout << cstack.top().real() << ", " <<
                    cstack.top().imag() << "i" << '\n';
            cstack.pop();
        }
    }
    /*
        Generated output:
    -3.14, -2.71i
    3.14, 2.71i
    */
\end{verbatim}
The following member functions and operators are defined for complex
numbers (below, \texttt{value} may be either a primitive \index{scalar type}scalar type or a
\texttt{complex} object):
    \begin{itemize}
        \item  Apart from the standard container operators, the following
operators are supported from the \texttt{complex} container.
        \begin{itemize}
        \item \index{operator+}\texttt{complex operator+(value)}:\ \\  this
member returns the sum of the current \texttt{complex} container and \texttt{value}.
        \item \index{operator-}\texttt{complex operator-(value)}:\ \\  this
member returns the difference between the current \texttt{complex} container and
\texttt{value}.
        \item \index{operator*}\texttt{complex operator$*$(value)}:\ \\  this
member returns the product of the current \texttt{complex} container and
\texttt{value}.
        \item \index{operator/}\texttt{complex operator/(value)}:\ \\  this
member returns the quotient of the current \texttt{complex} container and
\texttt{value}.
        \item \index{operator+=}\texttt{complex operator+=(value)}:\ \\  this
member adds \texttt{value} to the current \texttt{complex} container, returning the
new value.
        \item \index{operator-=}\texttt{complex operator-=(value)}:\ \\ 
this member subtracts \texttt{value} from the current \texttt{complex} container,
returning the new value.
        \item \index{operator*=}\texttt{complex operator$*$=(value)}:\ \\  this
member multiplies the current \texttt{complex} container by \texttt{value}, returning
the new value
        \item \index{operator/=}\texttt{complex operator/=(value)}:\ \\  this
member divides the current \texttt{complex} container by \texttt{value}, returning the
new value.
        \end{itemize}
        \item \index{real}\texttt{Type real()}:\ \\ returns the \index{real part}real part of a
complex number.
        \item \index{imag}\texttt{Type imag()}:\ \\ returns the \index{imaginary part}imaginary part
of a complex number.
        \item  Several \index{mathematical functions}mathematical functions are available for the
\texttt{complex} container, such as \index{abs}\texttt{abs}, \index{arg}\texttt{arg}, \index{conj}\texttt{conj}, \index{cos}\texttt{cos},
\index{cosh}\texttt{cosh}, \index{exp}\texttt{exp}, \index{log}\texttt{log}, \index{norm}\texttt{norm}, \index{polar}\texttt{polar}, \index{pow}\texttt{pow},
\index{sin}\texttt{sin}, \index{sinh}\texttt{sinh} and \index{sqrt}\texttt{sqrt}. All these functions are free functions,
not member functions, accepting complex numbers as their arguments. For
example,
    \begin{verbatim}
abs(complex<double>(3, -5));
pow(target, complex<int>(2, 3));
\end{verbatim}
\item  Complex numbers may be \index{operator\textgreater{}\textgreater{}} extracted from \texttt{istream}
objects and inserted \index{operator\textless{}\textless{}} into \texttt{ostream} objects. The insertion
results in an \index{ordered pair}ordered pair \texttt{(x, y)}, in which \texttt{x} represents the real
part and \texttt{y} the imaginary part of the complex number. The same form may
also be used when extracting a complex number from an \texttt{istream}
object. However, simpler forms are also allowed. E.g., when extracting
\texttt{1.2345} the imaginary part is set to 0.
    \end{itemize}


\cleardoublepage\chapter{Inheritance}\label{INHERITANCE}
\typeout{Original Yodl file: inheritance}\typeout{Original Yodl file: inheritance/intro}When programming in \textbf{C}, programming problems are commonly approached using
a top-down structured approach: functions and actions of the program are
defined in terms of sub-functions, which again are defined in
sub-sub-functions, etc..  This yields a \index{hierarchy of code}hierarchy of code: \texttt{main} at
the top, followed by a level of functions which are called from \texttt{main},
etc..

In \textbf{C++} the \index{relationship between code and data}relationship between code and data is also frequently
defined in terms of dependencies among \emph{classes}. This looks like
\index{composition}\emph{composition} (see section \ref{Composition}), where objects of a class
contain objects of another class as their data. But the relation described
here is of a different kind: a class can be \emph{defined} in terms of an older,
pre-existing, class. This produces a new class having all the functionality of
the older class, and additionally defining its own specific functionality.
Instead of composition, where a given class \emph{contains} another class, we
here refer to \index{derivation}\emph{derivation}, where a given class \emph{is} or
\emph{is-implemented-in-terms-of} another class.

Another term for derivation is \index{inheritance}\emph{inheritance}: the new class inherits the
functionality of an existing class, while the existing class does not appear
as a data member in the interface of the new class. When discussing
inheritance the existing class is called the \index{base class}\emph{base class}, while the new
class is called the \index{derived class}\emph{derived class}.

Derivation of classes is often used when the methodology of \textbf{C++} program
development is fully exploited. In this chapter we first address the
syntactic possibilities offered by \textbf{C++} for deriving classes. Following
this we address some of the specific possibilities offered by
class derivation (inheritance).

As we have seen in the introductory chapter (see section \ref{OOP}), in the
object-oriented approach to problem solving classes are identified during the
\index{problem analysis}problem analysis. Under this approach objects of the defined classes
represent entities that can be observed in the problem at hand. The classes
are placed in a hierarchy, with the top-level class containing limited
functionality.  Each new derivation (and hence descent in the
 \index{class hierarchy}class hierarchy) adds new functionality compared to yet existing classes.

In this chapter we shall use a simple vehicle classification system to build a
hierarchy of classes. The first class is \texttt{Vehicle}, which implements as its
functionality the possibility to set or retrieve the mass of a vehicle. The
next level in the object hierarchy are land-, water- and air vehicles.

The initial \index{object hierarchy}object hierarchy is illustrated in Figure \ref{hierarchy}.
    \begin{figure}[tbp]
\centerline{\epsffile{inheritance/hierarchy.eps}}
\caption{\label{hierarchy}Initial object hierarchy of vehicles.}
\end{figure}

This chapter mainly focuses on the technicalities of class derivation. The
distinction between inheritance used to create derived classes whose objects
should be considered objects of the base class and inheritance used to
implement derived classes \emph{in-terms-of} their base classes is postponed
until the next chapter (\ref{POLYMORPHISM}).

Inheritance (and polymorphism, cf. chapter \ref{POLYMORPHISM}) can be used with
classes and structs. It is not defined for unions.

\section{Related types}\label{VehicleSystem}
    \typeout{Original Yodl file: inheritance/related}The relationship between the proposed classes representing different kinds of
vehicles is further investigated here. The figure shows the object hierarchy:
a \texttt{Car} is a special case of a \texttt{Land} vehicle, which in turn is a
special case of a \texttt{Vehicle}.

The class \texttt{Vehicle} represents the `greatest common divisor' in the
classification system. \texttt{Vehicle} is given limited functionality: it can
store and retrieve a vehicle's mass:
        \begin{verbatim}
    class Vehicle
    {
        size_t d_mass;

        public:
            Vehicle();
            Vehicle(size_t mass);

            size_t mass() const;
            void setMass(size_t mass);
    };
\end{verbatim}
Using this class, the vehicle's mass can be defined as soon as the
corresponding object has been created. At a later stage the mass can be
changed or retrieved.

To represent vehicles traveling over land, a new class \texttt{Land} can be
defined offering \texttt{Vehicle}'s functionality and adding its own specific
functionality. Assume we are interested in the speed of land vehicles \emph{and}
in their mass. The relationship between \texttt{Vehicle}s and \texttt{Land}s could of
course be represented by composition but that would be awkward: composition
suggests that a \texttt{Land} vehicle \emph{is-implemented-in-terms-of}, i.e.,
\emph{contains}, a \texttt{Vehicle}, while the natural relationship clearly is that
the \texttt{Land} vehicle \emph{is} a kind of \texttt{Vehicle}.

A relationship in terms of composition would also somewhat complicate our
\texttt{Land} class's design.  Consider the following example showing a class
\texttt{Land} using composition (only the \texttt{setMass} functionality is shown):
        \begin{verbatim}
    class Land
    {
        Vehicle d_v;        // composed Vehicle
        public:
            void setMass(size_t mass);
    };

    void Land::setMass(size_t mass)
    {
        d_v.setMass(mass);
    }
\end{verbatim}
Using composition, the \texttt{Land::setMass} function only passes its
argument on to \texttt{Vehicle::setMass}. Thus, as far as mass handling is
concerned, \texttt{Land::setMass} introduces no extra functionality, just extra
code. Clearly this code duplication is superfluous: a \texttt{Land} object \emph{is} a
\texttt{Vehicle}; to state that a \texttt{Land} object \emph{contains} a \texttt{Vehicle} is at
least somewhat peculiar.

The intended relationship is represented better by \index{inheritance}inheritance.
        A \index{rule of thumb}rule of thumb for choosing between inheritance and composition
distinguishes between \emph{is-a} and \emph{has-a} relationships. A truck \emph{is} a
vehicle, so \texttt{Truck} should probably derive from \texttt{Vehicle}.  On the other
hand, a truck \emph{has} an engine; if you need to model engines in your system,
you should probably express this by composing an \texttt{Engine} class inside the
\texttt{Truck} class.

Following the above rule of thumb, \texttt{Land} is \emph{derived} from the base class
\texttt{Vehicle}:
        \begin{verbatim}
    class Land: public Vehicle
    {
        size_t d_speed;
        public:
            Land();
            Land(size_t mass, size_t speed);

            void setSpeed(size_t speed);
            size_t speed() const;
    };
\end{verbatim}
To derive a class (e.g., \texttt{Land}) from another class (e.g., \texttt{Vehicle})
postfix the class name \texttt{Land} in its interface by \texttt{: public Vehicle}:
        \begin{verbatim}
    class Land: public Vehicle
\end{verbatim}
The class \texttt{Land} now contains all the functionality of its base class
\texttt{Vehicle} as well as its own features. Here those features are a constructor
expecting two arguments and member functions to access the \texttt{d\_speed} data
member. Here is an example showing the possibilities of the derived class
\texttt{Land}:
        \begin{verbatim}
    Land veh{ 1200, 145 };

    int main()
    {
        cout << "Vehicle weighs " << veh.mass() << ";\n"
                "its speed is " << veh.speed() << '\n';
    }
\end{verbatim}
This example illustrates two features of derivation.
    \begin{itemize}
    \item  First, \texttt{mass} is not mentioned as a member in \texttt{Land}'s
interface. Nevertheless it is used in \texttt{veh.mass}.  This member function is
an implicit part of the class, inherited from its `parent' vehicle.
    \item  Second, although the derived class \texttt{Land} contains the
functionality of \texttt{Vehicle}, the \texttt{Vehicle}'s private members remain
private: they can only be accessed by \texttt{Vehicle}'s own member functions. This
means that \texttt{Land}'s member functions \emph{must} use \texttt{Vehicle}'s member
functions (like \texttt{mass} and \texttt{setMass}) to address the \texttt{mass}
field. Here there's no difference between the access rights granted to
\texttt{Land} and the access rights granted to other code outside of the class
\texttt{Vehicle}. The class \texttt{Vehicle} \index{encapsulation} \emph{encapsulates} the
specific \texttt{Vehicle} characteristics, and \index{data hiding}data hiding is one way to realize
encapsulation.
    \end{itemize}

Encapsulation is a core principle of good class design. Encapsulation
reduces the dependencies among classes improving the maintainability and
testability of classes and allowing us to modify classes without the need to
modify depending code. By strictly complying with the principle of data hiding
a class's internal data organization may change without requiring depending
code to be changed as well. E.g., a class \texttt{Lines} originally storing
\textbf{C}-strings could at some point have its data organization changed. It could
abandon its \texttt{char $*$$*$} storage in favor of a \texttt{vector$<$string$>$} based
storage. When \texttt{Lines} uses perfect data hiding depending source code
may use the new \texttt{Lines} class without requiring any modification at all.

As a \index{rule of thumb}rule of thumb, derived classes must be fully recompiled (but don't
have to be modified) when the \emph{data organization} (i.e., the data members)
of their base classes change.  Adding new member \emph{functions} to the base
class doesn't alter the data organization so no \index{recompilation}recompilation is needed
when new member \emph{functions} are added.

There is one subtle exception to this rule of thumb: if a new member function
is added to a base class and that function happens to be declared as the first
\emph{virtual} member function of the base class (cf. chapter \ref{POLYMORPHISM}
for a discussion of the virtual member function concept) then that
\emph{also} changes the data organization of the base class.

Now that \texttt{Land} has been derived from \texttt{Vehicle} we're ready for our next
class derivation. We'll define a class \texttt{Car} to represent
automobiles. Agreeing that a \texttt{Car} object is a \texttt{Land} vehicle, and that
a \texttt{Car} has a brand name it's easy to design the class \texttt{Car}:
        \begin{verbatim}
    class Car: public Land
    {
        std::string d_brandName;

        public:
            Car();
            Car(size_t mass, size_t speed, std::string const &name);

            std::string const &brandName() const;
    };
\end{verbatim}
In the above class definition, \texttt{Car} was derived from \texttt{Land}, which in
turn is derived from \texttt{Vehicle}. This is called \index{nested derivation}\emph{nested derivation}:
\texttt{Land} is called \texttt{Car}'s \index{direct base class}\emph{direct base class}, while \texttt{Vehicle} is
called \texttt{Car}'s  \index{indirect base class}\emph{indirect base class}.

\subsection{Inheritance depth: desirable?}
        \typeout{Original Yodl file: inheritance/depth}Now that \texttt{Car} has been derived from \texttt{Land} and \texttt{Land} has been derived
from \texttt{Vehicle} we might easily be seduced into thinking that these class
hierarchies are the way to go when designing classes. But maybe we should
temper our enthusiasm.

Repeatedly deriving classes from classes quickly results in big, complex class
hierarchies that are hard to understand, hard to use and hard to
maintain. Hard to understand and use as users of our derived class now also
have to learn all its (indirect) base class features as well. Hard to maintain
because all those classes are very closely coupled. While it may be true that
when data hiding is meticulously adhered to derived classes do not have to be
modified when their base classes alter their data organization, it also
quickly becomes practically infeasible to change those base classes once more
and more (derived) classes depend on their current organization.

What initially looks like a big gain, inheriting the base class's interface,
thus becomes a liability. The base class's interface is hardly ever completely
required and in the end a class may benefit from explicitly defining its own
member functions rather than obtaining them through inheritance.

Often classes can be defined \emph{in-terms-of} existing classes: some of their
features are used, but others need to be shielded off. Consider the \texttt{stack}
container: it is commonly implemented in-terms-of a \texttt{deque}, returning
\texttt{deque::back}'s value as \texttt{stack::top}'s value.

When using inheritance to implement an \emph{is-a} relationship make sure to get
the `direction of use' right: inheritance aiming at implementing an \emph{is-a}
relationship should focus on the base class: the base class facilities aren't
there to be used by the derived class, but the derived class facilities should
redefine (reimplement) the base class facilities using polymorphism (which is
the topic of the next chapter), allowing
code to use the derived class facilities polymorphically through the base
class.  We've seen this approach when studying streams: the base class (e.g.,
\texttt{ostream}) is used time and again. The facilities defined by classes derived
from \texttt{ostream} (like \texttt{ofstream} and \texttt{ostringstream}) are then used by
code only relying on the facilities offered by the \texttt{ostream} class, never
using the derived classes directly.

When designing classes always aim at the lowest possible coupling. Big class
hierarchies usually indicate poor understanding of robust class design. When a
class's interface is only partially used and if the derived class is
implemented in terms of another class consider using composition rather than
inheritance and define the appropriate interface members in terms of the
members offered by the composed objects.

\section{Access rights: public, private, protected}
    \typeout{Original Yodl file: inheritance/accessrights}Early in the \textbf{C++} Annotations (cf. section \ref{HIDING}) we encountered two
important design principles when developing classes: \emph{data hiding} and
\emph{encapsulation}.  Data hiding restricts control over an object's data to the
members of its class, encapsulation is used to restrict access to the
functionality of objects. Both principles are invaluable tools for maintaining
data integrity.

The keyword \texttt{private} starts sections in class interfaces in which members
are declared which can only be accessed by members of the class itself. This
is our main tool for realizing data hiding. According to established good
practices of class design the public sections are populated with member
functions offering a clean interface to the class's functionality. These
members allow users to communicate with objects; leaving it to the objects how
requests sent to objects are handled. In a well-designed class its objects are
in full control of their data.

Inheritance doesn't change these principles, nor does it change the way the
`\texttt{private}' and `\texttt{protected}' keywords operate. A derived class does not
have access to a base class's private section.

Sometimes this is a bit too restrictive. Consider a class implementing a
random number generating \texttt{streambuf} (cf. chapter \ref{IOStreams}). Such a
\texttt{streambuf} can be used to construct an \texttt{istream irand}, after which
extractions from \texttt{irand} produces series of random numbers, like in the next
example in which 10 random numbers are generated using stream I/O:
            \begin{verbatim}
    RandBuf buffer;
    istream irand(&buffer);

    for (size_t idx = 0; idx != 10; ++idx)
    {
        size_t next;
        irand >> next;
        cout << "next random number: " << next << '\n';
    }
\end{verbatim}
The question is, how many random numbers should \texttt{irand} be able to
generate? Fortunately, there's no need to answer this question, as
\texttt{RandBuf} can be made responsible for generating the next random
number. RandBuf, therefore, operates as follows:
        \begin{itemize}
        \item  It generates a random number;
        \item  It is passed in textual form to its base class \texttt{streambuf};
        \item  The \texttt{istream} object extracts this random number, merely
            using \texttt{streambuf}'s interface;
        \end{itemize}
        (this process is repeated for subsequent random numbers).

Once \texttt{RandBuf} has stored the text representation of the next
random number in some buffer, it must tell its base class (\texttt{streambuf})
where to find the random number's characters. For this \texttt{streambuf} offers a
member \texttt{setg}, expecting the location and size of the buffer holding the
random number's characters.

The member \texttt{setg} clearly cannot be declared in \texttt{streambuf}'s
private section, as \texttt{RandBuf} must use it to prepare for the
extraction of the next random number. But it should also not be in
\texttt{streambuf}'s public section, as that could easily result in unexpected
behavior by \texttt{irand}. Consider the following hypothetical example:
        \begin{verbatim}
    RandBuf randBuf;
    istream irand(&randBuf);

    char buffer[] = "12";
    randBuf.setg(buffer, ...);  // setg public: buffer now contains 12

    size_t next;
    irand >> next;              // not a *random* value, but 12.
\end{verbatim}
Clearly there is a close connection between \texttt{streambuf} and its derived
class \texttt{RandBuf}. By allowing \texttt{RandBuf} to specify the buffer from
which \texttt{streambuf} reads characters \texttt{RandBuf} remains in control,
denying other parts of the program to break its well-defined behavior.

This close connection between base- and derived-classes is realized by a third
keyword related to the accessibility of class members: \index{protected}\texttt{protected}. Here is
how the member \texttt{setg} could have been be declared in a class \texttt{streambuf}:
        \begin{verbatim}
    class streambuf
    {
        // private data here (as usual)
        protected:
            void setg(... parameters ...);  // available to derived classes

        public:
            // public members here
    };
\end{verbatim}
Protected members are members that can be accessed by derived classes, but are
not part of a class's public interface.

Avoid the temptation to declare \emph{data members} in a class's protected
section: it's a sure sign of bad class design as it needlessly results in
tight coupling of base and derived classes. The principle of \index{data hiding}data hiding
should not be abandoned now that the keyword \texttt{protected} has been
introduced. If a derived class (but not other parts of the software) should
be given access to its base class's data, use member functions:
accessors and modifiers declared in the base class's protected
section. This enforces the intended restricted access without resulting in
tightly coupled classes.

\subsection{Public, protected and private derivation}\label{DERIVATIONTYPES}
        \typeout{Original Yodl file: inheritance/derivationtypes}With inheritance public derivation is frequently used. When public derivation
is used the access rights of the base class's interface remains unaltered in
the derived class. But the type of inheritance may also be defined as
\emph{private} or \emph{protected}.

Protected derivation is used when the keyword \texttt{protected} is put in front of
the derived class's base class:
        \begin{verbatim}
    class Derived: protected Base
\end{verbatim}
When protected derivation is used all the base class's public and
protected members become protected members in the derived class. The derived
class may access all the base class's public and protected members. Classes
that are in turn derived from the derived class view the base class's members
as protected. Any other code (outside of the inheritance tree) is unable to
access the base class's members.

Private derivation is used when the keyword \texttt{private} is put in front of the
derived class's base class:
        \begin{verbatim}
    class Derived: private Base
\end{verbatim}
When private derivation is used all the base class's members turn into
private members in the derived class. The derived class members may access
all base class public and protected members but base class members cannot be
used elsewhere.

Public derivation should be used to define an \emph{is-a} relationship
between a derived class and a base class: the derived class object \emph{is-a}
base class object allowing the derived class object to be used polymorphically
as a base class object in code expecting a base class object. Private
inheritance is used in situations where a derived class object is defined
in-terms-of the base class where composition cannot be used. There's little
documented use for protected inheritance, but one could maybe encounter
protected inheritance when defining a base class that is itself a derived
class making its base class members available to classes derived from it.

Combinations of inheritance types do occur. For example, when designing a
stream-class it is usually derived from \texttt{std::istream} or
\texttt{std::ostream}. However, before a stream can be constructed, a
\texttt{std::streambuf} must be available. Taking advantage of the fact that the
inheritance order is defined in the class interface, we use multiple
inheritance (see section \ref{MULTIPLE}) to derive the class from both
\texttt{std::streambuf} and (then) from \texttt{std::ostream}. To the class's users it
is a \texttt{std::ostream} and not a \texttt{std::streambuf}. So private derivation is
used for the latter, and public derivation for the former class:
        \begin{verbatim}
    class Derived: private std::streambuf, public std::ostream
\end{verbatim}
\subsection{Promoting access rights}\label{ACCESSPROMOTION}
        \typeout{Original Yodl file: inheritance/accessprom}When private or protected derivation is used, users of derived class objects
are denied access to the base class members. Private derivation denies access
to all base class members to users of the derived class, protected derivation
does the same, but allows classes that are in turn derived from the derived
class to access the base class's public and protected members.

In some situations this scheme is too
    \index{private derivation: too restrictive}
    \index{protected derivation: too restrictive}
        restrictive. Consider a class \texttt{RandStream} derived privately from a
class \texttt{RandBuf} which is itself derived from \texttt{std::streambuf} and also
publicly from \texttt{istream}:
        \begin{verbatim}
    class RandBuf: public std::streambuf
    {
        // implements a buffer for random numbers
    };
    class RandStream: private RandBuf, public std::istream
    {
        // implements a stream to extract random values from
    };
\end{verbatim}
Such a class could be used to extract, e.g., random numbers using the
standard \texttt{istream} interface.

Although the \texttt{RandStream} class is constructed with the
functionality of \texttt{istream} objects in mind, some of the members of the class
\texttt{std::streambuf} may be considered useful by themselves. E.g., the function
\texttt{streambuf::in\_avail} returns a lower bound to the number of characters
that can be read immediately. The standard way to make this function available
is to define a \index{shadow member}\emph{shadow member} calling the base class's member:
        \begin{verbatim}
    class RandStream: private RandBuf, public std::istream
    {
        // implements a stream to extract random values from
        public:
            std::streamsize in_avail();
    };
    inline std::streamsize RandStream::in_avail()
    {
        return std::streambuf::in_avail();
    }
\end{verbatim}
This looks like a lot of work for just making available a member from the
protected or private base classes. If the intent is to make available the
    \index{inheritance: access to base class member} \texttt{in\_avail} member
\index{access promotion}\emph{access promotion} can be used. Access promotion allows us to specify which
members of private (or protected) base classes become available in the
protected (or public) interface of the derived class. Here is the above
example, now using access promotion:
        \begin{verbatim}
    class RandStream: private RandBuf, public std::istream
    {
        // implements a stream to extract random values from
        public:
            using std::streambuf::in_avail;
    };
\end{verbatim}
It should be noted that access promotion makes available all overloaded
versions of the declared base class member. So, if \texttt{streambuf} would offer
not only \texttt{in\_avail} but also, e.g., \texttt{in\_avail(size\_t $*$)} \emph{both}
members would become part of the public interface.

\section{The constructor of a derived class}
    \typeout{Original Yodl file: inheritance/constructor}A derived class inherits functionality from its base class (or base classes,
as \textbf{C++} supports multiple inheritance, cf. section \ref{MULTIPLE}). When a
derived class object is constructed it is built on top of its base class
object. As a consequence the base class must have been constructed before the
actual derived class elements can be initialized. This results in some
requirements that must be observed when defining
 \index{constructor: of derived classes} derived class constructors.

A constructor exists to initialize the object's data members. A derived class
constructor is also responsible for the proper initialization of its base
class. Looking at the definition of the class \texttt{Land} introduced earlier
(section \ref{VehicleSystem}), its constructor could simply be defined as
follows:
        \begin{verbatim}
    Land::Land(size_t mass, size_t speed)
    {
        setMass(mass);
        setSpeed(speed);
    }
\end{verbatim}
However, this implementation has several disadvantages.
    \begin{itemize}
    \item  When constructing a derived class object a base class constructor is
\emph{always} called before any action is performed on the derived class object
itself. By default the base class's \index{default constructor}default constructor is going to be
called.
    \item  Using the base class constructor only to reassign new values to its
data members in the derived class constructor's body usually is inefficient,
but sometimes sheer impossible as in situations where base class reference or
\texttt{const} data members must be initialized. In those cases a specialized base
class constructor must be used instead of the base class default constructor.
    \end{itemize}
    A derived class's base class may be initialized using a dedicated base
class constructor by calling the base class constructor in the derived class
constructor's initializer clause. Calling a base class constructor in a
constructor's initializer clause is called a
 \index{base class initializer}\emph{base class initializer}. The base class initializer must be called before
initializing any of the derived class's data members and when using the base
class initializer none of the derived class data members may be used. When
constructing a derived class object the base class is constructed first and
only after that construction has successfully completed
the derived class data members are available for initialization. \texttt{Land}'s
constructor may therefore be improved:
        \begin{verbatim}
    Land::Land(size_t mass, size_t speed)
    :
        Vehicle(mass),
        d_speed(speed)
    {}
\end{verbatim}
Derived class constructors always by default call their base class's
default constructor. This is of course not correct for a derived class's
 \index{copy constructor}copy constructor. Assuming that the class \texttt{Land} must be provided with a
copy constructor its \texttt{Land const \&other} parameter also represents the other
object's base class:
        \begin{verbatim}
    Land::Land(Land const &other)   // assume a copy constructor is needed
    :
        Vehicle(other),             // copy-construct the base class part.
        d_speed(other.d_speed)      // copy-construct Land's data members
    {}
\end{verbatim}
\subsection{Move construction}
        \typeout{Original Yodl file: inheritance/move}As with classes using composition derived classes may benefit from defining a
 \index{move constructor}move constructor.
A derived class may offer a move constructor for two reasons:
    \begin{itemize}
    \item  it supports move construction for its  data members
    \item  its base class is move-aware
    \end{itemize}

The design of move constructors moving data members was covered in section
\ref{MOVE}. A move constructor for a derived class whose base class is
move-aware must \emph{anonymize} the rvalue reference before passing it to the
base class move constructor. The \texttt{std::move} function should be used when
implementing the move constructor to move the information in base classes or
composed objects to their new destination object.

The first example shows the move constructor for the class \texttt{Car},
assuming it has a movable \texttt{char $*$d\_brandName} data member and
assuming that \texttt{Land} is a move-aware class. The second example shows the
move constructor for the class \texttt{Land}, assuming that it does not itself have
movable data members, but that its \texttt{Vehicle} base class is move-aware:
        \begin{verbatim}
    Car::Car(Car &&tmp)
    :
        Land(std::move(tmp)),           // anonymize `tmp'
        d_brandName(tmp.d_brandName)    // move the char *'s value
    {
        tmp.d_brandName = 0;
    }

    Land(Land &&tmp)
    :
        Vehicle(std::move(tmp)),    // move-aware Vehicle
        d_speed(tmp.d_speed)        // plain copying of plain data
    {}
\end{verbatim}
\subsection{Move assignment}
        \typeout{Original Yodl file: inheritance/assignment}Derived classes may also benefit from move assignment operations. If the
derived class and its base class support swapping then the implementation is
simple, following the standard shown earlier in section \ref{MOVEASS}. For the
class \texttt{Car} this could boil down to:
        \begin{verbatim}
    Car &Car::operator=(Car &&tmp)
    {
        swap(tmp);
        return *this;
    }
\end{verbatim}
If swapping is not supported then \texttt{std::move} can be used to call the
base class's move assignment operator:
        \begin{verbatim}
    Car &Car::operator=(Car &&tmp)
    {
        static_cast<Land &>(*this) = std::move(tmp);
        // move Car's own data members next
        return *this;
    }
\end{verbatim}
\subsection{Inheriting constructors}\label{BASECONS}
        \typeout{Original Yodl file: inheritance/usingbase}Derived classes can be constructed without
        \index{inheritance: no derived class constructors}
    explicitly defining derived class constructors. In those cases the
available base class constructors are called.

This feature is either used or not. It is not possible to omit some of the
derived class constructors, using the corresponding base class constructors
instead. To use this feature for classes that are derived from multiple base
classes (cf. section \ref{MULTIPLE}) all the base class constructors must
have different signatures. Considering the complexities that are involved here
it's probably best to avoid using base class constructors for classes using
multiple inheritance.

The construction of derived class objects can be delegated to
 \index{construction: delegate to base classes} base class constructor(s) using
the following syntax:
        \begin{verbatim}
    class BaseClass
    {
        public:
            // BaseClass constructor(s)
    };

    class DerivedClass: public BaseClass
    {
        public:
            using BaseClass::BaseClass; // No DerivedClass constructors
                                        // are defined
    };
\end{verbatim}
\subsection{Aggregate Initializations}
        \typeout{Original Yodl file: inheritance/aggregate}    Aggregates \index{aggregate initialization}(e.g., structs) can be initialized
using the familiar curly brace notation. Curly brace notations can also be
used when initializing base-structs of derived-structs. Each base-level struct
receives its own set of curly braces while initializing the derived-level
struct. Here is an example:
        \begin{verbatim}
    struct Base
    {
        int value;
    };
    struct Derived: public Base
    {
        string text;
    };

    // Initializiation of a Derived object:
    
    Derived der{{value}, "hello world"};
    //          -------
    //          initialization of Derived's base struct.
\end{verbatim}
\section{The destructor of a derived class}
    \typeout{Original Yodl file: inheritance/destructor}Destructors
 \index{destructor: derived class} of classes are automatically called when an
object is destroyed. This also holds true for objects of classes derived from
other classes. Assume we have the following situation:
        \begin{verbatim}
    class Base
    {
        public:
            ~Base();
    };

    class Derived: public Base
    {
        public:
            ~Derived();
    };

    int main()
    {
        Derived derived;
    }
\end{verbatim}
At the end of \texttt{main}, the \texttt{derived} object ceases to exists. Hence,
its destructor (\texttt{\textasciitilde{}Derived}) is called. However, since \texttt{derived} is also a
\texttt{Base} object, the \texttt{\textasciitilde{}Base} destructor is called as well.  The base class
destructor is never explicitly called from the derived class destructor.

Constructors
 \index{constructor: calling order} \index{destructor: calling order} and destructors
are called in a stack-like fashion: when \texttt{derived} is constructed, the
appropriate base class constructor is called first, then the appropriate
derived class constructor is called. When the object \texttt{derived} is destroyed,
its destructor is called first, automatically followed by the activation of
the \texttt{Base} class destructor. A \index{derived class destructor}derived class destructor is always called
before its \index{base class destructor}base class destructor is called.

When the construction of a derived class object did not successfully complete
(i.e., the constructor threw an exception) then its destructor is not
called. However, the destructors of properly constructed base classes \emph{will}
be called if a derived class constructor throws an exception. This, of course,
is how it should be: a properly constructed object should also be destroyed,
eventually. Example:
        \begin{verbatim}
    #include <iostream>
    struct Base
    {
        ~Base()
        {
            std::cout << "Base destructor\n";
        }
    };
    struct Derived: public Base
    {
        Derived()
        {
            throw 1;    // at this time Base has been constructed
        }
    };
    int main()
    {
        try
        {
            Derived d;
        }
        catch (...)
        {}
    }
    /*
        This program displays `Base destructor'
    */
\end{verbatim}
\section{Redefining member functions}\label{Truck}
    \typeout{Original Yodl file: inheritance/redefining}Derived classes may redefine base class members.  Let's assume that a vehicle
classification system must also cover trucks, consisting of two parts: the
front part, the tractor, pulls the rear part, the trailer. Both the
tractor and the trailer have their own mass, and the \texttt{mass} function
should return the combined mass.

The definition of a \texttt{Truck} starts with a class definition. Our initial
\texttt{Truck} class is derived from \texttt{Car} but it is then expanded to hold one
more \texttt{size\_t} field representing the additional mass information. Here we
choose to represent the mass of the tractor in the \texttt{Car} class and to store
the mass of a full truck (tractor + trailer) in its own \texttt{d\_mass} data
member: 
        \begin{verbatim}
    class Truck: public Car
    {
        size_t d_mass;

        public:
            Truck();
            Truck(size_t tractor_mass, size_t speed, char const *name,
                  size_t trailer_mass);

            void setMass(size_t tractor_mass, size_t trailer_mass);
            size_t mass() const;
    };

    Truck::Truck(size_t tractor_mass, size_t speed, char const *name,
                 size_t trailer_mass)
    :
        Car(tractor_mass, speed, name),
        d_mass(tractor_mass + trailer_mass)
    {}
\end{verbatim}
Note that the class \texttt{Truck} now contains two functions already
present in the base class \texttt{Car}: \texttt{setMass} and \texttt{mass}.
    \begin{itemize}
    \item  The redefinition of \texttt{setMass} poses no problems: this
function is simply redefined to perform actions which are specific to a
\texttt{Truck} object.
    \item  Redefining \texttt{setMass}, however,
    \index{hiding: base class  members} \index{base class: hiding members} \emph{hides}
\texttt{Car::setMass}. For a \texttt{Truck} only the \texttt{setMass} function having
two \texttt{size\_t} arguments can be used.
    \item  The \texttt{Vehicle}'s \texttt{setMass} function remains available for a
\texttt{Truck}, but it must now be
 \index{member function: called explicitly} called \emph{explicitly}, as
\texttt{Car::setMass} is hidden from view.  This latter function is hidden,
even though \texttt{Car::setMass} has only one \texttt{size\_t} argument. To implement
\texttt{Truck::setMass} we could write:
     \begin{verbatim}
void Truck::setMass(size_t tractor_mass, size_t trailer_mass)
{
    d_mass = tractor_mass + trailer_mass;
    Car::setMass(tractor_mass);     // note: Car:: is required
}
\end{verbatim}
\item  Outside of the class \texttt{Car::setMass} is
accessed using the \index{scope resolution operator}scope resolution operator. So, if a \texttt{Truck truck} needs
to set its \texttt{Car} mass, it must use
    \begin{verbatim}
truck.Car::setMass(x);
\end{verbatim}
\item  An alternative to using the scope resolution operator is to add a
member having the same function prototype as the base class member to the
derived class's interface. This derived class member could be implemented
inline to call the base class member. E.g., we add the following member to the
\texttt{class Truck}:
    \begin{verbatim}
// in the interface:
void setMass(size_t tractor_mass);

// below the interface:
inline void Truck::setMass(size_t tractor_mass)
{
    (d_mass -= Car::mass()) += tractor_mass;
    Car::setMass(tractor_mass);
}
\end{verbatim}
Now the single argument \texttt{setMass} member function can be used by
\texttt{Truck} objects without using the scope resolution operator. As the
function is defined inline, no overhead of an additional function call is
involved.

\item  \index{derived class: using declaration}\index{using: in derived classes} To
prevent hiding the base class members a \texttt{using} declaration may be added to
the derived class interface. The relevant section of \texttt{Truck}'s class
interface then becomes:
    \begin{verbatim}
class Truck: public Car
{
    public:
        using Car::setMass;
        void setMass(size_t tractor_mass, size_t trailer_mass);
};
\end{verbatim}
A using declaration imports (all overloaded versions of) the mentioned
member function directly into the derived class's interface. If a base class
member has a signature that is identical to a derived class member then
compilation fails (a \texttt{using Car::mass} declaration cannot be added to
\texttt{Truck}'s interface). Now code may use \texttt{truck.setMass(5000)} as well as
\texttt{truck.setMass(5000, 2000)}.

Using declarations obey access rights. To prevent non-class members from
using \texttt{setMass(5000)} without a scope resolution operator but allowing
derived class members to do so the \texttt{using Car::setMass} declaration
should be put in the class \texttt{Truck}'s private section.

\item  The function \texttt{mass} is also already defined in \texttt{Car}, as
it was inherited from \texttt{Vehicle}. In this case, the class \texttt{Truck} 
\emph{redefines} this member function to return the truck's full mass:
     \begin{verbatim}
size_t Truck::mass() const
{
    return d_mass;
}
\end{verbatim}
\end{itemize}
    Example:
        \begin{verbatim}
    int main()
    {
        Land vehicle{ 1200, 145 };
        Truck lorry{ 3000, 120, "Juggernaut", 2500 };
    
        lorry.Vehicle::setMass(4000);
    
        cout << '\n' << "Tractor weighs " <<
                        lorry.Vehicle::mass() << '\n' <<
            "Truck + trailer weighs " << lorry.mass() << '\n' <<
            "Speed is " << lorry.speed() << '\n' <<
            "Name is " << lorry.name() << '\n';
    }
\end{verbatim}
The class \texttt{Truck} was derived from \texttt{Car}. However, one might question
this class design. Since a truck is conceived of as a combination of a
tractor and a trailer it is probably better defined using a mixed design,
using inheritance for the tractor part (inheriting from \texttt{Car}, and
composition for the trailer part).

This redesign changes our point of view from a \texttt{Truck} \emph{being} a \texttt{Car}
(and some strangely added data members) to a \texttt{Truck} still \emph{being} an
\texttt{Car} (the tractor) and \emph{containing} a \texttt{Vehicle} (the trailer).

\texttt{Truck}'s interface is now very specific, not requiring users to study
\texttt{Car}'s and \texttt{Vehicle}'s interfaces and it opens up possibilities for
defining `road trains': tractors towing multiple trailers. Here is an example
of such an alternate class setup:
        \begin{verbatim}
    class Truck: public Car    // the tractor
    {
        Vehicle d_trailer;      // use vector<Vehicle> for road trains

        public:
            Truck();
            Truck(size_t tractor_mass, size_t speed, char const *name,
                  size_t trailer_mass);

            void setMass(size_t tractor_mass, size_t trailer_mass);
            void setTractorMass(size_t tractor_mass);
            void setTrailerMass(size_t trailer_mass);

            size_t tractorMass() const;
            size_t trailerMass() const;
        // consider:
            Vehicle const &trailer() const;
    };
\end{verbatim}
\section{Multiple inheritance}\label{MULTIPLE}
    \typeout{Original Yodl file: inheritance/multiple}Except for the class \texttt{Randbuf} classes thus far have always been derived
from a single base class. In addition to \index{single inheritance}single inheritance 
    \index{inheritance: multiple} 
    \textbf{C++} also supports \index{multiple inheritance}\emph{multiple inheritance}. In multiple inheritance a
class is derived from several base classes and hence inherits functionality
from multiple parent classes at the same time.

When using multiple inheritance it should be defensible to consider the
newly derived class an instantiation of both base classes. Otherwise,
\index{composition}composition is more appropriate. In general, linear derivation (using only
one base class) is used much more frequently than multiple derivation. Good
class design dictates that a class should have a single, well described
responsibility and that principle often conflicts with multiple inheritance
where we can state that objects of class \texttt{Derived} are \emph{both} \texttt{Base1}
\emph{and} \texttt{Base2} objects.

But then, consider \emph{the} prototype of an object for which
multiple inheritance was used to its extreme: the
    \index{Swiss army knife}\emph{Swiss army knife}! This object \emph{is} a knife, it \emph{is} a pair of
scissors, it \emph{is} a can-opener, it \emph{is} a corkscrew, it \emph{is} ....

The `Swiss army knife' is an extreme example of multiple inheritance. In
\textbf{C++} there \emph{are} various good arguments for using multiple inheritance as
well, without violating the `one class, one responsibility' principle. We
postpone those arguments until the next chapter. The
current section concentrates on the technical details of constructing classes
using multiple inheritance.

How to construct a `Swiss army knife' in \textbf{C++}? First we need (at least)
two base classes. For example, let's assume we are designing a toolkit
allowing us to construct an instrument panel of an aircraft's cockpit. We
design all kinds of instruments, like an artificial horizon and an
altimeter. One of the components that is often seen in aircraft is a
\emph{nav-com set}: a combination of a navigational beacon receiver (the `nav'
part) and a radio communication unit (the `com'-part). To define the nav-com
set, we start by designing the \texttt{NavSet} class (assume the existence of the
classes \texttt{Intercom, VHF\_Dial} and \texttt{Message}):
        \begin{verbatim}
    class NavSet
    {
        public:
            NavSet(Intercom &intercom, VHF_Dial &dial);

            size_t activeFrequency() const;
            size_t standByFrequency() const;

            void setStandByFrequency(size_t freq);
            size_t toggleActiveStandby();
            void setVolume(size_t level);
            void identEmphasis(bool on_off);
    };
\end{verbatim}
Next we design the class  \texttt{ComSet}:
        \begin{verbatim}
    class ComSet
    {
        public:
            ComSet(Intercom &intercom);

            size_t frequency() const;
            size_t passiveFrequency() const;

            void setPassiveFrequency(size_t freq);
            size_t toggleFrequencies();

            void setAudioLevel(size_t level);
            void powerOn(bool on_off);
            void testState(bool on_off);
            void transmit(Message &message);
    };
\end{verbatim}
Using objects of this class we can receive messages, transmitted
though the \texttt{Intercom}, but we can also \emph{transmit} messages using a
\texttt{Message} object that's passed to the \texttt{ComSet} object using its
\texttt{transmit} member function.

Now we're ready to construct our \texttt{NavCom} set:
        \begin{verbatim}
    class NavComSet: public ComSet, public NavSet
    {
        public:
            NavComSet(Intercom &intercom, VHF_Dial &dial);
    };
\end{verbatim}
Done. Now we have defined a \texttt{NavComSet} which is \emph{both} a \texttt{NavSet}
\emph{and} a \texttt{ComSet}: the facilities of both base classes  are now
available in the derived class using multiple inheritance.

Please note the following:
    \begin{itemize}
    \item  The keyword \index{public}\texttt{public} is present before both base class names
(\texttt{NavSet} and \texttt{ComSet}). By default inheritance uses
 \index{private derivation}\emph{private derivation} and the keyword \texttt{public} must be repeated before
each of the base class specifications. Base classes are not required to use
the same derivation type. One base class could have \texttt{public} derivation and
another base class could use \texttt{private} derivation.
    \item  The multiply derived class \texttt{NavComSet} introduces no additional
functionality of its own, but merely combines two existing classes into a new
aggregate class. Thus, \textbf{C++} offers the possibility to simply sweep
multiple simple classes into one more complex class.
    \item  Here is the implementation of The \texttt{NavComSet} \index{constructor}constructor:
    \begin{verbatim}
NavComSet::NavComSet(Intercom &intercom, VHF_Dial &dial)
:
    ComSet(intercom),
    NavSet(intercom, dial)
{}
\end{verbatim}
The constructor requires no extra code: Its purpose is to activate
the constructors of its base classes. The order in which the base class
initializers \index{base class initializers: calling order}
    \index{calling order of base class initializers} are called is \emph{not}
dictated by their calling order in the constructor's code, but by the ordering
of the base classes in the class interface.
    \item  The \texttt{NavComSet} class definition requires no additional data
members or member functions: here (and often) the inherited interfaces provide
all the required functionality and data for the multiply derived class to
operate properly.
    \end{itemize}
    Of course, while defining the base classes, we made life easy on ourselves
by strictly using different member function names. So, there is a function
\texttt{setVolume} in the \texttt{NavSet} class and a function \texttt{setAudioLevel} in the
\texttt{ComSet} class. A bit cheating, since we could expect that both units in
fact have a composed object \texttt{Amplifier}, handling the volume setting. A
revised class might offer an \texttt{Amplifier \&amplifier() const} member function,
and leave it to the application to set up its own interface to the
amplifier. Alternatively, a revised class could define members for setting the
volume of either the \texttt{NavSet} or the \texttt{ComSet} parts.

In situations where two base classes offer identically named members
 \index{identically named member functions}\index{member function: identically named}
special provisions need to be made to prevent ambiguity:
    \begin{itemize}
    \item  The intended base class can explicitly be specified using the base
class name and \index{scope resolution operator}scope resolution operator:
    \begin{verbatim}
NavComSet navcom(intercom, dial);

navcom.NavSet::setVolume(5);    // sets the NavSet volume level
navcom.ComSet::setVolume(5);    // sets the ComSet volume level
\end{verbatim}
\item  The class interface is provided with member functions that can be
called unambiguously. These additional members are usually defined \texttt{inline}:
    \begin{verbatim}
class NavComSet: public ComSet, public NavSet
{
    public:
        NavComSet(Intercom &intercom, VHF_Dial &dial);
        void comVolume(size_t volume);
        void navVolume(size_t volume);
};
inline void NavComSet::comVolume(size_t volume)
{
    ComSet::setVolume(volume);
}
inline void NavComSet::navVolume(size_t volume)
{
    NavSet::setVolume(volume);
}
\end{verbatim}
\item  If the \texttt{NavComSet} class is obtained from a third party, and cannot
be modified, a disambiguating \index{wrapper class}wrapper class may be used:
    \begin{verbatim}
class MyNavComSet: public NavComSet
{
    public:
        MyNavComSet(Intercom &intercom, VHF_Dial &dial);
        void comVolume(size_t volume);
        void navVolume(size_t volume);
};
inline MyNavComSet::MyNavComSet(Intercom &intercom, VHF_Dial &dial)
:
    NavComSet(intercom, dial);
{}
inline void MyNavComSet::comVolume(size_t volume)
{
    ComSet::setVolume(volume);
}
inline void MyNavComSet::navVolume(size_t volume)
{
    NavSet::setVolume(volume);
}
\end{verbatim}
\end{itemize}

\section{Conversions between base classes and derived classes}
    \typeout{Original Yodl file: inheritance/conversions}When public inheritance is used to define classes, an object of a derived
class \emph{is} at the same time an object of the base class.  This has important
consequences for object assignment and for the situation where pointers or
references to such objects are used. Both situations are now discussed.

\subsection{Conversions with object assignments}
        \typeout{Original Yodl file: inheritance/objectconv}Continuing our discussion of the \texttt{NavCom} class, introduced in section
\ref{MULTIPLE}, we now define two objects, a base class and a derived class
object:
        \begin{verbatim}
    ComSet com(intercom);
    NavComSet navcom(intercom2, dial2);
\end{verbatim}
The object \texttt{navcom} is constructed using an \texttt{Intercom} and a
\texttt{VHF\_Dial} object. However, a \texttt{NavComSet} is at the same time a
\texttt{ComSet}, allowing the \index{assignment}assignment \emph{from} \texttt{navcom} (a derived class
object) \emph{to} \texttt{com} (a base class object):
        \begin{verbatim}
    com = navcom;
\end{verbatim}
The effect of this assignment is that the object \texttt{com} now
communicates with \texttt{intercom2}.  As a \texttt{ComSet} does not have a \texttt{VHF\_Dial},
the \texttt{navcom}'s \texttt{dial} is ignored by the assignment. When assigning a
base class object from a derived class object only the base class data members
are assigned, other data members are dropped, a phenomenon called
\index{slicing}\emph{slicing}. In situations like these slicing probably does not have serious
consequences, but when passing derived class objects to functions defining
base class parameters or when returning derived class objects from functions
returning base class objects slicing also occurs and might have unwelcome
side-effects.

The assignment from a base class object to a derived class object is
problematic. In a statement like
        \begin{verbatim}
    navcom = com;
\end{verbatim}
it isn't clear how to reassign the \texttt{NavComSet}'s \texttt{VHF\_Dial} data
member as they are missing in the \texttt{ComSet} object \texttt{com}. Such an
assignment \index{assignment: refused} is therefore refused by the
compiler. Although derived class objects are also base class objects, the
reverse does not hold true: a base class object is not also a derived class
object.

The following general rule applies: in assignments in which base class
objects and derived class objects are involved, assignments in which data are
dropped are legal (called \emph{slicing}). Assignments in which data remain
unspecified are \emph{not} allowed.  Of course, it is possible to overload an
assignment operator to allow the assignment of a derived class object from a
base class object.  To compile the statement
        \begin{verbatim}
    navcom = com;
\end{verbatim}
the class \texttt{NavComSet} must have defined an overloaded assignment
operator accepting a \texttt{ComSet} object for its argument. In that case it's up
to the programmer to decide what the assignment operator will do with the
missing data.

\subsection{Conversions with pointer assignments}
        \typeout{Original Yodl file: inheritance/pointerconv}    We return to our \texttt{Vehicle} classes, and define the following objects and
pointer variable:
        \begin{verbatim}
    Land land(1200, 130);
    Car car(500, 75, "Daf");
    Truck truck(2600, 120, "Mercedes", 6000);
    Vehicle *vp;
\end{verbatim}
Now we can assign the  addresses of the three objects of
the derived classes to the \texttt{Vehicle} pointer:
        \begin{verbatim}
    vp = &land;
    vp = &car;
    vp = &truck;
\end{verbatim}
Each of these assignments is acceptable. However, an
    \index{implicit conversion}implicit conversion of the \index{derived class}derived class to the \index{base class}base class
\texttt{Vehicle} is used, since \texttt{vp} is defined as a pointer to a
\texttt{Vehicle}. Hence, when using \texttt{vp} only the member functions manipulating
\texttt{mass} can be called as this is the \texttt{Vehicle}'s \emph{only} functionality.
As far as the compiler can tell this is the object \texttt{vp} points to.

The same holds true for \index{reference} references to
\texttt{Vehicles}. If, e.g., a function is defined having a \texttt{Vehicle} reference
parameter, the function may be passed an object of a class derived from
\texttt{Vehicle}. Inside the function, the specific \texttt{Vehicle} members remain
accessible. This analogy between pointers and references holds true in
general. Remember that a reference is nothing but a \index{pointer in disguise}pointer in disguise: it
mimics a plain variable, but actually it is a pointer.

This restricted functionality has an important consequence
for the class \texttt{Truck}. Following  \texttt{vp = \&truck}, \texttt{vp} points to
a \texttt{Truck} object. So, \texttt{vp-$>$mass()} returns 2600 instead of
8600 (the combined mass of the cabin and of the trailer: 2600 + 6000),
which would have been returned by \texttt{truck.mass()}.

\index{pointer: to an object}
    When a function is called using a pointer to an object, then the
    \index{type of the pointer}\emph{type of the pointer} (and not the type of the object) determines
which
    \index{available member functions} \index{member function: available} member
functions are available and can be executed.  In other words, \textbf{C++}
implicitly converts the type of an object reached through a pointer to the
pointer's type.

If the actual type of the object pointed to by a pointer is known, an
explicit type cast can be used to access the full set of member functions
that are available for the object: \index{static\_cast}
        \begin{verbatim}
    Truck truck;
    Vehicle *vp;

    vp = &truck;        // vp now points to a truck object

    Truck *trp;

    trp = static_cast<Truck *>(vp);
    cout << "Make: " << trp->name() << '\n';
\end{verbatim}
Here, the second to last statement specifically casts a \texttt{Vehicle $*$}
variable to a \texttt{Truck $*$}. As usual (when using casts), this code
is not without risk. It \emph{only} works  if \texttt{vp} really points to a
\texttt{Truck}. Otherwise the program may produce unexpected results.

\section{Using non-default constructors with new{[}{]}}\label{NONDEFINIT}
    \typeout{Original Yodl file: inheritance/nondefault}An often heard complaint is that operator \texttt{new{[}{]}} calls the default
constructor
 \index{new[]: and non-default constructors} of a class to initialize the
allocated objects. For example, to allocate an array of 10 strings we can do
        \begin{verbatim}
    new string[10];
\end{verbatim}
but it is not possible to use another constructor. Assuming that we'd want
to initialize the strings with the text \texttt{hello world}, we can't write
something like:
        \begin{verbatim}
    new string{ "hello world" }[10];
\end{verbatim}
The initialization of a dynamically allocated object usually consists of a
two-step process: first the array is allocated (implicitly calling the default
constructor); second the array's elements are initialized, as in the following
little example:
        \begin{verbatim}
    string *sp = new string[10];
    fill(sp, sp + 10, string{ "hello world" });
\end{verbatim}
These approaches all suffer from `\index{double initialization}double initializations', comparable
to not using member initializers in constructors.

One way to avoid double initialization is to use inheritance.
Inheritance can profitably be used to call non-default constructors in
combination with operator \texttt{new{[}{]}}. The approach capitalizes on the
following:
    \begin{itemize}
    \item  A base class pointer may point to a derived class object;
    \item  A derived class without (non-static)
            \index{derived class vs. base class size}
            \index{sizeof derived vs base classes}
        data members has the same size as its base class.
    \end{itemize}

The above also suggests a possible approach:
    \begin{itemize}
    \item  Derive a simple, member-less class from the class we're interested
in;
    \item  Use the appropriate base class initializer in its default
constructor;
    \item  Allocate the required number of derived class objects, and assign
\texttt{new{[}{]}}'s return expression to a pointer to base class objects.
    \end{itemize}
    Here is a simple example, producing 10 lines containing
the text \texttt{hello world}:
        \begin{verbatim}
#include <iostream>
#include <string>
#include <algorithm>
#include <iterator>

using namespace std;

struct Xstr: public string
{
    Xstr()
    :
        string("hello world")
    {}
};

int main()
{
    string *sp = new Xstr[10];
    copy(sp, sp + 10, ostream_iterator<string>{ cout, "\n" });
}
\end{verbatim}
    Of course, the above example is fairly unsophisticated, but it's easy to
polish the example: the class \texttt{Xstr} can be defined in
an anonymous namespace, accessible only to a function \texttt{getString()} which
may be given a \texttt{size\_t nObjects} parameter, allowing users to specify the
number of \texttt{hello world}-initialized strings they would like to allocate.

Instead of hard-coding the base class arguments it's also possible to use
variables or functions providing the appropriate values for the base class
constructor's arguments. In the next example a
    \index{local class}\emph{local class}\index{class: local} \texttt{Xstr} is defined inside a function
\texttt{nStrings(size\_t nObjects, char const $*$fname)}, expecting the number of
\texttt{string} objects to allocate and the name of a file whose subsequent lines
are used to initialize the objects. The local class
is invisible outside of the function \texttt{nStrings}, so no special namespace
safeguards are required.

As discussed in section \ref{LOCAL}, members of local classes cannot access
local variables from their surrounding function. However, they can access
global and static data defined by the surrounding function.

Using a local class neatly allows us to hide the implementation details
within the function \texttt{nStrings}, which simply opens the file, allocates the
objects, and closes the file again. Since the local class is derived from
\texttt{string}, it can use any \texttt{string} constructor for its base class
initializer. In this particular case it doesn't even do that, as copy elision
ensures that \texttt{Xstr's} base class \texttt{string} in fact is the \texttt{string}
returned by \texttt{nextLine}. That latter function's \texttt{string} subsequently
receives the lines of the just opened stream. As \texttt{nextLine} is a static
member function, it's available to \texttt{Xstr} default constructor's member
initializers even though at that time the \texttt{Xstr} object isn't available yet.
        \begin{verbatim}
#include <fstream>
#include <iostream>
#include <string>
#include <algorithm>
#include <iterator>

using namespace std;

string *nStrings(size_t size, char const *fname)
{
    static thread_local ifstream in;

    struct Xstr: public string
    {
        Xstr()
        :
            string(nextLine())
        {}
        static string nextLine()
        {
            string line;

            getline(in, line);
            return line;        // copy elision turns this
        }                       // into Xstr's base class string
    };
    in.open(fname);
    string *sp = new Xstr[size];
    in.close();

    return sp;
}

int main()
{
    string *sp = nStrings(10, "nstrings.cc");
    copy(sp, sp + 10, ostream_iterator<string>{ cout, "\n" });
}
\end{verbatim}
    When this program is run, it displays the first 10 lines of the file
\texttt{nstrings.cc}.

Note that the example defines a \texttt{static thread\_local ifstream}
object. Thread\_local variables are formally introduced in chapter
\ref{THREADING}. The \texttt{thread\_local} specification assures that the function
can safely be used, even in multithreaded programs.

A completely different way to avoid the double initialization (not using
inheritance) is to use placement new (cf. section \ref{PLACEMENT}): simply
allocate the required amount of memory followed by the proper in-place
allocation of the objects, using the appropriate constructors. In the next
example a pair of static \texttt{construct/destroy} members are used to perform the
required initialization. In the example \texttt{construct} expects an \texttt{istream}
that provides the initialization strings for objects of a class \texttt{String}
simply containing a \texttt{std::string} object. \texttt{Construct} first allocates
enough memory for the \texttt{n} \texttt{String} objects plus room for an initial
\texttt{size\_t} value. This initial \texttt{size\_t} value is then initialized with
\texttt{n}. Next, in a \texttt{for} statement, lines are read from the provided stream
and the lines are passed to the constructors, using placement new
calls. Finally the address of the first \texttt{String} object is returned. Then,
the destruction of the objects is handled by the member \texttt{destroy}. It
retrieves the number of objects to destroy from the \texttt{size\_t} it finds just
before the location of the address of the first object to destroy. The objects
are then destroyed by explicitly calling their destructors. Finally the raw
memory, originally allocated by \texttt{construct} is returned.
        \begin{verbatim}
#include <fstream>
#include <iostream>
#include <string>
using namespace std;

class String
{
    union Ptrs
    {
        void *vp;
        String *sp;
        size_t *np;
    };

    std::string d_str;

    public:
        String(std::string const &txt)
        :
            d_str(txt)
        {}
        ~String()
        {
            cout << "destructor: " << d_str << '\n';
        }
        static String *construct(istream &in, size_t n)
        {
            Ptrs p = {operator new(n * sizeof(String) + sizeof(size_t))};
            *p.np++ = n;

            string line;
            for (size_t idx = 0; idx != n; ++idx)
            {
                getline(in, line);
                new(p.sp + idx) String{ line };
            }

            return p.sp;
        }
        static void destroy(String *sp)
        {
            Ptrs p = {sp};
            --p.np;
            for (size_t n = *p.np; n--; )
                sp++->~String();

            operator delete(p.vp);
        }
};

int main()
{
    String *sp = String::construct(cin, 5);

    String::destroy(sp);
}

/*
    After providing 5 lines containing, respectively
        alpha, bravo, charley, delta, echo
    the program displays:
                destructor: alpha
                destructor: bravo
                destructor: charley
                destructor: delta
                destructor: echo
*/
\end{verbatim}
\cleardoublepage\chapter{Polymorphism}\label{POLYMORPHISM}
\typeout{Original Yodl file: polymorphism}\typeout{Original Yodl file: polymorphism/intro}Using inheritance classes may be derived from other classes, called base
classes. In the previous chapter we saw that base class pointers may be used
to point to derived class objects. We also saw that when a base class pointer
points to an object of a derived class the pointer's type, rather than the
object's type, determines which member functions are visible. So when a
\texttt{Vehicle $*$vp}, points to a \texttt{Car} object \texttt{Car}'s \texttt{speed} or
\texttt{brandName} members can't be used.

In the previous chapter two fundamental ways classes may be related to each
other were discussed: a class may be \index{implemented-in-terms-of}\emph{implemented-in-terms-of} another
class and it can be stated that a derived class \index{is-a}\emph{is-a} base class. The
former relationship is usually implemented using composition, the latter
is usually implemented using a special form of inheritance, called
\index{polymorphism}\emph{polymorphism}, the topic of this chapter.

An \emph{is-a} relationship between classes allows us to apply the
 \index{Liskov Substitution Principle}\emph{Liskov Substitution Principle} (\index{LSP}\emph{LSP}) according to which a derived
class object may be passed to and used by code expecting a pointer or
reference to a base class object. In the \textbf{C++} Annotations so far the LSP has been
applied many times. Every time an \texttt{ostringstream, ofstream} or \texttt{fstream}
was passed to functions expecting an \texttt{ostream} we've been applying this
principle. In this chapter we'll discover how to design our own classes
accordingly.

LSP is implemented using a technique called \index{polymorphism}\emph{polymorphism}: although a base
class pointer is used it performs actions defined in the (derived) class
of the object it actually points to. So, a \texttt{Vehicle $*$vp} might behave like
a \texttt{Car $*$} when pointing to a \texttt{Car}\footnote{In one of the StarTrek
movies, Capt.  Kirk was in trouble, as usual. He met an extremely beautiful
lady who, however, later on changed into a hideous troll. Kirk was quite
surprised, but the lady told him: ``Didn't you know I am a polymorph?''}.

Polymorphism is implemented using a feature called \index{late binding}\emph{late binding}. It's
called that way because the decision \emph{which} function to call (a base class
function or a function of a derived class) cannot be made at \emph{compile-time},
but is postponed until the program is actually executed: only then it is
determined which member function will actually be called.

In \textbf{C++} late binding is \emph{not} the default way functions are called. By
default \index{static binding}\emph{static binding} (or \index{early binding}\emph{early binding}) is used. With static
binding the functions that are called are determined by the compiler, merely
using the class types of objects, object pointers or object references.

Late binding is an inherently different (and slightly slower) process as it is
decided at \index{run-time}run-time, rather than at \index{compile-time}compile-time what function is going
to be called. As \textbf{C++} supports \emph{both} late- and early-binding \textbf{C++}
programmers are offered an option as to what kind of binding to use.  Choices
can be optimized to the situations at hand. Many other languages offering
object oriented facilities (e.g., \textbf{Java}) only or by default offer late
binding. \textbf{C++} programmers should be keenly aware of this. Expecting early
binding and getting late binding may easily produce nasty bugs.

Let's look at a simple example to start appreciating the differences between
late and early binding. The example merely illustrates. Explanations of
\emph{why} things are as shown are shortly provided.

Consider the  following little program:
        \begin{verbatim}
    #include <iostream>
    using namespace std;

    class Base
    {
        protected:
            void hello()
            {
                cout << "base hello\n";
            }
        public:
            void process()
            {
                hello();
            }
    };
    class Derived: public Base
    {
        protected:
            void hello()
            {
                cout << "derived hello\n";
            }
    };
    int main()
    {
        Derived derived;

        derived.process();
    }
\end{verbatim}
    The important characteristic of the above program is the \texttt{Base::process}
function, calling \texttt{hello}. As \texttt{process} is the only member that is defined
in the public interface it is the only member that can be called by code not
belonging to the two classes. The class \texttt{Derived}, derived from \texttt{Base}
clearly inherits \texttt{Base}'s interface and so \texttt{process} is also available in
\texttt{Derived}. So the \texttt{Derived} object in \texttt{main} is able to call
\texttt{process}, but not \texttt{hello}.

So far, so good. Nothing new, all this was covered in the previous
chapter.  One may wonder why \texttt{Derived} was defined at all.  It was
presumably defined to create an implementation of \texttt{hello} that's appropriate
for \texttt{Derived} but differing from \texttt{Base::hello}'s
implementation. \texttt{Derived}'s author's reasoning was as follows: \texttt{Base}'s
implementation of \texttt{hello} is not appropriate; a \texttt{Derived} class object can
remedy that by providing an appropriate implementation. Furthermore our author
reasoned:
    \begin{quote}``since the type of an
object determines the interface that is used, \texttt{process} must call
\texttt{Derived::hello} as \texttt{hello} is called via \texttt{process} from a \texttt{Derived}
class object''.\end{quote}

Unfortunately our author's reasoning is flawed, due to static binding. When
\texttt{Base::process} was compiled static binding caused the compiler to bind
the \texttt{hello} call to \texttt{Base::hello()}.

The author \emph{intended} to create a \texttt{Derived} class that \texttt{is-a} \texttt{Base}
class. That only partially succeeded: \texttt{Base}'s interface was inherited, but
after that \texttt{Derived} has relinquished all control over what happens. Once
we're in \texttt{process} we're only able to see \texttt{Base}'s member
implementations. Polymorphism offers a way out, allowing us to redefine (in a
derived class) members of a base class allowing these redefined members to be
used from the base class's interface.

This is the essence of LSP: public inheritance should not be used to reuse the
base class members (in derived classes) but to be reused (by the base class,
polymorphically using derived class members reimplementing base class
members).

Take a second to appreciate the implications of the above little program. The
\texttt{hello} and \texttt{process} members aren't too impressive, but the implications
of the example are. The \texttt{process} member could implement directory travel,
\texttt{hello} could define the action to perform when encountering a
file. \texttt{Base::hello} might simply show the name of a file, but
\texttt{Derived::hello} might delete the file; might only list its name if its
younger than a certain age; might list its name if it contains a certain text;
etc., etc.. Up to now \texttt{Derived} would have to implement \texttt{process}'s
actions itself; Up to now code expecting a \texttt{Base} class reference or pointer
could only perform \texttt{Base}'s actions. Polymorphism allows us to reimplement
members of base classes and to use those reimplemented members in code
expecting base class references or pointers. Using polymorphism existing code
may be reused by derived classes reimplementing the appropriate members of
their base classes. It's about time to uncover how this magic can be realized.

Polymorphism, which is not the default in \textbf{C++}, solves the problem and
allows the author of the classes to reach its goal. For the curious reader:
prefix \texttt{void hello()} in the \texttt{Base} class with the keyword \texttt{virtual} and
recompile. Running the modified program produces the intended and expected
\texttt{derived hello}. Why this happens is explained next.

\section{Virtual functions}\label{virfunc}
\typeout{Original Yodl file: polymorphism/function}By default the behavior of a member function called via a pointer or reference
is determined by the implementation of that function in the pointer's or
reference's class. E.g., a \texttt{Vehicle $*$} activates \texttt{Vehicle}'s member
functions, even when pointing to an object of a derived class. This is known
as as \emph{early} or
    \index{early binding} \index{static binding} \emph{static} binding: the function to
call is determined at
 \index{compile-time}compile-time. In \textbf{C++} \emph{late}
 \index{late binding} or \index{dynamic binding} \emph{dynamic} binding is realized using
\emph{virtual member functions}.

A member function becomes a \index{virtual member function}virtual member function when its declaration
starts with the keyword \index{virtual}\texttt{virtual}. It is stressed once again that in
\textbf{C++}, different from several other object oriented languages, this is
\emph{not} the default situation. By default \emph{static} binding is used.

Once a function is declared \texttt{virtual} in a base class, it remains virtual in
all derived classes. The keyword \texttt{virtual} should not be mentioned for
members in derived classes which are declared virtual in base classes. In
derived classes those members should be provided with the \index{override}\texttt{override}
indicator, allowing the compiler to verify that you're indeed referring to an
existing virtual member function.

In the vehicle classification system (see section \ref{VehicleSystem}), let's
concentrate on the members \texttt{mass} and \texttt{setMass}. These members define the
\index{user interface}\emph{user interface} of the class \texttt{Vehicle}. What we would like to accomplish
is that this user interface can be used for \texttt{Vehicle} and for any class
inheriting from \texttt{Vehicle}, since objects of those classes are themselves
also \texttt{Vehicles}. 

If we can define the user interface of our base class (e.g., \texttt{Vehicle}) such
that it remains usable irrespective of the classes we derive from \texttt{Vehicle}
our software achieves an enormous reusability: we design our software around
\texttt{Vehicle's} user interface, and our software will also properly function for
derived classes. Using plain inheritance doesn't accomplish this. If we define 
        \begin{verbatim}
    std::ostream &operator<<(std::ostream &out, Vehicle const &vehicle)
    {
        return out << "Vehicle's mass is " << vehicle.mass() << " kg.";
    }
\end{verbatim}
and \texttt{Vehicle's} member \texttt{mass} returns 0, but \texttt{Car's} member
\texttt{mass} returns 1000, then twice a mass of 0 is reported when the following
program is executed:
        \begin{verbatim}
    int main()
    {
        Vehicle vehicle;
        Car vw{ 1000, 160, "Golf" };

        cout << vehicle << '\n' << vw << '\n';
    }
\end{verbatim}
We've defined an overloaded insertion operator, but since it only knows
about \texttt{Vehicle's} user interface, `\texttt{cout $<$$<$ vw}' will use \texttt{vw's
Vehicle's} user interface as well, thus displaying a mass of 0. 

Reusability is enhanced if we add a \emph{redefinable interface} to the base
class's interface. A redefinable interface allows derived classes to fill in
their own implementation, without affecting the user interface. At the same
time the user interface will behave according to the derived class's wishes,
and not just to the base class's default implementation.

Members of the reusable interface should be declared in the class's
private sections: conceptually they merely belong to their own classes
(cf. section \ref{INHERITWHY}). In the base class these members should be
declared \texttt{virtual}. These members can be redefined (overridden) by derived
classes, and should there be provided with \texttt{override} indicators.

We keep our user interface (\texttt{mass}), and add the redefinable member 
\texttt{vmass} to \texttt{Vehicle's} interface:
        \begin{verbatim}
    class Vehicle
    {
        public:
            size_t mass() const;
            size_t si_mass() const;    // see below

        private:
            virtual size_t vmass() const;
    };
\end{verbatim}
Separating the user interface from the redefinable interface is a sensible
thing to do. It allows us to fine-tune the user interface (only one point of
maintenance), while at the same time allowing us to standardize the expected
behavior of the members of the redefinable interface. E.g., in many countries
the International system of units is used, using the kilogram as the unit for
mass. Some countries use other units (like the \emph{lbs}: 1 kg being
approx. 2.2046 lbs). By separating the user interface from the redefinable
interface we can use one standard for the redefinable interface, and keep the
flexibility of transforming the information \emph{ad-lib} in the user
interface. 

Just to maintain a clean separation of user- and redefinable interface we
might consider adding another accessor to \texttt{Vehicle}, providing the
\texttt{si\_mass}, simply implemented like this:
        \begin{verbatim}
    size_t Vehicle::si_mass() const
    {
        return vmass();
    }
\end{verbatim}
If \texttt{Vehicle} supports a member \texttt{d\_massFactor} then its \texttt{mass} member can
be implemented like this:
        \begin{verbatim}
    size_t Vehicle::mass()
    {
        return d_massFactor * si_mass();
    }
\end{verbatim}
\texttt{Vehicle} itself could define \texttt{vmass} so that it returns a token
value. E.g.,
        \begin{verbatim}
    size_t Vehicle::vmass()
    {
        return 0;
    }
\end{verbatim}
Now let's have a look at the class \texttt{Car}. It is derived from
\texttt{Vehicle}, and it inherits \texttt{Vehicle's} user interface. It also has a data
member \texttt{size\_t d\_mass}, and it implements its own reusable interface:
        \begin{verbatim}
    class Car: public Vehicle
    {
        ...
        private:
            size_t vmass() override;
    }
\end{verbatim}
If \texttt{Car} constructors require us to specify the car's mass (stored
in \texttt{d\_mass}), then \texttt{Car} simply implements its \texttt{vmass} member like
this:
        \begin{verbatim}
    size_t Car::vmass() const
    {
        return d_mass;
    }
\end{verbatim}
The class \texttt{Truck}, inheriting from \texttt{Car} needs two mass values: the
tractor's mass and the trailer's mass. The tractor's mass is passed to its
\texttt{Car} base class, the trailor's mass is passed to its \texttt{Vehicle d\_trailor}
data member. \texttt{Truck}, too, overrides \texttt{vmass}, this time returning the sum
of its tractor and trailor masses:
        \begin{verbatim}
    size_t Truck::vmass() const
    {
        return Car::si_mass() + d_trailer.si_mass();
    }
\end{verbatim}
Once a class member has been declared \texttt{virtual} it becomes
a virtual member in all derived classes, whether or not these members are
provided with the \texttt{override} indicator. But \texttt{override} \emph{should} be used,
as it allows to compiler to catch typos when writing down the derived class
interface. 

A member function may be declared \texttt{virtual} \emph{anywhere} in a
    \index{class hierarchy}class hierarchy, but this probably defeats the underlying polymorphic
class design, as the original base class is no longer capable of completely
covering the redefinable interfaces of derived classes. If, e.g, \texttt{mass} is
declared virtual in \texttt{Car}, but not in \texttt{Vehicle}, then the specific
characteristics of virtual member functions would only be available for
\texttt{Car} objects and for objects of classes derived from \texttt{Car}. For a
\texttt{Vehicle} pointer or reference static binding would remain to be used.  

The effect of late binding (polymorphism) is illustrated below:
        \begin{verbatim}
    void showInfo(Vehicle &vehicle)
    {
        cout << "Info: " << vehicle << '\n';
    }

    int main()
    {
        Car car(1200);            // car with mass 1200
        Truck truck(6000, 115,      // truck with cabin mass 6000, 
              "Scania", 15000);     // speed 115, make Scania, 
                                    // trailer mass 15000

        showInfo(car);             // see (1) below
        showInfo(truck);            // see (2) below

        Vehicle *vp = &truck;
        cout << vp->speed() << '\n';// see (3) below
    }
\end{verbatim}
Now that \texttt{mass} is defined \texttt{virtual}, late binding is used:
    \begin{itemize}
    \item  at (1), \texttt{Car}'s mass is displayed;
    \item  at (2) \texttt{Truck}'s mass is displayed;
    \item  at (3) a syntax error is generated. The member
        \texttt{speed} is not a member of \texttt{Vehicle}, and hence not callable via
        a \texttt{Vehicle$*$}.
    \end{itemize}
    The example illustrates that when a pointer to a class is used \emph{only the
members of that class can be called}.  A member's \texttt{virtual} characteristic
only influences the type of binding (early vs. late), not the set of member
functions that is visible to the pointer.

Through virtual members derived classes may redefine the behavior performed by
functions called from base class members or from pointers or references to
base class objects. This redefinition of base class members by derived classes
is called \index{member: overriding}\index{overriding members}\emph{overriding members}.

\subsection{Constructors of polymorhic classes}\label{CONSPOLY}
    \typeout{Original Yodl file: polymorphism/construct}Although constructors of polymorphic classes may (indirectlly) call virtual
members, that's probably not what you want as constructors of polymorphic
classes don't consider that those members may be overridden by derived
classes. As an opening example: if the class \texttt{Vehicle} would
define these members:
    \begin{verbatim}
    public:
        void Vehicle::prepare()
        {
            vPrepare();
        }
    private:
        virtual void Vehicle::vPrepare()
        {
            cout << "Preparing the Vehicle\n";
        }
\end{verbatim}
    and \texttt{Car} would override \texttt{vPrepare}:
    \begin{verbatim}
    virtual void Car::vPrepare()
        {
            cout << "Preparing the Car\n";
        }
\end{verbatim}
    then \texttt{Preparing the Car} would be shown by the following code fragment:
    \begin{verbatim}
Car car{1200};
    Vehicle &veh = car;
    veh.prepare();
\end{verbatim}
Maybe a preparation is always required. So why not do it in the base
class's constructor? Thus, the \texttt{Vehicle's} constructor could be defined as:
    \begin{verbatim}
    Vehicle::Vehicle()
    {
        prepare();
    }
\end{verbatim}
However, the following code fragment shows \texttt{Preparing the Vehicle},
and \emph{not} \texttt{Preparing the Car}:
    \begin{verbatim}
Car car{1200};
\end{verbatim}
As base classes' constructors do not recognize overridden virtual members
\texttt{Vehicle's} constructor simply calls its own \texttt{vPrepare} member instead of
\texttt{Vehicle::vPrepare}. 

There is clear logic to base class constructors not recognizing overridden
member functions: polymorphism allows us to tailor the base class's interface
to derived classes. Virtual members exist to realize this tailoring process.
But that's completely different from not being able to call derived classes'
members from base classes' constructors: at that point the derived class
objects haven't yet properly been initialized. When derived class objects are
constructed their base class parts are constructed before the derived class
objects themselves are in a valid state. Therefore, \emph{if} a base class
constructor would be allowed to call an overridden virtual member then that
member would most likely use data of the derived class, which at that point
haven't properly been initialized yet (often resulting in undefined behavior
like segmentation faults).

\section{Virtual destructors}\label{VIRTDES}
\typeout{Original Yodl file: polymorphism/destructor}When an object ceases to exist the object's \index{destructor}destructor is called. Now
consider the following code fragment (cf. section \ref{VehicleSystem}):
        \begin{verbatim}
    Vehicle *vp = new Land{ 1000, 120 };

    delete vp;          // object destroyed
\end{verbatim}
Here \texttt{delete} is applied to a base class pointer. As the base class
defines the available interface \texttt{delete vp} calls \texttt{\textasciitilde{}Vehicle} and \texttt{\textasciitilde{}Land}
remains out of sight. Assuming that \texttt{Land} allocates memory a
 \index{memory leak}memory leak results. Freeing memory is not the only action destructors can
perform. In general they may perform any action that's necessary when an
object ceases to exist. But here none of the actions defined by \texttt{\textasciitilde{}Land} are
performed. Bad news....

In \textbf{C++} this problem is solved by
 \index{destructor: virtual}\index{virtual destructor} \emph{virtual destructors}.  A
destructor can be declared \texttt{virtual}. When a base class destructor is
declared virtual then the destructor of the actual class pointed to by a base
class pointer \texttt{bp} is going to be called when \texttt{delete bp} is
executed. Thus, late binding is realized for destructors even though the
destructors of derived classes have unique names. Example:
        \begin{verbatim}
    class Vehicle
    {
        public:
            virtual ~Vehicle();     // all derived class destructors are
                                    // now virtual as well.
    };
\end{verbatim}
By declaring a virtual destructor, the above \texttt{delete} operation
(\texttt{delete vp}) correctly calls \texttt{Land}'s destructor, rather than
\texttt{Vehicle}'s destructor.

Once a destructor is called it performs as usual, whether or not it
is a virtual destructor. So, \texttt{\textasciitilde{}Land} first executes its own statements
and then calls \texttt{\textasciitilde{}Vehicle}. Thus, the above \texttt{delete vp} statement
uses late binding to call \texttt{\textasciitilde{}Vehicle} and from this point on the object
destruction proceeds as usual.

Destructors should always be defined \texttt{virtual} in classes designed as a
base class from which other classes are going to be derived. Often those
destructors themselves have no tasks to perform. In these cases the virtual
    \index{empty destructor} \index{destructor: empty}
    destructor is given an empty body. For example, the definition of
\texttt{Vehicle::\textasciitilde{}Vehicle()} may be as simple as:
        \begin{verbatim}
    Vehicle::~Vehicle()
    {}
\end{verbatim}
Resist the temptation to define virtual destructors (even empty
destructors)
 \index{destructor: inline} \index{inline}inline as this complicates class
maintenance. Section \ref{VTABLE} discusses the reason behind this
 \index{rule of thumb}rule of thumb.

\section{Pure virtual functions}
\typeout{Original Yodl file: polymorphism/pure}The base class \texttt{Vehicle} is provided with its own concrete implementations
of its virtual members (\texttt{mass} and \texttt{setMass}).  However, virtual member
functions do not necessarily \emph{have} to be implemented in base classes.

When the implementations of virtual members are omitted from base classes the
class imposes requirements upon derived classes. The derived classes are
required to provide the `missing implementations'.

This approach, in some languages (like \textbf{C\#, Delphi}
 \index{Java interface} and \textbf{Java}) known as an \index{interface}\emph{interface}, defines a
 \index{protocol}\emph{protocol}. Derived classes \emph{must} obey the protocol by implementing the
as yet not implemented members. If a class contains at least one member whose
implementation is missing no objects of that class can be defined.

Such incompletely defined classes are always base classes. They enforce a
protocol by merely declaring names, return values and arguments of some of
their members. These classes are call \index{class: abstract}
 \index{abstract classes}\emph{abstract classes} or \emph{abstract base classes}.  Derived classes become
non-abstract classes by implementing the as yet not implemented members.

Abstract base classes are the foundation of many \emph{design patterns}
 \index{design pattern} (cf. \emph{Gamma et al.} (1995))
 \index{Gamma, E.}, allowing the programmer to create highly
 \index{reusable software}\emph{reusable software}. Some of these design patterns are covered by the
\textbf{C++} Annotations (e.g, the \index{Template Method}\emph{Template Method} in section \ref{FORK}), but for a
thorough discussion of design patterns the reader is referred to Gamma \emph{et
al.}'s book.

Members that are merely declared in base classes are called
 \index{pure virtual functions}\emph{pure virtual functions}. A virtual member becomes a pure virtual member
by postfixing \index{= 0}\texttt{= 0} to its declaration (i.e., by replacing the semicolon
ending its declaration by `\texttt{= 0;}'). Example:
        \begin{verbatim}
    #include <iosfwd>
    class Base
    {
        public:
            virtual ~Base();
            virtual std::ostream &insertInto(std::ostream &out) const = 0;
    };
    inline std::ostream &operator<<(std::ostream &out, Base const &base)
    {
        return base.insertInto(out);
    }
\end{verbatim}
All classes derived from \texttt{Base} \emph{must} implement the \texttt{insertInto}
member function, or their objects cannot be constructed. This is neat: all
objects of class types derived from \texttt{Base} can now always be inserted into
\index{ostream}\texttt{ostream} objects.

Could the \index{virtual destructor}virtual destructor of a base class ever be a pure virtual
function? The answer to this question is no. First of all, there is no need to
enforce the availability of destructors in derived classes as destructors are
provided by default (unless a destructor is declared with the \texttt{= delete}
attribute). Second, if it is a pure virtual member its implementation does not
exist. However, derived class destructors eventually call their base class
destructors. How could they call base class destructors if their
implementations are lacking? More about this in the next section.

Often, but not necessarily, pure virtual member functions are
\texttt{const} \index{const member functions} member functions. This allows the
construction of constant derived class objects. In other situations this might
not be necessary (or realistic), and
 \index{non-constant member functions}non-constant member functions might be required. The general rule for
\texttt{const} member functions also applies to pure virtual functions: if the
member function alters the object's data members, it cannot be a \texttt{const}
member function.

Abstract base classes frequently don't have
 \index{class: without data members} data members.  However, once a base class
declares a pure virtual member it \emph{must} be declared identically in derived
classes. If the implementation of a pure virtual function in a derived class
alters the derived class object's data, then \emph{that} function cannot be
declared as a \texttt{const} member. Therefore, the author of an abstract base
class should carefully consider whether a pure virtual member function should
be a \texttt{const} member function or not.

\subsection{Implementing pure virtual functions}
    \typeout{Original Yodl file: polymorphism/implementing}Pure virtual member functions may be implemented. To implement a pure virtual
    \index{member function: pure virtual implementation}
    \index{pure virtual member: implementation}
 member function, provide it with its normal \texttt{= 0;} specification, but
implement it as well. Since the \texttt{= 0;} ends in a semicolon, the pure virtual
member is always at most a declaration in its class, but an implementation may
either be provided outside from its interface (maybe using \texttt{inline}).

Pure virtual member functions may be called from derived class objects or
from its class or derived class members by specifying the base class and scope
resolution operator together with the member to be called. Example:

\begin{verbatim}
#include <iostream>

class Base
{
    public:
        virtual ~Base();
        virtual void pureimp() = 0;
};
Base::~Base()
{}
void Base::pureimp()
{
    std::cout << "Base::pureimp() called\n";
}
class Derived: public Base
{
    public:
        void pureimp() override;
};
inline void Derived::pureimp()
{
    Base::pureimp();
    std::cout << "Derived::pureimp() called\n";
}
int main()
{
    Derived derived;

    derived.pureimp();
    derived.Base::pureimp();

    Derived *dp = &derived;

    dp->pureimp();
    dp->Base::pureimp();
}
// Output:
//      Base::pureimp() called
//      Derived::pureimp() called
//      Base::pureimp() called
//      Base::pureimp() called
//      Derived::pureimp() called
//      Base::pureimp() called
\end{verbatim}
Implementing a pure virtual member has limited use. One could argue that
the pure virtual member function's implementation may be used to perform tasks
that can already be performed at the base class level. However, there is no
guarantee that the base class virtual member function is actually going to be
called.  Therefore base class specific tasks could as well be offered by a
separate member, without blurring the distinction between a member doing some
work and a pure virtual member enforcing a protocol.

\section{Explicit virtual overrides}\label{FINAL}
\typeout{Original Yodl file: polymorphism/explicit}Consider the following situations:
    \begin{itemize}
    \item  A class \texttt{Value} is a \emph{value} class. It offers a copy constructor,
an overloaded assignment operator, maybe move operations, and a public,
non-virtual constructor. In section \ref{INHERITWHY} it is argued that such
classes are not suited as base classes. New classes should not inherit from
\texttt{Value}. How to enforce this?
    \item  A polymorphic class \texttt{Base} defines a virtual member
\texttt{v\_process(int32\_t)}. A class derived from \texttt{Base} needs to override this
member, but the author mistakingly defined \texttt{v\_proces(int32\_t)}. How to
prevent such errors, breaking the polymorphic behavior of the derived class?
    \item  A class \texttt{Derived}, derived from a polymorphic \texttt{Base} class
overrides the member \texttt{Base::v\_process}, but classes that are in turn derived
from \texttt{Derived} should no longer override \texttt{v\_process}, but \emph{may} override
other virtual members like \texttt{v\_call} and \texttt{v\_display}. How to enforce this
restricted polymorphic character for classes derived from \texttt{Derived}?
    \end{itemize}
    Two special identifiers, \index{final}\texttt{final} and \index{override}\texttt{override} are used to realize
the above. These identifiers are special in the sense that they only require
their special meanings in specific contexts. Outside of this context they are
just plain identifiers, allowing the programmer to define a variable like
\texttt{bool final}.

The identifier \texttt{final} can be applied to class declarations to indicate
that the class cannot be used as a base class. E.g.:
        \begin{verbatim}
    class Base1 final               // cannot be a base class
    {};
    class Derived1: public Base1    // ERR: Base1 is final
    {};

    class Base2                     // OK as base class
    {};
    class Derived2 final: public Base2  // OK, but Derived2 can't be
    {};                                 //     used as a base class
    class Derived: public Derived2      // ERR: Derived2 is final
    {};
\end{verbatim}
The identifier \texttt{final} can also be added to virtual member
declarations. This indicates that those virtual members cannot be overridden
by derived classes. The restricted polymorphic character of a class, mentioned
above, can thus be realized as follows:
        \begin{verbatim}
    class Base
    {
        virtual int v_process();    // define polymorphic behavior
        virtual int v_call();
        virtual int v_display();
    };
    class Derived: public Base      // Derived restricts polymorphism
    {                               // to v_call and v_display
        virtual int v_process() final;
    };
    class Derived2: public Derived
    {
        // int v_process();            No go: Derived:v_process is final
        virtual int v_display();    // OK to override
    };
\end{verbatim}
To allow the compiler to detect typos, differences in parameter types, or
differences in member function modifiers (e.g., \texttt{const} vs. non-\texttt{const})
the identifier \texttt{override} can (should) be appended to derived class members
overriding base class members. E.g.,
        \begin{verbatim}
    class Base
    {
        virtual int v_process();
        virtual int v_call() const;
        virtual int v_display(std::ostream &out);
    };
    class Derived: public Base
    {
        virtual int v_proces() override;    // ERR: v_proces != v_process
        virtual int v_call() override;      // ERR: not const
                                            // ERR: parameter types differ
        virtual int v_display(std::istream &out) override;
    };
\end{verbatim}
\section{Virtual functions and multiple inheritance}\label{MULTIPLEPOLYMORPH}
\typeout{Original Yodl file: polymorphism/multiple}    In chapter \ref{IOStreams} we encountered the class \texttt{fstream}, one class
offering features of \texttt{ifstream} and \texttt{ofstream}. In chapter
\ref{INHERITANCE} we learned that a class may be derived from multiple base
classes. Such a derived class inherits the properties of all its base
classes. Polymorphism can also be used in combination with multiple
inheritance.

Consider what would happen if more than one `path' leads from the derived
class up to its (base) classes. This is illustrated in the next (fictitious)
example where a class \texttt{Derived} is doubly derived from \texttt{Base}:
        \begin{verbatim}
    class Base
    {
        int d_field;
        public:
            void setfield(int val);
            int field() const;
    };
    inline void Base::setfield(int val)
    {
        d_field = val;
    }
    inline int Base::field() const
    {
        return d_field;
    }
    class Derived: public Base, public Base
    {};
\end{verbatim}
Due to the double derivation, \texttt{Base}'s functionality now occurs twice in
\texttt{Derived}. This results in \index{ambiguity}ambiguity: when the function \texttt{setfield()} is
called for a \texttt{Derived} class object, which function will that be as there
are two of them? The scope resolution operator won't come to the rescue and so
the \textbf{C++} compiler cannot compile the above example and (correctly)
identifies an error.

The above code clearly duplicates its base class in the derivation, which can
of course easily be avoided by not doubly deriving from \texttt{Base} (or by using
composition (!)). But duplication of a base class can also occur through
 \index{nested inheritance}nested inheritance, where an object is derived from, e.g., a \texttt{Car} and
from an \texttt{Air} (cf. section \ref{VehicleSystem}). Such a class would be needed
to represent, e.g., a flying car\footnote{such as the one in James Bond
vs. the Man with the Golden Gun...}. An \texttt{AirCar} would ultimately contain
two \texttt{Vehicles}, and hence two \texttt{mass} fields, two \texttt{setMass()}
functions and two \texttt{mass()} functions. Is this what we want?

\subsection{Ambiguity in multiple inheritance}
    \typeout{Original Yodl file: polymorphism/ambiguity}Let's investigate closer why an \texttt{AirCar} introduces \index{ambiguity}ambiguity, when
derived from \texttt{Car} and \texttt{Air}.
    \begin{itemize}
    \item  An \texttt{AirCar} is a \texttt{Car}, hence a \texttt{Land}, and hence a
\texttt{Vehicle}.
    \item  However, an \texttt{AirCar} is also an \texttt{Air}, and hence a \texttt{Vehicle}.
    \end{itemize}
    The duplication of \texttt{Vehicle} data is further illustrated in
Figure \ref{ambiguity}.
    \begin{figure}[tbp]
\centerline{\epsffile{polymorphism/ambiguity.eps}}
\caption{\label{ambiguity}Duplication of a base class in multiple derivation.}
\end{figure}
    The internal organization of an \texttt{AirCar} is shown in
Figure \ref{InternalOrganization}
    \begin{figure}[tbp]
\centerline{\epsffile{polymorphism/internal.eps}}
\caption{\label{InternalOrganization}Internal organization of an \texttt{AirCar} object.}
\end{figure}
    The \textbf{C++} compiler detects the ambiguity in an \texttt{AirCar} object,
and will therefore not  compile  statements like:
        \begin{verbatim}
    AirCar jBond;
    cout << jBond.mass() << '\n';
\end{verbatim}
Which member function \texttt{mass} to call cannot be determined by the
compiler but the programmer has two possibilities to resolve the ambiguity for
the compiler:
    \begin{itemize}
    \item  First, the function call where the ambiguity originates can be
modified. The ambiguity is resolved using the \index{scope resolution operator}scope resolution operator:
    \begin{verbatim}
// let's hope that the mass is kept in the Car
// part of the object..
cout << jBond.Car::mass() << '\n';
\end{verbatim}
The scope resolution operator and the class name are put right before
the name of the member function.
    \item  Second, a dedicated function \texttt{mass} could be created for
the class \texttt{AirCar}:
    \begin{verbatim}
int AirCar::mass() const
{
    return Car::mass();
}
\end{verbatim}
\end{itemize}
    The second possibility is preferred as it does not require the compiler to
flag an error; nor does it require the programmer using the class
\texttt{AirCar} to take special precautions.

However, there exists a more elegant solution, discussed in the next
section.

\subsection{Virtual base classes}\label{VIRTUALBASE}
    \typeout{Original Yodl file: polymorphism/base}    As illustrated in Figure \ref{InternalOrganization}, an \texttt{AirCar} represents
\emph{two} \texttt{Vehicle}s. This not only results in an \index{ambiguity}ambiguity about which
function to use to access the \texttt{mass} data, but it also defines two
\texttt{mass} fields in an \texttt{AirCar}. This is slightly redundant, since we can
assume that an \texttt{AirCar} has but one mass.

It is, however, possible to define an \texttt{AirCar} as a class consisting of
but one \texttt{Vehicle} and yet using multiple derivation.  This is realized by
defining the base classes that are multiply mentioned in a derived class's
inheritance tree as a
 \index{base class: virtual} \index{virtual base class}\emph{virtual base class}.

For the class \texttt{AirCar} this implies a small change when deriving an
\texttt{AirCar} from \texttt{Land} and \texttt{Air} classes:
        \begin{verbatim}
    class Land: virtual public Vehicle
    {
        // etc
    };
    class Car: public Land
    {
        // etc
    };
    class Air: virtual public Vehicle
    {
        // etc
    };
    class AirCar: public Car, public Air
    {
    };
\end{verbatim}
Virtual derivation \index{virtual derivation} ensures that a \texttt{Vehicle} is
only added once to a derived class. This means that the route along which a
\texttt{Vehicle} is added to an \texttt{AirCar} is no longer depending on its direct
base classes; we can only state that an \texttt{AirCar} is a \texttt{Vehicle}.  The
internal organization of an \texttt{AirCar} after virtual derivation is shown in
Figure \ref{VirtualBaseClass}.
    \begin{figure}[tbp]
\centerline{\epsffile{polymorphism/virtbase.eps}}
\caption{\label{VirtualBaseClass}Internal organization of an \texttt{AirCar} object when the base
            classes are virtual.}
\end{figure}

When a class \texttt{Third} inherits from a base class \texttt{Second} which in turn
inherits from a base class \texttt{First} then the \texttt{First} class constructor
called by the \texttt{Second} class constructor is also used when this \texttt{Second}
constructor is used when constructing a \texttt{Third} object. Example:
        \begin{verbatim}
    class First
    {
        public:
            First(int x);
    };
    class Second: public First
    {
        public:
            Second(int x)
            :
                First(x)
            {}
    };
    class Third: public Second
    {
        public:
            Third(int x)
            :
                Second(x)           // calls First(x)
            {}
    };
\end{verbatim}
The above no longer holds true when \texttt{Second} uses virtual derivation.
When \texttt{Second} uses virtual derivation its base class constructor is
\emph{ignored} when \texttt{Second}'s constructor is called from \texttt{Third}. Instead
\texttt{Second} by default calls \texttt{First}'s default constructor. This is
illustrated by the next example:
        \begin{verbatim}
    class First
    {
        public:
            First()
            {
                cout << "First()\n";
            }
            First(int x);
    };
    class Second: public virtual First      // note: virtual
    {
        public:
            Second(int x)
            :
                First(x)
            {}
    };
    class Third: public Second
    {
        public:
            Third(int x)
            :
                Second(x)
            {}
    };
    int main()
    {
        Third third{ 3 };   // displays `First()'
    }
\end{verbatim}
    When constructing \texttt{Third} \texttt{First}'s default constructor is used by
default. \texttt{Third}'s constructor, however, may overrule this default behavior
by explicitly specifying the constructor to use. Since the \texttt{First} object
must be available before \texttt{Second} can be constructed it must be specified
first. To call \texttt{First(int)} when constructing \texttt{Third(int)} the latter
constructor can be defined as follows:
        \begin{verbatim}
    class Third: public Second
    {
        public:
            Third(int x)
            :
                First(x),           // now First(int) is called.
                Second(x)
            {}
    };
\end{verbatim}
This behavior may seem puzzling when simple linear inheritance is used but
it makes sense when multiple inheritance is used with base classes using
virtual inheritance. Consider \texttt{AirCar}: when \texttt{Air} and \texttt{Car} both
virtually inherit from \texttt{Vehicle} will \texttt{Air} and \texttt{Car} both initialize
the common \texttt{Vehicle} object? If so, which one is going to be called first?
What if \texttt{Air} and \texttt{Car} use different \texttt{Vehicle} constructors? All these
questions can be avoided by passing the responsibility for the initialization
of a common base class to the class eventually using the common base class
object. In the above example \texttt{Third}. Hence \texttt{Third} is provided an
opportunity to specify the constructor to use when initializing \texttt{First}.

Multiple inheritance may also be used to inherit from classes that do not all
use virtual inheritance. Assume we have two classes, \texttt{Derived1} and
\texttt{Derived2}, both (possibly virtually) derived from \texttt{Base}.

We now address the question which constructors will be called when calling a
constructor of the class \texttt{Final: public Derived1, public Derived2}.

To distinguish the involved constructors \texttt{Base1} indicates the \texttt{Base}
class constructor called as base class initializer for \texttt{Derived1} (and
analogously: \texttt{Base2} called from \texttt{Derived2}). A plain \texttt{Base}  indicates
\texttt{Base}'s  default constructor.

\texttt{Derived1} and \texttt{Derived2} indicate the base class initializers used when
constructing a \texttt{Final} object.

Now we're ready to distinguish the various cases when constructing an object
of the class \texttt{Final: public Derived1, public Derived2}:
        \begin{itemize}
        \item  classes:
                \begin{verbatim}
Derived1: public Base
Derived2: public Base
\end{verbatim}
\begin{quote}This is normal, non virtual multiple derivation. The
                following constructors are called in the order shown:
                \begin{verbatim}
Base1,
Derived1,
Base2,
Derived2
\end{verbatim}
\end{quote}
        \item  classes:
                \begin{verbatim}
Derived1: public Base
Derived2: virtual public Base
\end{verbatim}
\begin{quote}Only \texttt{Derived2} uses virtual derivation.
               \texttt{Derived2}'s base class constructor is ignored.  Instead,
                \texttt{Base} is called and it is called prior to any other
                constructor:
               \begin{verbatim}
Base,
Base1,
Derived1,
Derived2
\end{verbatim}
As only one class uses virtual derivation, \emph{two} \texttt{Base}
                class objects remain available in the eventual \texttt{Final}
                class.
            \end{quote}
        \item  classes:
                \begin{verbatim}
Derived1: virtual public Base
Derived2: public Base
\end{verbatim}
\begin{quote}Only \texttt{Derived1} uses virtual derivation.
               \texttt{Derived1}'s base class constructor is ignored.  Instead,
                \texttt{Base} is called and it is called prior to any other
                constructor. Different from the first (non-virtual) case
                \texttt{Base} is now called, rather than \texttt{Base1}:
               \begin{verbatim}
Base,
Derived1,
Base2,
Derived2
\end{verbatim}
\end{quote}
        \item  classes:
                \begin{verbatim}
Derived1: virtual public Base
Derived2: virtual public Base
\end{verbatim}
\begin{quote}Both base classes use virtual derivation and so
                only \emph{one} \texttt{Base} class object will be present in the
                \texttt{Final} class object. The following constructors are called
                in the order shown:
                \begin{verbatim}
Base,
Derived1,
Derived2
\end{verbatim}
\end{quote}
        \end{itemize}
    Virtual derivation is, in contrast to virtual functions, a pure
\index{compile-time}compile-time issue. Virtual inheritance merely defines
how the compiler defines a class's data organization and construction process.

\subsection{When virtual derivation is not appropriate}
    \typeout{Original Yodl file: polymorphism/notvirtual}Virtual inheritance can be used to merge multiply occurring base
classes. However, situations may be encountered where multiple occurrences of
base classes \emph{is} appropriate. Consider the definition of a \texttt{Truck} (cf.
section \ref{Truck}):
        \begin{verbatim}
    class Truck: public Car
    {
        int d_trailer_mass;

        public:
            Truck();
            Truck(int engine_mass, int sp, char const *nm,
                   int trailer_mass);

            void setMass(int engine_mass, int trailer_mass);
            int mass() const;
    };
    Truck::Truck(int engine_mass, int sp, char const *nm,
                  int trailer_mass)
    :
        Car(engine_mass, sp, nm)
    {
        d_trailer_mass = trailer_mass;
    }
    int Truck::mass() const
    {
        return                  // sum of:
            Car::mass() +    //   engine part plus
            trailer_mass;         //   the trailer
    }
\end{verbatim}
This definition shows how a \texttt{Truck} object is constructed to contain two
mass fields: one via its derivation from \texttt{Car} and one via its own \texttt{int
d\_trailer\_mass} data member. Such a definition is of course valid, but it
could also be rewritten. We could derive a \texttt{Truck} from a \texttt{Car}
\emph{and} from a \texttt{Vehicle}, thereby explicitly requesting the double presence
of a \texttt{Vehicle}; one for the mass of the engine and cabin, and one for the
mass of the trailer. A slight complication is that a class organization like
        \begin{verbatim}
    class Truck: public Car, public Vehicle
\end{verbatim}
is not accepted by the \textbf{C++} compiler. As a \texttt{Vehicle} is already part
of a \texttt{Car}, it is therefore not needed once again. This organization may,
however, be accepted using a small trick. By creating an additional class
inheriting from \texttt{Vehicle} and deriving \texttt{Truck} from that additional class
rather than directly from \texttt{Vehicle} the problem is solved. Simply derive a
class \texttt{TrailerVeh} from \texttt{Vehicle}, and then \texttt{Truck} from \texttt{Car} and
\texttt{TrailerVeh}:
        \begin{verbatim}
    class TrailerVeh: public Vehicle
    {
        public:
            TrailerVeh(int mass)
            :
                Vehicle(mass)
            {}
    };
    class Truck: public Car, public TrailerVeh
    {
        public:
            Truck();
            Truck(int engine_mass, int sp, char const *nm, int trailer_mass);
            void setMass(int engine_mass, int trailer_mass);
            int mass() const;
    };
    inline Truck::Truck(int engine_mass, int sp, char const *nm,
                        int trailer_mass)
    :
        Car(engine_mass, sp, nm),
        TrailerVeh(trailer_mass)
    {}
    inline int Truck::mass() const
    {
        return                      // sum of:
            Car::mass() +        //   engine part plus
            TrailerVeh::mass();   //   the trailer
    }
\end{verbatim}
\section{Run-time type identification}\label{RTTI}
\typeout{Original Yodl file: polymorphism/rtti}\textbf{C++} offers two ways to \index{type identification: run-time} retrieve types of
objects and expressions at run-time. The possibilities of \textbf{C++}'s run-time
type identification are limited compared to languages like
 \index{Java} \textbf{Java}. Usually
    \index{static type checking}static type checking and \index{static type identification}static type identification is used in
\textbf{C++}. Static type checking is possibly safer and certainly more efficient
than run-time type identification and should therefore be preferred over
run-time type identification. But situations exist where run-time type
identification is appropriate. \textbf{C++} offers run-time type identification
through the \index{dynamic cast}\emph{dynamic cast} and \index{typeid}\texttt{typeid} operators.
    \begin{itemize}
    \item  A \texttt{dynamic\_cast}  is used  to convert a base
class \index{base class: converting to derived class} pointer or reference to a
derived class pointer or reference. This is also known as \index{down-casting}\emph{down-casting}.
        \item  The \index{typeid}\texttt{typeid} operator returns the actual type of an expression.
            \index{expression: actual type}
    \end{itemize}
    These operators can be used with objects of classes having at least one
virtual member function.

\subsection{The dynamic\_cast operator}\label{DYNAMICCAST}
        \typeout{Original Yodl file: polymorphism/dynamiccast}The \index{dynamic\_cast}\texttt{dynamic\_cast$<$$>$} operator is used to convert a base
class pointer or \index{base class: converting to derived class} reference to,
respectively, a \index{derived class}derived class pointer or reference. This is also called
\index{down-casting}\emph{down-casting} as direction of the cast is \emph{down} the inheritance tree.

A dynamic cast's actions are determined \index{run-time}run-time; it can only be used if
the base class declares at least one virtual member function. For the dynamic
cast to succeed, the destination class's \texttt{Vtable} must be equal to the
\texttt{Vtable} to which the dynamic cast's argument refers to, lest the cast fails
and returns 0 (if a dynamic cast of a pointer was requested) or throws a
\texttt{std::bad\_cast} exception (if a dynamic cast of a reference was requested).

In the following example a pointer to the class \texttt{Derived} is obtained from
the \texttt{Base} class pointer \texttt{bp}:
        \begin{verbatim}
    class Base
    {
        public:
            virtual ~Base();
    };
    class Derived: public Base
    {
        public:
            char const *toString();
    };
    inline char const *Derived::toString()
    {
        return "Derived object";
    }
    int main()
    {
        Base *bp;
        Derived *dp,
        Derived d;

        bp = &d;

        dp = dynamic_cast<Derived *>(bp);

        if (dp)
            cout << dp->toString() << '\n';
        else
            cout << "dynamic cast conversion failed\n";
    }
\end{verbatim}
In the condition of the above \texttt{if} statement the success of the dynamic
cast is verified. This verification is performed at \emph{run-time}, as the
actual class of the objects to which the pointer points is only known by then.

If a base class pointer is provided, the dynamic cast operator returns 0 on
failure and a pointer to the requested derived class on success.

Assume a \texttt{vector$<$Base $*$$>$} is used. The pointers of such a vector may
point to objects of various classes, all derived from \texttt{Base}. A dynamic cast
returns a pointer to the specified class if the base class pointer indeed
points to an object of the specified class and returns 0 otherwise.

We could determine the actual class of an object a pointer points to by
performing a series of checks to find the derived class to which a base class
pointer points. Example:
        \begin{verbatim}
    class Base
    {
        public:
            virtual ~Base();
    };
    class Derived1: public Base;
    class Derived2: public Base;

    int main()
    {
        vector<Base *> vb(initializeBase());

        Base *bp = vb.front();

        if (dynamic_cast<Derived1 *>(bp))
            cout << "bp points to a Derived1 class object\n";
        else if (dynamic_cast<Derived2 *>(bp))
            cout << "bp points to a Derived2 class object\n";
    }
\end{verbatim}
Alternatively, a reference to a base class object may be available. In
this case the \texttt{dynamic\_cast} operator throws an \index{exception}exception if the down
casting fails. Example:
        \begin{verbatim}
    #include <iostream>
    #include <typeinfo>

    class Base
    {
        public:
            virtual ~Base();
            virtual char const *toString();
    };
    inline char const *Base::toString()
    {
        return "Base::toString() called";
    }
    class Derived1: public Base
    {};
    class Derived2: public Base
    {};

    Base::~Base()
    {}
    void process(Base &b)
    {
        try
        {
            std::cout << dynamic_cast<Derived1 &>(b).toString() << '\n';
        }
        catch (std::bad_cast)
        {}
        try
        {
            std::cout << dynamic_cast<Derived2 &>(b).toString() << '\n';
        }
        catch (std::bad_cast)
        {
            std::cout << "Bad cast to Derived2\n";
        }
    }
    int main()
    {
        Derived1 d;
        process(d);
    }
    /*
        Generated output:

        Base::toString() called
        Bad cast to Derived2
    */
\end{verbatim}
    In this example the value \texttt{std::bad\_cast} \index{bad\_cast} is used. A
\texttt{std::bad\_cast} exception is thrown if the dynamic cast of a reference to a
derived class object fails.

Note the form of the \texttt{catch} clause: \texttt{bad\_cast} is the name of a type.
Section \ref{EMPTYENUM} describes how  such a type can be defined.

The dynamic cast operator is a useful tool when an existing base class cannot
or should not be modified (e.g., when the sources are not available), and a
derived class may be modified instead. Code receiving a base class pointer or
reference may then perform a dynamic cast to the derived class to access the
derived class's functionality.

You may wonder in what way the behavior of the \texttt{dynamic\_cast} differs from
that of the \texttt{static\_cast}.

When the \texttt{static\_cast} is used, we tell the compiler that it must convert a
pointer or reference to its expression type to a pointer or reference of its
destination type. This holds true whether the base class declares virtual
members or not. Consequently, all the \texttt{static\_cast}'s actions can be
determined by the compiler, and the following compiles fine:
        \begin{verbatim}
    class Base
    {
        // maybe or not virtual members
    };
    class Derived1: public Base
    {};
    class Derived2: public Base
    {};

    int main()
    {
        Derived1 derived1;
        Base *bp = &derived1;

        Derived1 &d1ref = static_cast<Derived1 &>(*bp);
        Derived2 &d2ref = static_cast<Derived2 &>(*bp);
    }
\end{verbatim}
Pay attention to the second \texttt{static\_cast}: here the \texttt{Base} class
object is cast to a \texttt{Derived2} class reference. The compiler has no problems
with this, as \texttt{Base} and \texttt{Derived2} are related by inheritance.

Semantically, however, it makes no sense as \texttt{bp} in fact points to a
\texttt{Derived1} class object. This is detected by a \texttt{dynamic\_cast}.  A
\texttt{dynamic\_cast}, like the \texttt{static\_cast}, converts related pointer or
reference types, but the \texttt{dynamic\_cast} provides a run-time safeguard. The
dynamic cast fails when the requested type doesn't match the actual type of
the object we're pointing at. In addition, the \texttt{dynamic\_cast}'s use is much
more restricted than the \texttt{static\_cast}'s use, as the \texttt{dynamic\_cast} can
only be used for downcasting to derived classes having virtual members.

In the end a dynamic cast is a cast, and casts should be avoided whenever
possible. When the need for dynamic casting arises ask yourself whether the
base class has correctly been designed. In situations where code expects a
base class reference or pointer the base class interface should be all that is
required and using a dynamic cast should not be necessary. Maybe the base
class's virtual interface can be modified so as to prevent the use of dynamic
casts. Start frowning when encountering code using dynamic casts. When using
dynamic casts in your own code always properly document why the dynamic cast
was appropriately used and was not avoided.

\subsection{The `typeid' operator}\label{TYPEID}
        \typeout{Original Yodl file: polymorphism/typeid}As with the \index{dynamic\_cast}\texttt{dynamic\_cast} operator, \index{typeid}\texttt{typeid} is usually applied to
references to base class objects that refer to derived class
objects. \texttt{Typeid} should only be used with base classes offering virtual
members. 

Before using \texttt{typeid} the \index{typeinfo: header file}\texttt{$<$typeinfo$>$} header file must be included.

The \texttt{typeid} operator returns an object of type \texttt{type\_info}.
Different compilers may offer different implementations of the class
\texttt{type\_info}, but at the very least \texttt{typeid} must offer the following
interface:
        \begin{verbatim}
    class type_info
    {
        public:
            virtual ~type_info();
            int operator==(type_info const &other) const;
            int operator!=(type_info const &other) const;
            bool before(type_info const &rhs) const;
            char const *name() const;
        private:
            type_info(type_info const &other);
            type_info &operator=(type_info const &other);
    };
\end{verbatim}
Note that this class has a private copy constructor and a private
overloaded assignment operator. This prevents code from  constructing
\texttt{type\_info} objects and prevents code from assigning \texttt{type\_info} objects
to each other. Instead, \texttt{type\_info} objects are
constructed and returned by the \texttt{typeid} operator.

If the \texttt{typeid} operator is passed a base class reference it is able to
return the actual name of the type the reference refers to. Example:
        \begin{verbatim}
    class Base;
    class Derived: public Base;

    Derived d;
    Base    &br = d;

    cout << typeid(br).name() << '\n';
\end{verbatim}
In this example the \texttt{typeid} operator is given a base class reference.
It prints the text ``\texttt{Derived}'', being the \index{class name}class name of the class
\texttt{br} actually refers to. If \texttt{Base} does not contain virtual functions, the
text ``\texttt{Base}'' is printed.

The \texttt{typeid} operator can be used to determine the name of the actual
type of \index{expression: type of} expressions, not just of class type
objects. For example:
        \begin{verbatim}
    cout << typeid(12).name() << '\n';     // prints:  int
    cout << typeid(12.23).name() << '\n';  // prints:  double
\end{verbatim}
Note, however, that the above example is suggestive at most. It \emph{may}
print \texttt{int} and \texttt{double}, but this is not necessarily the case. If
portability is required, make sure no tests against these static, built-in
text-strings are required. Check out what your compiler produces in case of
doubt.

In situations where the \texttt{typeid} operator is applied to
determine the type of a derived class, a base class \emph{reference}
        \index{typeid: argument}
    should be used as the argument of the \texttt{typeid} operator. Consider
the following example:
        \begin{verbatim}
    class Base;     // contains at least one virtual function
    class Derived: public Base;

    Base *bp = new Derived;     // base class pointer to derived object

    if (typeid(bp) == typeid(Derived *))    // 1: false
        ...
    if (typeid(bp) == typeid(Base *))       // 2: true
        ...
    if (typeid(bp) == typeid(Derived))      // 3: false
        ...
    if (typeid(bp) == typeid(Base))         // 4: false
        ...
    if (typeid(*bp) == typeid(Derived))     // 5: true
        ...
    if (typeid(*bp) == typeid(Base))        // 6: false
        ...

    Base &br = *bp;

    if (typeid(br) == typeid(Derived))      // 7: true
        ...
    if (typeid(br) == typeid(Base))         // 8: false
        ...
\end{verbatim}
Here, \texttt{(1)} returns \texttt{false} as a \texttt{Base $*$} is not a \texttt{Derived
$*$}. \texttt{(2)} returns \texttt{true}, as the two pointer types are the same, \texttt{(3)}
and \texttt{(4)} return \texttt{false} as pointers to objects are not the objects
themselves.

On the other hand, if \texttt{$*$bp} is used in the above expressions, then
\texttt{(1)} and \texttt{(2)} return \texttt{false} as an object (or reference to an object)
is not a pointer to an object, whereas \texttt{(5)} now returns \texttt{true}: \texttt{$*$bp}
actually refers to a \texttt{Derived} class object, and \texttt{typeid($*$bp)} returns
\texttt{typeid(Derived)}.  A similar result is obtained if a base class reference
is used: \texttt{7} returning \texttt{true} and \texttt{8} returning \texttt{false}.

The \texttt{type\_info::before(type\_info const \&rhs)} member is used to
determine the \index{collating order}\emph{collating order} of classes. This is useful when comparing
two \emph{types} for equality.  The function returns a nonzero value if \texttt{$*$this}
precedes \texttt{rhs} in the hierarchy or collating order of the used types. When a
derived class is compared to its base class the comparison returns 0,
otherwise a non-zero value. E.g.:
        \begin{verbatim}
    cout << typeid(ifstream).before(typeid(istream)) << '\n' << // 0
            typeid(istream).before(typeid(ifstream)) << '\n';   // not 0
\end{verbatim}
With built-in types the implementor may implement that non-0 is returned
when a `wider' type is compared to a `smaller' type and 0 otherwise:
        \begin{verbatim}
    cout << typeid(double).before(typeid(int)) << '\n' <<   // not 0
            typeid(int).before(typeid(double)) << '\n';     // 0
\end{verbatim}
When two equal types are compared, 0 is returned:
        \begin{verbatim}
    cout << typeid(ifstream).before(typeid(ifstream)) << '\n';   // 0
\end{verbatim}
When a \texttt{0}-pointer is passed to the \texttt{operator typeid} a \index{bad\_typeid}\texttt{bad\_typeid}
exception is thrown.

\section{Inheritance: when to use to achieve what?}\label{INHERITWHY}
\typeout{Original Yodl file: polymorphism/inheritance}Inheritance should not be applied automatically and thoughtlessly. Often
composition can be used instead, improving on a class's design by reducing
coupling. When inheritance is used \emph{public} inheritance should not
automatically be used but the type of inheritance that is selected should
match the programmer's intent.

We've seen that polymorphic classes on the one hand offer interface members
defining the functionality that can be requested of base classes and on the
other hand offer virtual members that can be overridden. One of the signs of
good class design is that member functions are designed according to the
principle of `one function, one task'. In the current context: a class member
should either be a member of the class's public or protected interface or it
should be available as a virtual member for reimplementation by derived
classes. Often this boils down to virtual members that are defined in the base
class's \emph{private} section. Those functions shouldn't be called by code using
the base class, but they exist to be overridden by derived classes using
polymorphism to redefine the base class's behavior.

The underlying principle was mentioned before in the introductory paragraph
of this chapter: according to the \index{Liskov Substitution Principle}\emph{Liskov Substitution Principle}
(\index{LSP}\emph{LSP}) an \index{is-a}\emph{is-a} relationship between classes (indicating that a
derived class object \emph{is a} base class object) implies that a derived class
object may be used in code expecting a base class object.

In this case inheritance is used \emph{not} to let the derived class use the
facilities already implemented by the base class but to reuse the base class
polymorphically by reimplementing the base class's virtual members in the
derived class.

In this section we'll discuss the reasons for using inheritance. Why should
inheritance (not) be used? If it is used what do we try to accomplish by it?

Inheritance often competes with composition. Consider the following two
alternative class designs:
        \begin{verbatim}
    class Derived: public Base
    { ... };

    class Composed
    {
        Base d_base;
        ...
    };
\end{verbatim}
Why and when prefer \texttt{Derived} over \texttt{Composed} and vice versa? What
kind of inheritance should be used when designing the class \texttt{Derived}?
    \begin{itemize}
    \item  Since \texttt{Composed} and \texttt{Derived} are offered as alternatives we are
        looking at the design of a class (\texttt{Derived} or \texttt{Composed}) that
        \index{is-implemented-in-terms-of}\emph{is-implemented-in-terms-of} another class.
    \item  Since \texttt{Composed} does itself not make \texttt{Base}'s interface
        available, \texttt{Derived} shouldn't do so either. The underlying
        principle is that \index{private inheritance}\emph{private inheritance} should be used when
        deriving a classs \texttt{Derived} from \texttt{Base} where \texttt{Derived}
        is-implemented-in-terms-of \texttt{Base}.
    \item  Should we use inheritance or composition? Here are some arguments:
        \begin{itemize}
        \item  In general terms composition results in looser coupling and
            should therefore be preferred over inheritance.
        \item  Composition allows us to define classes having multiple members
            of the same type (think about a class having multiple
            \texttt{std::string} members) which can not be realized using
            inheritance.
        \item  Composition allows us to separate the class's interface from its
            implementation. This allows us to modify the class's data
            organization without the need to recompile code using our
            class. This is also known as the \index{bridge design pattern}\emph{bridge design pattern} or the
            \index{compiler firewall}\emph{compiler firewall} or \index{pimpl}\emph{pimpl} (pointer to the
            implementation) idiom.
        \item  If \texttt{Base} offers members in its \emph{protected} interface that
            must be used when implementing \texttt{Derived} inheritance must also
            be used. Again: since we're implementing-in-terms-of the
            inheritance type should be \texttt{private}.
        \item  Protected inheritance may be considered when the derived class
            (\texttt{D}) itself is intended as a base class that should only make
            the members of its own base class (\texttt{B}) available to classes
            that are derived from it (i.e., \texttt{D}).
        \end{itemize}
    \end{itemize}

Private inheritance should also be used when a derived class is-a certain
type of base class, but in order to initialize that base class an object of
another class type must be available. Example: a new \texttt{istream} class-type
(say: a stream \texttt{IRandStream} from which random numbers can be extracted) is
derived from \texttt{std::istream}.  Although an \texttt{istream} can be constructed
empty (receiving its \texttt{streambuf} later using its \texttt{rdbuf} member), it is
clearly preferable to initialize the \texttt{istream} base class right away.

Assuming that a \texttt{Randbuffer: public std::streambuf} has been created for
generating random numbers then \texttt{IRandStream} can be derived from
\texttt{Randbuffer} and \texttt{std::istream}. That way the \texttt{istream} base class can
be initialized using the \texttt{Randbuffer} base class.

As a \texttt{RandStream} is definitely not a \texttt{Randbuffer} \emph{public} inheritance
is \emph{not} appropriate. In this case \texttt{IRandStream}
is-implemented-in-terms-of a \texttt{Randbuffer} and so \emph{private} inheritance
should be used.

\texttt{IRandStream}'s class interface should therefore start like this:
        \begin{verbatim}
    class IRandStream: private Randbuffer, public std::istream
    {
        public:
            IRandStream(int lowest, int highest)    // defines the range
            :
                Randbuffer(lowest, highest),
                std::istream(this)                  // passes &Randbuffer
            {}
        ...
    };
\end{verbatim}
Public inheritance should be reserved for classes for which the LSP holds
true. In those cases the derived classes can always be used instead of the
base class from which they derive by code merely using base class references,
pointers or members (I.e., conceptually the derived class \index{is-a}\emph{is-a} base
class). This most often applies to classes derived from base classes offering
virtual members. To separate the user interface from the redefinable interface
the base class's public interface should \emph{not} contain virtual members
(except for the virtual destructor) and the virtual members should all be in
the base class's private section. Such virtual members can still be overridden
by derived classes (this should not come as a surprise, considering how
polymorphism is implemented) and this design offers the base class full
control over the context in which the redefined members are used. Often the
public interface merely calls a virtual member, but those members can always
be redefined to perform additional duties.

The prototypical form of a \index{base class: prototype} base class therefore
looks like this:
        \begin{verbatim}
    class Base
    {
        public:
            virtual ~Base();
            void process();             // calls virtual members (e.g.,
                                        // v_process)
        private:
            virtual void v_process();   // overridden by derived classes
    };
\end{verbatim}
Alternatively a base class may offer a non-virtual destructor, which
should then be protected. It shouldn't be public to prevent deleting objects
through their base class pointers (in which case virtual destructors should be
used). It should be protected to allow derived class destructors to call their
base class destructors. Such base classes should, for the same reasons, have
non-public constructors and overloaded assignment operators.

\section{The `streambuf' class}\label{STREAMBUF}
\typeout{Original Yodl file: polymorphism/streambufdef}The class \index{streambuf}\texttt{std::streambuf} receives the character sequences
processed by streams and defines the interface between stream objects and
devices (like a file on disk). A \texttt{streambuf} object is usually not directly
constructed, but usually it is used as base class of some derived class
implementing the communication with some concrete device.

The primary reason for existence of the class \texttt{streambuf} is to decouple
the \texttt{stream} classes from the devices they operate upon. The rationale here
is to add an extra layer between the classes allowing us to communicate with
devices and the devices themselves. This implements a \index{chain of command}\emph{chain of command}
which is seen regularly in software design.

The \emph{chain of command} is considered a generic pattern when designing
 \index{reusable software}reusable software, encountered also in, e.g., the
 \index{TCP/IP stack}TCP/IP stack.

A \texttt{streambuf} provides yet another example of the chain of command
pattern: the program talks to \texttt{stream} objects, which in turn forward
requests to \texttt{streambuf} objects, which in turn communicate with the
devices. Thus, as we will see shortly, we are able to do in user-software what
had to be done via (expensive) system calls before.

The class \texttt{streambuf} has no public constructor, but does make available
several public member functions. In addition to these public member functions,
several member functions are only available to classes derived from
\texttt{streambuf}.  In section \ref{FILEBUF} a predefined specialization of the
class \texttt{streambuf} is introduced. All public members of \texttt{streambuf}
discussed here are \emph{also} available in \texttt{filebuf}.

The next section shows the \texttt{streambuf} members that may be overridden
when deriving classes from \texttt{streambuf}. Chapter \ref{CONCRETE} offers
concrete examples of classes derived from \texttt{streambuf}.

The class \texttt{streambuf} is used by streams performing input operations and
by streams performing output operations and their member functions can be
ordered likewise. The type \texttt{std::streamsize}\index{streamsize} used below may,
for all practical purposes, be considered equal to the type \texttt{size\_t}.

\label{STRBUFLABEL}
    \index{streambuf: and exceptions}\index{exception: and streambuf}
    When inserting information into \texttt{ostream} objects the information is
eventually passed on to the \texttt{ostream}'s \texttt{streambuf}. The \texttt{streambuf} may
decide to throw an exception. However, this exception does not leave the
\texttt{ostream} using the \texttt{streambuf}. Rather, the exception is caught by the
\texttt{ostream}, which sets its \texttt{ios::bad\_bit}. Exceptions thrown by
manipulators which are inserted into \texttt{ostream} objects are \emph{not} caught by
\texttt{ostream} objects.

\textbf{Public members for input operations}

\begin{itemize}
    \item \index{in\_avail}\texttt{std::streamsize in\_avail()}:\ \\ Returns a lower bound on the number of characters that can currently
        be read from the streambuf (e.g., all characters from the stream's
        current offset position to its \texttt{EOF} position).
    \item \index{sbumpc}\texttt{int sbumpc()}:\ \\ The next available character or \texttt{EOF} is returned. The returned
        character is removed from the \texttt{streambuf} object. If no input is
        available, \texttt{sbumpc} calls the (protected) member \index{uflow}\texttt{uflow} (see
        section \ref{SBPROTECTED} below) to make new characters
        available. \texttt{EOF} is returned if no more characters are
        available.
    \item \index{sgetc}\texttt{int sgetc()}:\ \\ The next available character or \texttt{EOF} is returned. The character
        is \emph{not} removed from the \texttt{streambuf} object (i.e., the
        \texttt{streambif}'s offset position isn't incremented). To remove a
        character from the \texttt{streambuf} object, \texttt{sbumpc} (or \texttt{sgetn}) can
        be used.
    \item \index{sgetn}\texttt{int sgetn(char $*$buffer, std::streamsize n)}:\ \\ At most \texttt{n} characters are retrieved from the input buffer, and
        stored in \texttt{buffer}. The actual number of characters read is
        returned. The (protected) member \index{xsgetn}\texttt{xsgetn} (see section
        \ref{SBPROTECTED} below) is called to obtain the requested number of
        characters.
    \item \index{snextc}\texttt{int snextc()}:\ \\ The current character is obtained from the input buffer and returned as
        the next available character or \texttt{EOF} is returned. The character
        is \emph{not} removed from the \texttt{streambuf} object.
    \item \index{sputbackc}\texttt{int sputbackc(char c)}:\ \\ Inserts \texttt{c} into the \texttt{streambuf}'s buffer to be returned as the
        next character to read from the \texttt{streambuf} object. Caution should
        be exercised when using this function: often there is a maximum of
        just one character that can be put back.
    \item \index{sungetc}\texttt{int sungetc()}:\ \\ Returns the last character read to the input buffer, to be read again
        at the next input operation.  Caution should be exercised when using
        this function: often there is a maximum of just one character that
        can be put back.
    \end{itemize}

\textbf{Public members for output operations}

\begin{itemize}
    \item \index{pubsync}\texttt{int pubsync()}:\ \\ Synchronizes (i.e., flushes) the buffer by writing any information
        currently available in the \texttt{streambuf}'s buffer to the
        device. Normally only used by classes derived from \texttt{streambuf}.
    \item \index{sputc}\texttt{int sputc(char c)}:\ \\ Character \texttt{c} is inserted into the \texttt{streambuf} object.  If, after
        writing the character, the buffer is full, the function calls the
        (protected) member function \index{overflow}\texttt{overflow} to flush the buffer to the
        device (see section \ref{SBPROTECTED} below).
    \item \index{sputn}\texttt{int sputn(char const $*$buffer, std::streamsize n)}:\ \\ At most \texttt{n} characters from \texttt{buffer} are inserted into the
        \texttt{streambuf} object. The actual number of characters inserted is
        returned. This member function calls the (protected) member \index{xsputn}\texttt{xsputn}
        (see section \ref{SBPROTECTED} below) to insert the requested number of
        characters.
    \end{itemize}

\textbf{Public members for miscellaneous operations}

The next three members are normally only used by classes derived from
\texttt{streambuf}.
    \begin{itemize}
    \item \index{pubseekoff}\texttt{ios::pos\_type pubseekoff(ios::off\_type offset, ios::seekdir way,
            ios::openmode mode = ios::in \textbar{} ios::out)}:\ \\ Sets the offset of the next character to be read or written to
        \texttt{offset}, relative to the standard \index{seekdir} \texttt{ios::seekdir}
        values indicating the direction of the seeking operation.
    \item \index{pubseekpos}\texttt{ios::pos\_type pubseekpos(ios::pos\_type pos,
            ios::openmode mode = ios::in \textbar{} ios::out)}:\ \\ Sets the \index{absolute position}absolute position of the next character to be read or
        written to \texttt{pos}.
    \item \index{pubsetbuf}\texttt{streambuf $*$pubsetbuf(char$*$ buffer, std::streamsize n)}:\ \\ The \texttt{streambuf} object is going to use \index{buffer}\texttt{buffer}, which may contain
        at least \texttt{n} characters.
    \end{itemize}

\subsection{Protected `streambuf' members}\label{SBPROTECTED}
    \typeout{Original Yodl file: polymorphism/protectedstreambuf}The \emph{protected} members of the class \texttt{streambuf} are important for
understanding and using \texttt{streambuf} objects. Although there are both
protected \index{data member}data members and protected member functions
    \index{member function} defined in the \texttt{class streambuf} using the protected
\emph{data} members is strongly discouraged as using them violates the principle
of \index{data hiding}\emph{data hiding}. As \texttt{streambuf}'s set of member functions is quite
extensive, it is hardly ever necessary to use its data members directly. The
following subsections do not even list all protected member functions but only
those are covered that are useful for constructing specializations.

\texttt{Streambuf} objects control a buffer, used for input and/or output, for
which begin-, actual- and end-pointers have been defined, as depicted in
figure \ref{SBBUFFERS}.
    \begin{figure}[tbp]
\centerline{\epsffile{iostreams/sbbuffers.eps}}
\caption{\label{SBBUFFERS}Input- and output buffer pointers of the class `streambuf'}
\end{figure}

\texttt{Streambuf} offers two protected constructors:
    \begin{itemize}
    \item \texttt{streambuf::streambuf()}:\ \\ Default (protected) constructor of the \texttt{class streambuf}.
    \item \texttt{streambuf::streambuf(streambuf const \&rhs)}:\ \\ (Protected) copy constructor of the \texttt{class streambuf}. Note that
this copy constructor merely copies the values of the data members of \texttt{rhs}:
after using the copy constructor both \texttt{streambuf} objects refer to the same
data buffer and initially their pointers point at identical positions. Also
note that these are \emph{not} shared pointers, but only `raw copies'.
    \end{itemize}

\subsubsection{Protected members for input operations}
        \typeout{Original Yodl file: polymorphism/protectedinput}Several protected member functions are available for input operations. The
member functions marked \texttt{virtual} may of course be redefined in derived
classes:
    \begin{itemize}
    \item \index{eback}\texttt{char $*$eback()}:\ \\ \texttt{Streambuf} maintains three pointers controlling its input buffer:
        \texttt{eback} points to the `end of the putback' area: characters can
        safely be put back up to this position. See also figure
        \ref{SBBUFFERS}. \texttt{Eback} points to the \emph{beginning} of the input
        buffer.
    \item \index{egptr}\texttt{char $*$egptr()}:\ \\ \texttt{Egptr} points just beyond the last character that can be retrieved
        from the input buffer. See also figure \ref{SBBUFFERS}. If \texttt{gptr}
        equals \texttt{egptr} the buffer must be refilled which is
        handled by member  \texttt{underflow}, see below.
    \item \index{gbump}\texttt{void gbump(int n)}:\ \\ The object's \texttt{gptr} (see below) is advanced over  \texttt{n} positions.
    \item \index{gptr}\texttt{char $*$gptr()}:\ \\ \texttt{Gptr} points to the next character to be
        retrieved from the object's input buffer. See also figure
        \ref{SBBUFFERS}.
    \item \index{pbackfail}\texttt{virtual int pbackfail(int c)}:\ \\ This member function may be overridden by derived classes to do
        something intelligent when putting back character \texttt{c} fails. One
        might consider restoring the old read pointer when input buffer's
        begin has been reached. This member function is called when ungetting
        or putting back a character fails. In particular, it is called when
            \begin{itemize}
            \item \texttt{gptr() == 0}: no buffering used,
            \item \texttt{gptr() == eback()}: no more room to push back,
            \item \texttt{$*$gptr() != c}: a different character than the next character
                to be read must be pushed back.
            \end{itemize}
       If \texttt{c == endOfFile()} then the input device must be reset by one
        character position. Otherwise \texttt{c} must be prepended to the
        characters to be read. The function should return \texttt{EOF} on
        failure. Otherwise 0 can be returned.
    \item \index{setg}\texttt{void setg(char $*$beg, char $*$next, char $*$beyond)}:\ \\ Initializes an input buffer. \texttt{beg} points to the beginning of the
        input area, \texttt{next} points to the next character to be retrieved, and
        \texttt{beyond} points to the location just beyond the input buffer's last
        character. Often \texttt{next} is at least \texttt{beg + 1}, to allow a put back
        operation. No input buffering is used when this member is called as
        \texttt{setg(0, 0, 0)}. See also the member \texttt{uflow}, below.
    \item \index{showmanyc}\texttt{virtual streamsize showmanyc()}:\ \\ (Pronounce: s-how-many-c) This member function may be overridden by
        derived classes. It must return a guaranteed lower bound on the number
        of characters that can be read from the device before \texttt{uflow} or
        \texttt{underflow} returns \texttt{EOF}. By default 0 is returned (meaning
        no or some characters are returned before the latter two functions
        return \texttt{EOF}). When a positive value is returned then the next
        call of \texttt{u(nder)flow} does not return \texttt{EOF}.
    \item \index{uflow}\texttt{virtual int uflow()}:\ \\ This member function may be overridden by derived classes to reload an
        input buffer with fresh characters. By default it calls \texttt{underflow}
        (see below) to reload the input buffer. If \texttt{underflow} fails,
        \texttt{EOF} is returned.  Otherwise, the next available character
        (\texttt{$*$gptr()}) is returned as an \texttt{unsigned char}, and then increments
        \texttt{gptr}. This is different from
        \texttt{underflow}, which merely returns the next available character,
        without incrementing \texttt{gptr's} position.

When the \texttt{streambuf} doesn't use input buffering this function,
        rather than \texttt{underflow}, can be overridden to produce the next
        available character from the device.
    \item \index{underflow}\texttt{virtual int underflow()}:\ \\ This member function may be overridden by derived classes to read
        another character from the device. The default implementation is to
        return \texttt{EOF}.

It is called when
            \begin{itemize}
            \item  there is no input buffer (\texttt{eback() == 0})
            \item \texttt{gptr() $>$= egptr()}: the input buffer is exhausted.
            \end{itemize}

Often, when buffering is used, the complete buffer
        is not refreshed as this would make it impossible to put back
        characters immediately following a reload. Instead, buffers are often
        refreshed in halves. This system is called a \index{split buffer}\emph{split buffer}.

Classes derived from \texttt{streambuf} for reading normally at least
        override \texttt{underflow}. The prototypical example of an overridden
        \texttt{underflow} function looks like this:
            \begin{verbatim}
int underflow()
{
    if (not refillTheBuffer())  // assume a member d_buffer is available
        return EOF;
                                // reset the input buffer pointers
    setg(d_buffer, d_buffer, d_buffer + d_nCharsRead);

                                // return the next available character
                                // (the cast is used to prevent
                                // misinterpretations of 0xff characters
                                // as EOF)
    return static_cast<unsigned char>(*gptr());
}
\end{verbatim}
       This example can be used by streams reading the information made
        available by devices. Section \ref{IOSTREAMBUF} covers a more
        complex situation: stream supporting both input and output.
    \item \index{xsgetn}\texttt{virtual streamsize xsgetn(char $*$buffer, streamsize n)}:\ \\ This member function may be overridden by derived classes to retrieve
        at once \texttt{n} characters from the input device. The default
        implementation is to call \texttt{sbumpc} for every single character
        meaning that by default this member (eventually) calls \texttt{underflow}
        for every single character. The function returns the actual number of
        characters read or \texttt{EOF}. Once \texttt{EOF} is returned the
        \texttt{streambuf} stops reading the device (see also section
        \ref{IOSTREAMBUF}.)
\end{itemize}

\subsubsection{Protected members for output operations}
        \typeout{Original Yodl file: polymorphism/protectedoutput}The following  protected members are available for output
operations. Again, some members may be overridden by derived classes:
    \begin{itemize}
    \item \index{overflow}\texttt{virtual int overflow(int c)}:\ \\ This member function may be overridden by derived classes to flush the
        characters currently stored in the output buffer to the output device,
        and then to reset the output buffer pointers so as to represent an
        empty buffer. Its parameter \texttt{c} is initialized to the next character
        to be processed. If no output buffering is used \texttt{overflow} is called
        for every single character that is written to the \texttt{streambuf}
        object. No output buffering is accomplished by setting the buffer
        pointers (using, \texttt{setp}, see below) to 0. The
        \index{default implementation}default implementation returns \texttt{EOF}, indicating that no
        characters can be written to the device.

Classes derived from \texttt{streambuf} for writing normally at least
        override \texttt{overflow}. The prototypical example of an overridden
        \texttt{overflow} function looks like this (see also section
        \ref{IOSTREAMBUF}):
 \begin{verbatim}
int OFdStreambuf::overflow(int c)
{
    sync();                             // flush the buffer
    if (c != EOF)                       // write a character?
    {
        *pptr() = static_cast<char>(c); // put it into the buffer
        pbump(1);                       // advance the buffer's pointer
    }
    unsigned char ch = c;
    return ch;
}
\end{verbatim}
\item \index{pbase}\texttt{char $*$pbase()}:\ \\ \texttt{Streambuf} maintains three pointers controlling its output buffer:
        \texttt{pbase} points to the beginning of the output buffer area. See also
        figure \ref{SBBUFFERS}.
    \item \index{pptr}\texttt{char $*$epptr()}:\ \\ \texttt{Streambuf} maintains three pointers controlling its output buffer:
        \texttt{epptr} points just beyond the output buffer's last available
        location. See also figure \ref{SBBUFFERS}. If \texttt{pptr} (see below)
        equals \texttt{epptr} the buffer must be flushed. This is implemented by
        calling \texttt{overflow}, see before.
    \item \index{pbump}\texttt{void pbump(int n)}:\ \\ The location returned by \texttt{pptr} (see below) is advanced by \texttt{n}
        positions. The next character will be written at that location.
    \item \index{pptr}\texttt{char $*$pptr()}:\ \\ \texttt{Streambuf} maintains three pointers controlling its output buffer:
        \texttt{pptr} points to the location in the output buffer where the next
        available character will be written (note that in order to write a
        character \texttt{pptr()} must point to a location in the range \texttt{pbase()}
        to \texttt{epptr()}). See also figure \ref{SBBUFFERS}.
    \item \index{setp}\texttt{void setp(char $*$beg, char $*$beyond)}:\ \\ \texttt{Streambuf}'s output buffer is initialized to the locations passed
        to \texttt{setp}. \texttt{Beg} points to the beginning of the output buffer and
        \texttt{beyond} points just beyond the last available location of the
        output buffer. Use \texttt{setp(0, 0)} to indicate that \index{no buffering}no buffering
        should be used. In that case \texttt{overflow} is called for every single
        character to be written to the device.
    \item \index{xsputn}\texttt{virtual streamsize xsputn(char const $*$buffer, streamsize n)}:\ \\ This member function may be overridden by derived classes to write a
        series of at most \texttt{n} characters to the output buffer. The actual
        number of inserted characters is returned. If \texttt{EOF} is returned
        writing to the device stops. The default implementation calls
        \texttt{sputc} for each individual character. Redefine this member if,
        e.g., the \texttt{streambuf} should support the \texttt{ios::openmode ios::app}.
        Assuming the class \texttt{MyBuf}, derived from \texttt{streambuf}, features a
        data member \texttt{ios::openmode d\_mode} (representing the requested
        \texttt{ios::openmode}), and a member \texttt{write(char const $*$buf, streamsize
        len)} (writing \texttt{len} bytes at \texttt{pptr()}), then the following code
        acknowledges the \texttt{ios::app} mode (see also section
        \ref{IOSTREAMBUF}):
 \begin{verbatim}
std::streamsize MyStreambuf::xsputn(char const *buf, std::streamsize len)
{
    if (d_openMode & ios::app)
        seekoff(0, ios::end);

    return write(buf, len);
}
\end{verbatim}
\end{itemize}

\subsubsection{Protected members for buffer manipulation}
        \typeout{Original Yodl file: polymorphism/protectedbuffer}Several protected members are related to buffer management and positioning:
    \begin{itemize}
    \item \index{setbuf}\texttt{virtual streambuf $*$setbuf(char $*$buffer, streamsize n)}:\ \\ This member function may be overridden by derived classes to install a
        buffer. The default implementation performs no actions. It is called
        by \texttt{pubsetbuf}.
    \item \index{seekoff}\texttt{virtual ios::pos\_type seekoff(ios::off\_type offset, 
                   ios::seekdir way, ios::openmode mode = ios::in \textbar{} ios::out)}:\ \\ This member function may be overridden by derived classes to
        reset the next pointer for input or output to a new relative
        position (using
       \index{cur}\index{beg}\texttt{ios::beg, ios::cur} or \index{end}\texttt{ios::end}). The
        default implementation indicates failure by returning -1. This
        function is called when \texttt{tellg} or \texttt{tellp} are called. When
        derived class supports seeking, then it should also define this
        function to handle repositioning requests. It is called by
        \index{pubseekoff}\texttt{pubseekoff}. The new position or (by default) an invalid position
        (i.e., -1) is returned (see also section \ref{IOSTREAMBUF}).
    \item \index{seekpos}\texttt{virtual ios::pos\_type seekpos(ios::pos\_type offset,
            ios::openmode mode = ios::in \textbar{} ios::out)}:\ \\ This member function may be overridden by derived classes to reset the
        next pointer for input or output to a new absolute position (i.e,
        relative to \texttt{ios::beg}). This function is called when \texttt{seekg} or
        \texttt{seekp} are called. The new position or (by default) an invalid
        position (i.e., -1) is returned.
    \item \index{sync}\texttt{virtual int sync()}:\ \\ This member function may be overridden by derived classes to flush the
        output buffer to the output device or to reset the input device just
        beyond the position of the character that was returned last. It
        returns 0 on success, -1 on failure. The default implementation (not
        using a buffer) is to return 0, indicating successful syncing. This
        member is used to ensure that any characters that are still buffered
        are written to the device or to put unconsumed characters back to the
        device when the \texttt{streambuf} object ceases to exist.
   \end{itemize}

\subsubsection{Deriving classes from `streambuf'}
        \typeout{Original Yodl file: polymorphism/derivingfromstreambuf}    When classes are derived from \texttt{streambuf} at least \texttt{underflow} should
be overridden by classes intending to read information from devices, and
\texttt{overflow} should be overridden by classes intending to write information to
devices. Several examples of classes derived from \texttt{streambuf} are provided
in chapter \ref{CONCRETE}.

\texttt{Fstream} class type objects use a combined input/output buffer,
resulting from \texttt{istream} and \texttt{ostream} being virtually derived from
\texttt{ios}, which class defines a \texttt{streambuf}. To construct a class
supporting both input and output using separate buffers, the \texttt{streambuf}
itself may define two buffers. When \texttt{seekoff} is called for reading, a
\texttt{mode} parameter can be set to \texttt{ios::in}, otherwise to \texttt{ios::out}. Thus
the derived class knows whether it should access the \texttt{read} buffer or the
\texttt{write} buffer. Of course, \texttt{underflow} and \texttt{overflow} do not have to
inspect the mode flag as they by implication know on which buffer they should
operate.

\subsection{A streambuf used for input and output}\label{IOSTREAMBUF}
    \typeout{Original Yodl file: polymorphism/iostreambuf}Several complexities might be encountered when overriding \texttt{underflow}
especially when buffers must repeatedly be refreshed and loaded. They are:
    \begin{itemize}
    \item  How to keep track of the over-all current offset?
    \item  The actions performed by \texttt{underflow} and \texttt{overflow}.
    \item  Should \texttt{uflow} be overridden?
    \item  Which members are called by which stream read/write requests?
    \item  Overriding \texttt{xsgetn}.
    \item  Overriding \texttt{xsputn}.
    \end{itemize}

\begin{figure}[tbp]
\centerline{\epsffile{polymorphism/buffers.eps}}
\caption{\label{BuffersFig}Multi-buffer I/O handling}
\end{figure}

Figure \ref{BuffersFig} shows a situation where multiple buffers are used: the
device's information is made available in a buffer which is processed and
managed by the derived \texttt{streambuf} class. In this figure the following
variables are introduced:
    \begin{itemize}
    \item \texttt{offset} is the device's current position. Its lower limit is 0,
        and for all practical purposes there is no upper limit.
    \item \texttt{maxEnd}, however, is the device's current physical maximum offset
        value. Such a physical maximum may not exist, but it \emph{does} exist if,
        e.g., a physical buffer in memory is used which cannot contain more
        than a fixed number of bytes. In those cases \texttt{maxEnd} is set to that
        maximum value, representing the offset just beyond the highest offset
        where a byte may be written to the device;
    \item \texttt{getEnd} is the current maximum number of characters that can be read
        from the device. With a newly defined device its value is 0 (zero),
        but once bytes are written to the device \texttt{getEnd} is updated to the
        position just beyond to the highest ever offset where a byte was
        written. When disk-files are used \texttt{getEnd} would be equal to the
        file's size;
    \item  All of the device's information cannot at once be made available in
        the \texttt{streambuf's} buffer. Instead it is split up in blocks of a
        fixed size. The device's offset of the first byte of such a
        block is available in \texttt{bufBeg}, and the offset just beyond the last
        byte of such a block is available in \texttt{bufEnd}; \texttt{bufEnd} never
        exceeds \texttt{maxEnd}.
    \end{itemize}

This section covers how such multi-buffer data can be handled by \texttt{iostream}
objects: streams supporting reading \emph{and} writing. Such streams offer
\texttt{seekg} and \texttt{seekp} members, but the device's offset position applies to
both \texttt{seekg} and \texttt{seekp}: after either \texttt{seekg} or \texttt{seekp} reading and
writing both start at the position defined by either of these two seek
members. Furthermore, when switching between reading and writing no
\texttt{seekg/seekp} call is required: by default new read or write requests
continue at the device's current offset, set by the last read, write, or seek
request.

\subsubsection{Keeping track of the offset}
        \typeout{Original Yodl file: polymorphism/offset}Keeping track of the current offset is not a trivial problem. As long as
neither reading nor writing has been used \texttt{seekg} and \texttt{seekp} simply
compute the requested offset. Seek requests specifying \texttt{ios::beg} change
\texttt{offset} to the requested value. When \texttt{ios::end} is specified the offset
is computed relative to \texttt{getEnd} (since \texttt{getEnd} corresponds to the file
size of a physical disk-file \texttt{ios::end} should use \texttt{getEnd} as the current
end-offset and not \texttt{maxEnd}).

Computing offsets as shifts relative to the current offset is slightly
more complicated. When so far neither reading nor writing has been used
things are easy: the new offset equals the current offset plus the specified
\texttt{ios::off\_type} sthift. But once information has just been read or written
things get complicated because \texttt{offset} doesn't correspond anymore to
the actual offset. 

For example, initially, when information is written to the device's \texttt{offset,
bufBeg} and \texttt{bufEnd} are computed so that \texttt{offset} is located inside the
buffer starting at \texttt{bufBegin} and continuing to \texttt{bufEnd}, but thereafter
subsequent write requests are handled by the stream itself, and therefore
\texttt{offset} isn't updated. Instead only \texttt{pptr()'s} location, is updated,
invalidating \texttt{offset}.

Assume buffers are 100 bytes large, and in a concrete situation the buffer
covers the device's offsets 500 to 600 while \texttt{offset} equals 510. Then,
after writing \texttt{"hello" pptr()} is 515, but \texttt{offset} is still at
510. Consequently, in that situation issuing \texttt{seekp(-5, ios::cur).tellp()}
should not return 5 (i.e., \texttt{offset - 5}), but 10: \texttt{bufBegin + pptr() -
pbase() - 5}. A similar situation is encountered when reading: \texttt{gptr()} is
updated by read operations.

This problem is solved by introducing three states: the \texttt{streambuf} object
starts in the \texttt{SEEK}-state: the last-used operation wasn't reading or
writing. Once reading is used the state changes to \texttt{READ}, and to \texttt{WRITE}
once writing is used.

When s seek-request is issued the relative position depends on the current
state: in state \texttt{SEEK} the seek's shift value (as in \texttt{seekg(shift,
ios::cur)})is added to \texttt{offset}, in state \texttt{READ} it's added to \texttt{bufBegin
+ gptr() - eback()}, and in state \texttt{WRITE} it's added to \texttt{bufBegin + pptr()
- pbase()}. Seek-requests also change the state to \texttt{SEEK}, so subsequent
seek requests are computed relative to the last computed \texttt{offset}. Finally,
to ensure that \texttt{underflow} and \texttt{overflow} are called when subsequent read
or write operations are requested seek requests also reset \texttt{setg} and
\texttt{setp} by calling them with 0 (zero) arguments. Here is a skeleton
implementation of \texttt{seekoff} (assuming \texttt{using namespace std}):
    \begin{verbatim}
ios::pos_type StreamBuf::seekoff(ios::off_type step,
                                 ios::seekdir way, ios::openmode mode)
{
    off_type offs;

    switch (way)
    {
        default:                    // ios::beg: buffOffset is step
            offs = step;
        break;

        case ios::cur:
            switch (d_last)
            {
                                    // default: case SEEK
                default:            // no read/write used so far
                    offs = offset;
                break;              // add step to bufOffset (below)

                case READ:          // setg was used, set bufOffset to
                                    // the abs offset of gptr()
                    offs = bufbeg + gptr() - eback();
                break;

                case WRITE:         // setp was used, set bufOffset to
                                    // the abs offset of pptr()
                    offs = bufbeg + pptr() - pbase();

                                    // may extend the writing area
                    if (offs > static_cast<off_type>(getend))
                        getend = offs;
                break;
            }

            offs += step;         // add the step
        break;

        case ios::end:
            offs = getend + step; // shift from the last write position
        break;
    }

    if (offs < 0)
        offs = 0;                 // offset always >= 0

    d_last = SEEK;

    setg(0, 0, 0);                  // reset the buffers
    setp(0, 0);

    return offset = offs;      // the updated offset
}
\end{verbatim}
\subsubsection{The members overflow and underflow}
        \typeout{Original Yodl file: polymorphism/overunder}The member \texttt{overflow} is called then the stream's write buffer is empty or
exhausted. The member \texttt{underflow} is called then the stream's read buffer is
empty or exhausted.

In both cases a new buffer (from \texttt{bufBeg} to \texttt{bufEnd}) is computed
containing \texttt{offset}. But \texttt{offset} depends on the streambuf's state. When
called in the \texttt{SEEK} state \texttt{offset} is up-to-date; when called in the
\texttt{WRITE} state the offset is at the last-used write offset; when called in
the \texttt{READ} state the current offset is at the end of the current read
buffer. 

When called in the \texttt{SEEK} state the read and write buffers are already
empty. When called in the \texttt{READ} state the actual offset is determined and
the read buffer is reset to ensure that \texttt{underflow} is called at the next
read operation.

Likewise, when called in the \texttt{WRITE} state the write buffer is reset to
ensure that \texttt{overflow} is called at the next write request. 

Both \texttt{underflow} and \texttt{overflow} therefore start by determining the current
offset, computing the corresponding buffer boundaries. The member \texttt{getOffset}
is called by both \texttt{underflow} and \texttt{overflow}. Here's its skeleton
implementation: 
    \begin{verbatim}
size_t StreamBuf::getOffset()
{
    size_t offs;

    switch (d_last)
    {
        default:        // no buffers so far: use offset
            offs = offset;
        break;

        case READ:      // use the lastused read offset
            offs = bufbeg + (gptr() - eback());
            setg(0, 0, 0);
        break;

        case WRITE:     // use the lastused write offset
            offs = bufbeg + (pptr() - pbase());
            setp(0, 0);
        break;
    }

    bufLimits(offs);  // set the buffer limits

    return offs;
}
\end{verbatim}
The member \texttt{bufLimits} simply ensures that \texttt{offset} is located inside a
buffer: 
    \begin{verbatim}
void StreamBuf::bufLimits(size_t offset)
{
    bufbeg = offset / blockSize * blockSize;
    bufend = bufbeg + blockSize;

    if (bufend > maxend)        // never exceed maxend
        bufend = maxend;
}
\end{verbatim}
The member \texttt{overflow} returns \texttt{EOF} or initializes a new read
buffer. Since \texttt{overflow} is guaranteed to be called when writing is
requested from states \texttt{SEEK} and \texttt{READ} it calls \texttt{getOffset} to obtain
the current absolute offset and the corresponding \texttt{bufBeg} en \texttt{bufEnd}
values. Writing can only be used if \texttt{offset $<$ maxEnd}. If so, a new write
buffer is installed whose \texttt{pptr()} points at the \texttt{offset} position in the
physical device. After calling \texttt{setp} \texttt{overflow} \emph{must} return \texttt{ch} on
success. Here's \texttt{overflow's} skeleton:
    \begin{verbatim}
int StreamBuf::overflow(int ch)     // writing
{
    size_t offs = getOffset();

    if (offs >= maxend)           // at maxend: no more space
        return EOF;
                                    // define the writing buffer
    setp(allData + bufbeg, allData + bufend);
    pbump(offs - bufbeg);       // go to the pos. to write the next ch

    *pptr() = ch;                   // write ch to the buffere
    pbump(1);
    ++offset;
                                    // maybe enlarge getend
    getend = max(getend, bufbeg + (pptr() - pbase()));

    d_last = WRITE;                 // change to writing mode
                                    // return the last written char
    return static_cast<unsigned char>(ch);
}
\end{verbatim}
The member \texttt{underflow} returns \texttt{EOF} or initializes a new read
buffer. Since \texttt{underflow} is guaranteed to be called when reading is
requested from states \texttt{SEEK} and \texttt{WRITE} it calls, like \texttt{overflow},
\texttt{getOffset} to obtain the current absolute offset as well as the
matching \texttt{bufBeg} en \texttt{bufEnd} values. Reading can only be used if
\texttt{offset $<$ getEnd}. If so, a new read buffer is installed whose \texttt{gptr()}
points at the \texttt{offset} position in the physical device.

As with \texttt{overflow}, after calling \texttt{setg} it's \emph{essential} that the first
available character (i.e., \texttt{$*$gptr()}) is returned. If not and the buffer
contains just one character then that character might not be processed by
\texttt{underflow's} caller. Here's \texttt{underflow's} skeleton:
    \begin{verbatim}
int StreamBuf::underflow()
{
    offset = getOffset();

    if (offset >= getend)    // beyond the reading area
        return EOF;
                                // define the reading buffer
    setg(allData + bufbeg, allData + offset,
         allData + min(getend, bufend));

    d_last = READ;
    return static_cast<unsigned char>(*gptr());
}
\end{verbatim}
\subsubsection{Overriding uflow?}
        \typeout{Original Yodl file: polymorphism/uflow}Should \texttt{uflow} be overridden?  The function \texttt{uflow} is called when it's
available to return the next character from the device. In practice this is
handled by \texttt{underflow}, so there's probably little need for overriding
\texttt{uflow}. But \emph{if} \texttt{uflow} is overridden then it must return the next
avaialble character and update \texttt{gptr()} to the next available
character. If the update isn't performed then the returned characters is
received twice by the stream. Here's a skeleton:
    \begin{verbatim}
int StreamBuf::uflow()
{
    if (gptr() == egptr() and underflow() == EOF)
        return EOF;

    unsigned char ch = *gptr();
    gbump(1);
    return ch;
}
\end{verbatim}
\subsubsection{When are which members called?}
        \typeout{Original Yodl file: polymorphism/whencalled}The following overview shows which members are called by which \emph{stream}
read/write/seek requests:
    \begin{itemize}
    \item \texttt{seek} requests \texttt{seekg, seekp} call \texttt{seekoff}. The member
        \texttt{streambuf::seekpos} is maybe also called, but in practice
        \texttt{seekpos} calls \texttt{seekoff};

\item \texttt{get} calls \texttt{underflow} if there's no (or an exhausted) read
        buffer. Otherwise it returns the character at \texttt{gptr()}, incrementing
        its position;

\item \texttt{$>$$>$}  calls \texttt{underflow} if there's no (or an exhausted) read
        buffer. Otherwise if white-space characters are ignored (which is the
        default) all white-space characters are skipped and the stream reads
        the matching bytes from the read buffer, refreshing the buffer when
        needed;

\item \texttt{read} calls \texttt{xsgetn} (which itself calls \texttt{underflow}) if there's
        no or an exhausted read buffer, and tries to read the requested number
        of characters from the device;

\item \texttt{rdbuf()} is used to insert the device's content from its current
        offset position. It calls \texttt{underflow} and reads all the buffer's
        characters until \texttt{underflow} returns \textbf{EOF}.

\item \texttt{put} calls \texttt{overflow} if there's no (or a  filled up) write
        buffer. Otherwise it returns the character at \texttt{pptr()}, incrementing
        its position;

\item \texttt{$<$$<$} calls \texttt{overflow} if there's no (or a filled up) write
        buffer. Otherwise the argument may be converted to characters (like
        when insterting an \texttt{int} value) and the resulting characters are
        inserted into the device, refreshing the buffer when needed;

\item \texttt{write} calls \texttt{xsputn} (which itself calls \texttt{overflow}) if there's
        no or a filled up wrte buffer, and tries to write the requested number
        of characters to the device.
    \end{itemize}

\subsubsection{The member xsgetn}
        \typeout{Original Yodl file: polymorphism/xsgetn}A stream's \texttt{read} member calls \texttt{xsgetn} to read \texttt{nChars} characters from
the device. The \texttt{nChar} characters might not be available in the current
buffer. In those cases \texttt{underflow} is called to refresh the
buffer. Initially some bytes may already be available. At each cycle the
number of available characters are copied to the next location of its \texttt{buf}
parameter, calling \texttt{underflow} if there are no available characters
anymore. So \texttt{xsgetn}, while there are (still) characters to be read from the
device, must
    \begin{itemize}
    \item  determine whether the current buffer contains available characters;
    \item  if not, it must call \texttt{underflow};
    \item  the number of available characters are copied to the next position of
        the \texttt{buf} parameter;
    \item  the number of bytes to read is reduced by the number of available
        bytes; 
    \item  the \texttt{buf} pointer and the counters are updated using the
        number of read bytes. 
    \end{itemize}

Here is a skeleton of \texttt{xsgetn}:
    \begin{verbatim}
streamsize StreamBuf::xsgetn(char *buf, streamsize nChars)
{
    size_t toRead = nChars;
    size_t nRead = 0;

    while (toRead)
    {
        size_t avail = egptr() - gptr();    // available buffer space

                                            // no or empty memory buffer
                                            // but no more readable chars
        if (avail == 0 and underflow() == EOF)
            return nRead;

        avail = min(getend, bufend) - offset;
        size_t next = min(avail, toRead);   // next #bytes to write

        memcpy(buf, gptr(), next);          // write to the buffer
        gbump(next);                        // update gptr

        buf += next;                        // update the buf location
        toRead -= next;                     // and update the counters
        nRead += next;
        offset += next;
    }

    d_last = READ;                  // now reading: also if underflow
                                    // wasn't called.
    return nRead;
}
\end{verbatim}
\subsubsection{The member xsputn}
        \typeout{Original Yodl file: polymorphism/xsputn}A stream's \texttt{write} member calls \texttt{xputn} to write \texttt{nChars} characters
into the device. As with \texttt{xsgetn} the \texttt{nChar} characters might not be
available in the current buffer. In those cases \texttt{overflow} is called to
refresh the buffer. Room for some bytes may still be available, and at each
cycle the number of available locations are copied from the member's \texttt{buf}
parameter to the \texttt{streambuf's} write buffer, calling \texttt{overflow} if there's
no space available anymore in the current write buffer. So \texttt{xsputn}, while
there are (still) characters to be written to the device, must
    \begin{itemize}
    \item  determine whether the current buffer contains some space;
    \item  if not, it must call \texttt{overflow};
    \item  the number of available characters are copied to the device's 
        write-buffer;
    \item  the number of bytes to write is reduced by the number of available
        bytes; 
    \item  the \texttt{buf} pointer and the counters are updated using the
        number of written bytes. 
    \end{itemize}

Here is a skeleton of \texttt{xsputn}:
    \begin{verbatim}
streamsize StreamBuf::xsputn(char const *buf, streamsize nChars)
{
    size_t toWrite = nChars;
    size_t nWritten = 0;

    size_t offs = getOffset();
    size_t avail = epptr() - pptr();        // available buffer space

    while (toWrite)
    {
        if (avail == 0)                     // no space: try to reload
        {                                   // the buffer
            if (overflow(*buf) == EOF)      // storage space exhausted?
                break;                      // yes: done

            ++buf;                          // no: 1 byte was written
            ++nWritten;
            ++offs;

            --toWrite;

            avail = epptr() - pptr();       // remaining buffer space

            if (avail == 0)                 // next cycle if avail == 0
                continue;
        }

        size_t next = min(avail, toWrite);  // next #bytes to write

        memcpy(pptr(), buf, next);          // write to the buffer
        pbump(next);                        // update pptr

        buf += next;                        // update the buf location
        nWritten += next;                   // and update the counters
        toWrite -= next;
        offset = offs += next;
    }

    if (getend < offs + nWritten)           // maybe enlarge the reading
        getend = offs + nWritten;           // area

    d_last = WRITE;                         // WRITE state: now writing,
                                            // maybe overflow wasn't used
    return nWritten;
}
\end{verbatim}
\subsection{The class `filebuf'}\label{FILEBUF}
    \typeout{Original Yodl file: polymorphism/filebuf}The \texttt{class} \index{filebuf}\texttt{filebuf} is a specialization of \texttt{streambuf} used by the
file \index{stream}\texttt{stream} classes. Before using a \texttt{filebuf} the header file
\index{fstream: header file}\texttt{$<$fstream$>$} must be included.

In addition to the (public) members that are available through the \texttt{class
streambuf}, \texttt{filebuf} offers the following (public) members:
    \begin{itemize}
    \item \index{filebuf}\texttt{filebuf()}:\ \\ \texttt{Filebuf} offers a public constructor. It initializes
        a plain \texttt{filebuf} object that is not yet connected to a stream.
    \item \index{is\_open}\texttt{bool is\_open()}:\ \\ \texttt{True} is returned if the \texttt{filebuf} is actually connected to an
        open file, \texttt{false} otherwise. See the \texttt{open} member, below.
    \item \index{open}\texttt{filebuf $*$open(char const $*$name, ios::openmode mode)}:\ \\ Associates the \texttt{filebuf} object with a file
        whose name is provided. The file is opened according to the provided
        \index{openmode}\texttt{openmode}.
    \item \index{close}\texttt{filebuf $*$close()}:\ \\ Closes the association between the \texttt{filebuf}
        object and its file. The association is automatically closed when the
        \texttt{filebuf} object ceases to exist.
    \end{itemize}

\section{A polymorphic exception class}\label{POLYMORPHEXCEPTION}
\typeout{Original Yodl file: polymorphism/exception}Earlier in the \textbf{C++} Annotations (section \ref{EMPTYTHROW}) we hinted at the
possibility of designing a class \texttt{Exception} whose \texttt{process} member
would behave differently, depending on the kind of exception that was
thrown. Now that we've introduced \index{polymorphism}polymorphism we can further develop this
example.

It probably does not come as a surprise that our class \texttt{Exception} should be
a polymorphic base class from which special exception handling classes can be
derived. In section \ref{EMPTYTHROW} a member \texttt{severity} was used offering
functionality that may be replaced by members of the \texttt{Exception} base class.

The base class \texttt{Exception} may be  designed as follows:
        \begin{verbatim}
    #ifndef INCLUDED_EXCEPTION_H_
    #define INCLUDED_EXCEPTION_H_
    #include <iostream>
    #include <string>

    class Exception
    {
        std::string d_reason;

        public:
            Exception(std::string const &reason);
            virtual ~Exception();

            std::ostream &insertInto(std::ostream &out) const;
            void handle() const;

        private:
            virtual void action() const;
    };

    inline void Exception::action() const
    {
        throw;
    }
    inline Exception::Exception(std::string const &reason)
    :
        d_reason(reason)
    {}
    inline void Exception::handle() const
    {
        action();
    }
    inline std::ostream &Exception::insertInto(std::ostream &out) const
    {
        return out << d_reason;
    }

    inline std::ostream &operator<<(std::ostream &out, Exception const &e)
    {
        return e.insertInto(out);
    }

    #endif
\end{verbatim}
    Objects of this class may be inserted into \texttt{ostream}s but the core
element of this class is the virtual member function \texttt{action}, by default
rethrowing an exception.

A derived class \texttt{Warning} simply prefixes the thrown warning text by the
text \texttt{Warning:}, but a derived class \texttt{Fatal} overrides
\texttt{Exception::action} by calling \index{terminate}\texttt{std::terminate}, forcefully
terminating the program.

Here are the classes \texttt{Warning} and \texttt{Fatal}
        \begin{verbatim}
    #ifndef WARNINGEXCEPTION_H_
    #define WARNINGEXCEPTION_H_

    #include "exception.h"

    class Warning: public Exception
    {
        public:
            Warning(std::string const &reason)
            :
                Exception("Warning: " + reason)
            {}
    };
    #endif
\end{verbatim}
        \begin{verbatim}
    #ifndef FATAL_H_
    #define FATAL_H_

    #include "exception.h"

    class Fatal: public Exception
    {
        public:
            Fatal(std::string  const &reason);
        private:
            void action() const override;
    };

    inline Fatal::Fatal(std::string  const &reason)
    :
        Exception(reason)
    {}

    inline void Fatal::action() const
    {
        std::cout << "Fatal::action() terminates" << '\n';
        std::terminate();
    }

    #endif
\end{verbatim}
When the example program is started without arguments it throws a
\texttt{Fatal} exception, otherwise it throws a \texttt{Warning} exception. Of
course, additional exception types could also easily be defined. To make the
example compilable the \texttt{Exception} destructor is defined above \texttt{main}. The
default destructor cannot be used, as it is a virtual destructor. In practice
the destructor should be defined in its own little source file:
        \begin{verbatim}
    #include "warning.h"
    #include "fatal.h"

    Exception::~Exception()
    {}

    using namespace std;

    int main(int argc, char **argv)
    try
    {
        try
        {
            if (argc == 1)
                throw Fatal("Missing Argument") ;
            else
                throw Warning("the argument is ignored");
        }
        catch (Exception const &e)
        {
            cout << e << '\n';
            e.handle();
        }
    }
    catch (...)
    {
        cout << "caught rethrown exception\n";
    }
\end{verbatim}
\section{How polymorphism is implemented}\label{howpolymorphism}
\typeout{Original Yodl file: polymorphism/implementation}This section briefly describes how \index{polymorphism: how} polymorphism is
implemented in \textbf{C++}.  It is not necessary to understand how polymorphism is
implemented if you just want to \emph{use} polymorphism. However, we think it's
nice to know how polymorphism is possible. Also, knowing how polymorphism is
implemented clarifies why there is a (small) penalty to using polymorphism in
terms of memory usage and efficiency.

The fundamental idea behind polymorphism is that the compiler does not know
which function to call at compile-time. The appropriate function is
selected at run-time. That means that the address of the function must be
available somewhere, to be looked up prior to the actual call. This
`somewhere' place must be accessible to the object in question. So when a
\texttt{Vehicle $*$vp} points to a \texttt{Truck} object, then \texttt{vp-$>$mass()} calls
\texttt{Truck}'s member function. The address of this function is obtained through
the actual object to which \texttt{vp} points.

Polymorphism is commonly implemented as follows: an object containing virtual
member functions also contains, usually as its first data member a
 \index{hidden data member}hidden data member, pointing to an array containing the addresses of the
class's virtual member functions. The hidden data member is usually called the
\index{vpointer}\emph{vpointer}, the array of virtual member function addresses the \index{vtable}\emph{vtable}.

The class's vtable is shared by all objects of that class.  The overhead of
polymorphism in terms of \index{memory consumption}memory consumption is therefore:
    \begin{itemize}
    \item  one vpointer data member per object pointing to:
    \item  one vtable per class.
    \end{itemize}
    Consequently, a statement like \texttt{vp-$>$mass} first inspects the hidden
data member of the object pointed to by \texttt{vp}. In the case of the vehicle
classification system, this data member points to a table containing two
addresses: one pointer to the function \texttt{mass} and one pointer to the
function \texttt{setMass} (three pointers if the class also defines (as it
should) a virtual destructor). The actually called function is determined from
this table.

The internal organization of the objects having virtual functions is
illustrated in Figure \ref{ImplementationFigure} and Figure \ref{CaumonFigure}
(originals provided by \texttt{Guillaume Caumon}\footnote{mailto:Guillaume.Caumon@ensg.inpl-nancy.fr}).

\begin{figure}[tbp]
\centerline{\epsffile{polymorphism/implementation.eps}}
\caption{\label{ImplementationFigure}Internal organization objects when virtual functions are defined.}
\end{figure}

\begin{figure}[tbp]
\centerline{\epsffile{polymorphism/caumon.eps}}
\caption{\label{CaumonFigure}Complementary figure, provided by Guillaume Caumon}
\end{figure}

As shown by Figure \ref{ImplementationFigure} and Figure \ref{CaumonFigure},
objects potentially using virtual member functions must have one (hidden) data
member to address a table of function pointers. The objects of the classes
\texttt{Vehicle} and \texttt{Car} both address the same table. The class \texttt{Truck},
however, overrides \texttt{mass}. Consequently, \texttt{Truck} needs its own vtable.

A small complication arises when a class is derived from multiple base
classes, each defining virtual functions. Consider the following example:
        \begin{verbatim}
    class Base1
    {
        public:
            virtual ~Base1();
            void fun1();        // calls vOne and vTwo
        private:
            virtual void vOne();
            virtual void vTwo();
    };
    class Base2
    {
        public:
            virtual ~Base2();
            void fun2();        // calls vThree
        private:
            virtual void vThree();
    };
    class Derived: public Base1, public Base2
    {
        public:
            ~Derived() override;
        private:
            void vOne() override;
            void vThree() override;
    };
\end{verbatim}
In the example \texttt{Derived} is multiply derived from \texttt{Base1} and \texttt{Base2},
each supporting virtual functions. Because of this, \texttt{Derived} also has
virtual functions, and so \texttt{Derived} has a \texttt{vtable} allowing a base class
pointer or reference to access the proper virtual member.

When \texttt{Derived::fun1} is called (or a \texttt{Base1} pointer pointing to a
\texttt{Derived} object calls \texttt{fun1}) then \texttt{fun1} calls \texttt{Derived::vOne} and
\texttt{Base1::vTwo}. Likewise, when \texttt{Derived::fun2} is called
\texttt{Derived::vThree} is called.

The complication
 \index{multiple inheritance: vtable}\index{vtable: and multiple inheritance} occurs
with \texttt{Derived}'s vtable. When \texttt{fun1} is called its class type determines
the vtable to use and hence which virtual member to call. So when \texttt{vOne} is
called from \texttt{fun1}, it is presumably the second entry in \texttt{Derived}'s
vtable, as it must match the second entry in \texttt{Base1}'s vtable. However, when
\texttt{fun2} calls \texttt{vThree} it apparently is also the second entry in
\texttt{Derived}'s vtable as it must match the second entry in \texttt{Base2}'s vtable.

Of course this cannot be realized by a single vtable. Therefore, when multiple
inheritance is used (each base class defining virtual members) another
approach is followed to determine which virtual function to call. In this
situation (cf. figure Figure \ref{MultiVtableFig}) the class \texttt{Derived} receives
\emph{two} \texttt{vtable}s, one for each of its base classes and each \texttt{Derived}
class object harbors \emph{two} hidden vpointers, each one pointing to its
corresponding vtable.

\begin{figure}[tbp]
\centerline{\epsffile{polymorphism/multivtable.eps}}
\caption{\label{MultiVtableFig}Vtables and vpointers with multiple base classes}
\end{figure}

Since base class pointers, base class references, or base class interface
members unambiguously refer to one of the base classes the compiler can
determine which vpointer to use.

The following therefore holds true for classes multiply derived from base
classes offering virtual member functions:
    \begin{itemize}
    \item  the derived class defines a vtable for each of its base classes
offering virtual members;
    \item  Each derived class object contains as many hidden vpointers as it has
vtables.
    \item  Each of a derived class object's vpointers points to a unique vtable
and the vpointer to use is determined by the class type of the base class
pointer, the base class reference, or the base class interface function that
is used.
    \end{itemize}

\section{Undefined reference to vtable ...}\label{VTABLE}
\typeout{Original Yodl file: polymorphism/undefined}Occasionaly, the linker generates an error like the following:
 \index{undefined reference to vtable} \index{vtable: undefined reference}
        \begin{verbatim}
    In function `Derived::Derived()':
        : undefined reference to `vtable for Derived'
\end{verbatim}
This error is generated when a virtual function's implementation is
missing in a derived class, but the function is mentioned in the derived
class's interface.

Such a situation is easily encountered:
    \begin{itemize}
    \item  Construct a (complete) base class defining a virtual member function;
    \item  Construct a Derived class mentioning the virtual function in its
        interface;
    \item  The Derived class's virtual function is not implemented. Of course,
the compiler doesn't know that the derived class's function is not implemented
and will, when asked, generate code to create a derived class object;
    \item  Eventually, the linker is unable to find the derived class's virtual
member function. Therefore, it is unable to construct the derived class's
vtable;
    \item  The linker complains with the message:
    \begin{verbatim}
undefined reference to `vtable for Derived'
\end{verbatim}
\end{itemize}
    Here is an example producing the error:
        \begin{verbatim}
    class Base
    {
        virtual void member();
    };
    inline void Base::member()
    {}
    class Derived: public Base
    {
        void member() override;      // only declared
    };
    int main()
    {
        Derived d;  // Will compile, since all members were declared.
                    // Linking will fail, since we don't have the
                    // implementation of Derived::member()
    }
\end{verbatim}
    It's of course easy to correct the error: implement the derived class's
missing virtual member function.

Virtual functions should \emph{never} be implemented inline. Since the vtable
contains the addresses of the class's virtual functions, these functions must
have addresses and so they must have been compiled as real (out-of-line)
functions. By defining virtual functions inline you run the risk that the
compiler simply overlooks those functions as they may very well never be
explicitly called (but only polymorphically, from a base class pointer or
reference). As a result their addresses may never enter their class's vtables
(and even the vtable itself might remain undefined), causing linkage problems
or resulting in programs showing unexpected behavior. All these kinds of
problems are simply avoided: \emph{never} define virtual members inline (see also
section \ref{NOTINLINE}).

\section{Virtual constructors}\label{VIRTCONS}
\typeout{Original Yodl file: polymorphism/constructors}In section \ref{VIRTDES} we learned that \textbf{C++} supports \emph{virtual
destructors}. Like many other object oriented languages (e.g., \textbf{Java}),
however, the notion of a \index{virtual constructor}\emph{virtual constructor} is not supported. Not having
virtual constructors becomes a liability when only base class references or
pointers are available, and a copy of a derived class object is
required. \emph{Gamma et al.} (1995) \index{Gamma, E.} discuss the
 \index{Prototype design pattern}\emph{Prototype design pattern} \index{design pattern: Prototype} to deal with this
situation.

According to the \emph{Prototype Design Pattern} each derived class is given
the responsibility of implementing a member function returning a pointer to a
copy of the object for which the member is called. The usual name for this
function is \texttt{clone}. Separating the user interface from the reimplementation
interface \texttt{clone} is made part of the interface and \texttt{newCopy} is defined
in the reimplementation interface. A base class supporting `cloning' defines a
virtual destructor, \texttt{clone}, returning \texttt{newCopy}'s return value and the
\emph{virtual copy constructor}, a pure virtual function, having the prototype
\texttt{virtual Base $*$newCopy() const = 0}. As \texttt{newCopy} is a pure virtual
function all derived classes must now implement their own `virtual
constructor'.

This setup suffices in most situations where we have a pointer or
reference to a base class, but it fails when used with abstract
containers. We can't create a \texttt{vector$<$Base$>$}, with \texttt{Base} featuring the
pure virtual \texttt{copy} member in its interface, as \texttt{Base} is called to
initialize new elements of such a vector. This is impossible as \texttt{newCopy} is a
pure virtual function, so a \texttt{Base} object can't be constructed.

The intuitive solution, providing \texttt{newCopy} with a default
implementation, defining it as an ordinary virtual function, fails too as the
container calls \texttt{Base(Base const \&other)}, which would have to call
\texttt{newCopy} to copy \texttt{other}.  At this point it is unclear what to do with
that copy, as the new \texttt{Base} object already exists, and contains no \texttt{Base}
pointer or reference data member to assign \texttt{newCopy}'s return value to.

Alternatively (and preferred) the original \texttt{Base} class (defined as an
\index{abstract base class}abstract base class) is kept as-is and a wrapper class \texttt{Clonable} is used
to manage the \texttt{Base} class pointers returned by \texttt{newCopy}. In chapter
\ref{NESTEDCLASSES} ways to merge \texttt{Base} and \texttt{Clonable} into one class are
discussed, but for now we'll define \texttt{Base} and \texttt{Clonable} as separate
classes.

The class \texttt{Clonable} is a very standard class. It contains a pointer member
so it needs a copy constructor, destructor, and overloaded assignment
operator. It's given at least one non-standard member: \texttt{Base \&base() const},
returning a reference to the derived object to which \texttt{Clonable}'s \texttt{Base $*$}
data member refers. It is also provided with an additional constructor to
initialize its \texttt{Base $*$} data member.

Any non-abstract class derived from \texttt{Base} must implement \texttt{Base
$*$newCopy()}, returning a pointer to a newly created (allocated) copy of the
object for which \texttt{newCopy} is called.

Once we have defined a derived class (e.g., \texttt{Derived1}), we can put our
\texttt{Clonable} and \texttt{Base} facilities to good use.  In the next example we see
\texttt{main} defining a \texttt{vector$<$Clonable$>$}. An anonymous \texttt{Derived1}
object is then inserted into the vector using the following steps:
    \begin{itemize}
    \item  A new anonymous \texttt{Derived1} object is created;
    \item  It initializes a \texttt{Clonable} using \texttt{Clonable(Base $*$bp)};
    \item  The just created \texttt{Clonable} object is inserted into the vector,
using \texttt{Clonable}'s move constructor. There are only temporary \texttt{Derived}
and \texttt{Clonable} objects at this point, so no copy construction is required.
    \end{itemize}
    In this sequence, only the \texttt{Clonable} object containing the \texttt{Derived1
$*$} is used. No additional copies need to be made (or destroyed).

Next, the \texttt{base} member is used in combination with \texttt{typeid} to show
the actual type of the \texttt{Base \&} object: a \texttt{Derived1} object.

\texttt{Main} then contains the interesting definition \texttt{vector$<$Clonable$>$
v2(bv)}. Here a copy of \texttt{bv} is created. This copy construction observes
the actual types of the \texttt{Base} references, making sure that the appropriate
types appear in the vector's copy.

At the end of the program, we have created two \texttt{Derived1} objects, which
are correctly deleted by the vector's destructors. Here is the full program,
illustrating the `virtual constructor' concept\footnote{
   Jesse van den Kieboom created an alternative implementation of a class
    \texttt{Clonable}, implemented as a class template. His
    implementation is found in the source archive under
    \texttt{contrib/classtemplates/}.}: 
        \begin{verbatim}
    #include <iostream>
    #include <vector>
    #include <algorithm>
    #include <typeinfo>

// Base and its inline member:
    class Base
    {
        public:
            virtual ~Base();
            Base *clone() const;
        private:
            virtual Base *newCopy() const = 0;
    };
    inline Base *Base::clone() const
    {
        return newCopy();
    }

// Clonable and its inline members:
    class Clonable
    {
        Base *d_bp;

        public:
            Clonable();
            explicit Clonable(Base *base);
            ~Clonable();
            Clonable(Clonable const &other);
            Clonable(Clonable &&tmp);
            Clonable &operator=(Clonable const &other);
            Clonable &operator=(Clonable &&tmp);

            Base &base() const;
    };
    inline Clonable::Clonable()
    :
        d_bp(0)
    {}
    inline Clonable::Clonable(Base *bp)
    :
        d_bp(bp)
    {}
    inline Clonable::Clonable(Clonable const &other)
    :
        d_bp(other.d_bp->clone())
    {}
    inline Clonable::Clonable(Clonable &&tmp)
    :
        d_bp(tmp.d_bp)
    {
        tmp.d_bp = 0;
    }
    inline Clonable::~Clonable()
    {
        delete d_bp;
    }
    inline Base &Clonable::base() const
    {
        return *d_bp;
    }

// Derived and its inline member:
    class Derived1: public Base
    {
        public:
            ~Derived1() override;
        private:
            Base *newCopy() const override;
    };
    inline Base *Derived1::newCopy() const
    {
        return new Derived1(*this);
    }

// Members not implemented inline:
    Base::~Base()
    {}
    Clonable &Clonable::operator=(Clonable const &other)
    {
        Clonable tmp(other);
        std::swap(d_bp, tmp.d_bp);
        return *this;
    }
    Clonable &Clonable::operator=(Clonable &&tmp)
    {
        std::swap(d_bp, tmp.d_bp);
        return *this;
    }
    Derived1::~Derived1()
    {
        std::cout << "~Derived1() called\n";
    }

// The main function:
    using namespace std;

    int main()
    {
        vector<Clonable> bv;

        bv.push_back(Clonable(new Derived1()));
        cout << "bv[0].name: " << typeid(bv[0].base()).name() << '\n';

        vector<Clonable> v2(bv);
        cout << "v2[0].name: " << typeid(v2[0].base()).name() << '\n';
    }
    /*
        Output:
            bv[0].name: 8Derived1
            v2[0].name: 8Derived1
            ~Derived1() called
            ~Derived1() called
    */
\end{verbatim}
\cleardoublepage\chapter{Friends}\label{Friends}
\typeout{Original Yodl file: friends}\typeout{Original Yodl file: friends/intro}In all examples discussed up to now, we've seen that \texttt{private} members are
only accessible by the members of their class. This is \emph{good}, as it
enforces \index{encapsulation}encapsulation and \index{data hiding}data hiding. By encapsulating functionality
within a class we prevent that a class exposes multiple responsibilities; by
hiding data we promote a class's \index{data integrity}data integrity and we prevent that other
parts of the software become \index{implementation dependent}implementation dependent on the data that
belong to a class.

In this (very) short chapter we introduce the \index{friend}\texttt{friend} keyword and the
principles that underly its use. The bottom line being that by using the
\texttt{friend} keyword functions are granted access to a class's \texttt{private}
members. Even so, this does not imply that the principle of data hiding is
abandoned when the \texttt{friend} keyword is used.

In this chapter the topic of
    \index{friendship among classes}friendship among classes is not discussed. Situations in which it is
natural to use friendship among classes are discussed in chapters
\ref{NESTEDCLASSES} and \ref{TEMPLATES} and such situations are natural
extensions of the way friendship is handled for functions.

There should be a well-defined conceptual reason for declaring friendship
(i.e., using the \texttt{friend} keyword). The traditionally offered definition of
the \index{class: definition} class concept usually looks something like
this:
    \begin{quote}\emph{A class is a set of data together with the functions that operate
        on that data.}\end{quote}

As we've seen in chapter \ref{OVERLOADING} some functions have to be defined
outside of a class interface. They are defined outside of the class interface
to allow promotions for their operands or to extend the facilities of existing
classes not directly under our control. According to the above traditional
definition of the class concept those functions that cannot be defined in the
class interface itself should nevertheless be considered functions belonging
to the class. Stated otherwise: if permitted by the language's syntax they
would certainly have been defined inside the class interface. There are two
ways to implement such functions. One way consists of implementing those
functions using available public member functions. This approach was used,
e.g., in section \ref{EXTRACTORS}. Another approach applies the definition of
the class concept to those functions. By stating that those functions in fact
belong to the class they should be given direct access to the data members of
objects. This is accomplished by the \texttt{friend} keyword.

As a general principle
    \index{class: externally declared functions} we state that all functions
operating on the data of objects of a class that are declared in the same file
as the class interface itself belong to that class and may be granted direct
access to the class's data members.

\section{Friend functions}\label{FriendsFriendfun}
    \typeout{Original Yodl file: friends/friendfun}    In section \ref{EXTRACTORS} the insertion operator of the class
\texttt{Person} (cf. section \ref{ASSIGNMENT}) was implemented like this:
        \begin{verbatim}
    ostream &operator<<(ostream &out, Person const &person)
    {
        return
            out <<
                "Name:    " << person.name() <<  ", "
                "Address: " << person.address() <<  ", "
                "Phone:   " << person.phone();
    }
\end{verbatim}
\texttt{Person} objects can now be inserted into streams.

However, this implementation required three member functions to be called,
which may be considered a source of inefficiency. An improvement would be
reached by defining a member \texttt{Person::insertInto} and let \texttt{operator$<$$<$}
call that function.  These two functions could be defined as follows:
        \begin{verbatim}
    std::ostream &operator<<(std::ostream &out, Person const &person)
    {
        return person.insertInto(out);
    }
    std::ostream &Person::insertInto(std::ostream &out)
    {
        return
            out << "Name:    " << d_name << ", "
                   "Address: " << d_address << ", "
                   "Phone:   " << d_phone;
    }
\end{verbatim}
As \texttt{insertInto} is a member function it has direct access to the
object's data members so no additional member functions must be called when
inserting \texttt{person} into \texttt{out}.

The next step consists of realizing that \texttt{insertInto} is only defined
for the benefit of \texttt{operator$<$$<$}, and that \texttt{operator$<$$<$}, as it is declared
in the header file containing \texttt{Person}'s class interface should be
considered a function belonging to the class \texttt{Person}. The member
\texttt{insertInto} can therefore be omitted when \texttt{operator$<$$<$} is declared as a
friend.

Friend functions must be declared as friends in the class interface. These
\index{friend: function declaration} \emph{friend declarations} are not \emph{member}
functions, and so they are independent of the class's \texttt{private, protected}
and \texttt{public} sections. Friend declaration may be placed anywhere in the
class interface. Convention dictates that friend declarations are listed
directly at the top of the class interface. The class \texttt{Person}, using
\texttt{friend} declaration for its extraction and insertion operators starts like
this:
        \begin{verbatim}
    class Person
    {
        friend std::ostream &operator<<(std::ostream &out, Person &pd);
        friend std::istream &operator>>(std::istream &in, Person &pd);

        // previously shown interface (data and functions)
    };
\end{verbatim}
The insertion operator may now directly access a \texttt{Person} object's data
members:
        \begin{verbatim}
    std::ostream &operator<<(std::ostream &out, Person const &person)
    {
        return
            cout << "Name:    " << person.d_name << ", "
                    "Address: " << person.d_address << ", "
                    "Phone:   " << person.d_phone;
    }
\end{verbatim}
Friend declarations are true declarations. Once a class contains friend
declarations these friend functions do not have to be declared again below the
class's interface. This also clearly indicates the class designer's intent:
the friend functions are declared by the class, and can thus be considered
functions belonging to the class.

\section{Extended friend declarations}
    \typeout{Original Yodl file: friends/extended}\textbf{C++} has added 
    \index{extended friend}\emph{extended friend} \emph{declarations}
    \index{friend: extended declaration}
        to the language. When a class is declared as a friend, then the
\texttt{class} keyword no longer has to be provided. E.g.,
        \begin{verbatim}
    class Friend;                   // declare a class
    using FriendClass = Friend;           // and maybe a using declaration

    class Class1
    {
        friend FriendClass;              // Friend: also OK
    };
\end{verbatim}
In the pre-C++11 standards the friend declaration required an explicit
\texttt{class}; e.g., \texttt{friend class Friend}.

The explicit use of \texttt{class} remains required if the compiler hasn't seen
the friend's name yet. E.g.,
        \begin{verbatim}
    class Class1
    {
        // friend Unseen;           // fails to compile: Unseen unknown.
        friend class Unseen;        // OK
    };
\end{verbatim}
Section \ref{TEMPFRIENDS} covers the use of extended friend declarations in
class templates.


\cleardoublepage\chapter{Classes Having Pointers To Members}\label{PointMembers}
\typeout{Original Yodl file: pointermembers}\typeout{Original Yodl file: pointermembers/intro}Classes having \texttt{pointer data members} have been discussed in detail in
chapter \ref{MEMORY}.  Classes defining pointer data-members deserve some
special attention, as they usually require the definitions of copy
constructors, overloaded assignment operators and destructors

\index{pointer: to member}
Situations exist where we do not need a pointer to an object but rather a
pointer to members of a class. Pointers to members can profitably be used
to configure the behavior of objects of classes. Depending on which member a
pointer to a member points to objects will show certain behavior.

Although pointers to members have their use, polymorphism can frequently be
used to realize comparable behavior. Consider a class having a member
\texttt{process} performing one of a series of alternate behaviors. Instead of
selecting the behavior of choice at object construction time the class could
use the interface of some (abstract) base class, passing an object of some
derived class to its constructor and could thus configure its behavior. This
allows for easy, extensible and flexible configuration, but access to the
class's data members would be less flexible and would possibly require the use
of `friend' declarations. In such cases pointers to members may actually be
preferred as this allows for (somewhat less flexible) configuration as well as
direct access to a class's data members.

So the choice apparently is between on the one hand ease of configuration and
on the other hand ease of access to a class's data members. In this chapter
we'll concentrate on pointers to members, investigating what these pointers
have to offer.

\section{Pointers to members: an example}
    \typeout{Original Yodl file: pointermembers/example}Knowing how pointers to variables and objects are used does not intuitively
lead to the concept of \emph{pointers to members} \index{pointer: to member}. Even if
the return types and parameter types of member functions are taken into
account, surprises can easily be encountered.  For example, consider the
following class:
        \begin{verbatim}
    class String
    {
        char const *(*d_sp)() const;

        public:
            char const *get() const;
    };
\end{verbatim}
For this class, it is not possible to let \texttt{char const $*$($*$d\_sp)() const}
point to the \texttt{String::get} member function as \texttt{d\_sp} cannot be given the
address of the member function \texttt{get}.

One of the reasons why this doesn't work is that the variable \texttt{d\_sp} has
\index{scope: global}\index{global scope}global scope (it is a pointer to \emph{a} function, not a
pointer to a function within \texttt{String}), while the member function \texttt{get} is
defined within the \texttt{String} class, and thus has \texttt{class scope}. The fact
that \texttt{d\_sp} is a data member of the class \texttt{String} is irrelevant
here. According to \texttt{d\_sp}'s definition, it points to a function living
somewhere \emph{outside} of the class.

Consequently, to define a pointer to a member (either data or function, but
usually a function) of a class, the scope of the pointer must indicate
\index{scope: class}\index{class scope}class scope.  Doing so, a pointer to the member
\texttt{String::get} is defined like this:
        \begin{verbatim}
    char const *(String::*d_sp)() const;
\end{verbatim}
So, by prefixing the \texttt{$*$d\_sp} pointer data member by \texttt{String::}, it is
defined as a pointer in the context of the class \texttt{String}. According to its
definition it is \emph{a pointer to a function in the class \texttt{String}, not
expecting arguments, not modifying its object's data, and returning a pointer
to constant characters}.

\section{Defining  pointers to members}
    \typeout{Original Yodl file: pointermembers/defining}    \index{pointer: to member: defining} 
    Pointers to members are defined by prefixing the normal pointer notation
with the appropriate class plus scope resolution operator. Therefore, in the
previous section, we used \texttt{char const $*$ (String::$*$d\_sp)() const} to indicate
that \texttt{d\_sp}
    \begin{itemize}
    \item  is a pointer (\texttt{$*$d\_sp});
    \item  points to something in the class \texttt{String} (\texttt{String::$*$d\_sp});
    \item  is a pointer to a \texttt{const} function, returning a \texttt{char const $*$}
            (\texttt{char const $*$ (String::$*$d\_sp)() const}).
    \end{itemize}

The prototype of a matching function is therefore:
        \begin{verbatim}
    char const *String::somefun() const;
\end{verbatim}
which is any \texttt{const} parameterless function in the class
\texttt{String}, returning a \texttt{char const $*$}.

When defining pointers to members the standard procedure for constructing
pointers to functions can still be applied:
    \begin{itemize}
    \item  put parentheses around the fully qualified function name (i.e., the
function's header, including the function's  class name):
        \begin{verbatim}
char const * ( String::somefun ) () const
\end{verbatim}
\item  Put a pointer (a star (\texttt{$*$})) character immediately before the
function name itself:
        \begin{verbatim}
char const * ( String:: * somefun ) () const
\end{verbatim}
\item  Replace the function name with the name of the pointer variable:
        \begin{verbatim}
char const * (String::*d_sp)() const
\end{verbatim}
\end{itemize}

\index{pointer: to data member} 
    Here is another example, defining a pointer
to a data member. Assume the class \texttt{String} contains a \texttt{string d\_text}
member. How to construct a pointer to this member? Again we follow standard
procedure:
    \begin{itemize}
    \item  put parentheses around the fully qualified variable name:
        \begin{verbatim}
std::string (String::d_text)
\end{verbatim}
\item  Put a pointer (a star (\texttt{$*$})) character immediately before the
variable-name itself:
        \begin{verbatim}
std::string (String::*d_text)
\end{verbatim}
\item  Replace the variable name with the name of the pointer variable:
        \begin{verbatim}
std::string (String::*tp)
\end{verbatim}
In this case, the parentheses are superfluous and may be omitted:
        \begin{verbatim}
string String::*tp
\end{verbatim}
\end{itemize}

Alternatively, a very simple \index{rule of thumb}rule of thumb is
    \begin{itemize}
    \item  Define a normal (i.e., global) pointer variable,
    \item  Prefix the class name to the pointer character, once you point to
something inside a class
    \end{itemize}
    For example, the following pointer to a global function
        \begin{verbatim}
    char const * (*sp)() const;
\end{verbatim}
becomes a pointer to a member function after prefixing the class-scope:
        \begin{verbatim}
    char const * (String::*sp)() const;
\end{verbatim}
Nothing forces us to define pointers to members in their target
(\texttt{String}) classes. Pointers to members \emph{may} be defined in their target
classes (so they become data members), or in another class, or as a local
variable or as a global variable. In all these cases the pointer to member
variable can be given the address of the kind of member it points to. The
important part is that a pointer to member can be initialized or assigned
without requiring the existence of an object of the pointer's target class.

Initializing or assigning an address to such a pointer merely indicates to
which member the pointer points. This can be considered some kind of
 \index{relative address}\emph{relative address}; relative to the object for which the function is
called. No object is required when pointers to members are initialized or
assigned. While it is allowed to initialize or assign a pointer to member, it
is (of course) not possible to \emph{call} those members without specifying an
object of the correct type.

\index{pointer: to member: assignment}
    \index{assignment: pointer to member} 
In the following example initialization of and assignment to
pointers to members is illustrated (for illustration purposes all members of
the class \texttt{PointerDemo} are defined \texttt{public}). In the example itself the
\texttt{\&}-operator is used to determine the addresses of the members. These
operators as well as the class-scopes are required. Even when used inside
member implementations:
        \begin{verbatim}
    #include <cstddef>

    class PointerDemo
    {
        public:
            size_t d_value;
            size_t get() const;
    };

    inline size_t PointerDemo::get() const
    {
        return d_value;
    }

    int main()
    {                                           // initialization
        size_t (PointerDemo::*getPtr)() const = &PointerDemo::get;
        size_t PointerDemo::*valuePtr         = &PointerDemo::d_value;

        getPtr   = &PointerDemo::get;           // assignment
        valuePtr = &PointerDemo::d_value;
    }
\end{verbatim}
    This involves nothing special. The difference with pointers at
global scope is that we're now restricting ourselves to the scope of the
\texttt{PointerDemo} class. Because of this restriction, all \emph{pointer}
definitions and all variables whose addresses are used must be given the
\texttt{PointerDemo} class scope.

\index{pointer: to virtual member}
    Pointers to members can also be used with \texttt{virtual}
    member functions. No special syntax is required when pointing to virtual
members. Pointer construction, initialization and assignment is done
identically to the way it is done with non-virtual members.

\section{Using pointers to members}
    \typeout{Original Yodl file: pointermembers/using}Using pointers to members to call a member function requires the existence of
an object of the class of the members to which the pointer to member refers
to.  With pointers operating at global scope, the dereferencing operator \texttt{$*$}
is used.  With pointers to objects the \index{field selector}field selector operator operating on
pointers (\index{-\textgreater{}}\texttt{-$>$}) or the field selector operating operating on objects (\texttt{.})
can be used to select appropriate members.

\index{pointer: to member field selector} 
To use a pointer to member in combination with an object the
    pointer to member field selector (\index{.*}\texttt{.$*$}) must be specified.  To use a
pointer to a member via a pointer to an object the `pointer to member field
selector through a pointer to an object' (\index{-\textgreater{}*}\texttt{-$>$$*$}) must be specified. These
two operators combine the notions of a field selection (the \texttt{.} and \texttt{-$>$}
parts) to reach the appropriate field in an object and of dereferencing: a
dereference operation is used to reach the function or variable the pointer to
member points to.

Using the example from the previous section, let's see how we can use
pointers to member functions and pointers to data members:
        \begin{verbatim}
    #include <iostream>

    class PointerDemo
    {
        public:
            size_t d_value;
            size_t get() const;
    };

    inline size_t PointerDemo::get() const
    {
        return d_value;
    }

    using namespace std;

    int main()
    {                                           // initialization
        size_t (PointerDemo::*getPtr)() const = &PointerDemo::get;
        size_t PointerDemo::*valuePtr   = &PointerDemo::d_value;

        PointerDemo object;                     // (1) (see text)
        PointerDemo *ptr = &object;

        object.*valuePtr = 12345;               // (2)
        cout << object.*valuePtr << '\n' <<
                object.d_value << '\n';

        ptr->*valuePtr = 54321;                 // (3)
        cout << object.d_value << '\n' <<
                (object.*getPtr)() << '\n' <<   // (4)
                (ptr->*getPtr)() << '\n';
    }
\end{verbatim}
    We note:
    \begin{itemize}
    \item  At (1) a \texttt{PointerDemo} object and (in the next line) a pointer to
such an object is defined.
    \item  At (2) we specify an object (and hence the \texttt{.$*$} operator) to reach
the member \texttt{valuePtr} points to. This member is given a value.
    \item  At (3) the same member is assigned another value, but this time using
the pointer to a \texttt{PointerDemo} object. Hence we use the \texttt{-$>$$*$} operator.
    \item  At (4) the \texttt{.$*$} and \texttt{-$>$$*$} are used once again, this time to call
a function through a pointer to member. As the function argument list
has a higher priority than the pointer to member field selector
operator, the latter \emph{must} be protected by parentheses.
    \end{itemize}
    Pointers to members can be used profitably in situations where a class has
a member that behaves differently depending on a configuration
setting. Consider once again the class \texttt{Person} from section
\ref{ASSIGNMENT}. \texttt{Person} defines data members holding a person's name,
address and phone number. Assume we want to construct a \texttt{Person}
database of employees.  The employee database can be queried, but depending on
the kind of person querying the database either the name, the name and phone
number or all stored information about the person is made available. This
implies that a member function like \texttt{address} must return something like
`\texttt{$<$not available$>$}' in cases where the person querying the database is not
allowed to see the person's address, and the actual address in other cases.

The employee database is opened specifying an argument reflecting the
status of the employee who wants to make some queries. The status could
reflect his or her position in the organization, like \texttt{BOARD},
\texttt{SUPERVISOR}, \texttt{SALESPERSON}, or \texttt{CLERK}. The first two categories are
allowed to see all information about the employees, a \texttt{SALESPERSON} is
allowed to see the employee's phone numbers, while the \texttt{CLERK} is only
allowed to verify whether a person is actually a member of the organization.

We now construct a member \texttt{string personInfo(char const $*$name)} in the
database class. A standard implementation of this class could be:
        \begin{verbatim}
    string PersonData::personInfo(char const *name)
    {
        Person *p = lookup(name);   // see if `name' exists

        if (!p)
            return "not found";

        switch (d_category)
        {
            case BOARD:
            case SUPERVISOR:
                return allInfo(p);
            case SALESPERSON:
                return noPhone(p);
            case CLERK:
                return nameOnly(p);
        }
    }
\end{verbatim}
Although it doesn't take much time, the \texttt{switch} must nonetheless be
evaluated every time \texttt{personInfo} is called. Instead of using a switch, we
could define a member \texttt{d\_infoPtr} as a pointer to a member function of the
class \texttt{PersonData} returning a \texttt{string} and expecting a pointer to a
\texttt{Person} as its argument.

Instead of evaluating the switch this pointer can be used to point to
\texttt{allInfo}, \texttt{noPhone} or \texttt{nameOnly}. Furthermore, the member function
the pointer points to will be known by the time the \texttt{PersonData}
object is constructed and so its value needs to be determined only once (at
the PersonData object's construction time).

Having initialized \texttt{d\_infoPtr} the \texttt{personInfo} member function is now
implemented simply as:
        \begin{verbatim}
    string PersonData::personInfo(char const *name)
    {
        Person *p = lookup(name);       // see if `name' exists

        return p ? (this->*d_infoPtr)(p) :  "not found";
    }
\end{verbatim}
The member \texttt{d\_infoPtr} is defined as follows (within the class
\texttt{PersonData}, omitting other members):
        \begin{verbatim}
    class PersonData
    {
        std::string (PersonData::*d_infoPtr)(Person *p);
    };
\end{verbatim}
Finally, the constructor initializes \texttt{d\_infoPtr}. This could be realized
using a simple switch:
        \begin{verbatim}
    PersonData::PersonData(PersonData::EmployeeCategory cat)
    {
        switch (cat)
        {
            case BOARD:
            case SUPERVISOR:
                d_infoPtr = &PersonData::allInfo;
            break;
            case SALESPERSON:
                d_infoPtr = &PersonData::noPhone;
            break;
            case CLERK:
                d_infoPtr = &PersonData::nameOnly;
            break;
        }
    }
\end{verbatim}
Note how addresses of member functions are determined. The class
\texttt{PersonData} scope \emph{must} be specified, even though we're already inside
a member function of the class \texttt{PersonData}.

Since the \texttt{EmployeeCategory} values are known, the \texttt{switch} in the
above constructor can also easily be avoided by defining a static array of
pointers to functions. The class \texttt{PersonData} defines the static array:
        \begin{verbatim}
    class PersonData
    {
        std::string (PersonData::*d_infoPtr)(Person *p);
        static std::string (PersonData::*s_infoPtr[])(Person *p);
    };
\end{verbatim}
and \texttt{s\_infoPtr{[}{]}} can be initialized compile-time:
        \begin{verbatim}
    string (PersonData::*PersonData::s_infoPtr[])(Person *p) = 
    {
        &PersonData::allInfo,       // BOARD
        &PersonData::allInfo,       // SUPERVISOR
        &PersonData::noPhone,       // SALESPERSON
        &PersonData::nameOnly       // CLERK
    };
\end{verbatim}
The constructor, instead of using a \texttt{switch}, now directly calls the
required member from the appropriate array element:
        \begin{verbatim}
    PersonData::PersonData(PersonData::EmployeeCategory cat)
    :
        d_infoPtr(s_infoPtr[cat])
    {}
\end{verbatim}
An example using pointers to data members is provided in section
\ref{SORT}, in the context of the \texttt{stable\_sort} generic algorithm.

\section{Pointers to static members}
    \typeout{Original Yodl file: pointermembers/static}Static \index{static: members} members of a class can be used without having
available an object of their class. Public static members can be called like
free functions, albeit that their class names must be specified when they are
called.

Assume a class \texttt{String} has a public static member function
\texttt{count}, returning the number of string objects created so
far. Then, without using any \texttt{String} object the function
\texttt{String::count} may be called:
        \begin{verbatim}
    void fun()
    {
        cout << String::count() << '\n';
    }
\end{verbatim}
\emph{Public} static members can be called like free functions (but see also
section \ref{CALLINGCONVENTION}).  \emph{Private} static members can only be
called within the context of their class, by their class's member or friend
functions.

Since static members have no associated objects their addresses can be
stored in ordinary function pointer variables, operating at the global
level. Pointers to members cannot be used to store addresses of static
members. Example:
        \begin{verbatim}
    void fun()
    {
        size_t (*pf)() = String::count;
                // initialize pf with the address of a static member function

        cout << (*pf)() << '\n';
                // displays the value returned by String::count()
    }
\end{verbatim}
\section{Pointer sizes}
    \typeout{Original Yodl file: pointermembers/sizes}    \index{size: pointer to member}\index{pointer: to member: size} An interesting
characteristic of pointers to members is that their sizes differ from those of
`normal' pointers. Consider the following little program:
        \begin{verbatim}
    #include <string>
    #include <iostream>

    class X
    {
        public:
            void fun();
            std::string d_str;
    };
    inline void X::fun()
    {
        std::cout << "hello\n";
    }

    using namespace std;
    int main()
    {
        cout <<
           "size of pointer to data-member:     " << sizeof(&X::d_str) << "\n"
           "size of pointer to member function: " << sizeof(&X::fun) << "\n"
           "size of pointer to non-member data: " << sizeof(char *) << "\n"
           "size of pointer to free function:   " << sizeof(&printf) << '\n';
    }

    /*
        generated output (on 32-bit architectures):

        size of pointer to data-member:     4
        size of pointer to member function: 8
        size of pointer to non-member data: 4
        size of pointer to free function:   4
    */
\end{verbatim}
    On a 32-bit architecture a pointer to a member function requires eight
bytes, whereas other kind of pointers require four bytes (Using GNU's g++
compiler).

Pointer sizes are hardly ever explicitly used, but their sizes may cause
confusion in statements like:
        \begin{verbatim}
    printf("%p", &X::fun);
\end{verbatim}
Of course, \texttt{printf} is likely not the right tool for displaying the
value of these \textbf{C++} specific pointers. The values of these pointers can be
inserted into streams when a \texttt{union}, reinterpreting the 8-byte pointers as
a series of size\_t \texttt{char} values, is used:
        \begin{verbatim}
    #include <string>
    #include <iostream>
    #include <iomanip>

    class X
    {
        public:
            void fun();
            std::string d_str;
    };
    inline void X::fun()
    {
        std::cout << "hello\n";
    }

    using namespace std;
    int main()
    {
        union
        {
            void (X::*f)();
            unsigned char *cp;
        }
            u = { &X::fun };

        cout.fill('0');
        cout << hex;
        for (unsigned idx = sizeof(void (X::*)()); idx-- > 0; )
            cout << setw(2) << static_cast<unsigned>(u.cp[idx]);
        cout << '\n';
    }
\end{verbatim}
But why are their sizes different from the sizes of ordinary pointers? To
answer this question let's first have a look at the familiar
\texttt{std::fstream}. It is derived from \texttt{std::ifstream} and
\texttt{std::ofstream}. An \texttt{fstream}, therefore, contains both an \texttt{ifstream} and
an \texttt{ofstream}. An \texttt{fstream} will be organized as shown in figure
\ref{PMSIZES}. 

\begin{figure}[tbp]
\centerline{\epsffile{pointermembers/sizes.eps}}
\caption{\label{PMSIZES}std::fstream object organization}
\end{figure}

In \texttt{fstream (a)} the first base class was \texttt{std::istream}, and the second
baseclass was \texttt{std::ofstream}. But it could also very well be the other way
around, as illustrated in \texttt{fstream (b)}: first the \texttt{std::ofstream}, then
the \texttt{std::ifstream}. And that's the crux of the biscuit.

If we have an \texttt{fstream fstr\{"myfile"\}} object and do \texttt{fstr.seekg(0)}, then
we call \texttt{ifstream's seekg} function. But if we do \texttt{fstr.seekp(0)}, then we
call \texttt{ofstream's seekp} function. These functions have their own addresses,
say \&seekg and \&seekp. But when we call a member function (like
\texttt{fstr.seekp(0)}) then what we in fact are doing is \texttt{seekp(\&fstr, 0)}.

But the problem here is that \texttt{\&fstr} does not represent the correct object
address: \texttt{seekp} operates on an \texttt{ofstream}, and that object does not start
at \texttt{\&fstr}, so (in \texttt{fstream (a)}), at \texttt{\&(fstr + sizeof(ifstream))}.

So, the compiler, when calling a member function of a class using inheritance,
must make a correction for the relative location of an object whose members we
are calling.

However, when we're defining something like
        \begin{verbatim}
    ostream &(fstream::*ptr)(ios::off_type step, ios::seekdir org) = &seekp;
\end{verbatim}
and then do \texttt{(fstr-$>$$*$)ptr(0)} the compiler doesn't know anymore which
function is actually being called: it merely receives the function's
address. To solve the compiler's problem the shift (for the location of the
ofstream object) is now stored in the member pointer itself. That's one reason
why the extra data field is needed when using function pointers.

Here is a concrete illustration: first we define 2 structs, each having a
member function (all inline, using single line implementations to save some
space):
        \begin{verbatim}
    struct A
    {
        int a;
    };

    struct B
    {
        int b;
        void bfun() {}
    };
\end{verbatim}
Then we define C, which is derived from both A (first) and B (next)
(comparable to \texttt{fstream}, which embeds \texttt{ifstream} and \texttt{ofstream}):
        \begin{verbatim}
    struct C: public A, public B
    {};
\end{verbatim}
Next, in \texttt{main} we define objects of two different unions and assign the
address of \texttt{B::bfun} to their \texttt{ptr} fields, but \texttt{BPTR.ptr} looks at it
as a member in the \texttt{struct B} world, while \texttt{CPTR.ptr} looks at it as a
member in the \texttt{struct C} world.

Once the unions' pointer fields have been assigned their value{[}{]} arrays are
used to display the content of the ptr fields (see below):
        \begin{verbatim}
    int main()
    {
        union BPTR
        {
            void (B::*ptr)();
            unsigned long value[2];
        };
        BPTR bp;
        bp.ptr = &B::bfun;
        cout << hex << bp.value[0] << ' ' << bp.value[1] << dec << '\n';

        union CPTR
        {
            void (C::*ptr)();
            unsigned long value[2];
        };
        CPTR cp;
        cp.ptr = &C::bfun;
        cout << hex << cp.value[0] << ' ' << cp.value[1] << dec << '\n';
    }
\end{verbatim}
When this program is run, we see
        \begin{verbatim}
    400b0c 0
    400b0c 4
\end{verbatim}
(your address values (the first ones on the two lines) may differ). Note
that the functions' addresses are the same, but since in the C world the B
object lives beyond the A object, and the A object is 4 bytes large, we must
add 4 to the value of the `\texttt{this}' pointer when calling the function from a C
object. That's exactly what the shift value in the pointer's second field is
telling the compiler.


\cleardoublepage\chapter{Nested Classes}\label{NESTEDCLASSES}
\typeout{Original Yodl file: nested}\typeout{Original Yodl file: nested/nesting}Classes can be defined inside other classes. Classes defined inside
other classes are called \index{nested class} \emph{nested classes}. Nested classes
are used in situations where the nested class has a close conceptual
relationship to its surrounding class. For example, with the class \texttt{string}
a type \index{string::iterator}\texttt{string::iterator} is available which provides all characters
that are stored in the \texttt{string}. This \texttt{string::iterator} type could be
defined as an object \index{iterator}\texttt{iterator}, defined as nested class in the class
\texttt{string}. 

Since  nested classes are defined inside other classes their members, when
provided with references or pointers to objects of their surrounding classes,
may access all members of those objects, even their private members.

A class can be nested in every part of the surrounding class: in the
\texttt{public, protected} or \texttt{private} section. If a class is nested in the
\texttt{public} section of a class, it is
    \index{visibility: nested classes} visible outside the surrounding class. If
it is nested in the \texttt{protected} section it is visible in subclasses, derived
from the surrounding class, if it is nested in the \texttt{private} section, it is
only visible for the members of the surrounding class.

The surrounding class has no special privileges with respect to the nested
class. For example, consider the following class definition:
        \begin{verbatim}
    class Surround
    {
        public:
            class FirstWithin
            {
                int d_variable;

                public:
                    FirstWithin();
                    int var() const;
            };
        private:
            class SecondWithin
            {
                int d_variable;

                public:
                    SecondWithin();
                    int var() const;
            };
    };
    inline int Surround::FirstWithin::var() const
    {
        return d_variable;
    }
    inline int Surround::SecondWithin::var() const
    {
        return d_variable;
    }
\end{verbatim}
In the \textbf{C++} Annotations, in order to save space, nested class interfaces are
usually declared inside their surrounding class, as shown above. Often this
can be avoided, which is desirable as it more clearly separates the outer
class's interface and the nested class's interface. Likewise, in-class member
implementations should be avoided. Here is an illustration of how outer- and
nested class interfaces can be separated:
        \begin{verbatim}
    class Surround
    {
        class SecondWithin;

        public:
            class FirstWithin;
    };

    class Surround::FirstWithin
    {
        int d_variable;

        public:
            FirstWithin();
            int var() const;
    };

    class Surround::SecondWithin
    {
        int d_variable;

        public:
            SecondWithin();
            int var() const;
    };
\end{verbatim}
For these three classes access to members is defined as follows:
        \begin{itemize}
        \item  The class \texttt{Surround::FirstWithin} is visible outside and inside
\texttt{Surround}. The class \texttt{Surround::FirstWithin} thus has  global visibility.
        \item  \texttt{FirstWithin}'s constructor and its member function
\texttt{var} are also globally visible.
        \item  The data member \texttt{d\_variable} is only visible to the members of
the class \texttt{Surround::FirstWithin}. Neither the members of \texttt{Surround} nor
the members of \texttt{Surround::SecondWithin} can directly access
\texttt{Surround::FirstWithin::d\_variable}.
        \item  The class \texttt{Surround::SecondWithin} is only visible inside
\texttt{Surround}. The public members of the class \texttt{Surround::SecondWithin} can
also be used by the members of the class \texttt{Surround::FirstWithin}, as nested
classes can be considered members of their surrounding class.
        \item  \texttt{Surround::SecondWithin}'s constructor and its member function
\texttt{var} also can only be reached by the members of \texttt{Surround} (and by the
members of its nested classes).
        \item  \texttt{Surround::SecondWithin::d\_variable} is only visible to
\texttt{Surround::SecondWithin}'s members. Neither the members of \texttt{Surround} nor
the members of \texttt{Surround::FirstWithin} can access \texttt{d\_variable} of the
class \texttt{Surround::SecondWithin} directly.
        \item  As always, an object of the class type is required before
its members can be called. This also holds true for nested classes.
        \end{itemize}
    To grant the surrounding class access rights to the private members of a
nested class the nested class may declare its surrounding class as a
friend. Conversely, as nested classes can be considered members of their
surrounding class their member functions have full access to the outer class
members, if they are provided with an outer class object (see section
\ref{NESTEDFRIENDS}).

Although nested classes can be considered members of the surrounding
class, members of nested classes are \emph{not} members of the surrounding
class: members of the class \texttt{Surround} may not directly call
\texttt{FirstWithin::var}. This is understandable considering that a
\texttt{Surround} object is not also a \texttt{FirstWithin} or \texttt{SecondWithin}
object. In fact, nested classes are just typenames. It is not implied that
objects of such classes automatically exist in the surrounding class. If a
member of the surrounding class should use a (non-static) member of a nested
class then the surrounding class must define a nested class object, which can
thereupon be used by the members of the surrounding class to use members of
the nested class.

For example, in the following class definition there is a surrounding
class \texttt{Outer} and a nested class \texttt{Inner}. The class \texttt{Outer} contains a
member function \texttt{caller}. The member function \texttt{caller} uses the
\texttt{d\_inner} object that is composed within \texttt{Outer} to call
\texttt{Inner::infunction}:
        \begin{verbatim}
    class Outer
    {
        public:
            void caller();

        private:
            class Inner
            {
                public:
                    void infunction();
            };
            Inner d_inner;      // class Inner must be known
    };
    void Outer::caller()
    {
        d_inner.infunction();
    }
\end{verbatim}
\section{Defining nested class members}
\typeout{Original Yodl file: nested/defining}Member functions of nested classes may be defined as inline functions.  Inline
 \index{inline member functions} member functions can be defined as if they were
defined outside of the class definition. To define the member function
\texttt{Outer::caller} outside of the class \texttt{Outer}, the function's
 \index{fully qualified name: nested class members} fully qualified name (starting
from the outermost class scope (\texttt{Outer})) must be provided to the
compiler. Inline and in-class functions can be defined accordingly. They can
be defined and they can use any nested class. Even if the nested class's
definition appears later in the outer class's interface.

When (nested) member functions are defined inline, their definitions should be
put below their class interface. Static nested data members are also usually
defined outside of their classes.
    \index{nested class: static members}
        If the class \texttt{FirstWithin} would have had a \texttt{static size\_t}
datamember \texttt{epoch}, it could have been initialized as follows:
        \begin{verbatim}
    size_t Surround::FirstWithin::epoch = 1970;
\end{verbatim}
Furthermore, multiple scope resolution operators are needed to refer to
public static members in code outside of the surrounding class:
        \begin{verbatim}
    void showEpoch()
    {
        cout << Surround::FirstWithin::epoch;
    }
\end{verbatim}
Within the class \texttt{Surround} only the \texttt{FirstWithin::}
scope must be used; within the class \texttt{FirstWithin} there is
no need to refer explicitly to the scope.

What about the members of the class \texttt{SecondWithin}? The classes
\texttt{FirstWithin} and \texttt{SecondWithin} are both nested within \texttt{Surround}, and
can be considered members of the surrounding class. Since members of a class
may directly refer to each other, members of the class \texttt{SecondWithin} can
refer to (public) members of the class \texttt{FirstWithin}. Consequently, members
of the class \texttt{SecondWithin} could refer to the \texttt{epoch} member of
\texttt{FirstWithin} as \texttt{FirstWithin::epoch}.

\section{Declaring nested classes}
\typeout{Original Yodl file: nested/declaring}Nested classes \index{nested class: declaration} may be declared before they are
actually defined in a surrounding class. Such forward declarations are
required if a class contains multiple nested classes, and the nested classes
contain pointers, references, parameters or return values to objects of the
other nested classes.

For example, the following class \texttt{Outer} contains two nested classes
\texttt{Inner1} and \texttt{Inner2}. The class \texttt{Inner1} contains a pointer to
\texttt{Inner2} objects, and \texttt{Inner2} contains a pointer to \texttt{Inner1}
objects. Cross references require forward declarations. Forward declarations
must be given an access specification that is identical to the access
specification of their definitions. In the following example the \texttt{Inner2}
forward declaration must be given in a \texttt{private} section, as its definition
is also part of the class \texttt{Outer}'s private interface:
        \begin{verbatim}
    class Outer
    {
        private:
            class Inner2;       // forward declaration

            class Inner1
            {
                Inner2 *pi2;    // points to Inner2 objects
            };
            class Inner2
            {
                Inner1 *pi1;    // points to Inner1 objects
            };
    };
\end{verbatim}
\section{Accessing private members in nested classes}\label{NESTEDFRIENDS}
\typeout{Original Yodl file: nested/nestedfriends}To grant nested classes access rights to the private members of other nested
classes, or to grant a surrounding class access to the private members of its
nested classes the \index{friend: nested classes}\texttt{friend} keyword must be used.

No friend declaration is required to grant a nested class access to the
private members of its surrounding class. Static members of the surrounding
class can directly be accessed, other members can be accessed if a surrounding
class object is defined by or passed to members of the nested class. After
all, a nested class is a type defined by its surrounding class and as such
objects of the nested class are members of the outer class and thus can access
all the outer class's members. Here is an example showing this principle. The
example won't compile as members of the class \texttt{Extern} are denied access to
\texttt{Outer}'s private members, but \texttt{Outer::Inner}'s members \emph{can} access
\texttt{Outer}'s private members:
        \begin{verbatim}
    class Outer
    {
        int d_value;
        static int s_value;

        public:
            Outer()
            :
                d_value(12)
            {}
            class Inner
            {
                public:
                    Inner()
                    {
                        cout << "Outer's static value: " << s_value << '\n';
                    }
                    Inner(Outer &outer)
                    {
                        cout << "Outer's value: " << outer.d_value << '\n';
                    }
            };
    };
    class Extern            // won't compile!
    {
        public:
            Extern(Outer &outer)
            {
                cout << "Outer's value: " << outer.d_value << '\n';
            }

            Extern()
            {
                cout << "Outer's static value: " << Outer::s_value << '\n';
            }
    };

    int Outer::s_value = 123;
    int main()
    {
        Outer outer;
        Outer::Inner in1;
        Outer::Inner in2{ outer };
    }
\end{verbatim}
Now consider the situation where a class \texttt{Surround} has two nested
classes \texttt{FirstWithin} and \texttt{SecondWithin}. Each of the three classes has a
static data member \texttt{int s\_variable}:
        \begin{verbatim}
    class Surround
    {
        static int s_variable;
        public:
            class FirstWithin
            {
                static int s_variable;
                public:
                    int value();
            };
            int value();
        private:
            class SecondWithin
            {
                static int s_variable;
                public:
                    int value();
            };
    };
\end{verbatim}
If the class \texttt{Surround} should be able to access \texttt{FirstWithin} and
\texttt{SecondWithin}'s private members, these latter two classes must declare
\texttt{Surround} to be their friend. The function \texttt{Surround::value} can
thereupon access the private members of its nested classes. For example (note
the \texttt{friend} declarations in the two nested classes):
        \begin{verbatim}
    class Surround
    {
        static int s_variable;
        public:
            class FirstWithin
            {
                friend class Surround;
                static int s_variable;
                public:
                    int value();
            };
            int value();
        private:
            class SecondWithin
            {
                friend class Surround;
                static int s_variable;
                public:
                    int value();
            };
    };
    inline int Surround::FirstWithin::value()
    {
        FirstWithin::s_variable = SecondWithin::s_variable;
        return (s_variable);
    }
\end{verbatim}
Friend declarations may be provided \emph{beyond} the definition of the
entity that is to be considered a friend. So a class can be declared a friend
\emph{beyond} its definition. In that situation in-class code may already use the
fact that it is going to be declared a friend by the upcoming class. As an
example, consider an in-class implementation of the function
\texttt{Surround::FirstWithin::value}. The required \texttt{friend} declaration can also
be inserted \emph{after} the implementation of the function \texttt{value}:
        \begin{verbatim}
    class Surround
    {
        public:
            class FirstWithin
            {
                static int s_variable;
                public:
                    int value();
                    {
                        FirstWithin::s_variable = SecondWithin::s_variable;
                        return s_variable;
                    }
                friend class Surround;
            };
        private:
            class SecondWithin
            {
                friend class Surround;
                static int s_variable;
            };
    };
\end{verbatim}
Note that members named identically in outer and inner classes
(e.g., `\texttt{s\_variable}')
  \index{nested class: member access}
    may be accessed using the proper scope resolution expressions, as
illustrated below:
        \begin{verbatim}
    class Surround
    {
        static int s_variable;
        public:
            class FirstWithin
            {
                friend class Surround;
                static int s_variable;  // identically named
                public:
                    int value();
            };
            int value();

        private:
            class SecondWithin
            {
                friend class Surround;
                static int s_variable;  // identically named
                public:
                    int value();
            };
            static void classMember();
    };
    inline int Surround::value()
    {                                   // scope resolution expression
        FirstWithin::s_variable = SecondWithin::s_variable;
        return s_variable;
    }
    inline int Surround::FirstWithin::value()
    {
        Surround::s_variable = 4;       // scope resolution expressions
        Surround::classMember();
        return s_variable;
    }
    inline int Surround::SecondWithin::value()
    {
        Surround::s_variable = 40;      // scope resolution expression
        return s_variable;
    }
\end{verbatim}
Nested classes aren't automatically each other's friends. Here \texttt{friend}
declarations must be provided to grant one nested classes access to another
nested class's private members. 

To grant \texttt{FirstWithin} access to \texttt{SecondWithin}'s private members,
\texttt{SecondWithin} must contain a \texttt{friend} declaration.

Likewise, the class \texttt{FirstWithin} simply uses \texttt{friend class
SecondWithin} to grant \texttt{SecondWithin} access to \texttt{FirstWithin}'s private
members. Even though the compiler hasn't seen \texttt{SecondWithin} yet, a friend
declaration is also considered a forward declaration.

Note that \texttt{SecondWithin}'s forward declaration cannot be specified inside
\texttt{FirstWithin} by using `\texttt{class Surround::SecondWithin;}', as this would
generate an error message like:
        \begin{quote}`Surround' does not have a nested type named `SecondWithin'\end{quote}

Now assume that in addition to the nested class \texttt{SecondWithin} there also
exists an outer-level class \texttt{SecondWithin}. To declare that class a friend
of \texttt{FirstWithin's} declare \texttt{friend ::SecondWithin} inside \texttt{class
FirstWithin}. In that case, an outer level class declaration of
\texttt{FirstWithin} must be provided before the compiler encounters the \texttt{friend
::SecondWithin} declaration.

Here is an example in which all classes have full access to all private
members of all involved classes: \index{friend: as forward declaration}, and a
outer level \texttt{FirstWithin} has also been declared:
        \begin{verbatim}
    class SecondWithin;

    class Surround
    {
        // class SecondWithin;      not required (but no error either): 
        //                          friend declarations (see below)
        //                          are also forward declarations

        static int s_variable;
        public:
            class FirstWithin
            {
                friend class Surround;
                friend class SecondWithin;
                friend class ::SecondWithin;

                static int s_variable;
                public:
                    int value();
            };
            int value();            // implementation given above
        private:
            class SecondWithin
            {
                friend class Surround;
                friend class FirstWithin;

                static int s_variable;
                public:
                    int value();
            };
    };
    inline int Surround::FirstWithin::value()
    {
        Surround::s_variable = SecondWithin::s_variable;
        return s_variable;
    }
    inline int Surround::SecondWithin::value()
    {
        Surround::s_variable = FirstWithin::s_variable;
        return s_variable;
    }
\end{verbatim}
\section{Nesting enumerations}
\typeout{Original Yodl file: nested/enumerations}Enumerations \index{enumeration: nested} \index{nested enumerations} may also be
nested in classes. Nesting enumerations is a good way to show the close
connection between the enumeration and its class. Nested enumerations have the
same controlled visibility as other class members. They may be defined in the
private, protected or public sections of classes and are inherited by derived
classes.  In the class \index{ios}\texttt{ios} we've seen values like \texttt{ios::beg} and
\texttt{ios::cur}. In the current \index{GNU}GNU \textbf{C++} implementation these values are
defined as values of the \index{seek\_dir}\texttt{seek\_dir} enumeration:
        \begin{verbatim}
    class ios: public _ios_fields
    {
        public:
            enum seek_dir
            {
                beg,
                cur,
                end
            };
    };
\end{verbatim}
As an illustration assume that a class \texttt{DataStructure} represents a data
structure that
may be traversed in a forward or backward direction. Such a class can define
an enumeration \texttt{Traversal} having the values \texttt{FORWARD} and
\texttt{BACKWARD}. Furthermore, a member function \texttt{setTraversal} can be defined
requiring a \texttt{Traversal} type of argument. The class can be defined as
follows:
        \begin{verbatim}
    class DataStructure
    {
        public:
            enum Traversal
            {
                FORWARD,
                BACKWARD
            };
            setTraversal(Traversal mode);
        private:
            Traversal
                d_mode;
    };
\end{verbatim}
Within the class \texttt{DataStructure} the values of the \texttt{Traversal}
enumeration can be used directly. For example:
        \begin{verbatim}
    void DataStructure::setTraversal(Traversal mode)
    {
        d_mode = mode;
        switch (d_mode)
        {
            FORWARD:
                // ... do something
            break;

            BACKWARD:
                // ... do something else
            break;
        }
    }
\end{verbatim}
Outside of the class \texttt{DataStructure} the name of the enumeration type is
not used to refer to the values of the enumeration. Here the classname is
sufficient. Only if a variable of the enumeration type is required the name of
the enumeration type is needed, as illustrated by the following piece of code:
        \begin{verbatim}
    void fun()
    {
        DataStructure::Traversal                // enum typename required
            localMode = DataStructure::FORWARD; // enum typename not required

        DataStructure ds;
                                                // enum typename not required
        ds.setTraversal(DataStructure::BACKWARD);
    }
\end{verbatim}
In the above example the constant \texttt{DataStructure;:FORWARD} was used to
specify a value of an enum defined in the class \texttt{DataStructure}. Instead of
\texttt{DataStructure::FORWARD} the construction \texttt{ds.FORWARD} is also
accepted. In my opinion this syntactic liberty is ugly: \texttt{FORWARD} is a
symbolic value that is defined at the class level; it's not a member of \texttt{ds},
which is suggested by the use of the member selector operator.

Only if \texttt{DataStructure} defines a nested class \texttt{Nested}, in
turn defining the enumeration \texttt{Traversal}, the two class scopes are
required. In that case the latter example should have been coded as follows:
        \begin{verbatim}
    void fun()
    {
        DataStructure::Nested::Traversal
            localMode = DataStructure::Nested::FORWARD;

        DataStructure ds;

        ds.setTraversal(DataStructure::Nested::BACKWARD);
    }
\end{verbatim}
Here a construction like \texttt{DataStructure::Nested::Traversal localMode =
ds.Nested::FORWARD} could also have been used, although I personally would
avoid it, as \texttt{FORWARD} is not a member of \texttt{ds} but rather a symbol that is
defined in \texttt{DataStructure}.

\subsection{Empty enumerations}\label{EMPTYENUM}
    \typeout{Original Yodl file: nested/emptyenum}\texttt{Enum} types usually define symbolic values. However, this is not
required. In section \ref{DYNAMICCAST} the \texttt{std::bad\_cast} type was
introduced. A \texttt{bad\_cast} is thrown by the \texttt{dynamic\_cast$<$$>$} operator
when a reference to a base class object cannot be cast to a derived
class reference. The \texttt{bad\_cast} could be caught as type, irrespective
of any value it might represent.

Types may be defined \index{type: without values} without any associated
values. An \index{empty enum}\emph{empty enum} can be defined which is an \texttt{enum} not defining
any values. The empty enum's type name may thereupon be used as a legitimate
type in, e.g. a \index{catch: empty enum} \texttt{catch} clause.

The example shows how an empty enum is defined (often, but not necessarily
within a \index{class}\texttt{class}) and how it may be thrown (and caught) as exceptions:
        \begin{verbatim}
    #include <iostream>

    enum EmptyEnum
    {};

    int main()
    try
    {
        throw EmptyEnum();
    }
    catch (EmptyEnum)
    {
        std::cout << "Caught empty enum\n";
    }
\end{verbatim}
\section{Revisiting virtual constructors}\label{NESTEDVIRTCONS}
\typeout{Original Yodl file: nested/virtcons.yo}In section \ref{VIRTCONS} the notion of virtual constructors was introduced. In
that section a class \texttt{Base} was defined as an abstract base class.  A class
\texttt{Clonable} was defined to manage \texttt{Base} class pointers in containers like
vectors.

As the class \texttt{Base} is a minute class, hardly requiring any implementation,
it can very well be defined as a nested class in \texttt{Clonable}. This
emphasizes the close relationship between \texttt{Clonable} and
\texttt{Base}. Nesting \texttt{Base} under \texttt{Clonable} changes
        \begin{verbatim}
    class Derived: public Base
\end{verbatim}
into:
        \begin{verbatim}
    class Derived: public Clonable::Base
\end{verbatim}
Apart from defining \texttt{Base} as a nested class and deriving from
\texttt{Clonable::Base} rather than from \texttt{Base} (and providing \texttt{Base} members
with the proper \texttt{Clonable::} prefix to complete their fully qualified
names), no further modifications are required. Here are the modified parts of
the program shown earlier (cf. section \ref{VIRTCONS}), now using \texttt{Base}
nested under \texttt{Clonable}:
        \begin{verbatim}
// Clonable and nested Base, including their inline members:
    class Clonable
    {
        public:
            class Base;
        private:
            Base *d_bp;
        public:
            class Base
            {
                public:
                    virtual ~Base();
                    Base *clone() const;
                private:
                    virtual Base *newCopy() const = 0;
            };
            Clonable();
            explicit Clonable(Base *base);
            ~Clonable();
            Clonable(Clonable const &other);
            Clonable(Clonable &&tmp);
            Clonable &operator=(Clonable const &other);
            Clonable &operator=(Clonable &&tmp);

            Base &base() const;
    };
    inline Clonable::Base *Clonable::Base::clone() const
    {
        return newCopy();
    }
    inline Clonable::Base &Clonable::base() const
    {
        return *d_bp;
    }

// Derived and its inline member:
    class Derived1: public Clonable::Base
    {
        public:
            ~Derived1();
        private:
            virtual Clonable::Base *newCopy() const;
    };
    inline Clonable::Base *Derived1::newCopy() const
    {
        return new Derived1(*this);
    }

// Members not implemented inline:
    Clonable::Base::~Base()
    {}
\end{verbatim}
\cleardoublepage\chapter{The Standard Template Library}\label{STL}
\typeout{Original Yodl file: stl}\typeout{Original Yodl file: stl/intro}The \index{Standard Template Library}\texttt{Standard Template Library} (\index{STL}STL) is a general purpose library
consisting of containers, generic algorithms, iterators, function objects,
allocators, adapters and data structures. The data structures used by the
algorithms are \emph{abstract} in the sense that the algorithms can be used with
(practically) any data type.

The algorithms can process these abstract data types because they are
\index{template}\emph{template} based. This chapter does not cover template \emph{construction}
(see chapter \ref{TEMPLATES} for that). Rather, it focuses on the \emph{use}
of the algorithms.

Several elements also used by the standard template library have already been
discussed in the \textbf{C++} Annotations. In chapter \ref{CONTAINERS} abstract containers
were discussed, and in section \ref{FUNOBJ} function objects were introduced.
Also, \emph{iterators} were mentioned at several places in this document.

The main components of the STL are covered in this and the next
chapter. Iterators, adapters, smart pointers, multi threading and other
features of the STL are discussed in coming sections. Generic
algorithms are covered in the next chapter (\ref{GENERIC}).

\emph{Allocators} take care of the memory allocation within the
STL. The default \index{allocator class}allocator class suffices for most applications, and is
not further discussed in the \textbf{C++} Annotations.

All elements of the STL \index{standard namespace: and STL} are defined in the
standard namespace. Therefore, a \texttt{using namespace std} or a comparable
directive is required unless it is preferred to specify the required namespace
explicitly. In header files  the \texttt{std} namespace should explicitly
be used (cf. section \ref{NAMESPACEHDR}).

In this chapter the empty \index{angle bracket notation}angle bracket notation is frequently used. In
code a typename must be supplied between the angle brackets. E.g., \texttt{plus$<$$>$}
is used in the \textbf{C++} Annotations, but in code \texttt{plus$<$string$>$} may be encountered.

\section{Predefined function objects}\label{PREDEFINED}
\typeout{Original Yodl file: stl/predefined}Before using the predefined function objects presented in this section the
\index{functional: header file}\texttt{$<$functional$>$} header file must be included.

Function objects play important roles in generic
algorithms. For example, there exists a generic algorithm \texttt{sort}
expecting two iterators defining the range of objects that should be sorted,
as well as a function object calling the appropriate comparison operator for
two objects. Let's take a quick look at this situation. Assume strings are
stored in a vector, and we want to sort the vector in descending order. In
that case, sorting the vector \texttt{stringVec} is as simple as:
            \begin{verbatim}
        sort(stringVec.begin(), stringVec.end(), greater<string>());
\end{verbatim}
The last argument is recognized as a \index{constructor}\emph{constructor}: it is an
\emph{instantiation} of the \texttt{greater$<$$>$} class template, applied to
\texttt{strings}. This object is called as a function object by the \texttt{sort}
generic algorithm. The generic algorithm calls the function object's
\texttt{operator()} member to compare two \texttt{string} objects. The function object's
\texttt{operator()} will, in turn, call \texttt{operator$>$} of the \texttt{string} data
type. Eventually, when \texttt{sort} returns, the first element of the vector will
contain the string having the greatest \texttt{string} value of all.

The function object's \texttt{operator()} itself is \emph{not} visible at this
point. Don't confuse the parentheses in the `\texttt{greater$<$string$>$()}' argument
with calling \texttt{operator()}. When \texttt{operator()} is actually used inside
\texttt{sort}, it receives two arguments: two strings to compare for
`greaterness'. Since \texttt{greater$<$string$>$::operator()} is defined \index{inline}inline, the
call itself is not actually present in the above \texttt{sort} call.  Instead
\texttt{sort} calls \texttt{string::operator$>$} through \texttt{greater$<$string$>$::operator()}.

Now that we know that a constructor is passed as argument to (many) generic
algorithms, we can design our own function objects. Assume we want to sort our
vector case-insensitively. How do we proceed? First we note that the default
\texttt{string::operator$<$} (for an incremental sort) is not appropriate, as it does
case sensitive comparisons. So, we provide our own \texttt{CaseInsensitive} class,
which compares two strings case insensitively. Using the \texttt{POSIX} function
\index{strcasecmp}\texttt{strcasecmp}, the following program performs the trick. It
case-insensitively sorts its command-line arguments in ascending alphabetic
order:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <cstring>
    #include <algorithm>
    using namespace std;

    class CaseInsensitive
    {
        public:
            bool operator()(string const &left, string const &right) const
            {
                return strcasecmp(left.c_str(), right.c_str()) < 0;
            }
    };
    int main(int argc, char **argv)
    {
        sort(argv, argv + argc, CaseInsensitive{});
        for (int idx = 0; idx < argc; ++idx)
            cout << argv[idx] << " ";
        cout << '\n';
    }
\end{verbatim}
    The default constructor of the \texttt{class CaseInsensitive} is used to
provide \texttt{sort} with its final argument. So the only member function that
must be defined is \texttt{CaseInsensitive::operator()}. Since we know it's called
with \texttt{string} arguments, we define it to expect two \texttt{string} arguments,
which are used when calling \texttt{strcasecmp}. Furthermore, the function call
operator \texttt{operator()} is defined \index{inline}inline, so that it does not produce
overhead when called by the \texttt{sort} function. The \texttt{sort} function calls the
function object with various combinations of \texttt{strings}. If the compiler
grants our inline requests, it will in fact call \texttt{strcasecmp}, skipping two
extra function calls.

The comparison function object is often a \index{predefined function object}\emph{predefined function object}.
Predefined function object classes are available for many commonly used
operations.  In the following sections the available predefined function
objects are presented, together with some examples showing their use. Near the
end of the section about function objects \index{function adapters}\emph{function adapters} are
introduced.

Predefined function objects are used predominantly with generic
algorithms. Predefined function objects exists for arithmetic, relational, and
logical operations.

\subsection{Arithmetic function objects}
    \typeout{Original Yodl file: stl/arithmetic}The \index{function object: arithmetic}\index{arithmetic function object} arithmetic
function objects support the standard \index{arithmetic operations}arithmetic operations: addition,
subtraction, multiplication, division, modulo and negation. These function
objects invoke the corresponding operators of the data types for which they
are instantiated. For example, for addition the function object \texttt{plus$<$Type$>$}
\index{plus} is available. If we replace \texttt{Type} by \texttt{size\_t} then the addition
operator for \texttt{size\_t} values is used, if we replace \texttt{Type} by \texttt{string},
the addition operator for strings is used. For example:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <functional>
    using namespace std;

    int main(int argc, char **argv)
    {
        plus<size_t> uAdd;              // function object to add size_ts

        cout << "3 + 5 = " << uAdd(3, 5) << '\n';

        plus<string> sAdd;              // function object to add strings

        cout << "argv[0] + argv[1] = " << sAdd(argv[0], argv[1]) << '\n';
    }
    /*
        Output when called as: a.out going

        3 + 5 = 8
        argv[0] + argv[1] = a.outgoing
    */
\end{verbatim}
    Why is this useful? Note that the function object can be used with all
kinds of data types (not only with the predefined datatypes) supporting the
operator called by the function object.

Suppose we want to perform an operation on a left hand side operand which is
always the same variable and a right hand side argument for which, in turn,
all elements of an array should be used. E.g., we want to compute the sum of
all elements in an array; or we want to concatenate all the strings in a
text-array. In situations like these function objects come in handy.

As stated, function objects are heavily used in the context of the generic
algorithms, so let's take a quick look ahead at yet another one.

The generic algorithm \texttt{accumulate} visits all elements specified by an
iterator-range, and performs a requested binary operation on a common element
and each of the elements in the range, returning the accumulated result after
visiting all elements specified by the iterator range. It's easy to use this
algorithm. The next program accumulates all command line arguments and prints
the final string:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <functional>
    #include <numeric>
    using namespace std;

    int main(int argc, char **argv)
    {
        string result =
                accumulate(argv, argv + argc, string{}, plus<string>());

        cout << "All concatenated arguments: " << result << '\n';
    }
\end{verbatim}
    The first two arguments define the (iterator) range of elements to visit,
the third argument is \texttt{string}. This anonymous string object provides an
initial value. We could also have used
        \begin{verbatim}
    "All concatenated arguments: "s
\end{verbatim}
in which case the \texttt{cout} statement could simply have been
\texttt{cout $<$$<$ result $<$$<$ '\textbackslash{}n'}.
    The string-addition operation is used, called from \texttt{plus$<$string$>$}. The
final concatenated string is returned.

Now we define a class \texttt{Time}, overloading \index{operator+}\texttt{operator+}. Again, we can
apply the predefined function object \texttt{plus}, now tailored to our newly
defined datatype, to add times:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <vector>
    #include <functional>
    #include <numeric>
    using namespace std;

    class Time
    {
        friend ostream &operator<<(ostream &str, Time const &time);
        size_t d_days;
        size_t d_hours;
        size_t d_minutes;
        size_t d_seconds;
        public:
            Time(size_t hours, size_t minutes, size_t seconds);
            Time &operator+=(Time const &rhs);
    };

    Time operator+(Time const &lhs, Time const &rhs)
    {
        Time ret(lhs);
        return ret += rhs;
    }

    Time::Time(size_t hours, size_t minutes, size_t seconds)
    :
        d_days(0),
        d_hours(hours),
        d_minutes(minutes),
        d_seconds(seconds)
    {}
    Time &Time::operator+=(Time const &rhs)
    {
        d_seconds   += rhs.d_seconds;
        d_minutes   += rhs.d_minutes   + d_seconds / 60;
        d_hours     += rhs.d_hours     + d_minutes / 60;
        d_days      += rhs.d_days      + d_hours   / 24;
        d_seconds   %= 60;
        d_minutes   %= 60;
        d_hours     %= 24;
        return *this;
    }
    ostream &operator<<(ostream &str, Time const &time)
    {
        return str << time.d_days << " days, " << time.d_hours <<
                                                    " hours, " <<
                      time.d_minutes << " minutes and " <<
                      time.d_seconds << " seconds.";
    }
    int main(int argc, char **argv)
    {
        vector<Time> tvector;

        tvector.push_back(Time( 1, 10, 20));
        tvector.push_back(Time(10, 30, 40));
        tvector.push_back(Time(20, 50,  0));
        tvector.push_back(Time(30, 20, 30));

        cout <<
            accumulate
            (
                tvector.begin(), tvector.end(), Time(0, 0, 0), plus<Time>()
            ) <<
            '\n';
    }
    //  Displays: 2 days, 14 hours, 51 minutes and 30 seconds.
\end{verbatim}
    The design of the above program is fairly straightforward.  \texttt{Time}
defines a constructor, it defines an insertion operator and it defines its own
\texttt{operator+}, adding two time objects. In \texttt{main} four \texttt{Time} objects are
stored in a \texttt{vector$<$Time$>$} object. Then, \texttt{accumulate} is used to compute
the accumulated time. It returns a \texttt{Time} object, which is inserted into
\texttt{cout}.

While this section's first example illustrated using a \emph{named} function
object, the last two examples illustrate how \index{anonymous}\emph{anonymous} objects can be
passed to the (\texttt{accumulate}) function.

The STL supports the following set of arithmetic function objects.  The
function call operator (\texttt{operator()}) of these function objects calls the
matching arithmetic operator for the objects that are passed to the function
call operator, returning that arithmetic operator's return value. The
arithmetic operator that is actually called is mentioned below:
    \begin{itemize}
    \item \index{plus}\texttt{plus$<$$>$}: calls the binary \index{operator+}\texttt{operator+};
    \item \index{minus}\texttt{minus$<$$>$}: calls the binary \index{operator-}\texttt{operator-};
    \item \index{multiplies}\texttt{multiplies$<$$>$}: calls the binary \index{operator*}\texttt{operator$*$};
    \item \index{divides}\texttt{divides$<$$>$}: calls \index{operator/}\texttt{operator/};
    \item \index{modulus}\texttt{modulus$<$$>$}:  calls \index{operator%}\texttt{operator\%};
    \item \index{negate}\texttt{negate$<$$>$}: calls the unary \texttt{operator-}. This arithmetic
function object is a unary function object as it expects one argument.
    \end{itemize}
    In the next example the \index{transform}\texttt{transform} generic algorithm is used to toggle
the signs of all elements of an array. \texttt{Transform}
expects two iterators, defining the range of objects to be transformed; an
iterator defining the begin of the destination range (which may be the same
iterator as the first argument); and a function object defining a unary
operation for the indicated data type.
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <functional>
    #include <algorithm>
    using namespace std;

    int main(int argc, char **argv)
    {
        int iArr[] = { 1, -2, 3, -4, 5, -6 };

        transform(iArr, iArr + 6, iArr, negate<int>());

        for (int idx = 0; idx < 6; ++idx)
            cout << iArr[idx] << ", ";
        cout << '\n';
    }
    // Displays:  -1, 2, -3, 4, -5, 6,
\end{verbatim}
\subsection{Relational function objects}\label{RELATIONAL}
    \typeout{Original Yodl file: stl/relational}The relational operators are called by the
 \index{function object: relational}\index{relational function object} relational
function objects. All standard relational operators are supported: \texttt{==, !=,
$>$, $>$=, $<$} and \texttt{$<$=}.

The STL supports the following set of relational function objects.  The
function call operator (\texttt{operator()}) of these function objects calls the
matching relational operator for the objects that are passed to the function
call operator, returning that relational operator's return value. The
relational operator that is actually called is mentioned below:
    \begin{itemize}
    \item \index{equal\_to}\texttt{equal\_to$<$$>$}: calls \index{operator==}\texttt{operator==};
    \item \index{not\_equal\_to}\texttt{not\_equal\_to$<$$>$}: calls \index{operator!=}\texttt{operator!=};
    \item \index{greater}\texttt{greater$<$$>$}: calls \index{operator\textgreater{}}\texttt{operator$>$};
    \item \index{greater\_equal}\texttt{greater\_equal$<$$>$}: calls \index{operator\textgreater{}=}\texttt{operator$>$=};
    \item \index{less}\texttt{less$<$$>$}: this object's member \texttt{operator()} calls
        \index{operator\textless{}}\texttt{operator$<$};
    \item \index{less\_equal}\texttt{less\_equal$<$$>$}: calls \index{operator\textless{}=}\texttt{operator$<$=}.
    \end{itemize}
    An example using the relational function objects in combination with
\index{sort}\texttt{sort} is:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <functional>
    #include <algorithm>
    using namespace std;

    int main(int argc, char **argv)
    {
        sort(argv, argv + argc, greater_equal<string>());

        for (int idx = 0; idx < argc; ++idx)
            cout << argv[idx] << " ";
        cout << '\n';

        sort(argv, argv + argc, less<string>());

        for (int idx = 0; idx < argc; ++idx)
            cout << argv[idx] << " ";
        cout << '\n';
    }
\end{verbatim}
    The example illustrates how strings may be sorted alphabetically and
reversed alphabetically. By passing \texttt{greater\_equal$<$string$>$} the strings are
sorted in \emph{decreasing} order (the first word will be the 'greatest'), by
passing \texttt{less$<$string$>$} the strings are sorted in \emph{increasing} order (the
first word will be the 'smallest').

Note that \texttt{argv} contains \texttt{char $*$} values, and that the relational
function object expects a \texttt{string}.  The promotion from \texttt{char const $*$} to
\texttt{string} is silently performed.

\subsection{Logical function objects}
    \typeout{Original Yodl file: stl/logical}The \index{logical operators}logical operators are called by the
 \index{function object: logical}\index{logical function object} logical function
objects. The standard logical operators are supported: \texttt{and, or,} and
\texttt{not}.

The STL supports the following set of logical function objects. The
function call operator (\texttt{operator()}) of these function objects calls the
matching logical operator for the objects that are passed to the function
call operator, returning that logical operator's return value. The
logical operator that is actually called is mentioned below:
    \begin{itemize}
    \item \index{logical\_and}\texttt{logical\_and$<$$>$}: calls \index{operator\&\&}\texttt{operator\&\&};
    \item \index{logical\_or}\texttt{logical\_or$<$$>$}: calls \index{operator||}\texttt{operator\textbar{}\textbar{}};
    \item \index{logical\_not}\texttt{logical\_not$<$$>$}: calls \texttt{operator!}.
    \end{itemize}
    An example using \texttt{operator!} is provided in the following trivial
program, using \index{transform}\texttt{transform}  to transform
the logical values stored in an array:
        \begin{verbatim}
    #include <iostream>
    #include <string>
    #include <functional>
    #include <algorithm>
    using namespace std;

    int main(int argc, char **argv)
    {
        bool bArr[] = {true, true, true, false, false, false};
        size_t const bArrSize = sizeof(bArr) / sizeof(bool);

        for (size_t idx = 0; idx < bArrSize; ++idx)
            cout << bArr[idx] << " ";
        cout << '\n';

        transform(bArr, bArr + bArrSize, bArr, logical_not<bool>());

        for (size_t idx = 0; idx < bArrSize; ++idx)
            cout << bArr[idx] << " ";
        cout << '\n';
    }
    /*
      Displays:

        1 1 1 0 0 0
        0 0 0 1 1 1
    */
\end{verbatim}
\subsection{The `std::not\_fn' negator}
    \typeout{Original Yodl file: stl/notfn}A \index{negator}\emph{negator} is a function object toggling the truth value of
a function that's called from the negator: if the function returns \texttt{true}
the negator returns \texttt{false} and vv.

The standard negator is \texttt{std::not\_fn}\index{not\_fn}, declared in the
\index{functional: header file}\texttt{$<$functional$>$} header file.

The function \texttt{not\_fn} expects a (movable) object as its argument, returning
the negated value of the return value of its argument's function call
operator. 

As an example consider a \texttt{main} function defining an array of \texttt{int}
values:
        \begin{verbatim}
    int main()
    {
        int arr[] = {1, 2, 3, 4, 5, 6, 7, 8, 9};
    }
\end{verbatim}
To count the number of even values \texttt{count\_if}, using a lambda function can
be used:
        \begin{verbatim}
        cout << 
            count_if(arr, arr + size(arr),
                [&](int value)
                {
                    return (value & 1) == 0;
                }
            ) << '\n';
\end{verbatim}
To count the number of odd values, \texttt{not\_fn} can be used in the above code
like so:
        \begin{verbatim}
        cout << 
            count_if(arr, arr + size(arr),
                not_fn(
                    [&](int value)
                    {
                        return (value & 1) == 0;
                    }
                )
            ) << '\n';
\end{verbatim}
Of course, in this simple example the lambda function could also easily have
been modified. But if instead of a lambda function an existing class
implementing a function object had been used it would have been difficult or
impossible to change the behavior of that class. If the class offers moving
operations then \texttt{not\_fn} can be used to negate the values returned by that
class's function call operator.

\section{Iterators}\label{ITERATORS}
\typeout{Original Yodl file: stl/iterators}In addition to the conceptual iterator types presented in this section the STL
defines several adapters \index{adapter: object to iterator} allowing objects to
be passed as iterators. These adapters are presented in the upcoming
sections. Before those adapters can be used the \index{iterator: header file}\texttt{$<$iterator$>$} header file
must be included. 

The standard iterator \index{iterator (std::) - deprecated} (\texttt{std::iterator}) is
now
deprecated\footnote{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0174r1.html\#2.1},
and the compiler issues a corresponding warning. Consequently,
\texttt{std::iterator} should no longer be used when designing your own iterators
(section \ref{ITERATORCONS} describes how to design your own).

Iterators are objects acting like pointers. Iterators have the following
general  \index{iterator} characteristics:
    \begin{itemize}
    \item  Two iterators may be compared for (in)equality using the \texttt{==} and
\texttt{!=} operators. The \emph{ordering} operators (e.g., \texttt{$>$}, \texttt{$<$})
can usually not be used.
    \item  Given an iterator \texttt{iter}, \texttt{$*$iter} represents the object the
iterator points to (alternatively, \texttt{iter-$>$} can be used to reach the members
of the object the iterator points to).
    \item  Given an iterator \texttt{iter}, \index{base}\texttt{iter.base()} returns the
address of \texttt{$*$iter}. It returns the same type as \texttt{\&$*$iter}. E.g.,
            \begin{verbatim}
    vector<int> vi{ 1, 2, 3 };
    int *ip = vi.begin().base();
    cout << *ip << '\n';        // shows: 1
\end{verbatim}
    \item  \texttt{++iter} or \texttt{iter++} advances the iterator to the next
element. The notion of advancing an iterator to the next element is
consequently applied: several containers support \index{reverse\_iterator}\emph{reverse\_iterator} types,
in which the \texttt{++iter} operation actually reaches a previous element in a
sequence.
    \item  \emph{Pointer arithmetic} may be used with iterators of containers
storing their elements consecutively in memory like \index{vector}\texttt{vector} and
\index{deque}\texttt{deque}. For such containers \texttt{iter + 2} points to the second element
beyond the one to which \texttt{iter} points. See also section \ref{DISTANCE},
covering \index{distance}\texttt{std::distance}.
    \item  Merely defining an iterator is comparable to having a
        0-pointer. Example:
        \begin{verbatim}
#include <vector>
#include <iostream>
using namespace std;

int main()
{
    vector<int>::iterator vi;

    cout << &*vi;       // prints 0
}
\end{verbatim}
\end{itemize}
    STL containers usually define members offering iterators (i.e., they
define their own type \index{iterator}\texttt{iterator}). These members are commonly called
\index{begin}\texttt{begin} and \index{end}\texttt{end} and (for reversed iterators (type \texttt{reverse\_iterator}))
\index{rbegin}\texttt{rbegin} and \index{rend}\texttt{rend}.

\index{iterators: forward \textless{}-\textgreater{} reverse}
    Whereas reverse iterators can be constructed from ordinary (forward)
iterators using \texttt{reverse\_iterator} constructors as in:
    \begin{verbatim}
    string str;
    auto revit = string::reverse_iterator{ str.begin() };
\end{verbatim}
the opposite is not accomplished that way. To retrieve the forward
iterator corresponding to a reverse iterator, the \index{reverse\_iterator.base()}\texttt{reverse\_iterator.base()}
    \index{base}\index{base(): reverse\_terator}
member can be used. E.g., to obtain the forward iterator corresponding to
\texttt{revit} use
        \begin{verbatim}
    auto forward { revit.base() };
\end{verbatim}
Standard practice requires \index{iterator: range} iterator ranges to be
\emph{left inclusive}.  The notation \index{[left, right)}\texttt{[left, right)} indicates that \texttt{left}
is an iterator pointing to the first element, while \texttt{right} is an iterator
pointing just \emph{beyond} the last element. The iterator range is \emph{empty}
when \texttt{left == right}.

The following example shows how all elements of a vector of strings can be
inserted into \texttt{cout} using its iterator ranges \texttt{[begin(), end())}, and
\texttt{[rbegin(), rend())}. Note that the \texttt{for-loops} for both ranges are
identical. Furthermore it nicely illustrates how the \texttt{auto} keyword can be
used to define the type of the loop control variable instead of using a much
more verbose variable definition like \texttt{vector$<$string$>$::iterator} (see also
section \ref{AUTO}):
    \begin{verbatim}
    #include <iostream>
    #include <vector>
    #include <string>
    using namespace std;

    int main(int argc, char **argv)
    {
        vector<string> args(argv, argv + argc);

        for (auto iter = args.begin(); iter != args.end(); ++iter)
            cout << *iter << " ";
        cout << '\n';

        for (auto iter = args.rbegin(); iter != args.rend(); ++iter)
            cout << *iter << " ";
        cout << '\n';
    }
\end{verbatim}
Furthermore, the STL defines
 \index{iterator: to const elements}\index{const\_iterator}\emph{const\_iterator} types that must be used
when visiting a series of elements in a constant container. Whereas the
elements of the vector in the previous example could have been altered, the
elements of the vector in the next example are immutable, and
\texttt{const\_iterator}s are required:
        \begin{verbatim}
    #include <iostream>
    #include <vector>
    #include <string>
    using namespace std;

    int main(int argc, char **argv)
    {
        vector<string> const args(argv, argv + argc);

        for
        (
            vector<string>::const_iterator iter = args.begin();
                iter != args.end();
                    ++iter
        )
            cout << *iter << " ";
        cout << '\n';

        for
        (
            vector<string>::const_reverse_iterator iter = args.rbegin();
                iter != args.rend();
                    ++iter
        )
            cout << *iter << " ";
        cout << '\n';
    }
\end{verbatim}
    The examples also illustrate that plain
 \index{pointer as iterator} pointers can be used as iterators. The
initialization \texttt{vector$<$string$>$ args(argv, argv + argc)} provides the
\texttt{args} vector with a pair of pointer-based iterators: \texttt{argv} points to the
first element to initialize \texttt{args} with, \texttt{argv + argc} points just beyond
the last element to be used, \texttt{++argv} reaches the next command line
argument. This is a general pointer characteristic, which is why they too can
be used in situations where \texttt{iterators} are expected.

The STL defines six types \index{iterator: types} of iterators. These
iterator types are expected by generic algorithms, and in order to create a
particular type of iterator yourself it is important to know their
characteristics. In general, iterators \index{iterator: requirements} (see also
section \ref{ITERATORCONS}) must define:
    \begin{itemize}
    \item \index{operator==}\texttt{operator==}, testing two iterators for equality,
    \item \index{operator!=}\texttt{operator!=}, testing two iterators for inequality,
    \item \index{operator++}\texttt{operator++}, incrementing the iterator, as prefix operator,
    \item \index{operator*}\texttt{operator$*$}, to access the element the iterator refers to,
    \end{itemize}
    The following types of iterators are used when describing generic
algorithms  in chapter \ref{GENERIC}:
    \begin{itemize}
    \item  \index{InputIterator}\textbf{InputIterator}\textbf{s}:
        \begin{quote}InputIterators are used to read from a container.  The
dereference operator is guaranteed to work as \index{rvalue}\texttt{rvalue} in
expressions. Instead of an InputIterator it is also possible to use (see
below) Forward-, Bidirectional- or RandomAccessIterators.  Notations like
\texttt{InputIterator1} and \texttt{InputIterator2} may be used as well. In these cases,
numbers are used to indicate which iterators `belong together'. E.g., the
generic algorithm \texttt{inner\_product} has the following
prototype:
        \begin{verbatim}
Type inner_product(InputIterator1 first1, InputIterator1 last1,
               InputIterator2 first2, Type init);
\end{verbatim}
\texttt{InputIterator1 first1} and \texttt{InputIterator1 last1} define a pair of
input iterators on one range, while \texttt{InputIterator2 first2} defines the
beginning of another range. Analogous notations may be used with other
iterator types.\end{quote}
    \item  \index{OutputIterator}\textbf{OutputIterator}\textbf{s}:
        \begin{quote}OutputIterators can be used to write to a container. The
dereference operator is guaranteed to work as an \index{lvalue}\texttt{lvalue} in expressions,
but not necessarily as \texttt{rvalue}. Instead of an OutputIterator it is also
possible to use (see below) Forward-, Bidirectional- or
RandomAccessIterators.\end{quote}
    \item  \index{ForwardIterator}\textbf{ForwardIterator}\textbf{s}:
        \begin{quote}ForwardIterators combine InputIterators and
OutputIterators. They can be used to traverse containers in one direction,
for reading and/or writing. Instead of a ForwardIterator it is also possible
to use (see below) Bidirectional- or RandomAccessIterators.\end{quote}
    \item  \index{BidirectionalIterator}\textbf{BidirectionalIterator}\textbf{s}:
        \begin{quote}BidirectionalIterators can be used to traverse containers in
both directions, for reading and writing. Instead of a BidirectionalIterator
it is also possible to use (see below) a RandomAccessIterator.\end{quote}
    \item  \index{RandomAccessIterator}\textbf{RandomAccessIterator}\textbf{s}:
        \begin{quote}RandomAccessIterators provide \index{random access}random access to container
elements. An algorithm like \texttt{sort} requires a
RandomAccessIterator, and can therefore \emph{not} be used to sort the elements
of lists or maps, which only provide BidirectionalIterators.\end{quote}
    \item  \index{ContiguousIterator}\textbf{ContiguousIterator}\textbf{s}:
        \begin{quote}ContiguousIterators are like random access iterators, but in
addition guarantee that the elements these iterators point to are stored
contiguously in memory. A container like \texttt{std::vector} offers contiguous
iterators.\end{quote}
    \end{itemize}
    The example given with the RandomAccessIterator illustrates how to relate
iterators and generic algorithms: look for the iterator that's required by the
(generic) algorithm, and then see whether the datastructure supports the
required type of iterator. If not, the algorithm cannot be used with the
particular datastructure.

\subsection{std::distance and std::size}\label{DISTANCE}
    \typeout{Original Yodl file: stl/distance}Earlier, in section \ref{ITERATORS} it was stated that iterators support
pointer arithmetic for containers storing their elements consecutively in
memory. This is not completely true: to determine the number of elements
between the elements to which two iterators refer the iterator must 
support the subtraction operator.  

Using pointer arithmetic to compute the number of elements between two
iterators in, e.g., a \texttt{std::list} or \texttt{std::unordered\_map} is not possible,
as these containers do not store their elements consecutively in memory.

The function \texttt{std::distance}\index{distance} fills in that little gap:
\texttt{std::distance} expects two InputIterators and returns the number of
elements between them.

Before using \texttt{distance} the \index{iterator: header file}\texttt{$<$iterator$>$} header file must be included.

If the iterator specified as first argument exceeds the iterator specified as
its second argument then the number of elements is non-positive, otherwise it
is non-negative. If the number of elements cannot be determined (e.g., the
iterators do not refer to elements in the same container), then \texttt{distance's}
return value is undefined.

Example:
        \begin{verbatim}
    #include <iostream>
    #include <unordered_map>
        
    using namespace std;
    
    int main()
    {
        unordered_map<int, int> myMap = {{1, 2}, {3, 5}, {-8, 12}};
    
        cout << distance(++myMap.begin(), myMap.end()) << '\n'; // shows: 2
    }
\end{verbatim}
The \texttt{iterator} header file also defines the function \texttt{std::size}\index{size},
returning the number of elements in a containers (as returned by the
container's \texttt{size} member) or of an array whose dimension is known to the
compiler at the point of \texttt{std::size's} call. E.g., if the size of an array
\texttt{data} is known to the compiler, then to call a function \texttt{handler}
(expecting the address of the first element of an array and the address of the
location just beyond that array) the following statement can be used:
        \begin{verbatim}
    handler(data, data + std::size(data));
\end{verbatim}
As noted, the \texttt{std::size} function is defined in the \texttt{iterator}
header. However, it's also guaranteed available when including the header file
of a container supporting iterators (including the \texttt{string} header file).

\subsection{Insert iterators}\label{INSERTER}
    \typeout{Original Yodl file: stl/insertiterators}Generic algorithms often require a target container into which the results of
the algorithm are deposited. For example, the \texttt{copy} generic
algorithm has three parameters. The first two define the range of visited
elements, the third defines the first position where the results
of the copy operation should be stored.

With the \texttt{copy} algorithm the number of elements to copy is usually
available beforehand, since that number can usually be provided by pointer
arithmetic. However, situations exist where pointer arithmetic cannot be
used. Analogously, the number of resulting elements sometimes differs from the
number of elements in the initial range. The generic algorithm
\texttt{unique\_copy} is a case in point. Here the number of
elements that are copied to the destination container is normally not known
beforehand.

In situations like these an \index{inserter}\emph{inserter} \index{adapter: inserter} adapter
function can often be used to create elements in the destination container.
There are three types of inserter adapters:
    \begin{itemize}
    \item \index{back\_inserter}\texttt{back\_inserter}: calls the container's \index{push\_back}\texttt{push\_back} member to add
new elements at the end of the container. E.g., to copy all elements of
\texttt{source} in reversed order to the back of \texttt{destination}, using the
\texttt{copy} generic algorithm:
        \begin{verbatim}
copy(source.rbegin(), source.rend(), back_inserter(destination));
\end{verbatim}
\item \index{front\_inserter}\texttt{front\_inserter} calls the container's \index{push\_front}\texttt{push\_front} member, adding
new elements at the beginning of the container. E.g., to copy all elements of
\texttt{source} to the front of the destination container (thereby also reversing
the order of the elements):
        \begin{verbatim}
copy(source.begin(), source.end(), front_inserter(destination));
\end{verbatim}
\item \index{inserter}\texttt{inserter} calls the container's \index{insert}\texttt{insert} member adding new elements
starting at a specified starting point. E.g., to copy all elements of
\texttt{source} to the destination container, starting at the beginning of
\texttt{destination}, shifting up existing elements to beyond the newly inserted
elements:
        \begin{verbatim}
copy(source.begin(), source.end(), inserter(destination,
    destination.begin()));
\end{verbatim}
    \end{itemize}
    The inserter adapters
 \index{adapter: required types} \index{inserter: required types}
 require the existence of two types:
    \begin{itemize}
    \item \texttt{using value\_type = Data}, where \texttt{Data} is the data type stored in
the class offering \texttt{push\_back, push\_front} or \texttt{insert} members (Example:
\texttt{using value\_type = std::string});
    \item \texttt{using const\_reference = const \&value\_type}
    \end{itemize}
    Concentrating on \texttt{back\_inserter}, this iterator expects the name of a
container supporting a member \texttt{push\_back}. The inserter's \texttt{operator()}
member calls the container's \texttt{push\_back} member. Objects
 \index{inserter: and non-STL classes} of any class supporting a \texttt{push\_back}
member can be passed as arguments to \texttt{back\_inserter} provided the class adds
        \begin{verbatim}
    using const_reference = DataType const &;
\end{verbatim}
to its interface (where \texttt{DataType const \&} is the type of the parameter
of the class's member \texttt{push\_back}). Example:
        \begin{verbatim}
    #include <iostream>
    #include <algorithm>
    #include <iterator>
    using namespace std;

    class Insertable
    {
        public:
            using value_type = int;
            using const_reference = int const &;

            void push_back(int const &)
            {}
    };

    int main()
    {
        int arr[] = {1};
        Insertable insertable;

        copy(arr, arr + 1, back_inserter(insertable));
    }
\end{verbatim}
\subsection{Iterators for `istream' objects}\label{ISTREAMITERATORS}
    \typeout{Original Yodl file: stl/istreamiterators}The \index{istream\_iterator}\texttt{istream\_iterator$<$Type$>$} can be used to define a set
of iterators for
 \index{istream: iterator} \texttt{istream} objects. The general form of the
\texttt{istream\_iterator} iterator is:
        \begin{verbatim}
    istream_iterator<Type> identifier(istream &in)
\end{verbatim}
Here, \texttt{Type} is the type of the data elements read from the \texttt{istream}
stream. It is used as the `begin' iterator in an iterator range. \texttt{Type} may
be any type for which \texttt{operator}$>>$ is defined in combination with \texttt{istream}
objects.

The default constructor is used as the end-iterator and corresponds to the
 \index{end-of-stream}end-of-stream. For example,
        \begin{verbatim}
    istream_iterator<string> endOfStream;
\end{verbatim}
The \emph{stream} object that was specified when defining the
begin-iterator is \emph{not} mentioned with the default constructor.

Using \texttt{back\_inserter} and \texttt{istream\_iterator} adapters, all strings
from a stream can easily be stored in a container. Example (using \index{anonymous}anonymous
\texttt{istream\_iterator} adapters):
        \begin{verbatim}
    #include <iostream>
    #include <iterator>
    #include <string>
    #include <vector>
    #include <algorithm>
    using namespace std;

    int main()
    {
        vector<string> vs;

        copy(istream_iterator<string>(cin), istream_iterator<string>(),
             back_inserter(vs));

        for
        (
            vector<string>::const_iterator begin = vs.begin(), end = vs.end();
                begin != end; ++begin
        )
            cout << *begin << ' ';
        cout << '\n';
    }
\end{verbatim}
\subsubsection{Iterators for `istreambuf' objects}
        \typeout{Original Yodl file: stl/istreambufiterators}Input iterators are also available for \index{streambuf}\texttt{streambuf} objects.

To read from \texttt{streambuf} objects supporting input operations
 \index{istreambuf\_iterator}\texttt{istreambuf\_iterators} can be used, supporting the
operations that are also available for \texttt{istream\_iterator}. Different from
the latter iterator type \texttt{istreambuf\_iterators} support three constructors:
    \begin{itemize}
    \item \texttt{istreambuf\_iterator$<$Type$>$}:\ \\ The end iterator of an iterator range is created using the default
\texttt{istreambuf\_iterator} constructor. It represents the \index{end-of-stream}end-of-stream
condition when extracting values of type \texttt{Type} from the \texttt{streambuf}.

\item \texttt{istreambuf\_iterator$<$Type$>$(streambuf $*$)}:\ \\ A pointer to a \texttt{streambuf} may be used when defining an
\texttt{istreambuf\_iterator}. It represents the begin iterator of an iterator
range.
    \item \texttt{istreambuf\_iterator$<$Type$>$(istream)}:\ \\ An \emph{istream} may be also used when defining an
\texttt{istreambuf\_iterator}. It accesses the \texttt{istream}'s \texttt{streambuf} and it
also represents the begin iterator of an iterator range.
    \end{itemize}
    In section \ref{OSTREAMBUFITER} an example is given using both
\texttt{istreambuf\_iterators} and \texttt{ostreambuf\_iterators}.

\subsection{Iterators for `ostream' objects}
    \typeout{Original Yodl file: stl/ostreamiterators}An \index{ostream\_iterator}\texttt{ostream\_iterator$<$Type$>$} adapter can be used to pass
an \texttt{ostream} to algorithms expecting an OutputIterator. Two constructors are
available for defining \texttt{ostream\_iterators}:
        \begin{verbatim}
    ostream_iterator<Type> identifier(ostream &outStream);
    ostream_iterator<Type> identifier(ostream &outStream, char const *delim);
\end{verbatim}
\texttt{Type} is the type of the data elements that should be inserted into an
\texttt{ostream}. It may be any type for which \texttt{operator}$<<$ is defined in
combination with \texttt{ostream} objects.  The latter constructor can be used to
separate the individual \texttt{Type} data elements by \index{delimiter}\texttt{delimiter} strings. The
former constructor does not use any delimiters.

The example shows how \texttt{istream\_iterators} and an
\texttt{ostream\_iterator} may be used to copy information of a file to another
file. A subtlety here is that you probably want to use
\texttt{in.unsetf(ios::skipws)}. It is used to clear the
 \index{skipws}\texttt{ios::skipws} flag. As a consequence whitespace characters are
simply returned by the operator, and the file is copied character by
character. Here is the program:
        \begin{verbatim}
    #include <iostream>
    #include <algorithm>
    #include <iterator>
    using namespace std;

    int main()
    {
        cin.unsetf(ios::skipws);
        copy(istream_iterator<char>(cin), istream_iterator<char>(),
             ostream_iterator<char>(cout));
    }
\end{verbatim}
\subsubsection{Iterators for `ostreambuf' objects}\label{OSTREAMBUFITER}
        \typeout{Original Yodl file: stl/ostreambufiterators}Output iterators are also available for \index{streambuf}\texttt{streambuf} objects.

To write to  \texttt{streambuf} objects supporting output operations
 \index{ostreambuf\_iterator}\texttt{ostreambuf\_iterators} can be used, supporting the
operations that are also available for
\texttt{ostream\_iterator}. \texttt{Ostreambuf\_iterators} support two constructors:
    \begin{itemize}
    \item \texttt{ostreambuf\_iterator$<$Type$>$(streambuf $*$)}:\ \\ A pointer to a \texttt{streambuf} may be used when defining an
\texttt{ostreambuf\_iterator}. It can be used as an OutputIterator.
    \item \texttt{ostreambuf\_iterator$<$Type$>$(ostream)}:\ \\ An \emph{ostream} may be also used when defining an
\texttt{ostreambuf\_iterator}. It accesses the \texttt{ostream}'s \texttt{streambuf} and it
can also be used as an OutputIterator.
    \end{itemize}
    The next example illustrates the use of both
 \index{istreambuf\_iterator}\texttt{istreambuf\_iterators} and \texttt{ostreambuf\_iterators}
when copying a stream in yet another way. Since the stream's \texttt{streambuf}s
are directly accessed the streams and stream flags are bypassed. Consequently
there is no need to clear \texttt{ios::skipws} as in the previous section, while
the next program's efficiency probably also exceeds the efficiency of the
program shown in the previous section.
        \begin{verbatim}
    #include <iostream>
    #include <algorithm>
    #include <iterator>
    using namespace std;

    int main()
    {
        istreambuf_iterator<char> in(cin.rdbuf());
        istreambuf_iterator<char> eof;
        ostreambuf_iterator<char> out(cout.rdbuf());

        copy(in, eof, out);
    }
\end{verbatim}
\subsection{Moving elements to another container}
    \typeout{Original Yodl file: stl/moveiterator}Sometimes we want to move elements from one container to another one. Instead
of retrieving elements in sequence and then moving them into the destination
container (e.g., when extracting words from streams) or explicitly calling
\texttt{std::move} on the source container's elements it's also possible to use
\index{make\_move\_iterator}\texttt{make\_move\_iterator}(std::make\_move\_iterator(iterator iter)). The function's
argument is an iterator referring to a movable element, and the range of
elements to move from one container to another can be specified by calling
two \texttt{make\_move\_iterators}. One receives the source's begin iterator, and
other one the source's end iterator. The example illustrates how words
can be moved into a \texttt{std::vector$<$std::string$>$}:
        \begin{verbatim}
    #include <iostream>
    #include <algorithm>
    #include <vector>
    #include <string>
    #include <iterator>

    using namespace std;

    size_t fstNonEmpty(vector<string> const &vs)
    {
        return
            find_if(vs.begin(), vs.end(),
                    [&](string const &str)
                    {
                        return str != "";
                    }
            ) - vs.begin();
    }

    int main()
    {
        vector<string> vs;

        copy(istream_iterator<string>(cin), istream_iterator<string>(),
                back_inserter(vs));

        cout << "vs contains " << vs.size() << " words\n"
                "first non-empty word at index " << fstNonEmpty(vs) << "\n"
                "moving the first half into vector v2\n";

        vector<string> v2{ make_move_iterator(vs.begin()),
                           make_move_iterator(vs.begin() + vs.size() / 2) };

        cout << "vs contains " << vs.size() << " words\n"
                "first non-empty word at index " << fstNonEmpty(vs) << "\n"
                "v2 contains " << v2.size() << " words\n";
    }
\end{verbatim}
    Note that the elements in the source container have merely moved into the
destination container: the elements in the source container are empty after
moving. When moving other types of objects the results may be different,
although in all cases the source objects should keep their valid states.

\section{The class 'unique\_ptr'}\label{UNIQUEPTR}
\typeout{Original Yodl file: stl/uniqueptr}Before using the \texttt{unique\_ptr} class presented in this section the
\index{memory: header file}\texttt{$<$memory$>$} header file must be included.

When pointers are used to access dynamically allocated memory strict
bookkeeping is required to prevent memory leaks. When a pointer variable
referring to dynamically allocated memory goes out of scope, the dynamically
allocated memory becomes inaccessible and the program suffers from a 
    \index{memory leak}memory leak.
    Consequently, the programmer has to make sure that the dynamically
allocated memory is returned to the common pool just before the pointer
variable goes out of scope.

When a pointer variable points to a dynamically allocated single value or
object, bookkeeping requirements are greatly simplified when the pointer
variable is defined as a \texttt{std::unique\_ptr}\index{unique\_ptr} object.

Unique\_ptrs are \emph{objects} masquerading as pointers. Since they are objects,
their destructors are called when they go out of scope.  Their destructors
automatically delete the dynamically allocated memory to which they
point. Unique\_ptrs (and their cousins shared\_ptrs (cf. section \ref{SHAREDPTR})
are also called
    \index{smart pointer}\emph{smart pointers}).

\texttt{Unique\_ptrs} have several special characteristics:
    \begin{itemize}
    \item  when assigning a \texttt{unique\_ptr} to another \emph{move semantics} is
used. If move semantics is not available compilation fails. On the other
hand, if compilation succeeds then the used containers or generic algorithms
support the use of \texttt{unique\_ptr}s. Here is an example:
        \begin{verbatim}
std::unique_ptr<int> up1(new int);
std::unique_ptr<int> up2(up1);      // compilation error
\end{verbatim}
The second definition fails to compile as \texttt{unique\_ptr}'s copy
constructor is private (the same holds true for the assignment operator). But
the \texttt{unique\_ptr} class \emph{does} offer facilities to initialize and assign
from \emph{rvalue references}:
        \begin{verbatim}
class unique_ptr                        // interface partially shown
{
    public:
        unique_ptr(unique_ptr &&tmp);   // rvalues bind here
    private:
        unique_ptr(const unique_ptr &other);
};
\end{verbatim}
In the next example move semantics is used and so it compiles correctly:
        \begin{verbatim}
unique_ptr<int> cp(unique_ptr<int>(new int));
\end{verbatim}
\item  a \texttt{unique\_ptr} object should only point to memory that was made
available dynamically, as only dynamically allocated memory can be deleted.

\item  multiple \texttt{unique\_ptr} objects should not be allowed to point to the
same block of dynamically allocated memory. The \texttt{unique\_ptr}'s interface was
designed to prevent this from happening. Once a \texttt{unique\_ptr} object goes out
of scope, it deletes the memory it points to, immediately changing any other
object also pointing to the allocated memory into a \index{pointer: wild} wild
pointer.

\item  When a class \texttt{Derived} is derived from \texttt{Base}, then a newly
allocated \texttt{Derived} class object can be assigned to a \texttt{unique\_ptr$<$Base$>$},
without having to define a virtual destructor for \texttt{Base}. The \texttt{Base $*$}
pointer that is returned by the \texttt{unique\_ptr} object can simply be cast
statically to \texttt{Derived}, and \texttt{Derived's} destructor is automatically
called as well, if the \texttt{unique\_ptr} definition is provided with a
\emph{deleter} function address. This is illustrated in the next example:
        \begin{verbatim}
    class Base
    { ... };
    class Derived: public Base
    {
        ...
        public:
            // assume Derived has a member void process()
   
            static void deleter(Base *bp);
    };
    void Derived::deleter(Base *bp)
    {
        delete static_cast<Derived *>(bp);
    }
    int main()
    {
        unique_ptr<Base, void (*)(Base *)> bp(new Derived, &Derived::deleter);
        static_cast<Derived *>(bp.get())->process(); // OK!

    } // here ~Derived is called: no polymorphism required.
\end{verbatim}
\end{itemize}
    The class \texttt{unique\_ptr} offers several member functions to access the
pointer itself or to have a \texttt{unique\_ptr} point to another block of
memory. These member functions (and \texttt{unique\_ptr} constructors) are
introduced in the next few sections.

\texttt{Unique\_ptr} can also be used with containers and (generic) algorithms. They
can properly destruct any type of object, as their constructors accept
customizable deleters. In addition, arrays can be handled by \texttt{unique\_ptrs}.

\subsection{Defining `unique\_ptr' objects}
    \typeout{Original Yodl file: stl/defining}There are three ways to \index{unique\_ptr: defining} define \texttt{unique\_ptr}
objects. Each definition contains the usual \texttt{$<$type$>$} specifier between
angle brackets:
    \begin{itemize}
    \item  The default constructor simply creates a \texttt{unique\_ptr} object that
does not point to a particular block of memory. Its pointer is initialized to
0 (zero):
        \begin{verbatim}
unique_ptr<type> identifier;
\end{verbatim}
This form is discussed in section \ref{UNIQUEPLAIN}.
    \item  The \emph{move constructor}  initializes an \texttt{unique\_ptr} object.
Following the use of the move constructor its \texttt{unique\_ptr} argument no
longer points to the dynamically allocated memory and its pointer data member
is turned into a zero-pointer:
        \begin{verbatim}
unique_ptr<type> identifier(another unique_ptr for type);
\end{verbatim}
This form is discussed in section \ref{UNIQUEMOVE}.
    \item  The form that is used most often initializes a \texttt{unique\_ptr} object
to the block of dynamically allocated memory that is passed to the object's
constructor. Optionally \index{deleter}\texttt{deleter} can be provided. A (free) function (or
function object) receiving the \texttt{unique\_ptr}'s pointer as its argument can be
passed as deleter. It is supposed to return the dynamically allocated
memory to the common pool (doing nothing if the pointer equals zero).
        \begin{verbatim}
unique_ptr<type> identifier (new-expression [, deleter]);
\end{verbatim}
This form is discussed in section \ref{UNIQUENEW}.
    \end{itemize}

\subsection{Creating a plain `unique\_ptr'}\label{UNIQUEPLAIN}
    \typeout{Original Yodl file: stl/uniqueplain}\texttt{Unique\_ptr}'s default constructor defines a \index{unique\_ptr: default}
\texttt{unique\_ptr} not pointing to a particular block of memory:
        \begin{verbatim}
    unique_ptr<type> identifier;
\end{verbatim}
The \index{unique\_ptr: 0-pointer} pointer controlled by the \texttt{unique\_ptr}
object is initialized to \texttt{0} (zero). Although the \texttt{unique\_ptr} object
itself is not the pointer, its value \emph{can} be compared to \texttt{0}. Example:
        \begin{verbatim}
    unique_ptr<int> ip;

    if (!ip)
        cout << "0-pointer with a unique_ptr object\n";
\end{verbatim}
Alternatively, the member \index{get}\texttt{get} can be used (cf. section \ref{UNIQUEMEM}).

\subsection{Moving  another `unique\_ptr'}\label{UNIQUEMOVE}
    \typeout{Original Yodl file: stl/uniquemove}    A \texttt{unique\_ptr} \index{unique\_ptr: move constructor} may be initialized
using an rvalue reference to a \texttt{unique\_ptr} object for the same type:
        \begin{verbatim}
    unique_ptr<type> identifier(other unique_ptr object);
\end{verbatim}
The move constructor is used, e.g., in the following example:
        \begin{verbatim}
    void mover(unique_ptr<string> &&param)
    {
        unique_ptr<string> tmp(move(param));
    }
\end{verbatim}
Analogously, the assignment operator can \index{unique\_ptr: assignment} be
used. A \texttt{unique\_ptr} object may be assigned to a temporary  \texttt{unique\_ptr}
object of the same type (again move-semantics is used). For example:
        \begin{verbatim}
    #include <iostream>
    #include <memory>
    #include <string>

    using namespace std;

    int main()
    {
        unique_ptr<string> hello1{ new string{ "Hello world" } };
        unique_ptr<string> hello2{ move(hello1) };
        unique_ptr<string> hello3;

        hello3 = move(hello2);
        cout << // *hello1 << '\n' <<   // would have segfaulted
                // *hello2 << '\n' <<   // same
                *hello3 << '\n';
    }
    // Displays:    Hello world
\end{verbatim}
    The example illustrates that
    \begin{itemize}
    \item  \texttt{hello1} is initialized by a pointer to a dynamically allocated
\texttt{string} (see the next section).
    \item  The \texttt{unique\_ptr hello2} grabs the pointer controlled by \texttt{hello1}
using a move constructor. This effectively changes \texttt{hello1} into a
0-pointer.
    \item  Then \texttt{hello3} is defined as a default \texttt{unique\_ptr$<$string$>$}. But
then it grabs its value using move-assignment from \texttt{hello2} (which, as a
consequence, is changed into a 0-pointer).
    \end{itemize}
    If \texttt{hello1} or \texttt{hello2} had been inserted into \texttt{cout} a
\index{segmentation fault}\emph{segmentation fault} would have resulted. The reason for this should now be
clear: it is caused by dereferencing 0-pointers. In the end, only \texttt{hello3}
actually points to the originally allocated \texttt{string}.

\subsection{Pointing to a newly allocated object}\label{UNIQUENEW}
    \typeout{Original Yodl file: stl/uniquenew}A \texttt{unique\_ptr} \index{unique\_ptr: initialization} is most often initialized
using a pointer to dynamically allocated memory. The generic form is:
        \begin{verbatim}
    unique_ptr<type [, deleter_type]> identifier(new-expression
            [, deleter = deleter_type{}]);
\end{verbatim}
The second (template) argument (\texttt{deleter(\_type)}) is optional and may
 \index{deleter} refer to a free function, a function object handling the
destruction of the allocated memory, or a lambda function. A deleter is used,
e.g., in situations where a double pointer is allocated and the destruction
must visit each nested pointer to destroy the allocated memory (see below for
an illustration).

Here is an example initializing a \texttt{unique\_ptr} pointing to a \texttt{string}
object:
        \begin{verbatim}
    unique_ptr<string> strPtr{ new string{ "Hello world" } };
\end{verbatim}
The argument that is passed to the constructor is the pointer returned by
\texttt{operator new}. Note that \texttt{type} does \emph{not} mention the pointer.  The
\index{unique\_ptr: used type} type that is used in the \texttt{unique\_ptr} construction
is the same as the type that is used in \texttt{new} expressions.

Here is an example showing how an explicitly defined deleter may be used to
delete a dynamically allocated array of pointers to strings:
        \begin{verbatim}
    #include <string>
    #include <memory>
    using namespace std;

    struct Deleter
    {
        size_t d_size;
        Deleter(size_t size = 0)
        :
            d_size(size)
        {}
        void operator()(string **ptr) const
        {
            for (size_t idx = 0; idx < d_size; ++idx)
                delete ptr[idx];
            delete[] ptr;
        }
    };
    int main()
    {
        unique_ptr<string *, Deleter> sp2{ new string *[10](),
                                           Deleter{ 10 } };

                                        // for illustration purposes:
                                        // retrieving the Deleter
        [[maybe_unused]] Deleter &obj = sp2.get_deleter();
    }
\end{verbatim}
A \texttt{unique\_ptr} can be used to reach the
 \index{unique\_ptr: reaching members} member functions that are available for
objects allocated by the \texttt{new} expression.  These members can be reached as
if the \texttt{unique\_ptr} was a plain pointer to the dynamically allocated
object. For example, in the following program the text `\texttt{C++}' is inserted
behind the word `\texttt{hello}':
        \begin{verbatim}
    #include <iostream>
    #include <memory>
    #include <cstring>
    using namespace std;

    int main()
    {
        unique_ptr<string> sp{ new string{ "Hello world" } };

        cout << *sp << '\n';
        sp->insert(strlen("Hello "), "C++ ");
        cout << *sp << '\n';
    }
    /*
        Displays:
            Hello world
            Hello C++ world
    */
\end{verbatim}
\subsection{Operators and members}\label{UNIQUEMEM}
    \typeout{Original Yodl file: stl/uniquemembers}The class \texttt{unique\_ptr} offers the  following
 \index{unique\_ptr: operators} operators:
    \begin{itemize}
    \item \index{operator=}\texttt{unique\_ptr$<$Type$>$ \&operator=(unique\_ptr$<$Type$>$ \&\&tmp)}:\ \\ This operator transfers the memory pointed to by the \index{rvalue}rvalue
        \texttt{unique\_ptr} object to the \index{lvalue}lvalue \texttt{unique\_ptr} object using
        \emph{move semantics}. So, the rvalue object \emph{loses} the memory it
        pointed at and turns into a 0-pointer. An existing \texttt{unique\_ptr} may
        be assigned to another \texttt{unique\_ptr} by converting it to an rvalue
        reference first using \texttt{std::move}. Example:
   \begin{verbatim}
unique_ptr<int> ip1(new int);
unique_ptr<int> ip2;

ip2 = std::move(ip1);
\end{verbatim}
\item \index{operator bool}\texttt{operator bool() const}:\ \\ This operator returns \texttt{false} if the \texttt{unique\_ptr} does not point
        to memory (i.e., its \texttt{get} member, see below, returns 0). Otherwise,
        \texttt{true} is returned.
    \item \index{operator*}\texttt{Type \&operator$*$()}:\ \\ This operator returns a reference to the information accessible via
        a \texttt{unique\_ptr} object . It acts like a normal pointer dereference
        operator.
    \item \index{operator-\textgreater{}}\texttt{Type $*$operator-$>$()}:\ \\ This operator returns a pointer to the information accessible via a
        \texttt{unique\_ptr} object. This operator allows you to select
        members of an object accessible via a \texttt{unique\_ptr} object. Example:
   \begin{verbatim}
unique_ptr<string> sp{ new string{ "hello" } };
cout << sp->c_str();
\end{verbatim}
\end{itemize}

The class \texttt{unique\_ptr} supports the following \index{member function}
member functions:
    \begin{itemize}
    \item \index{get}\texttt{Type $*$get()}:\ \\ A pointer to the information controlled by the \texttt{unique\_ptr} object
        is returned. It acts like \texttt{operator-$>$}. The returned pointer can be
        inspected. If it is zero the \texttt{unique\_ptr} object does not point to
        any memory.
    \item \index{get\_deleter}\texttt{Deleter \&unique\_ptr$<$Type$>$::get\_deleter()}:\ \\ A reference to the deleter object used by the \texttt{unique\_ptr} is
        returned.
    \item \index{release}\texttt{Type $*$release()}:\ \\ A pointer to the information accessible via a \texttt{unique\_ptr} object is
        returned. At the same time the object itself becomes a 0-pointer
        (i.e., its pointer data member is turned into a 0-pointer). This
        member can be used to transfer the information accessible via a
        \texttt{unique\_ptr} object to a plain \texttt{Type} pointer. After calling this
        member the proper destruction of the dynamically allocated memory
        is the \index{responsibility of the programmer}responsibility of the programmer.
    \item \index{reset}\texttt{void reset(Type $*$)}:\ \\ The dynamically allocated memory controlled by the \texttt{unique\_ptr}
        object is returned to the common pool; the object thereupon controls
        the memory  to which the argument that is passed to the function
        points. It can also be called without argument, turning the object
        into a 0-pointer. This member function can be used to assign a new
        block of dynamically allocated memory to a \texttt{unique\_ptr} object.
    \item \index{swap}\texttt{void swap(unique\_ptr$<$Type$>$ \&)}:\ \\ Two identically typed \texttt{unique\_ptrs} are swapped.
    \end{itemize}

\subsection{Using `unique\_ptr' objects for arrays}
    \typeout{Original Yodl file: stl/uniquearrays}When a \texttt{unique\_ptr} is used to store arrays the dereferencing operator makes
little sense but with arrays \texttt{unique\_ptr} objects benefit from index
operators. The distinction between a single object \texttt{unique\_ptr} and a
\texttt{unique\_ptr} referring to a dynamically allocated array of objects is
realized through a template specialization.

With dynamically allocated arrays the following syntax is available:
    \begin{itemize}
    \item  the index (\texttt{{[}{]}}) notation is used to specify that the smart
        pointer controls a dynamically allocated \emph{array}. Example:
            \begin{verbatim}
unique_ptr<int[]> intArr(new int[3]);
\end{verbatim}
\item  the index operator can be used to access the array's
        elements. Example:
            \begin{verbatim}
intArr[2] = intArr[0];
\end{verbatim}
\end{itemize}
    In these cases the smart pointer's destructors call
\texttt{delete{[}{]}} rather than \texttt{delete}.

\section{The class `shared\_ptr'}\label{SHAREDPTR}
\typeout{Original Yodl file: stl/sharedptr}In addition to the class \texttt{unique\_ptr} the class
\index{shared\_ptr}\texttt{std::shared\_ptr$<$Type$>$} is available, which is a reference
counting smart pointer.

Before using \texttt{shared\_ptrs} the \index{memory: header file}\texttt{$<$memory$>$} header file must be included.

The shared pointer automatically destroys its content once its reference
count has decayed to zero. As with \texttt{unique\_ptr}, when defining a
\texttt{shared\_ptr$<$Base$>$} to store a newly allocated \texttt{Derived} class object, the
returned \texttt{Base $*$} may be cast to a \texttt{Derived $*$} using a \texttt{static\_cast}:
polymorphism isn't required, and when resetting the \texttt{shared\_ptr} or when the
\texttt{shared\_ptr} goes out of scope, no slicing occurs, and \texttt{Derived}'s
destructor (or, if configured: deleter) is called (cf. section
\ref{UNIQUEPTR}).

\texttt{Shared\_ptrs} support copy and move constructors as well as standard and
move overloaded assignment operators.

Like \texttt{unique\_ptrs, shared\_ptrs} may refer to dynamically allocated arrays.

\subsection{Defining `shared\_ptr' objects}
    \typeout{Original Yodl file: stl/definingshared}There are four ways to \index{shared\_ptr: defining} define \texttt{shared\_ptr}
objects. Each definition contains the usual \texttt{$<$type$>$} specifier between
angle brackets:
    \begin{itemize}
    \item  The default constructor simply creates a \texttt{shared\_ptr} object that
does not point to a particular block of memory. Its pointer is initialized to
0 (zero):
        \begin{verbatim}
shared_ptr<type> identifier;
\end{verbatim}
This form is discussed in section \ref{SHAREDPLAIN}.

\item  The copy constructor initializes a \texttt{shared\_ptr} so that both
objects share the memory pointed at by the existing object. The copy
constructor also increments the \texttt{shared\_ptr}'s reference count. Example:
        \begin{verbatim}
shared_ptr<string> org{ new string{ "hi there" } };
shared_ptr<string> copy(org);   // reference count now 2
\end{verbatim}
\item  The move constructor initializes a \texttt{shared\_ptr} with the pointer
and reference count of a temporary \texttt{shared\_ptr}. The temporary
\texttt{shared\_ptr} is changed into a 0-pointer. An existing \texttt{shared\_ptr} may
have its data moved to a newly defined \texttt{shared\_ptr} (turning the existing
\texttt{shared\_ptr} into a 0-pointer as well). In the next example a temporary,
anonymous \texttt{shared\_ptr} object is constructed, which is then used to
construct \texttt{grabber}. Since \texttt{grabber}'s constructor receives an anonymous
temporary object, the compiler uses \texttt{shared\_ptr}'s move constructor:
        \begin{verbatim}
shared_ptr<string> grabber{ shared_ptr<string>{ new string{ "hi there" } } };
\end{verbatim}
\item  The form that is used most often initializes a \texttt{shared\_ptr} object
to the block of dynamically allocated memory that is passed to the object's
constructor. Optionally \index{deleter}\texttt{deleter} can be provided. A (free) function (or
function object) receiving the \texttt{shared\_ptr}'s pointer as its argument can be
passed as deleter. It is supposed to return the dynamically allocated
memory to the common pool (doing nothing if the pointer equals zero).
        \begin{verbatim}
shared_ptr<type> identifier (new-expression [, deleter]);
\end{verbatim}
This form is discussed in section \ref{SHAREDNEW}.
    \end{itemize}

\subsection{Creating a plain `shared\_ptr'}\label{SHAREDPLAIN}
    \typeout{Original Yodl file: stl/sharedplain}\texttt{Shared\_ptr}'s default constructor defines a \index{shared\_ptr: default}
\texttt{shared\_ptr} not pointing to a particular block of memory:
        \begin{verbatim}
    shared_ptr<type> identifier;
\end{verbatim}
The \index{shared\_ptr: 0-pointer} pointer controlled by the \texttt{shared\_ptr}
object is initialized to \texttt{0} (zero). Although the \texttt{shared\_ptr} object
itself is not the pointer, its value \emph{can} be compared to \texttt{0}. Example:
        \begin{verbatim}
    shared_ptr<int> ip;

    if (!ip)
        cout << "0-pointer with a shared_ptr object\n";
\end{verbatim}
Alternatively, the member \index{get}\texttt{get} can be used (cf. section \ref{SHAREDMEM}).

\subsection{Pointing to a newly allocated object}\label{SHAREDNEW}
    \typeout{Original Yodl file: stl/sharednew}Most often a \texttt{shared\_ptr} \index{shared\_ptr: initialization} is initialized by a
dynamically allocated block of memory. The generic form is:
        \begin{verbatim}
    shared_ptr<type> identifier(new-expression [, deleter]);
\end{verbatim}
The second argument (\texttt{deleter}) is optional and
 \index{deleter} refers to a function object or free function handling the
destruction of the allocated memory. A deleter is used, e.g., in situations
where a double pointer is allocated and the destruction must visit each nested
pointer to destroy the allocated memory (see below for an illustration).  It
is used in situations comparable to those encountered with \texttt{unique\_ptr}
(cf. section \ref{UNIQUENEW}).

Here is an example initializing a \texttt{shared\_ptr} pointing to a \texttt{string}
object:
        \begin{verbatim}
    shared_ptr<string> strPtr{ new string{ "Hello world" } };
\end{verbatim}
The argument that is passed to the constructor is the pointer returned by
\texttt{operator new}. Note that \texttt{type} does \emph{not} mention the pointer.  The
\index{shared\_ptr: used type} type that is used in the \texttt{shared\_ptr} construction
is the same as the type that is used in \texttt{new} expressions.

The next example illustrates that two \texttt{shared\_ptrs} indeed share their
information. After modifying the information controlled by one of the
objects the information controlled by the other object is modified as well:
        \begin{verbatim}
    #include <iostream>
    #include <memory>
    #include <cstring>
    using namespace std;

    int main()
    {
        shared_ptr<string> sp(new string{ "Hello world" });
        shared_ptr<string> sp2(sp);

        sp->insert(strlen("Hello "), "C++ ");
        cout << *sp << '\n' <<
                *sp2 << '\n';
    }
    /*
        Displays:
            Hello C++ world
            Hello C++ world
    */
\end{verbatim}
\subsection{Operators and members}\label{SHAREDMEM}
    \typeout{Original Yodl file: stl/sharedmembers}The class \texttt{shared\_ptr} offers the following \index{shared\_ptr: operators}
operators:
    \begin{itemize}
    \item \index{operator=}\texttt{shared\_ptr \&operator=(shared\_ptr$<$Type$>$ const \&other)}:\ \\ Copy assignment: the reference count of the operator's left hand side
        operand is reduced. If the reference count decays to zero the
        dynamically allocated memory controlled by the left hand side operand
        is deleted. Then it shares the information with the operator's
        right hand side operand, incrementing the information's reference
        count.
    \item \index{operator=}\texttt{shared\_ptr \&operator=(shared\_ptr$<$Type$>$ \&\&tmp)}:\ \\ Move assignment: the reference count of the operator's left hand side
        operand is reduced. If the reference count decays to zero the
        dynamically allocated memory controlled by the left hand side operand
        is deleted. Then it grabs the information controlled by the
        operator's right hand side operand which is turned into a 0-pointer.
    \item \index{operator bool}\texttt{operator bool() const}:\ \\ If the \texttt{shared\_ptr} actually points to memory \texttt{true} is returned,
        otherwise, \texttt{false} is returned.
    \item \index{operator*}\texttt{Type \&operator$*$()}:\ \\ A reference to the information stored in the
        \texttt{shared\_ptr} object is returned. It acts like a normal pointer.
    \item \index{operator-\textgreater{}}\texttt{Type $*$operator-$>$()}:\ \\ A pointer to the information controlled by the \texttt{shared\_ptr} object
        is returned. Example:
   \begin{verbatim}
shared_ptr<string> sp{ new string{ "hello" } };
cout << sp->c_str() << '\n';
\end{verbatim}
\end{itemize}

The following \index{member function}member function member functions are supported:
    \begin{itemize}
    \item \index{get}\texttt{Type $*$get()}:\ \\ A pointer to the information controlled by the \texttt{shared\_ptr} object
        is returned. It acts like \texttt{operator-$>$}. The returned pointer can be
        inspected. If it is zero the \texttt{shared\_ptr} object does not point to
        any memory.
    \item \index{get\_deleter}\texttt{Deleter \&get\_deleter()}:\ \\ A reference to the \texttt{shared\_ptr}'s deleter (function or function
        object) is returned.
    \item \index{reset}\texttt{void reset(Type $*$)}:\ \\ The reference count of the information controlled by the \texttt{shared\_ptr}
        object is reduced and if it decays to zero the memory it points to
        is deleted. Thereafter the
        object's information will refer to the argument that is passed to the
        function, setting its shared count to 1. It can also be called without
        argument, turning the object into a 0-pointer. This member function
        can be used to assign a new block of dynamically allocated memory to a
        \texttt{shared\_ptr} object.
    \item \index{reset}\texttt{void reset(Type $*$, DeleterType \&\&)}:\ \\ This variant of the previous member accepts a specific \texttt{Deleter}
        type: if \texttt{Type} is a base-class and derived class objects are used,
        these derived class objects may require specific actions at
        destruction time. When the previous member is used, then eventually the
        newly assigned object's destructor is called without using an
        explicit deleter function. The current member ensures that by the time
        the shared counter has decayed to zero the provided deleter is used.
      \item \index{swap}\texttt{void shared\_ptr$<$Type$>$::swap(shared\_ptr$<$Type$>$ \&\&)}:\ \\ Two identically typed \texttt{shared\_ptrs} are swapped.
    \item \index{unique}\texttt{bool unique() const}:\ \\ If the current object is the only object referring to the memory
        controlled by the object \texttt{true} is returned otherwise (including the
        situation where the object is a 0-pointer) \texttt{false} is returned.
    \item \index{use\_count}\texttt{size\_t use\_count() const}:\ \\ The number of objects sharing the memory controlled by the object is
        returned.
    \end{itemize}

\subsection{Casting shared pointers}\label{SHAREDCAST}
    \typeout{Original Yodl file: stl/sharedcasts}Be cautious when using standard \textbf{C++} style casts in combination with
\texttt{shared\_ptr} objects. Consider the following two classes:
        \begin{verbatim}
    struct Base
    {};
    struct Derived: public Base
    {};
\end{verbatim}
As with \texttt{unique\_ptr}, when defining a \texttt{shared\_ptr$<$Base$>$} to store a
newly allocated \texttt{Derived} class object, the returned \texttt{Base $*$} may be cast
to a \texttt{Derived $*$} using a \texttt{static\_cast}: polymorphism isn't required, and
when resetting the \texttt{shared\_ptr} or when the \texttt{shared\_ptr} goes out of
scope, no slicing occurs, and \texttt{Derived}'s destructor is called (cf. section
\ref{UNIQUEPTR}).

Of course, a \texttt{shared\_ptr$<$Derived$>$} can easily be defined. Since a
\texttt{Derived} object is also a \texttt{Base} object, a pointer to \texttt{Derived} can
be considered a pointer to \texttt{Base} without using casts, but a \texttt{static\_cast}
could be used to force the interpretation of a \texttt{Derived $*$} to a \texttt{Base $*$}:
        \begin{verbatim}
    Derived d;
    static_cast<Base *>(&d);
\end{verbatim}
However, a plain \texttt{static\_cast} cannot be used when initializing a shared
pointer to a \texttt{Base} using the \texttt{get} member of a shared pointer to a
\texttt{Derived} object. The following code snipped eventually results in an
attempt to delete the dynamically allocated \texttt{Base} object twice:
        \begin{verbatim}
    shared_ptr<Derived> sd{ new Derived };
    shared_ptr<Base> sb{ static_cast<Base *>(sd.get()) };
\end{verbatim}
Since \texttt{sd} and \texttt{sb} point at the same object \texttt{\textasciitilde{}Base} will be called
for the same object when \texttt{sb} goes out of scope and when \texttt{sd} goes out of
scope, resulting in premature termination of the program due to a
 \index{double free}\emph{double free} error.

These errors can be prevented using casts that were specifically designed
for being used with \texttt{shared\_ptrs}. These casts use specialized constructors
that create a \texttt{shared\_ptr} pointing to memory but shares ownership (i.e.,
a reference count) with an existing \texttt{shared\_ptr}. These special casts are:
    \begin{itemize}
    \item \index{static\_pointer\_cast}\texttt{std::static\_pointer\_cast$<$Base$>$(std::shared\_ptr$<$Derived$>$ ptr)}:\ \\ A \texttt{shared\_ptr} to a \texttt{Base} class object is returned. The returned
\texttt{shared\_ptr} refers to the base class portion of the \texttt{Derived} class to
which the \texttt{shared\_ptr$<$Derived$>$ ptr} refers. Example:
        \begin{verbatim}
shared_ptr<Derived> dp{ new Derived };
shared_ptr<Base> bp = static_pointer_cast<Base>(dp);
\end{verbatim}
\item \index{const\_pointer\_cast}\texttt{std::const\_pointer\_cast$<$Class$>$(std::shared\_ptr$<$Class const$>$ ptr)}:\ \\ A \texttt{shared\_ptr} to a \texttt{Class} class object is returned. The
returned \texttt{shared\_ptr} refers to a non-const \texttt{Class} object whereas the
\texttt{ptr} argument refers to a \texttt{Class const} object. Example:
        \begin{verbatim}
shared_ptr<Derived const> cp{ new Derived };
shared_ptr<Derived> ncp = const_pointer_cast<Derived>(cp);
\end{verbatim}
\item \index{dynamic\_pointer\_cast}\texttt{std::dynamic\_pointer\_cast$<$Derived$>$(std::shared\_ptr$<$Base$>$ ptr)}:\ \\ A \texttt{shared\_ptr} to a \texttt{Derived} class object is returned. The
\texttt{Base} class must have at least one virtual member function, and the class
\texttt{Derived}, inheriting from \texttt{Base} may have overridden \texttt{Base}'s virtual
member(s). The returned \texttt{shared\_ptr} refers to a \texttt{Derived} class object if
the dynamic cast from \texttt{Base $*$} to \texttt{Derived $*$} succeeded. If the dynamic
cast did not succeed the \texttt{shared\_ptr}'s \texttt{get} member returns 0.  Example
(assume \texttt{Derived} and \texttt{Derived2} were derived from \texttt{Base}):
        \begin{verbatim}
shared_ptr<Base> bp(new Derived());
cout << dynamic_pointer_cast<Derived>(bp).get() << ' ' <<
        dynamic_pointer_cast<Derived2>(bp).get() << '\n';
\end{verbatim}
The first \texttt{get} returns a non-0 pointer value, the second \texttt{get}
returns 0.

\end{itemize}

\subsection{Using `shared\_ptr' objects for arrays}\label{SHAREDARRAY}
    \typeout{Original Yodl file: stl/sharedarrays}The \texttt{shared\_ptr} class can also be used to handle dynamically allocated
arrays of objects. To use it on arrays simply use the square brackets when
specifying the \texttt{shared\_ptr's} type. Here is an example:
    \begin{verbatim}
    struct Type
    {
        ~Type()
        {
            cout << "destr\n";  // show the object's destruction
        }
    };

    int main()
    {
        shared_ptr<Type[]> sp{ new Type[3] };
        sp[0] = sp[1];
    }
\end{verbatim}
When the \texttt{shared\_ptr} itself is initialized with an array of pointers, then
a \emph{deleter} must be used to delete the memory the pointers point at. In that
case the deleter is responsible for returning the memory to the common pool,
using \texttt{delete{[}{]}} when eventually deleting the array of pointers:
    \begin{verbatim}
    struct Type
    {
        int value = 0;

        ~Type()
        {
            cout << "destr " << this << '\n';
        }
    };

    template<typename Tp>
    struct Deleter
    {
        size_t d_size;
        Deleter(size_t size)
        :
            d_size(size)
        {}
        void operator()(Tp **ptr)
        {
            for (; d_size--; )
                delete ptr[d_size];

            delete[] ptr;           // <-- NOTE !
        }
    };

    int main()
    {
        shared_ptr<Type *[]> sp{ new Type *[2] {new Type, new Type},
                                 Deleter<Type>{ 2 } };
    }
\end{verbatim}
\section{Smart `smart pointer' construction: `make\_shared' and `make\_unique'}
\typeout{Original Yodl file: stl/makeshared}Usually a \texttt{shared\_ptr} is initialized at definition time
with a pointer to a newly allocated object. Here is an example:
        \begin{verbatim}
    std::shared_ptr<string> sptr{ new std::string{ "hello world" } }
\end{verbatim}
In such statements \emph{two} memory allocation calls are used: one for the
allocation of the \texttt{std::string} and one used interally by
\texttt{std::shared\_ptr}'s constructor itself.

The two allocations can be combined into one single allocation (which is
also slightly more efficient than explicitly calling \texttt{shared\_ptr}'s
constructor) using the \index{make\_shared}\texttt{make\_shared} template. The function template
\texttt{std::make\_shared} has the following prototype:
        \begin{verbatim}
    template<typename Type, typename ...Args>
    std::shared_ptr<Type> std::make_shared(Args ...args);
\end{verbatim}
Before using \texttt{make\_shared} the \index{memory: header file}\texttt{$<$memory$>$} header file must be included.

This function template allocates an object of type \texttt{Type}, passing
\texttt{args} to its constructor (using \emph{perfect forwarding}, see section
\ref{PERFECT}), and returns a \texttt{shared\_ptr} initialized with the address of
the newly allocated \texttt{Type} object.

Here is how the above \texttt{sptr} object can be initialized
using \texttt{std::make\_shared}. Notice the use of \texttt{auto} which frees us from
having to specify \texttt{sptr}'s type explicitly:
        \begin{verbatim}
    auto sptr(std::make_shared<std::string>("hello world"));
\end{verbatim}
After this initialization \texttt{std::shared\_ptr$<$std::string$>$ sptr} has been
defined and initialized. It could be used as follows:
        \begin{verbatim}
    std::cout << *sptr << '\n';
\end{verbatim}
In addition to \texttt{make\_shared} the function
    \index{make\_unique}\texttt{std::make\_unique} can be used. It can be used
\texttt{make\_shared} but returns a \texttt{std::unique\_ptr} rather than a
\texttt{shared\_ptr}.

\section{Classes having pointer data members}
\typeout{Original Yodl file: stl/classeshavingpointers}Classes having \index{class: having pointers} pointer data members require special
attention. In particular at construction time one must be careful to prevent
 \index{pointer: wild} wild pointers and/or \index{memory leak} memory leaks. Consider
the following class defining two pointer data members:
        \begin{verbatim}
    class Filter
    {
        istream *d_in;
        ostream *d_out;
        public:
            Filter(char const *in, char const *out);
    };
\end{verbatim}
Assume that \texttt{Filter} objects filter information read from \texttt{$*$d\_in} and
write the filtered information to \texttt{$*$d\_out}.  Using pointers to streams
allows us to have them point at any kind of stream like \texttt{istreams,
ifstreams, fstreams} or \texttt{istringstreams}.  The shown constructor could be
implemented like this:
        \begin{verbatim}
    Filter::Filter(char const *in, char const *out)
    :
        d_in(new ifstream{ in }),
        d_out(new ofstream{ out })
    {
        if (!*d_in || !*d_out)
            throw "Input and/or output stream not available"s;
    }
\end{verbatim}
Of course, the construction could fail. \texttt{new} could throw an exception;
the stream constructors could throw exceptions; or the streams could not be
opened in which case an exception is thrown from the constructor's body. Using
a function try block helps. Note that if \texttt{d\_in}'s initialization throws,
there's nothing to be worried about. The \texttt{Filter} object hasn't been
constructed, its destructor is not called and processing continues at the
point where the thrown exception is caught. But \texttt{Filter}'s destructor is
also not called when \texttt{d\_out}'s initialization or the constructor's \texttt{if}
statement throws: no object, and hence no destructor is called. This may
result in memory leaks, as \texttt{delete} isn't called for \texttt{d\_in} and/or
\texttt{d\_out}. To prevent this, \texttt{d\_in} and \texttt{d\_out} must first be initialized
to 0 and only then the initialization can be performed:
        \begin{verbatim}
    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(0),
        d_out(0)
    {
        d_in = new ifstream{ in };
        d_out = new ofstream{ out };

        if (!*d_in || !*d_out)
            throw "Input and/or output stream not available"s;
    }
    catch (...)
    {
        delete d_out;
        delete d_in;
    }
\end{verbatim}
This quickly gets complicated, though. If \texttt{Filter} harbors yet another
data member of a class whose constructor needs two streams then that data
cannot be constructed or it must itself be converted into a pointer:
        \begin{verbatim}
    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(0),
        d_out(0)
        d_filterImp(*d_in, *d_out)    // won't work
    { ... }

    // instead:

    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(0),
        d_out(0),
        d_filterImp(0)
    {
        d_in = new ifstream(in);
        d_out = new ofstream(out);
        d_filterImp = new FilterImp(*d_in, *d_out);
        ...
    }
    catch (...)
    {
        delete d_filterImp;
        delete d_out;
        delete d_in;
    }
\end{verbatim}
Although the latter alternative works, it quickly gets hairy. In
situations like these smart pointers should be used to prevent the
hairiness. By defining the stream pointers as (smart pointer) objects they
will, once constructed, properly be destroyed even if the rest of the
constructor's code throws exceptions. Using a \texttt{FilterImp} and two
\texttt{unique\_ptr} data members \texttt{Filter}'s setup and its constructor becomes:
        \begin{verbatim}
    class Filter
    {
        std::unique_ptr<std::ifstream> d_in;
        std::unique_ptr<std::ofstream> d_out;
        FilterImp d_filterImp;
        ...
    };

    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(new ifstream(in)),
        d_out(new ofstream(out)),
        d_filterImp(*d_in, *d_out)
    {
        if (!*d_in || !*d_out)
            throw "Input and/or output stream not available"s;
    }
\end{verbatim}
We're back at the original implementation but this time without having to
worry about wild pointers and memory leaks. If one of the member initializers
throws the destructors of previously constructed data members (which are now
objects) are always called.

As a \index{rule of thumb}rule of thumb: when classes need to define pointer data members
they should define those pointer data members as smart pointers if there's any
chance that their constructors throw exceptions.

\section{Comparison classes}\label{COMPARISONS}
\typeout{Original Yodl file: stl/comparisons}With the introduction of the \emph{spaceship operator} (\texttt{$<$=$>$}, cf. section
\ref{SPACESHIP}) several \emph{comparison category classes} 
    \index{comparison classes} were added to the standard namespace.

Comparison classes are required when implementing the spaceship operator, and
to use them (or when declaring and implementing the spachip operator) the
\index{compare: header file}\texttt{$<$compare$>$} header file must be included.

The weak class types do not support \index{substitutability}\emph{substitutability}. Substitutability
means that if two objects \texttt{one} and \texttt{two} are equal (so: \texttt{one == two} is
\texttt{true}), then \texttt{fun(one) == fun(two)} is also \texttt{true}. Here \texttt{fun} is any
function that only uses public const members of its argument that return
\emph{value types} (as compared to pointer types) which also support comparisons
(also called \index{comparison-salient state}\emph{comparison-salient state}).

The operators of comparison classes expect at least one argument of their own
class types. The other argument may either also be of their own class types or
it can be the value 0 (or any value that can be considered 0, like
\texttt{nullptr\_t}).

There are five comparison classes, primarily used when implementing
spaceship operators:
    \begin{itemize}
    \item \texttt{weak\_equality}, used for classes that only support the \texttt{==} and
        \texttt{!=} operators, but not substitutability;
    \item \texttt{strong\_equality}, used for classes that only support the \texttt{==} and
        \texttt{!=} operators, as well as substitutability;
    \item \texttt{partial\_ordering} used for classes that support all comparison
        operators, do not support substitutability, and can be used when
        comparing incomparable arguments (i.e., all comparison operators
        return false);
    \item \texttt{weak\_ordering} used for classes that support all comparison
        operators and that do not support substitutability;
    \item \texttt{strong\_ordering} used for classes that support all comparison
        operators as well as substitutability;
    \end{itemize}

\subsection{The class `weak\_equality'}
    \typeout{Original Yodl file: stl/weakequal}The class \texttt{std::weak\_equality}\index{weak\_equality} is used when implementing
the spaceship operator for classes that only support (in)equality comparisons,
but not substitutability. The class provides free functions 
\texttt{operator==} and \texttt{operator!=} expecting \texttt{weak\_equality} arguments (one
argument may be 0) and it defines two static objects:
    \begin{itemize}
    \item \texttt{weak\_equality::equivalent}, indicating equality;
    \item \texttt{weak\_equality::nonequivalent}, indicating non-equality;
    \end{itemize}

Note: at the current release of the Gnu \textbf{C++} compiler (10.0.0) this class
is not yet available in the \index{compare: header file}\texttt{$<$compare$>$} header file.

\subsection{The class `strong\_equality'}
    \typeout{Original Yodl file: stl/strongequal}The class \texttt{std::strong\_equality}\index{strong\_equality} is used when implementing
the spaceship operator for classes that only support (in)equality comparisons
as well as substitutability. The class provides free functions 
\texttt{operator==} and \texttt{operator!=} expecting \texttt{strong\_equality} arguments (one
argument may be 0) and it defines four static objects:
    \begin{itemize}
    \item \texttt{strong\_equality::equal}, indicating equality;
    \item \texttt{strong\_equality::equivalent}, indicating equality;
    \item \texttt{strong\_equality::nonequal}, indicating non-equality;
    \item \texttt{strong\_equality::nonequivalent}, indicating non-equality;
    \end{itemize}

Note: at the current release of the Gnu \textbf{C++} compiler (10.0.0) this class
is not yet available in the \index{compare: header file}\texttt{$<$compare$>$} header file.

\subsection{The class `partial\_ordering'}\label{PARTORD}
    \typeout{Original Yodl file: stl/partialorder}The class \texttt{std::partial\_ordering}\index{partial\_ordering} is used when
implementing the spaceship operator for classes that support all comparison
operators (where one operand may be zero), that do not support
substitutability, and whose objects, using the spaceship operator itself, can
also be compared to any other type of object.

The class \texttt{partial\_ordering} provides free functions for all comparison
operations (\texttt{==, !=, $<$, $<$=, $>$,} and \texttt{$>$=}) expecting \texttt{partial\_ordering}
arguments (one argument may be 0). It also defines four static objects which
can be returned by the spaceship operator:
    \begin{itemize}
    \item \texttt{partial\_ordering::less}, returned when the lhs operand of the
        spaceship operator should be ordered before the rhs operand;
    \item \texttt{partial\_ordering::equivalent}, indicating equality: there is no
        ordering preference between the two operands of the spaceship operator;
    \item \texttt{partial\_ordering::greater}, returned when the lhs operand of the
        spaceship operator should be ordered after the rhs operand;
    \item \texttt{partial\_ordering::unordered}, returned when all comparison operators
        of a class implementing the spaceship operator should return \texttt{false}
        (so \texttt{==, !=, $<$, $<$=, $>$,} and \texttt{$>$=} all return \texttt{false}).
    \end{itemize}

As an example, consider road taxes. Trucks, cars, and motor cycles have to pay
road taxes, but there's no road tax for bicycles. For ordering road taxes a
class \texttt{RoadTax} may be used, defining the following spaceship operator
(assuming that all types of vehicles are derived from a class \texttt{Vehicle}, and
that \texttt{Vehicle} has a (virtual) member \texttt{double roadTax()} returning the
amount of road tax that is due for the various types of vehicles; the amount
is negative if no road tax is required):
    \begin{verbatim}
    partial_ordering RoadTax::operator<=>(Vehicle const &lhs, 
                                          Vehicle const &rhs)
    {
        return
          lhs.roadTax() < 0 or rhs.roadTax() < 0 ?
                                          partial_ordering::unordered :
          lhs.roadTax() < rhs.roadTax() ? partial_ordering::less      :
          lhs.roadTax() > rhs.roadTax() ? partial_ordering::greater   :
                                          partial_ordering::equivalent;
    }
\end{verbatim}
\subsection{The class `weak\_ordering'}
    \typeout{Original Yodl file: stl/weakorder}The class \texttt{std::weak\_ordering}\index{weak\_ordering} is used when
implementing the spaceship operator for classes that support all comparison
operators (where one operand may be zero), and that do not support
substitutability.

The class \texttt{weak\_ordering} differs from the \texttt{partial\_ordering} class in
that \emph{unordered} cannot be used as a comparison result. Like the class
\texttt{partial\_ordering} it provides free functions for all comparison
operations (\texttt{==, !=, $<$, $<$=, $>$,} and \texttt{$>$=}) expecting \texttt{partial\_ordering}
arguments (one argument may be 0). It also defines three static objects which
can be returned by the spaceship operator:
    \begin{itemize}
    \item \texttt{weak\_ordering::less}, returned when the lhs operand of the
        spaceship operator should be ordered before the rhs operand;
    \item \texttt{weak\_ordering::equal}, indicating equality: there is no
        ordering preference between the two operands of the spaceship operator;
    \item \texttt{weak\_ordering::greater}, returned when the lhs operand of the
        spaceship operator should be ordered after the rhs operand;
    \end{itemize}

The example in the previous section can easily adapted to the
\texttt{weak\_ordering} comparison class: if the \texttt{roadTax} members of vehicles for
which no road tax is due return zero then \texttt{RoadTax's} spaceship operator can
be implemented this way:
    \begin{verbatim}
    weak_ordering RoadTax::operator<=>(Vehicle const &lhs, 
                                          Vehicle const &rhs)
    {
        return
          lhs.roadTax() < rhs.roadTax() ? weak_ordering::less      :
          lhs.roadTax() > rhs.roadTax() ? weak_ordering::greater   :
                                          weak_ordering::equal;
    }
\end{verbatim}
\subsection{The class `strong\_ordering'}
    \typeout{Original Yodl file: stl/strongorder}The class \texttt{std::strong\_ordering}\index{strong\_ordering} is used when
implementing the spaceship operator for classes that support all comparison
operators (where one operand may be zero), as well as substitutability.

The class \texttt{strong\_ordering} provides free functions for all comparison
operations (\texttt{==, !=, $<$, $<$=, $>$,} and \texttt{$>$=}) expecting \texttt{partial\_ordering}
arguments (one argument may be 0). It also defines three static objects which
can be returned by the spaceship operator:
    \begin{itemize}
    \item \texttt{strong\_ordering::less}, returned when the lhs operand of the
        spaceship operator should be ordered before the rhs operand;
    \item \texttt{strong\_ordering::equal}, indicating equality: there is no
        ordering preference between the two operands of the spaceship operator;
    \item \texttt{strong\_ordering::greater}, returned when the lhs operand of the
        spaceship operator should be ordered after the rhs operand;
    \end{itemize}

An example where the class \texttt{strong\_ordering} was used has already been
provided in section \ref{SPACESHIP}, where the spaceship operator itself was
introduced.

\section{Regular Expressions}
\typeout{Original Yodl file: stl/regularexp}\textbf{C++} itself provides facilities for handling regular expressions. Regular
expressions were already available in \textbf{C++} via its \textbf{C} heritage (as \textbf{C}
has always offered functions like \index{regcomp}\texttt{regcomp} and \index{regexec}\texttt{regexec}), but the
dedicated regular expression facilities have a richer interface than the
traditional \textbf{C} facilities, and can be used in code using templates.

Before using the specific \textbf{C++} implementations of regular expressions the
header file \index{regex: header file}\texttt{$<$regex$>$} must be included.

Regular expressions are extensively documented elsewhere (e.g., \textbf{regex}(7),
\index{Friedl, J.E.F}Friedl, J.E.F
  \texttt{Mastering Regular Expressions}\footnote{http://oreilly.com/catalog/}, O'Reilly).
    The reader is referred to these sources for a refresher on the topic of
regular expressions. In essence, regular expressions define a small
meta-language recognizing textual units (like `numbers', `identifiers', etc.).
They are extensively used in the context of \emph{lexical scanners} (cf. section
\ref{Flexcpp}) when defining the sequence of input characters associated with
\emph{tokens}. But they are also intensively used in other situations.  Programs
like \textbf{sed}(1) and \textbf{grep}(1) use regular expressions to find pieces of text
in files having certain characteristics, and a program like \textbf{perl}(1) adds
some `sugar' to the regular expression language, simplifying the construction
of regular expressions. However, though extremely useful, it is also well
known that regular expressions tend to be very hard to read. Some even call
the regular expression language a \emph{write-only language}: while specifying a
regular expression it's often clear why it's written in a particular way. But
the opposite, understanding what a regular expression is supposed to represent
if you lack the proper context, can be extremely difficult. That's why, from
the onset and as a \index{rule of thumb}\emph{rule of thumb}, it is stressed that an appropriate
comment should be provided, with \emph{each} regular expression, as to what it is
supposed to match.

In the upcoming sections first a short overview of the regular expression
language is provided, which is then followed by the facilities \textbf{C++} is
currently offering for using regular expressions. These facilities mainly
consist of classes helping you to specify regular expression, matching them to
text, and determining which parts of the text (if any) match (parts of) the
text being analyzed.

\subsection{The regular expression mini language}
    \typeout{Original Yodl file: stl/regexlanguage}Regular expressions are expressions consisting of elements resembling those of
numeric expressions. Regular expressions consist of basic elements and
operators, having various priorities and associations. Like numeric
expressions, parentheses can be used to group elements together to form a
unit on which operators operate. For an extensive discussion the reader is
referred to, e.g., section 15.10 of the \texttt{ecma-international.org}\footnote{http://ecma-international.org/ecma-262/5.1/\#sec-15.10} page, which
describes the characteristics of the regular expressions used by default by
\textbf{C++}'s \texttt{regex} classes.

\textbf{C++}'s default definition of regular expressions distinguishes the
following \emph{atoms}:
    \begin{itemize}
    \item \texttt{x}: the character `x';

\item \texttt{.}: any character except for the newline character;

\item \texttt{{[}xyz{]}}: a character class; in this case, either an `x', a `y', or a `z'
        matches the regular expression.  See also the paragraph about
        character classes below;

\item \texttt{{[}abj-oZ{]}}: a character class containing a range of characters; this
        regular expression matches an `a', a `b', any letter from `j' through
        `o', or a `Z'.  See also the paragraph about character classes below;

\item \texttt{{[}\textasciicircum{}A-Z{]}}: a negated character class: this regular expression matches
        any character but those in the class beyond \texttt{\textasciicircum{}}.  In this case, any
        character \emph{except for} an uppercase letter.  See also the paragraph
        about character classes below;

\item \texttt{{[}:predef:{]}}: a \emph{predefined} set of characters. See below for an
        overview. When used, it is interpreted as an element in a character
        class. It is therefore always embedded in a set of square brackets
        defining the character class (e.g., \texttt{{[}{[}:alnum:{]}{]}});

\item \texttt{\textbackslash{}X}: if X is `a', `b', `f', `n', `r', `t', or `v', then the ANSI-C
        interpretation of `\textbackslash{}x'. Otherwise, a literal `X' (used to escape
        operators such as \texttt{$*$});

\item \texttt{(r)}: the regular expression \texttt{r}. It is used to override precedence
        (see below), but also to define \texttt{r} as a
       \index{marked sub-expression}\emph{marked sub-expression} whose matching characters may directly be
        retrieved from, e.g., a \texttt{std::smatch} object (cf. section
        \ref{SMATCH});

\item \texttt{(?:r)}: the regular expression \texttt{r}. It is used to override
        precedence (see below), but it is \emph{not} regarded as a \emph{marked
        sub-expression};
    \end{itemize}

In addition to these basic atoms, the following special atoms are available
(which can also be used in character classes):
    \begin{itemize}
    \item \texttt{\textbackslash{}s}: a whitespace character;

\item \texttt{\textbackslash{}S}: any character but a whitespace character;

\item \texttt{\textbackslash{}d}: a decimal digit character;

\item \texttt{\textbackslash{}D}: any character but a decimal digit character;

\item \texttt{\textbackslash{}w}: an alphanumeric character or an underscore (\texttt{\_}) character;

\item \texttt{\textbackslash{}W}: any character but an alphanumeric character or an underscore
        (\texttt{\_}) character.
    \end{itemize}

Atoms may be concatenated. If \texttt{r} and \texttt{s} are atoms then the regular
expression \texttt{rs} matches a target text if the target text matches \texttt{r}
\emph{and} \texttt{s}, in that order (without any intermediate characters 
inside the target text). E.g., the regular expression \texttt{{[}ab{]}{[}cd{]}} matches the
target text \texttt{ac}, but not the target text \texttt{a:c}. 

Atoms may be combined using operators. Operators bind to the preceding
atom. If an operator should operate on multiple atoms the atoms must be
surrounded by parentheses (as in \texttt{(r)} used above: if \texttt{r} is \texttt{one}, then
use \texttt{(one)} when applying the operator to the word \texttt{one}, instead of just
the final \texttt{e}).  To use an operator character as an atom it can be
escaped. Eg., \texttt{$*$} represents an operator, \texttt{\textbackslash{}$*$} the atom character
star. Note that character classes do not recognize escape sequences: \texttt{{[}\textbackslash{}$*${]}}
represents a character class consisting of two characters: a backslash and a
star.

The following operators are supported (\texttt{r} and \texttt{s} represent regular
expression atoms):
    \begin{itemize}
    \item \texttt{r$*$}: zero or more \texttt{r}s;

\item \texttt{r+}: one or more \texttt{r}s;

\item \texttt{r?}: zero or one \texttt{r}s (that is, an optional r);

\item \texttt{r\{m, n\}}: where \texttt{1 $<$= m $<$= n}: matches `r' at least m, but at most n
        times;

\item \texttt{r\{m,\}}: where \texttt{1 $<$= m}: matches `r' at least m times;

\item \texttt{r\{m\}}: where \texttt{1 $<$= m}: matches `r' exactly m times;

\item \texttt{r\textbar{}s}: matches either an `r' or an `s'. This operator has a lower
        priority than any of the multiplication operators;

\item \texttt{\textasciicircum{}r} : \texttt{\textasciicircum{}} is a pseudo operator. This expression matches `r', if
        appearing at the beginning of the target text. If the \texttt{\textasciicircum{}}-character
        is not the first character of a regular expression it is interpreted
        as a literal \texttt{\textasciicircum{}}-character;

\item \texttt{r\$}: \texttt{\$} is a pseudo operator. This expression matches `r', if
        appearing at the end of the target text. If the \texttt{\$}-character is not
        the last character of a regular expression it is interpreted as a
        literal \texttt{\$}-character;
    \end{itemize}

When a regular expression contains marked sub-expressions and multipliers, and
the marked sub-expressions are multiply matched, then the target's final
sub-string matching the marked sub-expression is reported as the text matching
the marked sub-expression. E.g, when using \texttt{regex\_search} (cf. section
\ref{REGSRCH}), marked sub-expression (\texttt{((a\textbar{}b)+\textbackslash{}s?)}), and target text \texttt{a a
b}, then \texttt{a a b} is the fully matched text, while \texttt{b} is reported as the
sub-string matching the first and second marked sub-expressions.

\subsubsection{Character classes}
        \typeout{Original Yodl file: stl/charclass}Inside a character class all regular expression operators lose their special
meanings, except for the special atoms \texttt{\textbackslash{}s, \textbackslash{}S, \textbackslash{}d, \textbackslash{}D, \textbackslash{}w,} and \texttt{\textbackslash{}W}; the
character range operator \texttt{-}; the end of character class operator \texttt{{]}};
and, at the beginning of the character class, \texttt{\textasciicircum{}}. Except in combination
with the special atoms the escape character is interpreted as a literal
backslash character (to define a character class containing a backslash and a
\texttt{d} simply use \texttt{{[}d\textbackslash{}{]}}).

To add a closing bracket to a character class use \texttt{{[}{]}} immediately following
the initial open-bracket, or start with \texttt{{[}\textasciicircum{}{]}} for a negated character class
not containing the closing bracket.  Minus characters are used to define
character ranges (e.g., \texttt{{[}a-d{]}}, defining \texttt{{[}abcd{]}}) (be advised that the
actual range may depend on the locale being used). To add a literal minus
character to a character class put it at the very beginning (\texttt{{[}-}, or
\texttt{{[}\textasciicircum{}-}) or at the very end (\texttt{-{]}}) of a character class.

Once a character class has started, all subsequent characters are added to the
class's set of characters, until the final closing bracket (\texttt{{]}}) has been
reached.

In addition to characters and ranges of characters, character classes may also
contain \emph{predefined sets of character}. They are:
    \begin{verbatim}
         [:alnum:] [:alpha:] [:blank:]
         [:cntrl:] [:digit:] [:graph:]
         [:lower:] [:print:] [:punct:]
         [:space:] [:upper:] [:xdigit:]
\end{verbatim}
These predefined sets designate sets of characters equivalent to the
corresponding standard \textbf{C} \texttt{isXXX} function. For example, \texttt{{[}:alnum:{]}}
defines all  characters for which \textbf{isalnum}(3) returns true.

\subsection{Defining regular expressions: std::regex}
    \typeout{Original Yodl file: stl/regex}Before using the \texttt{(w)regex} class presented in this section the
\index{regex: header file}\texttt{$<$regex$>$} header file must be included.

The types \texttt{std::regex}\index{regex} and \texttt{std::wregex}\index{wregex} define regular
expression patterns. They define, respectively the types
\texttt{basic\_regex$<$char$>$}\index{basic\_regex} and \texttt{basic\_regex$<$wchar\_t$>$}
types. Below, the class \texttt{regex} is used, but in the examples \texttt{wregex}
could also have been used.

Regular expression facilities were, to a large extent, implemented through
templates, using, e.g., the \texttt{basic\_string$<$char$>$} type (which is equal to
\texttt{std::string}). Likewise, generic types like \emph{OutputIter} (output
iterator) and \emph{BidirConstIter} (bidirectional const iterator) are used with
several functions. Such functions are function templates. Function templates
determine the actual types from the arguments that are provided at
\emph{call-time}.

These are the steps that are commonly taken when using regular expressions:
    \begin{itemize}
    \item  First, a regular expression is defined. This involves
        defining or modifying a \texttt{regex} object.
    \item  Then the regular expression is provided with a \emph{target text}, which
        may result in sections of the target text matching the regular
        expression. 
    \item  The sections of the target text matching (or not matching) the
        regular expression are retrieved to be processed elsewhere, or:
    \item  The sections of the target text matching (or not matching) the
        regular expression are directly modified by existing regular
        expression facilities, after which the modified target text may be
        processed elsewhere.
    \end{itemize}

The way \texttt{regex} objects handle regular expressions can be configured using a
\texttt{bit\_or} combined set of \texttt{std::regex\_constants}\index{regex\_constants} values,
defining a \texttt{regex::flag\_type}\index{flag\_type} value. These
\texttt{regex\_constants} are:
    \begin{itemize}
    \item \texttt{std::regex\_constants::awk}:\ \\ \textbf{awk}(1)'s (POSIX) regular expression grammar is used to specify
        regular exressions (e.g., regular expressions are delimited by
        \texttt{/}-characters, like \texttt{/\textbackslash{}w+/}; for further details and for details
        of other regular expression grammars the reader should consult the
        man-pages of the respective programs);

\item \texttt{std::regex\_constants::basic}:\ \\ the basic POSIX regular expression grammar is used to specify regular
        expressions; 

\item \texttt{std::regex\_constants::collate}:\ \\ the character range operator (\texttt{-}) used in character classes defines
        a locale sensitive range (e.g., \texttt{{[}a-k{]}});

\item \index{ECMAScript}\texttt{std::regex\_constants::ECMAScript}:\ \\ this \texttt{flag\_type} is used by default by \texttt{regex}
        constructors. The regular expression uses the Modified \index{ECMAScript}ECMAScript
        regular expression grammar;

\item \texttt{std::regex\_constants::egrep}:\ \\ \textbf{egrep}(1)'s (POSIX) regular expression grammar is used to specify
        regular expressions. This is the same grammar as used by
        \texttt{regex\_constants::extended}, with the addition of the newline
        character (\texttt{'\textbackslash{}n'}) as an alternative for the \texttt{'\textbar{}'}-operator;

\item \texttt{std::regex\_constants::extended}:\ \\ the extended POSIX regular expression grammar is used to specify
        regular expressions;

\item \texttt{std::regex\_constants::grep}:\ \\ \textbf{grep}(1)'s (POSIX) regular expression grammar is used to specify
        regular expressions. This is the same grammar as used by
        \texttt{regex\_constants::basic}, with the addition of the newline character
        (\texttt{'\textbackslash{}n'}) as an alternative for the \texttt{'\textbar{}'}-operator;

\item \index{icase}\texttt{std::regex\_constants::icase}:\ \\ letter casing in the target string is ignored. E.g., the regular
        expression \texttt{A} matches \texttt{a} and \texttt{A};  

\item \texttt{std::regex\_constants::nosubs}:\ \\ When performing matches, all sub-expressions (\texttt{(expr)}) are
        treated as non-marked (\texttt{?:expr});

\item \texttt{std::regex\_constants::optimize}:\ \\ optimizes the speed of matching regular expressions, at the cost of
        slowing down the construction of the regular expression somewhat. If
        the same regular expression object is frequently used then this flag
        may substantially improve the speed of matching target texts;
    \end{itemize}

\textbf{Constructors}

The default, move and copy constructors are available. Actually, the
default constructor defines one parameter of type \texttt{regex::flag\_type}, for
which the value \texttt{regex\_constants::ECMAScript} is used by default.
    \begin{itemize}
    \item \texttt{regex()}:\ \\ the default constructor defines a \texttt{regex} object not containing a
        regular expression;

\item \texttt{explicit regex(char const $*$pattern)}:\ \\ defines a \texttt{regex} object containing the regular expression found at
        \texttt{pattern};

\item \texttt{regex(char const $*$pattern, std::size\_t count)}:\ \\ defines a \texttt{regex} object containing the regular expression found at
        the first \texttt{count} characters of \texttt{pattern};

\item \texttt{explicit regex(std::string const \&pattern)}:\ \\ defines a \texttt{regex} object containing the regular expression found at
        \texttt{pattern}. This constructor is defined as a member template,
        accepting a \texttt{basic\_string}-type argument which may also use
        non-standard character traits and allocators;

\item \texttt{regex(ForwardIterator first, ForwardIterator last)}:\ \\ defines a \texttt{regex} object containing the regular expression found at
        the (forward) iterator range \texttt{[first, last)}. This constructor is
        defined as a member template, accepting any forward iterator type
        (e.g., plain \texttt{char} pointers) which can be used to define the
        regular expression's pattern;

\item \texttt{regex(std::initializer\_list$<$Char$>$ init)}:\ \\ defines a \texttt{regex} object containing the regular expression from the
        characters in the initializer list \texttt{init}.

Here are some examples:
        \begin{verbatim}
    std::regex re("\\w+");      // matches a sequence of alpha-numeric
                                // and/or underscore characters 

    std::regex re{'\\', 'w', '+'} ;     // idem

    std::regex re(R"(\w+xxx")", 3);     // idem
\end{verbatim}
\end{itemize}

\textbf{Member functions}

\begin{itemize}
    \item \texttt{regex \&operator=(RHS)}:\ \\ The copy and move assignment operators are available. Otherwise, RHS
        may be:
        \begin{itemize}
        \item  an NTBS (of type \texttt{char const $*$});
        \item  a \texttt{std::string const \&} (or any compatible
            \texttt{std::basic\_string}); 
        \item  a \texttt{std::initializer\_list$<$char$>$};
        \end{itemize}

\item \texttt{regex \&assign(RHS)}:\ \\ This member accepts the same arguments as \texttt{regex's} constructors,
        including the (optional) \texttt{regex\_constants} values;

\item \texttt{regex::flag\_type flag() const}:\ \\ Returns the \texttt{regex\_constants} flags that are active for the current
        \texttt{regex} object. E.g.,
            \begin{verbatim}
    int main()
    {
        regex re;

        regex::flag_type flags = re.flags();
    
        cout <<                                 // displays: 16 0 0
            (re.flags() & regex_constants::ECMAScript) << ' '  <<
            (re.flags() & regex_constants::icase) << ' '  <<
            (re.flags() & regex_constants::awk) << ' '  << '\n';
    }
\end{verbatim}
Note that when a combination of \texttt{flag\_type} values is specified at
        construction-time that only those flags that were specified are
        set. E.g., when \texttt{re(regex\_constants::icase)} would have been
        specified the \texttt{cout} statement would have shown \texttt{0 1
        0}. It's also possible to specify conflicting combinations of
        flag-values like \texttt{regex\_constants::awk \textbar{} regex\_constants::grep}. The
        construction of such \texttt{regex} objects succeeds, but should be
        avoided.

\item \texttt{locale\_type get\_loc() const}:\ \\ Returns the locale that is associated with the current \texttt{regex}
        object;

\item \texttt{locale\_type imbue(locale\_type locale)}:\ \\ Replaces the \texttt{regex} object's current locale setting with
        \texttt{locale}, returning the replaced locale;

\item \texttt{unsigned mark\_count() const}:\ \\ The number of \emph{marked sub-expressions}\index{marked sub-expression} in
        the \texttt{regex} object is returned. E.g., 
            \begin{verbatim}
    int main()
    {
        regex re("(\\w+)([[:alpha:]]+)"); 
        cout << re.mark_count() << '\n';        // displays: 2
    }
\end{verbatim}
\item \texttt{void swap(regex \&other) noexcept}:\ \\ Swaps the current \texttt{regex} object with \texttt{other}. Also available as a
        free function: \texttt{void swap(regex \&lhs, regex \&rhs)}, swapping \texttt{lhs}
        and \texttt{rhs}.
    \end{itemize}

\subsection{Retrieving matches: std::match\_results}\label{SMATCH}
    \typeout{Original Yodl file: stl/smatch}Once a \texttt{regex} object is available, it can be used to match some target text
against the regular expression. To match a target text against a regular
expression the following functions, described in the next section
(\ref{REGALG}), are available:
    \begin{itemize}
    \item \texttt{regex\_match} merely matches a target text against a regular
expression, informing the caller whether a match was found or not;
    \item \texttt{regex\_search} also  matches a target text against a regular
expression, but allows retrieval of matches of marked sub-expressions (i.e.,
parenthesized regular expressions);
    \item \texttt{regex\_replace} matches a target text against a regular
expression, and replaces pieces of matched sections of the target text by
another text.
    \end{itemize}

These functions must be provided with a target text and a \texttt{regex} object
(which is not modified by these functions). Usually another argument, a
\texttt{std::match\_results}\index{match\_results} object is also passed to these
functions, to contain the results of the regular expression matching
procedure.

Before using the \texttt{match\_results} class the \index{regex: header file}\texttt{$<$regex$>$} header file must be
included.

Examples of using \texttt{match\_results} objects are provided in section
\ref{REGALG}. This and the next section are primarily for referential
purposes. 

Various specializations of the class \texttt{match\_results} exist. The
specialization that is used should match the specializations of the used
\texttt{regex} class. E.g., if the regular expression was specified as a \texttt{char
const $*$} the \texttt{match\_results} specialization should also operate on \texttt{char
const $*$} values. The various specializations of \texttt{match\_results} have been
given names that can easily be remembered, so selecting the appropriate
specialization is simple.

The class \texttt{match\_results} has the following specializations:
    \begin{itemize}
    \item \texttt{cmatch}:\ \\ defines \texttt{match\_results$<$char const $*$$>$}, using a \texttt{char const $*$} type
        of iterator. It should be used with a \texttt{regex(char const $*$)} regular
        expression specification;
    \item \texttt{wcmatch}:\ \\ defines \texttt{match\_results$<$wchar\_ const $*$$>$}, using a \texttt{wchar\_t const $*$}
        type of iterator. It should be used with a \texttt{regex(wchar\_t const $*$)}
        regular expression specification;
    \item \texttt{smatch}:\ \\ defines \texttt{match\_results$<$std::string::const\_iterator$>$}, using a
        \texttt{std::string::const\_iterator} type of iterator. It should be used
        with a \texttt{regex(std::string const \&)} regular expression
        specification;
    \item \texttt{wsmatch}:\ \\ defines \texttt{match\_results$<$std::wstring::const\_iterator$>$}, using a
        \texttt{std::wstring::const\_iterator} type of iterator. It should be used
        with a \texttt{regex(wstring const \&)} regular expression specification.
    \end{itemize}

\textbf{Constructors}

The default, copy, and move constructors are available. The default
constructor defines an \texttt{Allocator const \&} parameter, which by default is
initialized to the default allocator. Normally, objects of the class
\texttt{match\_results} receive their match-related information by passing them to
the above-mentioned functions, like \texttt{regex\_match}. When returning from these
functions members of the class \texttt{match\_results} can be used to retrieve
specific results of the matching process.

\textbf{Member functions}

\begin{itemize}
    \item \texttt{match\_results \&operator=}:\ \\ The copy and move assignment operators are available;

\item \texttt{std::string const \&operator{[}{]}(size\_t idx) const}:\ \\ Returns a (const) reference to sub-match \texttt{idx}. With \texttt{idx} value 0
        a reference to the full match is returned. If \texttt{idx $>$= size()} (see
        below) a reference to an empty sub-range of the target string is
        returned. The behavior of this member is undefined if the member
        \texttt{ready()} (see below) returns \texttt{false};

\item \texttt{Iterator begin() const}:\ \\ Returns an iterator to the first sub-match. \texttt{Iterator} is a
        const-iterator for \texttt{const match\_results} objects;

\item \texttt{Iterator cbegin() const}:\ \\ Returns an iterator to the first sub-match. \texttt{Iterator} is a
        const-iterator;

\item \texttt{Iterator cend() const}:\ \\ Returns an iterator pointing beyond the last sub-match. \texttt{Iterator}
        is a const-iterator;

\item \texttt{Iterator end() const}:\ \\ Returns an iterator pointing beyond the last sub-match. \texttt{Iterator}
        is a const-iterator for \texttt{const match\_results} objects;

\item \texttt{ReturnType format(Parameters) const}:\ \\ As this member requires a fairly extensive description, it would break
        the flow of the current overview. This member is used in combination
        with the \texttt{regex\_replace} function, and it is therefore covered in
        detail in that function's section (\ref{REGREP});

\item \texttt{allocator\_type get\_allocator() const}:\ \\ Returns the object's allocator;

\item \texttt{bool empty() const}:\ \\ Returns \texttt{true} if the \texttt{match\_results} object contains
        no matches (which is also returned after merely using the default
        constructor). Otherwise it returns \texttt{false};

\item \texttt{int length(size\_t idx = 0) const}:\ \\ Returns the length of sub-match \texttt{idx}. By default the length of
        the full match is returned. If \texttt{idx $>$= size()} (see below) 0 is
        returned;

\item \texttt{size\_type max\_size() const}:\ \\ Returns the maximum number of sub-matches that can be contained in a
        \texttt{match\_results} object. This is an implementation dependent constant
        value;

\item \texttt{int position(size\_t idx = 0) const}:\ \\ Returns the offset in the target text of the first character of
        sub-match \texttt{idx}. By default the position of the first character of
        the full match is returned. If \texttt{idx $>$= size()} (see below) -1 is
        returned;

\item \texttt{std::string const \&prefix() const}:\ \\ Returns a (const) reference to a sub-string of the target text that
        ends at the first character of the full match;

\item \texttt{bool ready() const}:\ \\ No match results are available from a default constructed
        \texttt{match\_results} object. It receives its match results from one of
        the mentioned matching functions. Returns \texttt{true} once match results
        are available, and \texttt{false} otherwise.

\item \texttt{size\_type size() const}:\ \\ Returns the number of sub-matches. E.g., with a regular expression
        \texttt{(abc)\textbar{}(def)} and target \texttt{defcon} three submatches are reported:
        the total match (def); the empty text for \texttt{(abc)}; and \texttt{def} for
        the \texttt{(def)} marked sub-expression. 

Note: when multipliers are used only the last match is counted and
        reported. E.g., for the pattern \texttt{(a\textbar{}b)+} and target \texttt{aaab} \emph{two}
        sub-matches are reported: the total match \texttt{aaab}, and the last match
        (\texttt{b});

\item \texttt{std::string str(size\_t idx = 0) const}:\ \\ Returns the characters defining sub-match \texttt{idx}. By default this is
        the full match. If \texttt{idx $>$= size()} (see below) an empty string
        returned;

\item \texttt{std::string const \&suffix() const}:\ \\ Returns a (const) reference to a sub-string of the target text that
        starts beyond the last character of the full match;

\item \texttt{void swap(match\_results \&other) noexcept}:\ \\ Swaps the current \texttt{match\_results} object with \texttt{other}. Also
        available as a free function: \texttt{void swap(match\_results \&lhs,
        match\_results \&rhs)}, swapping \texttt{lhs} and \texttt{rhs}.
    \end{itemize}

\subsection{Regular expression matching functions}\label{REGALG}
    \typeout{Original Yodl file: stl/regalg}Before using the functions presented in this section the \index{regex: header file}\texttt{$<$regex$>$} header
file must be included.

There are three major families of functions that can be used to match a target
text against a regular expression. Each of these functions, as well as the
\texttt{match\_results::format} member, has a final
\texttt{std::regex\_constants::match\_flag\_type} parameter (see the next section),
which is given the default value \texttt{regex\_constants::match\_default} which can
be used to fine-tune the way the regular expression and the matching process
is being used. This
final parameter is not explicitly mentioned with the regular expression
matching functions or with the \texttt{format} member. The three families of
functions are:
    \begin{itemize}
    \item \index{regex\_match}\texttt{bool std::regex\_match(Parameters)}:\ \\ This family of functions is used to match a regular expression against
        a target text. Only if the regular expression matches the full target
        text \texttt{true} is returned; otherwise \texttt{false} is returned. Refer to
        section \ref{REGMATCH} for an overview of the available overloaded
        \texttt{regex\_match} functions;

\item \index{regex\_search}\texttt{bool std::regex\_search(Parameters)}:\ \\ This family of functions is also used to match a regular expression
        against a target text. This function returns true once the regular
        expression matches a sub-string of the target text; otherwise
        \texttt{false} is returned. See below for an overview of the available
        overloaded \texttt{regex\_search} functions;

\item \index{regex\_replace}\texttt{ReturnType std::regex\_replace(Parameters)}:\ \\ This family of functions is used to produce modified texts, using the
        characters of a target string, a \texttt{regex} object and a format
        string. This member closely resembles the functionality of the 
        \texttt{match\_results::format} member discussed in section \ref{FORMAT}.
    \end{itemize}
    The \texttt{match\_results::format} member can be used after \texttt{regex\_replace}
and is discussed after covering \texttt{regex\_replace} (section \ref{FORMAT}).

\subsubsection{The std::regex\_constants::match\_flag\_type flags}
        \typeout{Original Yodl file: stl/matchflags}All overloaded \texttt{format} members and all regular expression matching
functions accept a final
\texttt{regex\_constants::match\_flag\_type}\index{match\_flag\_type} argument, which is a
bit-masked type, for which the \texttt{bit\_or} operator can be used. All \texttt{format}
members by default specify the argument \texttt{match\_default}.

The \texttt{match\_flag\_type} enumeration defines the following values (below,
`\texttt{[first, last)}' refers to the character sequence being matched).

\begin{itemize}
\item \index{format\_default}\texttt{format\_default} (not a bit-mask value, but a default value which is
	equal to 0). With just this specification ECMAScript rules are used to
	construct strings in \texttt{std::regex\_replace};

\item \index{format\_first\_only}\texttt{format\_first\_only}: \texttt{std::regex\_replace} only replaces the first
	match;

\item \index{format\_no\_copy}\texttt{format\_no\_copy}: non-matching strings are not passed to the output
	by \texttt{std::regex\_replace};

\item \index{format\_sed}\texttt{format\_sed}:  POSIX \textbf{sed}(1) rules are used to construct strings in
	\texttt{std::regex\_replace};

\item \index{match\_any}\texttt{match\_any}: if multiple matches are possible, then any match is an
	acceptable result;

\item \index{match\_continuous}\texttt{match\_continuous}: sub-sequences are only matching if they start at
	\texttt{first}; 

\item \index{match\_not\_bol}\texttt{match\_not\_bol}: the first character in \texttt{[first, last)} is treated
	as an ordinary character:  \texttt{\textasciicircum{}} does not match \texttt{[first, first)};

\item \index{match\_not\_bow}\texttt{match\_not\_bow}: \texttt{\textbackslash{}b} does not match \texttt{[first, first)};

\item \index{match\_default}\texttt{match\_default} (not a bit-mask value, but equal to 0): the default
    value of the final argument that's passed to the regular expression
    matching functions and \texttt{match\_results::format} member. ECMAScript
	rules are used to construct strings in \texttt{std::regex\_replace};

\item \index{match\_not\_eol}\texttt{match\_not\_eol}: the last character in \texttt{[first, last)} is treated
	as an ordinary character: \texttt{\$} does not match \texttt{[last,last)};

\item \index{match\_not\_eow}\texttt{match\_not\_eow}: \texttt{\textbackslash{}b} does  not match \texttt{[last, last)};

\item \index{match\_not\_null}\texttt{match\_not\_null}: empty sequences are not considered matches;

\item \index{match\_prev\_avail}\texttt{match\_prev\_avail}: \texttt{+NOTRANS(-\{\}-\{\})first} refers to a valid character
	position. When specified \texttt{match\_not\_bol} and \texttt{match\_not\_bow} are
	ignored;
\end{itemize}

\subsubsection{Matching full texts: std::regex\_match}\label{REGMATCH}
        \typeout{Original Yodl file: stl/regexmatch}The regular expression matching function \texttt{std::regex\_match}\index{regex\_match}
returns \texttt{true} if the regular expression defined in its provided
\texttt{regex} argument \emph{fully} matches the provided target text. This means that
\texttt{match\_results::prefix} and \texttt{match\_results::suffix} must return empty
strings. But defining sub-expressions is OK.

The following overloaded variants of this function are available:
    \begin{itemize}
    \item \texttt{bool regex\_match(BidirConstIter first, BidirConstIter last,
                  std::match\_results \&results,
                  std::regex const \&re)}:\ \\ \texttt{BidirConstIter} is a bidirectional const iterator. The range
        \texttt{[first, last)} defines the target text. The match results are
        returned in \texttt{results}. The types of the iterators must match the
        type of the \texttt{match\_results} that's used. E.g., a \texttt{cmatch} should
        be used if the iterators are of \texttt{char const $*$} types, and a
        \texttt{smatch} should be used if the iterators are of
        \texttt{string::const\_iterator} types. Similar correspondence requirements
        hold true for the other overloaded versions of this function;

\item \texttt{bool regex\_match(BidirConstIter first, BidirConstIter last,
        std::regex const \&re)}:\ \\ this function behaves like the previous function, but does not
        return the results of the matching process in a \texttt{match\_results}
        object;

\item \texttt{bool regex\_match(char const $*$target,
                  std::match\_results \&results, std::regex const \&re)}:\ \\ this function behaves like the first overloaded variant, using
        the characters in \texttt{target} as its target text;

\item \texttt{bool regex\_match(char const $*$str, std::regex const \&re)}:\ \\ this function behaves like the previous function but does not return
        the match results;

\item \texttt{bool regex\_match(std::string const \&target,
                  std::match\_results \&results, std::regex const \&re)}:\ \\ this function behaves like the first overloaded variant, using
        the characters in \texttt{target} as its target text;

\item \texttt{bool regex\_match(std::string const \&str, std::regex const \&re)}:\ \\ this function behaves like the previous function but does not return
        the match results;

\item \texttt{bool regex\_match(std::string const \&\&, std::match\_results \&, 
                         std::regex \&) = delete}
       (the \texttt{regex\_match} function does not accept temporary \texttt{string}
        objects as target strings, as this would result in invalid string
        iterators in the \texttt{match\_result} argument.)
    \end{itemize}
    Here is a small example: the regular expression matches the matched text
(provided by \texttt{argv{[}1{]}}) if it starts with 5 digits and then 
merely contains  letters (\texttt{{[}{[}:alpha:{]}{]}}). The digits can be retrieved as
sub-expression 1:
        \begin{verbatim}
    #include <iostream>
    #include <regex>
    
    using namespace std;
    
    int main(int argc, char const **argv)
    {
        regex re("(\\d{5})[[:alpha:]]+"); 

        cmatch results;

        if (not regex_match(argv[1], results, re))
            cout << "No match\n";
        else
            cout << "size: " << results.size() << ": " << 
                    results.str(1) << " -- " << results.str() << '\n';
    }
\end{verbatim}
\subsubsection{Partially matching text: std::regex\_search}\label{REGSRCH}
        \typeout{Original Yodl file: stl/regexsearch}Different from \texttt{regex\_match} the regular expression matching function
\texttt{std::regex\_search}\index{regex\_search} returns \texttt{true} if the regular
expression defined in its \texttt{regex} argument partially matches the target
text.

The following overloaded variants of this function are available:
    \begin{itemize}
    \item \texttt{bool regex\_search(BidirConstIter first, BidirConstIter last,
                  std::match\_results \&results,
                  std::regex const \&re)}:\ \\ \texttt{BidirConstIter} is a bidirectional const iterator. The range 
        \texttt{[first, last)} defines the target text. The match results are
        returned in \texttt{results}. The types of the iterators must match the
        type of the \texttt{match\_results} that's used. E.g., a \texttt{cmatch} should
        be used if the iterators are of \texttt{char const $*$} types, and a
        \texttt{smatch} should be used if the iterators are of
        \texttt{string::const\_iterator} types. Similar correspondence requirements
        hold true for the other overloaded versions of this function;

\item \texttt{bool regex\_search(BidirConstIter first, BidirConstIter last,
        std::regex const \&re)}:\ \\ this function behaves like the previous function, but does not
        return the results of the matching process in a \texttt{match\_results}
        object;

\item \texttt{bool regex\_search(char const $*$target,
                  std::match\_results \&results, std::regex const \&re)}:\ \\ this function behaves like the first overloaded variant, using
        the characters in \texttt{target} as its target text;

\item \texttt{bool regex\_search(char const $*$str, std::regex const \&re)}:\ \\ this function behaves like the previous function but does not return
        the match results;

\item \texttt{bool regex\_search(std::string const \&target,
                  std::match\_results \&results, std::regex const \&re)}:\ \\ this function behaves like the first overloaded variant, using
        the characters in \texttt{target} as its target text;

\item \texttt{bool regex\_search(std::string const \&str, std::regex const \&re)}:\ \\ this function behaves like the previous function but does not return
        the match results;

\item \texttt{bool regex\_search(std::string const \&\&, std::match\_results \&, 
                         std::regex \&) = delete}:\ \\ the \texttt{regex\_search} function does not accept temporary \texttt{string}
        objects as target strings, as this would result in invalid string
        iterators in the \texttt{match\_result} argument.
    \end{itemize}
    The following example illustrates how \texttt{regex\_search} could be used:
    \begin{verbatim}
     1: #include <iostream>
     2: #include <string>
     3: #include <regex>
     4: 
     5: using namespace std;
     6: 
     7: int main()
     8: {
     9:     while (true)
    10:     {
    11:         cout << "Enter a pattern or plain Enter to stop: ";
    12: 
    13:         string pattern;
    14:         if (not getline(cin, pattern) or pattern.empty())
    15:             break;
    16: 
    17:         regex re(pattern);
    18:         while (true)
    19:         {
    20:             cout << "Enter a target text for `" << pattern << "'\n"
    21:                     "(plain Enter for the next pattern): ";
    22: 
    23:             string text;
    24:             if (not getline(cin, text) or text.empty())
    25:                 break;
    26: 
    27:             smatch results;
    28:             if (not regex_search(text, results, re))
    29:                 cout << "No match\n";
    30:             else
    31:             {
    32:                 cout << "Prefix: "  << results.prefix() << "\n"
    33:                         "Match:  "  << results.str()    << "\n"
    34:                         "Suffix: "  << results.suffix() << "\n";
    35:                 for (size_t idx = 1; idx != results.size(); ++idx)
    36:                     cout << "Match " << idx << " at offset " <<
    37:                                 results.position(idx) << ": " <<
    38:                                 results.str(idx) << '\n';
    39:             }
    40:         }
    41:     }
    42: }
\end{verbatim}
\subsubsection{The member std::match\_results::format}\label{FORMAT}
        \typeout{Original Yodl file: stl/format}The \index{format} \texttt{match\_results::format} member is a rather complex member
function of the class \texttt{match\_results}, which can be used to modify text
which was previously matched against a regular expression, e.g., using the
function \texttt{regex\_search}. Because of its complexity and because the
functionality of another regular expression processing function
(\texttt{regex\_replace}) offers similar functionality it is discussed at this point
in the \textbf{C++} Annotations, just before discussing the \texttt{regex\_replace} function.

The \texttt{format} member operates on (sub-)matches contained in a
\texttt{match\_results} object, using a \index{format string}\emph{format string}, and producing text in
which \index{format specifier} format specifiers (like \texttt{\$\&}) are replaced by
matching sections of the originally provided target text. In addition, the
\texttt{format} member recognizes all standard \textbf{C} escape sequences (like
\texttt{\textbackslash{}n}). The \texttt{format} member is used to create text that is modified with
respect to the original target text.

As a preliminary illustration: if \texttt{results} is a \texttt{match\_results} object
and \texttt{match{[}0{]}} (the fully matched text) equals `\texttt{hello world}', then
calling \texttt{format} with the format string \texttt{this is {[}\$\&{]}} produces the text
\texttt{this is {[}hello world{]}}. Note the specification \texttt{\$\&} in this format
string: this is an example of a format specifier. Here is an overview of all
supported format specifiers:
    \begin{itemize}
    \item \texttt{\$`}: corresponds to the text returned by the \texttt{prefix} member: all
        characters in the original target text up to the first character
        of the fully matched text;
    \item \texttt{\$\&}: corresponds to the fully matched text (i.e., the text returned by
        the \texttt{match\_results::str} member);
    \item \texttt{\$n}: (where \texttt{n} is an integral natural number): corresponds to the
        text returned bu \texttt{operator{[}{]}(n)};
    \item \texttt{\$'}: corresponds to the text returned by the \texttt{suffix} member: all
        characters in the original target string beyond the last character
        of the fully matched text;
    \item \texttt{\$\$}: corresponds to the single \texttt{\$} character.
    \end{itemize}

Four overloaded versions of the \texttt{format} members are available. All
overloaded versions define a final \texttt{regex\_constants::match\_flag\_type}
parameter, which is by default initialized to \texttt{match\_default}. This final
parameter is not explicitly mentioned in the following coverage of the
\texttt{format} members.

To further illustrate the way the \texttt{format} members can be used it is assumed
that the following code has been executed:
    \begin{verbatim}
     1:     regex re("([[:alpha:]]+)\\s+(\\d+)");  // letters blanks digits
     2: 
     3:     smatch results;
     4:     string target("this value 1024 is interesting");
     5: 
     6:     if (not regex_search(target, results, re))
     7:         return 1;
\end{verbatim}
  After calling \texttt{regex\_search} (line 6) the results of the regular
expression matching process are available in the \texttt{match\_results results}
object that is defined in line 3.

The first two overloaded \texttt{format} functions expect an output-iterator to
where the formatted text is written. These overloaded members return the 
final output iterator, pointing just beyond the character that was last
written.
    \begin{itemize}
    \item \texttt{OutputIter format(OutputIter out, char const $*$first, char const
        $*$last)  const}:\ \\ the characters in the range \texttt{[first, last)} are applied to the 
        sub-expressions stored in the \texttt{match\_results} object, and the
        resulting string is inserted at \texttt{out}. An illustration is provided
        with the next overloaded version;

\item \texttt{OutputIter format(OutputIter out, std::string const \&fmt)  const}:\ \\ the content of \texttt{fmt} is applied to the sub-expressions stored in
        the \texttt{match\_results} object, and the resulting string is inserted at
        \texttt{out}. The next line of code inserts the value 1024 into \texttt{cout}
        (note that \texttt{fmt} \emph{must} be a \texttt{std::string}, hence the explicit
        use of the \texttt{string} constructor):
         \begin{verbatim}
results.format(ostream_iterator<char>(cout, ""), "$2"s);
\end{verbatim}
\end{itemize}

The remaining two overloaded \texttt{format} members expect a \texttt{std::string} or
an NTBS defining the format string. Both members return a \texttt{std::string}
containing the formatted text:
    \begin{itemize}
    \item \texttt{std::string format(std::string const \&fmt) const}
    \item \texttt{std::string format(char const $*$fmt) const}
    \end{itemize}
    The next example shows how a \texttt{string} can be obtained
in which the order of the first and second marked sub-expressions contained in
the previously obtained \texttt{match\_results} object have been
swapped: 
    \begin{verbatim}
    string reverse(results.format("$2 and $1"));
\end{verbatim}
\subsubsection{Modifying target strings: std::regex\_replace}\label{REGREP}
        \typeout{Original Yodl file: stl/regexreplace}The family of \texttt{std::regex\_replace}\index{regex\_replace} functions uses regular
expressions to perform substitution on sequences of characters. Their
functionality closely resembles the functionality of the
\texttt{match\_results::format} member discussed in the previous section. The
following overloaded variants are available:
    \begin{itemize}
    \item \texttt{OutputIt regex\_replace(OutputIter out, 
                        BidirConstIter first, BidirConstIter last,
                        std::regex const \&re, std::string const \&fmt)}:\ \\ \texttt{OutputIter} is an output iterator; \texttt{BidirConstIter} a
        bidirectional const iterator.

The function returns the possibly modified text in an iterator range
            \texttt{[out, retvalue)}, where \texttt{out} is the output iterator
            passed as the first argument to \texttt{regex\_replace}, and
            \texttt{retvalue} is the output iterator returned by
            \texttt{regex\_replace}. 

The function matches the text at the range \texttt{[first, last)}
            against the regular expression stored in \texttt{re}. If the regular
            expression does \emph{not} match the target text in the range
            \texttt{[first, last)} then the target text is literally copied to
            \texttt{out}. If the regular expression \emph{does} match the target text
            then 
       \begin{itemize}
        \item  first, the match result's prefix is copied to \texttt{out}. The prefix
            equals the initial characters of the target text up to the very
            first character of the fully matched text.
        \item  next, the matched text is replaced by the content of the \texttt{fmt}
            format string, in which the format specifiers can be used that
            were described in the previous section (section \ref{FORMAT}), and
            the replaced text is copied to \texttt{out};
        \item  finally, the match result's suffix is copied to \texttt{out}. The
            suffix equals all characters of the target text beyond the last
            character of the matched text.
        \end{itemize}
        The workings of \texttt{regex\_replace} is illustrated in the next example:
    \begin{verbatim}
 1:     regex re("([[:alpha:]]+)\\s+(\\d+)");  // letters blanks digits
 2: 
 3:     string target("this value 1024 is interesting");
 4: 
 5:     regex_replace(ostream_iterator<char>(cout, ""), target.begin(),
 6:                     target.end(), re, "$2"s);
\end{verbatim}
       In line 5 \texttt{regex\_replace} is called. Its format string merely
        contains \texttt{\$2}, matching 1024 in the target text. The prefix ends at
        the word \texttt{value}, the suffix starts beyond 1024, so the statement in
        line 5 inserts the text \begin{verbatim}
this 1024 is interesting
\end{verbatim}
into the
        standard output stream.  

\item \texttt{OutputIt regex\_replace( OutputIter out, BidirConstIter first,
        BidirConstIter last, std::regex const \&re, char const $*$fmt)}:\ \\ This variant behaves like the first variant. When using, in the above
        example, \texttt{"\$2"} instead of \texttt{"\$2"s}, then this variant would
        have been used;

\item \texttt{std::string regex\_replace(std::string const \&str,
                   std::regex const \&re, std::string const \&fmt)}:\ \\ This variant returns a \texttt{std::string} containing the modified text,
        and expects a \texttt{std::string} containing the target text. Other than
        that, it behaves like the first variant. To use this overloaded
        variant in the above example the statement in line 5 could have been
        replaced by the following statement, initializing the \texttt{string
        result}:
       \begin{verbatim}
string result(regex_replace(target, re, "$2"s));
\end{verbatim}
\item \texttt{std::string regex\_replace(std::string const \&str,
                   std::regex const \&re, char const $*$fmt)}:\ \\ After changing, in the above statement, \texttt{"\$2"s} into
        \texttt{"\$2"}, this variant is used, behaving exactly like the previous
        variant;

\item \texttt{std::string regex\_replace(char const $*$str,
                   std::regex const \&re, std::string const \&fmt)}:\ \\ This variant uses a \texttt{char const $*$} to point to the target text, and
        behaves exactly like the previous but one variant;

\item \texttt{std::string regex\_replace(char const $*$str,
                   std::regex const \&re, char const $*$fmt)}:\ \\ This variant also uses a \texttt{char const $*$} to point to the target text,
        and also behaves exactly like the previous but one variant;
    \end{itemize}

\section{Randomization and Statistical Distributions}
\typeout{Original Yodl file: stl/statdist}    Before the statistical distributions and accompanying random number
generators can be used the \index{random: header file}\texttt{$<$random$>$} header file must be included.

The STL offers several standard mathematical (statistical)
distributions. These distributions allow programmers to obtain randomly
selected values from a selected distribution.

These statistical distributions need to be provided with a random number
generating object. Several of such random number generating objects are
provided, extending the traditional \index{rand}\texttt{rand} function that is part of the
\textbf{C} standard library.

These random number generating objects produce pseudo-random numbers, which
are then processed by the statistical distribution to obtain values that are
randomly selected from the specified distribution.

Although the STL offers various statistical distributions their functionality
is fairly limited. The distributions allow us to obtain a random number from
these distributions, but
    \index{probability density function}probability density functions
 or
    \index{cumulative distribution function}cumulative distribution functions
 are currently not provided by the STL. These functions (distributions as well
as the density and the cumulative distribution functions) are, however,
available in other libraries, like the
    \texttt{boost math library}\footnote{http://www.boost.org/} (specifically:\ \\ 
     \texttt{http://www.boost.org/doc/libs/1\_44\_0/libs/math/doc/sf\_and\_dist/html/index.html}).

It is beyond the scope of the \textbf{C++} Annotations to discuss the mathematical
characteristics of the various statistical distributions. The interested
reader is referred to the pertinent mathematical textbooks (like Stuart and
Ord's (2009)
    \index{Stuart, A. \& Ord, K}
    \index{Kendall's Advanced Theory of Statistics}\emph{Kendall's Advanced Theory of Statistics}, Wiley) or to web-locations
like \texttt{http://en.wikipedia.org/wiki/Bernoulli\_distribution}.

\subsection{Random Number Generators}
    \typeout{Original Yodl file: stl/randomnumber}The following \index{generator: random number}generators are available:
\begin{center}
\begin{tabular}{lllll}

\hline


Class template & Integral/Floating point & Quality & Speed & Size of state \\

\hline


\index{linear\_congruential\_engine}\texttt{linear\_congruential\_engine} & Integral & Medium & Medium & 1 \\


\index{subtract\_with\_carry\_engine}\texttt{subtract\_with\_carry\_engine} & Both & Medium & Fast & 25 \\


\index{mersenne\_twister\_engine}\texttt{mersenne\_twister\_engine} & Integral & Good & Fast & 624 \\

\hline


\end{tabular}\end{center}

The \index{linear\_congruential\_engine}\texttt{linear\_congruential\_engine} random number generator computes
    \begin{center}\texttt{value}$_{i+1}$\texttt{ = (+a $*$ value}$_{i}$\texttt{ +
                                                              c+) \% m}\end{center}
    It expects template arguments for, respectively, the data type to contain
the generated random values; the multiplier \texttt{a}; the additive constant
\texttt{c}; and the modulo value \texttt{m}. Example:
        \begin{verbatim}
    linear_congruential_engine<int, 10, 3, 13> lincon;
\end{verbatim}
The \texttt{linear\_congruential} generator may be seeded by providing its
constructor with a seeding-argument. E.g., \texttt{lincon(time(0))}.

The \index{subtract\_with\_carry\_engine}\texttt{subtract\_with\_carry\_engine} random number generator computes
    \begin{center}\texttt{value}$_{i}$\texttt{ = (value}$_{i-s}$\texttt{ -
                                                            value}$_{i-r}$\texttt{ - carry}$_{i-1}$\texttt{) \% m}\end{center}
    It expects template arguments for, respectively, the data type to contain
the generated random values; the modulo value \texttt{m}; and the subtractive
constants \texttt{s} and \texttt{r}. Example:
        \begin{verbatim}
    subtract_with_carry_engine<int, 13, 3, 13> subcar;
\end{verbatim}
The \texttt{subtract\_with\_carry\_engine} generator may be seeded by providing
its constructor with a seeding-argument. E.g., \texttt{subcar(time(0))}.

The predefined \texttt{mersenne\_twister\_engine mt19937} (predefined as type in the
\index{random: header file}\texttt{$<$random$>$} header file) is used in the examples below. It can be constructed
using
    \index{mt19937}`\texttt{mt19937 mt}' or it can be seeded by providing its
constructor with an argument (e.g., \texttt{mt19937 mt(time(0))}). Its function
call operator returns a random unsigned integral value.

Other ways to initialize the \texttt{mersenne\_twister\_engine} are beyond the
scope of the \textbf{C++} Annotations (but see Lewis\index{Lewis, P.A.W.} \emph{et
al.}\footnote{
    Lewis, P.A.W., Goodman, A.S., and Miller, J.M. (1969), A pseudorandom
number generator for the System/360, IBM Systems Journal, 8, 136-146.} (1969)).

The random number generators may also be seeded by calling their members
\texttt{seed}  accepting \texttt{unsigned long} values or generator functions (as in
\texttt{lc.seed(time(0)), lc.seed(mt)}).

The random number generators offer members \index{min}\texttt{min} and \index{max}\texttt{max}
returning, respectively, their minimum and maximum values (inclusive). If a
reduced range is required the generators can be nested in a function or class
adapting the range.

Here's a small example showing how the \texttt{mersenne\_twister\_engine
mt19937} can be used to generate random numbers:
        \begin{verbatim}
    #include <iostream>
    #include <ctime>
    #include <random>

    using namespace std;

        // arguments: 1st: number of random numbers to generate
        //            2nd: lowest positve random number,
        //            3rd: highest positive random number

    int main(int argc, char **argv)
    {
        mt19937 mt( time(0) );      // seed with the current time in secs.

        for (
            size_t nGenerate = stoul(argv[1]), lowest = stoul(argv[2]),
                                               mod = stoul(argv[3]) + 1 - lowest;
                nGenerate--;
        )
            cout << (lowest + mt() % mod) << ' ';

        cout << '\n';
    }
\end{verbatim}
\subsection{Statistical distributions}
    \typeout{Original Yodl file: stl/statistical}In the following sections the various statistical distributions that are
supported by \textbf{C++} are covered. The notation \index{RNG}\texttt{RNG} is used to
indicate a \emph{Random Number Generator} and \index{URNG}\texttt{URNG} is used to indicate a
\emph{Uniform Random Number Generator}. With each distribution a
\texttt{struct param\_type} is defined containing the distribution's parameters. The
organization of these \texttt{param\_type} structs depends on (and is described
at) the actual distribution.

All distributions offer the following members (\emph{result\_type} refers to
the type name of the values returned by the distribution):
    \begin{itemize}
    \item \texttt{result\_type max() const}\ \\ 
        returns the distribution's least upper bound;
    \item \texttt{result\_type min() const}\ \\ 
        returns the distribution's greatest lower bound;
    \item \texttt{param\_type param() const}\ \\ 
        returns the object's \texttt{param\_type} struct;
    \item \texttt{void param(const param\_type \&param)}
        redefines the parameters of the distribution;
    \item \texttt{void reset():}
       clears all of its cached values;
    \end{itemize}

All distributions support the following operators (\emph{distribution-name}
        should be replaced by the name of the intended distribution, e.g.,
        \texttt{normal\_distribution}):
    \begin{itemize}
    \item \texttt{template$<$typename URNG$>$ result\_type operator()(URNG \&urng)}\ \\ 
       returns the next random value from the statistical distribution, with
        the function object \texttt{urng} returning the next random number selected
        from a uniform random distribution;
    \item \texttt{template$<$typename URNG$>$ result\_type operator()}\ \\ 
       \texttt{(URNG \&urng, param\_type \&param)}\ \\  returns the next random value
        from the statistical distribution initialized with the parameters
        provided by the \texttt{param} struct.  The function object \texttt{urng}
        returns the next random number selected from a uniform random
        distribution;
    \item \texttt{std::istream \&operator$>$$>$(std::istream \&in,
            distribution-name \&object):}
       The parameters of the distribution are extracted from an
        \texttt{std::istream};
    \item \texttt{std::ostream \&operator$<$$<$(std::ostream \&out,
            distribution-name const \&bd):}
        The parameters of the distribution are inserted into an
        \texttt{std::ostream}
    \end{itemize}

The following example shows how the distributions can be used. Replacing
the name of the distribution (\texttt{normal\_distribution}) by another
distribution's name is all that is required to switch distributions. All
distributions have parameters, like the mean and standard deviation of the
normal distribution, and all parameters have default values. The names of the
parameters vary over distributions and are mentioned below at the individual
distributions. Distributions offer members returning or setting their
parameters.

Most distributions are defined as class templates, requiring the specification
of a data type that is used for the function's return type. If so, an empty
template parameter type specification (\texttt{$<$$>$}) will get you the default
type. The default types are either \texttt{double} (for real valued return types)
or \texttt{int} (for integral valued return types). The template parameter type
specification must be omitted with distributions that are not defined as
template classes.

Here is an example showing the use of the statistical distributions, applied
to the normal distribution:

\begin{verbatim}
#include <iostream>
#include <ctime>
#include <random>
using namespace std;

int main()
{
    std::mt19937 engine(time(0));
    std::normal_distribution<> dist;

    for (size_t idx = 0; idx < 10; ++idx)
        std::cout << "a random value: " << dist(engine) << "\n";

    cout << '\n' <<
        dist.min() << " " << dist.max() << '\n';
}
\end{verbatim}
\subsubsection{Bernoulli distribution}\label{BERNOULLI}
        \typeout{Original Yodl file: stl/bernoulli}The \index{bernoulli\_distribution}\texttt{bernoulli\_distribution} is used to generate logical truth (boolean)
values with a certain probability \texttt{p}. It is equal to a binomial
distribution for one experiment (cf \ref{BINOMIAL}).

The bernoulli distribution is \emph{not} defined as a class template.

Defined types:
            \begin{verbatim}
    using result_type = bool;
    struct param_type
    {
      explicit param_type(double prob = 0.5);
      double p() const;                     // returns prob
    };
\end{verbatim}
Constructor and members:
    \begin{itemize}
    \item \texttt{bernoulli\_distribution(double prob = 0.5)}\ \\ 
        constructs a bernoulli distribution with probability \texttt{prob} of
        returning \texttt{true};
    \item \texttt{double p() const}\ \\ 
        returns \texttt{prob};
    \item \texttt{result\_type min() const}\ \\ 
        returns \texttt{false};
    \item \texttt{result\_type max() const}\ \\ 
        returns \texttt{true};
    \end{itemize}

\subsubsection{Binomial distribution}\label{BINOMIAL}
        \typeout{Original Yodl file: stl/binomial}The \index{binomial\_distribution\textless{}IntType = int\textgreater{}}\texttt{binomial\_distribution$<$IntType = int$>$} is used to determine the
probability of the number of successes in a sequence of \texttt{n} independent
success/failure experiments, each of which yields success with probability
\texttt{p}.

The template type parameter \texttt{IntType} defines the type of the generated
random value, which must be an integral type.

Defined types:
            \begin{verbatim}
    using result_type =  IntType;
    struct param_type
    {
      explicit param_type(IntType trials, double prob = 0.5);
      IntType t() const;                    // returns trials
      double p() const;                     // returns prob
    };
\end{verbatim}
Constructors and members and example:
    \begin{itemize}
    \item \texttt{binomial\_distribution$<$$>$(IntType trials = 1, double prob = 0.5)}
        constructs a binomial distribution for \texttt{trials} experiments, each
        having probability \texttt{prob} of success.
    \item \texttt{binomial\_distribution$<$$>$(param\_type const \&param)}
        constructs a binomial distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{IntType t() const}\ \\ 
        returns \texttt{trials};
    \item \texttt{double p() const}\ \\ 
        returns \texttt{prob};
    \item \texttt{result\_type min() const} \ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns \texttt{trials};
    \end{itemize}

\subsubsection{Cauchy distribution}
        \typeout{Original Yodl file: stl/cauchy}The \index{cauchy\_distribution\textless{}RealType = double\textgreater{}}\texttt{cauchy\_distribution$<$RealType = double$>$} looks similar to a normal
distribution. But cauchy distributions have heavier tails.  When studying
hypothesis tests that assume normality, seeing how the tests perform on data
from a Cauchy distribution is a good indicator of how sensitive the tests are
to heavy-tail departures from normality.

The mean and standard deviation of the Cauchy distribution are undefined.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType a = RealType(0),
                            RealType b = RealType(1));

        double a() const;
        double b() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{cauchy\_distribution$<$$>$(RealType a = RealType(0),
                            RealType b = RealType(1))}
        constructs a cauchy distribution with specified \texttt{a} and \texttt{b}
        parameters.
    \item \texttt{cauchy\_distribution$<$$>$(param\_type const \&param)}
        constructs a cauchy distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType a() const}\ \\ 
        returns the distribution's \texttt{a} parameter;
    \item \texttt{RealType b() const}\ \\ 
        returns the distribution's \texttt{b} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns the smallest positive \texttt{result\_type} value;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Chi-squared distribution}\label{CHISQUARED}
        \typeout{Original Yodl file: stl/chisquared}The \index{chi\_squared\_distribution\textless{}RealType = double\textgreater{}}\texttt{chi\_squared\_distribution$<$RealType = double$>$} with \texttt{n} degrees of
freedom is the distribution of a sum of the squares of \texttt{n} independent
standard normal random variables.

Note that even though the distribution's parameter \texttt{n} usually is an
integral value, it doesn't have to be integral, as the chi\_squared
distribution is defined in terms of functions (\texttt{exp} and \texttt{Gamma}) that
take real arguments (see, e.g., the formula shown in the \texttt{$<$bits/random.h$>$}
header file, provided with the GNU \texttt{g++} compiler distribution).

The chi-squared distribution is used, e.g., when testing the goodness of fit
of an observed distribution to a theoretical one.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType n = RealType(1));

        RealType n() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{chi\_squared\_distribution$<$$>$(RealType n = 1)}
       constructs a chi\_squared distribution with specified number of degrees
        of freedom.
    \item \texttt{chi\_squared\_distribution$<$$>$(param\_type const \&param)}
       constructs a chi\_squared distribution according to the value stored in
        the \texttt{param} struct;
    \item \texttt{IntType n() const}\ \\ 
        returns the distribution's degrees of freedom;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Extreme value distribution}
        \typeout{Original Yodl file: stl/extremevalue}The \index{extreme\_value\_distribution\textless{}RealType = double\textgreater{}}\texttt{extreme\_value\_distribution$<$RealType = double$>$} is related to the
Weibull distribution and is used in statistical models where the variable of
interest is the minimum of many random factors, all of which can take positive
or negative values.

It has two parameters: a location parameter \texttt{a} and scale parameter \texttt{b}.
See also \ \\ 
    \texttt{http://www.itl.nist.gov/div898/handbook/apr/section1/apr163.htm}

Defined types:
        \begin{verbatim}
using result_type = RealType;

struct param_type
{
    explicit param_type(RealType a = RealType(0),
                        RealType b = RealType(1));

    RealType a() const;     // the location parameter
    RealType b() const;     // the scale parameter
};
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{extreme\_value\_distribution$<$$>$(RealType a = 0, RealType b = 1)}
        constructs an extreme value distribution with specified \texttt{a} and
        \texttt{b} parameters;
    \item \texttt{extreme\_value\_distribution$<$$>$(param\_type const \&param)}
        constructs an extreme value distribution according to the values
        stored in the \texttt{param} struct.
    \item \texttt{RealType a() const}\ \\ 
        returns the distribution's location parameter;
    \item \texttt{RealType stddev() const}\ \\ 
        returns the distribution's scale parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns the smallest positive value of \texttt{result\_type};
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Exponential distribution}
        \typeout{Original Yodl file: stl/exponential}The \index{exponential\_distribution\textless{}RealType = double\textgreater{}}\texttt{exponential\_distribution$<$RealType = double$>$} is used to describe the
lengths between events that can be modeled with a homogeneous Poisson
process. It can be interpreted as the continuous form of the
geometric distribution.

Its parameter \texttt{prob} defines the distribution's \emph{lambda} parameter, called
its \emph{rate} parameter. Its expected value and standard deviation are both
\texttt{1 / lambda}.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType lambda = RealType(1));

        RealType lambda() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{exponential\_distribution$<$$>$(RealType lambda = 1)}
       constructs an exponential distribution with specified \texttt{lambda}
        parameter.
    \item \texttt{exponential\_distribution$<$$>$(param\_type const \&param)}
       constructs an exponential distribution according to the value stored in
        the \texttt{param} struct.
    \item \texttt{RealType lambda() const}\ \\ 
        returns the distribution's \texttt{lambda} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Fisher F distribution}
        \typeout{Original Yodl file: stl/fisherf}The \index{fisher\_f\_distribution\textless{}RealType = double\textgreater{}}\texttt{fisher\_f\_distribution$<$RealType = double$>$} is intensively used in
statistical methods like the Analysis of Variance. It is the distribution
resulting from dividing two \emph{Chi-squared} distributions.

It is characterized by two parameters, being the degrees of freedom of the two
chi-squared distributions.

Note that even though the distribution's parameter \texttt{n} usually is an
integral value, it doesn't have to be integral, as the Fisher F distribution
is constructed from Chi-squared distributions that accept a non-integral
parameter value (see also section \ref{CHISQUARED}).

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType m = RealType(1),
                            RealType n = RealType(1));

        RealType m() const; // The degrees of freedom of the nominator
        RealType n() const; // The degrees of freedom of the denominator
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{fisher\_f\_distribution$<$$>$(RealType m = RealType(1),
                                RealType n = RealType(1))}
        constructs a fisher\_f distribution with specified degrees of freedom.
    \item \texttt{fisher\_f\_distribution$<$$>$(param\_type const \&param)}
        constructs a fisher\_f distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType m() const}\ \\ 
        returns the degrees of freedom of the nominator;
    \item \texttt{RealType n() const}\ \\ 
        returns the degrees of freedom of the denominator;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Gamma distribution}
        \typeout{Original Yodl file: stl/gamma}The \index{gamma\_distribution\textless{}RealType = double\textgreater{}}\texttt{gamma\_distribution$<$RealType = double$>$} is used when working with data
that are not distributed according to the normal distribution. It is often
used to model waiting times.

It has two parameters, \texttt{alpha} and \texttt{beta}. Its expected value is \texttt{alpha
$*$ beta} and its standard deviation is \texttt{alpha $*$ beta}$^{2}$.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType alpha = RealType(1),
                            RealType beta = RealType(1));

        RealType alpha() const;
        RealType beta() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{gamma\_distribution$<$$>$(RealType alpha = 1, RealType beta = 1)}
        constructs a gamma distribution with specified \texttt{alpha} and \texttt{beta}
        parameters.
    \item \texttt{gamma\_distribution$<$$>$(param\_type const \&param)}
        constructs a gamma distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType alpha() const}\ \\ 
        returns the distribution's \texttt{alpha} parameter;
    \item \texttt{RealType beta() const}\ \\ 
        returns the distribution's \texttt{beta} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Geometric distribution}
        \typeout{Original Yodl file: stl/geometric}The \index{geometric\_distribution\textless{}IntType = int\textgreater{}}\texttt{geometric\_distribution$<$IntType = int$>$} is used to model the number
of bernoulli trials (cf. \ref{BERNOULLI}) needed until the first success.

It has one parameter, \texttt{prob}, representing the probability of success in an
individual bernoulli trial.

Defined types:
        \begin{verbatim}
    using result_type = IntType;

    struct param_type
    {
        explicit param_type(double prob = 0.5);
        double p() const;
    };
\end{verbatim}
Constructors, members and example:
    \begin{itemize}
    \item \texttt{geometric\_distribution$<$$>$(double prob = 0.5)}
        constructs a geometric distribution for bernoulli trials each having
        probability \texttt{prob} of success.
    \item \texttt{geometric\_distribution$<$$>$(param\_type const \&param)}
        constructs a geometric distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{double p() const}\ \\ 
        returns the distribution's \texttt{prob} parameter;
    \item \texttt{param\_type param() const}\ \\ 
        returns the object's \texttt{param\_type} structure;
    \item \texttt{void param(const param\_type \&param)}
        redefines the parameters of the distribution;
    \item \texttt{result\_type min() const}\ \\ 
        returns the distribution's lower bound (= \texttt{0});
    \item \texttt{result\_type max() const}\ \\ 
        returns the distribution's upper bound;
    \item \texttt{template$<$typename URNG$>$ result\_type operator()(URNG \&urng)}\ \\ 
        returns the next random value from the geometric distribution
    \item \texttt{template$<$typename URNG$>$ result\_type operator()}\ \\ 
        \texttt{(URNG \&urng, param\_type \&param)}\ \\ 
        returns the next random value from a geometric distribution
        initialized by the provided \texttt{param} struct.
    \item  The random number generator that is passed to the generating
       functions must return integral values. Here is an example showing how
        the geometric distribution can be used:
        \begin{verbatim}
#include <iostream>
#include <ctime>
#include <random>

int main()
{
    std::linear_congruential_engine<unsigned, 7, 3, 61> engine(0);

    std::geometric_distribution<> dist;

    for (size_t idx = 0; idx < 10; ++idx)
        std::cout << "a random value: " << dist(engine) << "\n";

    std::cout << '\n' <<
        dist.min() << " " << dist.max() << '\n';

}
\end{verbatim}
    \end{itemize}

\subsubsection{Log-normal distribution}
        \typeout{Original Yodl file: stl/lognormal}The \index{lognormal\_distribution\textless{}RealType = double\textgreater{}}\texttt{lognormal\_distribution$<$RealType = double$>$} is a probability
distribution of a random variable whose logarithm is normally distributed. If
a random variable \texttt{X} has a normal distribution, then \texttt{Y = e}$^{X}$ has a
log-normal distribution.

It has two parameters, \emph{m} and \emph{s} representing, respectively, the mean
and standard deviation of \texttt{ln(X)}.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType m = RealType(0),
                            RealType s = RealType(1));

        RealType m() const;
        RealType s() const;
    };
\end{verbatim}
Constructor and members:
    \begin{itemize}
    \item \texttt{lognormal\_distribution$<$$>$(RealType m = 0, RealType s = 1)}
       constructs a log-normal distribution for a random variable whose mean
        and standard deviation is, respectively, \texttt{m} and \texttt{s}.
    \item \texttt{lognormal\_distribution$<$$>$(param\_type const \&param)} constructs a
        log-normal distribution according to the values stored in the
        \texttt{param} struct.
    \item \texttt{RealType m() const}\ \\ 
        returns the distribution's \texttt{m} parameter;
    \item \texttt{RealType stddev() const}\ \\ 
        returns the distribution's \texttt{s} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Normal distribution}
        \typeout{Original Yodl file: stl/normal}The \index{normal\_distribution\textless{}RealType = double\textgreater{}}\texttt{normal\_distribution$<$RealType = double$>$} is commonly used in science to
describe complex phenomena. When predicting or measuring variables, errors are
commonly assumed to be normally distributed.

It has two parameters, \emph{mean} and \emph{standard deviation}.

Defined types:
       \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType mean = RealType(0),
                            RealType stddev = RealType(1));

        RealType mean() const;
        RealType stddev() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{normal\_distribution$<$$>$(RealType mean = 0, RealType stddev = 1)}
        constructs a normal distribution with specified \texttt{mean} and \texttt{stddev}
        parameters. The default parameter values define the
        \index{standard normal distribution}\emph{standard normal distribution};
    \item \texttt{normal\_distribution$<$$>$(param\_type const \&param)}
        constructs a normal distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType mean() const}\ \\ 
        returns the distribution's \texttt{mean} parameter;
    \item \texttt{RealType stddev() const}\ \\ 
        returns the distribution's \texttt{stddev} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns the lowest positive value of \texttt{result\_type};
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Negative binomial distribution}
        \typeout{Original Yodl file: stl/negativebinomial}The \index{negative\_binomial\_distribution\textless{}IntType = int\textgreater{}}\texttt{negative\_binomial\_distribution$<$IntType = int$>$} probability distribution
describes the number of successes in a sequence of Bernoulli trials before a
specified number of failures occurs. For example, if one throws a die
repeatedly until the third time 1 appears, then the probability distribution
of the number of other faces that have appeared is a negative binomial
distribution.

It has two parameters: (\texttt{IntType}) k ($>$ 0), being the number of failures
until the experiment is stopped and (\texttt{double}) p the probability of success
in each individual experiment.

Defined types:
        \begin{verbatim}
    using result_type = IntType;

    struct param_type
    {
        explicit param_type(IntType k = IntType(1), double p = 0.5);

        IntType k() const;
        double p() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{negative\_binomial\_distribution$<$$>$(IntType k = IntType(1),
                                                            double p = 0.5)}
       constructs a negative\_binomial distribution with specified \texttt{k} and
        \texttt{p} parameters;
    \item \texttt{negative\_binomial\_distribution$<$$>$(param\_type const \&param)}
       constructs a negative\_binomial distribution according to the values
        stored in the \texttt{param} struct.
    \item \texttt{IntType k() const}\ \\ 
        returns the distribution's \texttt{k} parameter;
    \item \texttt{double p() const}\ \\ 
        returns the distribution's \texttt{p} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Poisson distribution}
        \typeout{Original Yodl file: stl/poisson}The \index{poisson\_distribution\textless{}IntType = int\textgreater{}}\texttt{poisson\_distribution$<$IntType = int$>$} is used to model the probability
of a number of events occurring in a fixed period of time if these events
occur with a known probability and independently of the time since the last
event.

It has one parameter, \texttt{mean}, specifying the expected number of events in
the interval under consideration. E.g., if on average 2 events are observed in
a one-minute interval and the duration of the interval under study is
10 minutes then \texttt{mean = 20}.

Defined types:
        \begin{verbatim}
    using result_type = IntType;

    struct param_type
    {
        explicit param_type(double mean = 1.0);

        double mean() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{poisson\_distribution$<$$>$(double mean = 1)}
        constructs a poisson distribution with specified \texttt{mean}
        parameter.
    \item \texttt{poisson\_distribution$<$$>$(param\_type const \&param)}
        constructs a poisson distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{double mean() const}\ \\ 
        returns the distribution's \texttt{mean} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Student t distribution}
        \typeout{Original Yodl file: stl/studentt}The \index{student\_t\_distribution\textless{}RealType = double\textgreater{}}\texttt{student\_t\_distribution$<$RealType = double$>$} is a probability
distribution that is used when estimating the mean of a normally distributed
population from small sample sizes.

It is characterized by one parameter: the degrees of freedom, which is equal
to the sample size - 1.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType n = RealType(1));

        RealType n() const;    // The degrees of freedom
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{student\_t\_distribution$<$$>$(RealType n = RealType(1))}
        constructs a student\_t distribution with indicated degrees of freedom.
    \item \texttt{student\_t\_distribution$<$$>$(param\_type const \&param)}
        constructs a student\_t distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType n() const}\ \\ 
        returns the degrees of freedom;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\subsubsection{Uniform int distribution}
        \typeout{Original Yodl file: stl/uniformint}The \index{uniform\_int\_distribution\textless{}IntType = int\textgreater{}}\texttt{uniform\_int\_distribution$<$IntType = int$>$} can be used to select integral
values randomly from a range of uniformly distributed integral values.

It has two parameters, \texttt{a} and \texttt{b}, specifying, respectively, the lowest
value that can be returned and the highest value that can be returned.

Defined types:
        \begin{verbatim}
    using result_type = IntType;

    struct param_type
    {
        explicit param_type(IntType a = 0, IntType b = max(IntType));

        IntType a() const;
        IntType b() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{uniform\_int\_distribution$<$$>$(IntType a = 0, IntType b = max(IntType))}
        constructs a uniform\_int distribution for the specified range of
        values.
    \item \texttt{uniform\_int\_distribution$<$$>$(param\_type const \&param)}
        constructs a uniform\_int distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{IntType a() const}\ \\ 
        returns the distribution's \texttt{a} parameter;
    \item \texttt{IntType b() const}\ \\ 
        returns the distribution's \texttt{b} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns the distribution's \texttt{a} parameter;
    \item \texttt{result\_type max() const}\ \\ 
        returns the distribution's \texttt{b} parameter;
    \end{itemize}

\subsubsection{Uniform real distribution}
        \typeout{Original Yodl file: stl/uniformreal}The \index{uniform\_real\_distribution\textless{}RealType = double\textgreater{}}\texttt{uniform\_real\_distribution$<$RealType = double$>$} can be used to select
\texttt{RealType} values randomly from a range of uniformly distributed
\texttt{RealType} values.

It has two parameters, \texttt{a} and \texttt{b}, specifying, respectively, the
half-open range of values (\texttt{[a, b)}) that can be returned by the
distribution.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType a = 0, RealType b = max(RealType));

        RealType a() const;
        RealType b() const;
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{uniform\_real\_distribution$<$$>$(RealType a = 0, RealType b = max(RealType))}
        constructs a uniform\_real distribution for the specified range of
        values.
    \item \texttt{uniform\_real\_distribution$<$$>$(param\_type const \&param)}
        constructs a uniform\_real distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType a() const}\ \\ 
        returns the distribution's \texttt{a} parameter;
    \item \texttt{RealType b() const}\ \\ 
        returns the distribution's \texttt{b} parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns the distribution's \texttt{a} parameter;
    \item \texttt{result\_type max() const}\ \\ 
        returns the distribution's \texttt{b} parameter;
    \end{itemize}

\subsubsection{Weibull distribution}
        \typeout{Original Yodl file: stl/weibull}The \index{weibull\_distribution\textless{}RealType = double\textgreater{}}\texttt{weibull\_distribution$<$RealType = double$>$} is commonly used in
reliability engineering and in survival (life data) analysis.

It has two or three parameters and the two-parameter variant is offered by the
STL. The three parameter variant has a shape (or slope) parameter, a scale
parameter and a location parameter. The two parameter variant implicitly uses
the location parameter value 0. In the two parameter variant the shape
parameter (a) and the scale parameter (b) are provided. See \ \\ 
    \texttt{http://www.weibull.com/hotwire/issue14/relbasics14.htm} for an
interesting coverage of the meaning of the Weibull distribution's parameters.

Defined types:
        \begin{verbatim}
    using result_type = RealType;

    struct param_type
    {
        explicit param_type(RealType a = RealType{ 1 },
                            RealType b = RealType{ 1 });

        RealType a() const;     // the shape (slope) parameter
        RealType b() const;     // the scale parameter
    };
\end{verbatim}
Constructors and members:
    \begin{itemize}
    \item \texttt{weibull\_distribution$<$$>$(RealType a = 1, RealType b = 1)}
        constructs a weibull distribution with specified \texttt{a} and \texttt{b}
        parameters;
    \item \texttt{weibull\_distribution$<$$>$(param\_type const \&param)}
        constructs a weibull distribution according to the values stored in
        the \texttt{param} struct.
    \item \texttt{RealType a() const}\ \\ 
        returns the distribution's shape (or slope) parameter;
    \item \texttt{RealType stddev() const}\ \\ 
        returns the distribution's scale parameter;
    \item \texttt{result\_type min() const}\ \\ 
        returns 0;
    \item \texttt{result\_type max() const}\ \\ 
        returns the maximum value of \texttt{result\_type};
    \end{itemize}

\section{tie}\label{TIE}
\typeout{Original Yodl file: stl/tie}We already encountered \emph{structured bindings} in section
\ref{STRUCTBIND}. Structured bindings allow us to access the fields of
structured types (like \texttt{structs, std::pair} or (cf. section \ref{TUPLES})
\texttt{tuples}) as local variables inside functions. A basic example using
structured bindings is shown in the following code snippet:
    \begin{verbatim}
    pair<int, int> factory()
    {
        return { 1, 2 };
    }
    
    void fun()
    {
        auto [one, two] = factory();
    
        cout << one << ' ' << two << '\n';
    }
\end{verbatim}
Being able to use structured bindings is very useful in cases like these. 

But what if we want to assign the fields of a struct to variables that have
already been defined or that were passed to a function via its parameters? In
those situations structured bindings offer no help. E.g., in the following
code snippet a function \texttt{retrieve} is defined having an \texttt{int \&} parameter
and an \texttt{int} local variable and we want to assign the values returned by
\texttt{factory} to those variables:
        \begin{verbatim}
    void retrieve(int &one)
    {
        int two;
        // ...  = factory() ??
    }
\end{verbatim}
Structured bindings cannot be used here: the elements of structured bindings
cannot be references. Although it \emph{is} possible to define a \texttt{std::pair$<$int
\&, int \&$>$} such an object cannot be initialized with the references of \texttt{one}
and \texttt{two} which are directly referring to the fields returned by
\texttt{factory}. These statements won't compile:
        \begin{verbatim}
    pair<int &, int &> p{one, two} = factory();
    pair<int &, int &>{one, two} = factory();
\end{verbatim}
While it is possible to first define a \texttt{pair$<$int \&, int \&$>$} object and then
assign \texttt{factory's} return value to it, that approach clearly is less elegant
than what's offered by structured bindings:
        \begin{verbatim}
    pair<int &, int &> p{one, two};
    p = factory();
\end{verbatim}
Fortunately, there is a better alternative. After including the \index{tuple: header file}\texttt{$<$tuple$>$}
header file (see also section \ref{TUPLES}) \texttt{std::tie} is available allowing
us to `tie' references to fields of structured data types. Using \texttt{std::tie}
it is very easy to associate the variables \texttt{one} and \texttt{two} of the function
\texttt{retrieve} with the fields of the pair returned by \texttt{factory}:
    \begin{verbatim}
    void retrieve(int &one)
    {
        int two;
    
        tie(one, two) = factory();
    
        cout << one << ' ' << two << '\n';
    }
\end{verbatim}
When Executing these statements:
    \begin{verbatim}
    int one = 0;
    int two = 0;

    cout << one << ' ' << two << '\n';

    retrieve(one);

    cout << one << ' ' << two << '\n';
\end{verbatim}
the following output is obtained:
    \begin{verbatim}
    0 0
    1 2
    1 0
\end{verbatim}
In addition to the above the \texttt{std::tie} function also supports ordering and
(in)equality comparisons. The \texttt{struct Data} in the next example defines
three fields: an \texttt{int}, a \texttt{std::string} and a \texttt{double}. Each of these
fields support ordering and (in)equality comparisons. In those cases, all
comparison operators can easily be implemented through the spaceship
operator (cf. section \ref{SPACESHIP}) using \texttt{std::tie}:
    \begin{verbatim}
    struct Data
    {
        int d_int;
        string d_string;
        double d_double;
    };
    
    
    bool operator==(Data const &lhs, Data const &rhs)
    {
        return tie(lhs.d_int, lhs.d_string, lhs.d_double) ==
               tie(rhs.d_int, rhs.d_string, rhs.d_double);
    }
    
    partial_ordering operator<=>(Data const &lhs, Data const &rhs)
    {
        return tie(lhs.d_int, lhs.d_string, lhs.d_double) <=>
               tie(rhs.d_int, rhs.d_string, rhs.d_double);
    }
\end{verbatim}
Note that \texttt{struct Data's} spaceship operator returns \texttt{partial\_ordering}
values (cf. section \ref{PARTORD}). Although \texttt{int} and \texttt{std::string's}
spaceship operators return \texttt{strong\_ordering} values, \texttt{double's} spaceship
operator doesn't. Instead it returns \texttt{partial\_ordering}
values. Consequently, \texttt{struct Data's} spaceship operator also returns
\texttt{partial\_ordering} values.

\section{Optional return values}\label{OPTIONAL}
\typeout{Original Yodl file: stl/optional}In order to use \texttt{std::optional} objects the \index{optional: header file}\texttt{$<$optional$>$} header file must
be included.

Consider a function returning subsequent lines from a stream. That function
could be a member function reading from a stream which was opened by its
object. A first implementation of such a member function could be
        \begin{verbatim}
    std::string Class::nextLine()
    {
        string line;
        getline(d_stream, line);
        return line;
    }
\end{verbatim}
    Of course, this implementation is sub-optimal as \texttt{getline} may fail.

Common ways to handle failures in these situations are
    \begin{itemize}
    \item  the functions return pointers to strings, which are 0 when
        \texttt{getline} fails, and point to strings containing the lines
        if \texttt{getline} succeeds;
    \item  the functions return bools and define string pointers or reference
        parameters: the functions' return values indicate whether or not
        \texttt{getline} succeeded;
    \item  the functions return \texttt{std::pair} or \texttt{std::tuple} objects of which
        one field is a \texttt{bool} and the other field is a \texttt{std::string}.
    \end{itemize}

The standard template library offers yet another way to handle situations like
these: the template class 
        \begin{verbatim}
    template <typename DataType>
    class optional;
\end{verbatim}
    Here, \texttt{DataType} refers to the name of the data type that is handled by
the \texttt{optional} class. Instead of returning a \texttt{std::string} the function
\texttt{nextLine} may specify a \texttt{std::optional$<$std::string$>$} return type:
\texttt{std::optional$<$std::string$>$ Class::nextLine()}.

The interpretation of \texttt{std::optional} objects is simple: either it contains
an object of its \texttt{DataType} or it doesn't. If it \emph{does} contain a
\texttt{DataType} object then that object is available as object instead of a
pointer to an object (which might have been dynamically allocated) of the
specified \texttt{DataType}. At the same type the \texttt{optional} object can be
interpreted as a \texttt{bool}. If the \texttt{optional} object contains a \texttt{DataType}
object the \texttt{optional's bool} value is \texttt{true}. If it doesn't contain a
\texttt{DataType} value, then its \texttt{bool} value is \texttt{false}. 

The class \texttt{std::optional} offers the following facilities:
    \begin{itemize}
    \item  Constructors\ \\ 
       The default constructor (e.g., \texttt{std::optional$<$std::string$>$ opt;})
        does not contain a value;\ \\ 
       copy- and move constructors are available;\ \\ 
       objects may be constructed from values that are convertible to the
        optional's \texttt{DataType} (e.g., an \texttt{optional$<$string$>$} can be
        initialized from a NTBS). If the initializing value is an rvalue
        reference then the \texttt{DataType} object is move-constructed from the
        initializing value;

\item \texttt{operator=}\ \\ 
       the assignment operator can be used to reassign the \texttt{DataType} values
        of \texttt{optional} objects or to reassign the \texttt{optional} objects from
        another \texttt{optional} object using the same \texttt{DataType}. Copy- and
        move-assignment operators are available;

\item  Accessors\ \\ 
       \texttt{explicit operator bool()} and the \texttt{has\_value()} members return
        \texttt{true} if the \texttt{optional} object contains a \texttt{DataType} value;\ \\ 
       \texttt{value(), operator$*$(),} and \texttt{operator-$>$()} return references to the
        optional's \texttt{DataType} value. The reference is a \texttt{const} reference
        if called from an \texttt{optional$<$DataType$>$ const} object; it is an
        rvalue-reference if called from an rvalue reference to an
        \texttt{optional$<$DataType$>$} object. Notes:
            \begin{itemize}
            \item  the \texttt{operator$*$} and
               \texttt{operator-$>$} members act like \texttt{value}, but do not imply
                that the \texttt{optional's DataType} member itself is stored as a
                pointer;
            \item \texttt{value()} checks whether the \texttt{optional} object actually
                contains a \texttt{DataType} object, and throws a
                \texttt{std::bad\_optional\_access} exception if not.
            \end{itemize}

\texttt{value\_or(Type \&\&defaultValue)} returns a copy of the \texttt{optional}
        object's \texttt{DataType} if the object contains a value or returns
        \texttt{DataType\{ defaultValue \}} if not. Note that \texttt{DataType} must be
        constructible from \texttt{Type};

\item  Modifiers\ \\ 
       \texttt{swap(optional$<$DataType$>$ \&other)}: swaps the current and other
        \texttt{optional} objects' content.\ \\ 
       \texttt{reset()}: erases the \texttt{optional's DataType} member. Following
        \texttt{reset() has\_value()} returns \texttt{false}.\ \\ 
       \texttt{emplace(Args \&\&...args), emplace(initialize\_list, Args \&\&...args)}:
        the first \texttt{emplace} forwards \texttt{args} to \texttt{DataType's} constructor;
        the second \texttt{emplace} forwards \texttt{args} to the initializer\_list, and
        forwards that list to \texttt{DataType's} constructor;

\item  Comparison operators\ \\ 
        all comparison operators (including \texttt{operator$<$=$>$}) are available (if
        defined for the \texttt{optional's DataType}) to compare the \texttt{DataType}
        objects of two \texttt{optional} objects;

\item \texttt{std::optional$<$DataType$>$ make\_optional(...)}\ \\ 
       returns an \texttt{optional} object constructed from a \texttt{DataType} lvalue
        or rvalue reference, or constructed from the same arguments that are
        accepted by \texttt{emplace}.
    \end{itemize}

Here is the implementation of a function \texttt{nextLine}, using
\texttt{std::optional$<$std::string$>$} and a simple \texttt{main} function illustrating its
workings: 
    \begin{verbatim}
    #include <iostream>
    #include <sstream>
    #include <string>
    #include <optional>

    using namespace std;

    optional<string> nextLine(istream &in)
    {
        std::optional<std::string> opt;

        string line;
        if (getline(in, line))
            opt = move(line);

        cout << "internal: has value: " << opt.has_value() <<
                                    ", value = " << *opt << '\n';
        return opt;
    }

    int main()
    {
        istringstream in{ "hello world\n" };

        auto opt = nextLine(in);

        cout << "main:     has value: " << opt.has_value() <<
                                    ", value = " << *opt << '\n';
        opt = nextLine(in);

        cout << "main:     has value: " << opt.has_value() <<
                                    ", value = " << *opt << '\n';
    }
\end{verbatim}
The ouput of this program is:
    \begin{verbatim}
    internal: has value: 1, value = hello world
    main:     has value: 1, value = hello world
    internal: has value: 0, value = 
    main:     has value: 0, value = hello world
\end{verbatim}
Note that after the 2nd call, when no value is returned, \texttt{opt} has kept the
value it received at the first call: \texttt{optional's} assignment operator
doesn't bother about values already present in their objects once it notices
that \texttt{has\_value} will return \texttt{false}. So be sure to inspect \texttt{has\_value}
or \texttt{operator bool} before calling \texttt{value}.


\cleardoublepage\chapter{The STL Generic Algorithms}\label{GENERIC}
\typeout{Original Yodl file: generic}\section{The Generic Algorithms}
\typeout{Original Yodl file: generic/intro}Before using the generic algorithms presented in this chapter, except for
those in the \texttt{Operators} category (defined below), the \index{algorithm: header file}\texttt{$<$algorithm$>$} header
file must be included. Before using a generic algorithm in the
\texttt{Operators} category the \index{numeric: header file}\texttt{$<$numeric$>$} header file must be included.

In the previous chapter the Standard Template Library (STL) was introduced. An
important element of the STL, the \index{generic algorithms}\emph{generic algorithms}, was not covered in
that chapter as they form a fairly extensive part of the STL.  Over time the
STL has grown considerably, mainly as a result of a growing importance and
appreciation of \emph{templates}. Covering generic algorithm in the STL chapter
itself would turn that chapter into an unwieldy one and so the generic
algorithms were moved to a chapter of their own.

Generic algorithms perform an amazing task. Due to the strength of templates,
algorithms could be developed that can be applied to a wide range of different
data types while maintaining type safety. The prototypical example of this is
the \texttt{sort} generic algorithm. To contrast: while \textbf{C} requires
programmers to write callback functions in which type-unsafe \texttt{void const $*$}
parameters have to be used, internally forcing the programmer to resort to
casts, STL's \texttt{sort} frequently allows the programmer merely to state
something akin to
        \begin{verbatim}
    sort(first-element, last-element)
\end{verbatim}
Generic algorithms should be used wherever possible. Avoid the urge to design
your own code for commonly encountered algorithms. Make it a habit to
\emph{first} thoroughly search the generic algorithms for an available
candidate. The generic algorithms should become your \emph{weapon of choice} when
writing code: acquire full familiarity with them and make their use your
`second nature'.

On the other hand, without downgrading the importance of the generic
algorithms, it's clear that over the years the number of available generic
algorithms have seen an almost unlimited growth. Many new algorithms were
added, even though for quite a few of them it's either very easy to provide
direct implementations, or which may hardly ever be used. An
example is the \texttt{is\_sorted} generic algorithm, simply returning \texttt{true} if a
range of elements is considered sorted and \texttt{false} if not. How hard is it to
define such a function in the occasional situation you might need it? This
applies to quite a few other generic algorithms. It's of course nice to have
an extensive toolbox, but do you need, e.g., screwdrivers that
perfectly match the screws' heads? Most likely not.... To avoid an excessive
growth of this chapter, some sections contain comparable algorithms, and in
some sections links to \texttt{cppreference}\footnote{https://en.cppreference.com} are
provided when referring to comparable algorithms. 

Nevertheless, this chapter's sections cover many of the STL's
    \index{generic algorithms}generic algorithms (in alphabetical order). For each algorithm the
following information is provided:
    \begin{itemize}
    \item  The required header file;
    \item  The function prototype;
    \item  A short description;
    \item  A short example.
    \end{itemize}
    In the prototypes of the algorithms \texttt{Type} is used to specify a
\index{generic data type}generic data type. Furthermore, the particular type of iterator (see
section \ref{ITERATORS}) that is required is mentioned as well as other generic
types that might be required (e.g., performing \texttt{BinaryOperations}, like
\texttt{plus$<$Type$>$}). Although iterators are commonly provided by abstract
containers and comparable pre-defined data structures, at some point you may
want to design your own iterators. Section \ref{ITERATORCONS} offers guidelines
for constructing your own iterator classes and provides an overview of of
operators that must be implemented for the various types of iterators.

Almost every generic algorithm expects an iterator range \index{[first, last)}\texttt{[first, last)},
defining the series of elements on which the algorithm operates. The iterators
point to objects or values. When an iterator points to a \texttt{Type} value or
object, function objects used by the algorithms usually receive \texttt{Type const
\&} objects or values. Usually function objects cannot modify the objects they
receive as their arguments. This does not hold true for \emph{modifying generic
algorithms}, which \emph{are} of course able to modify the objects they operate
upon.

\index{generic algorithm: categories} Generic algorithms may be categorized.  The
\textbf{C++} Annotations distinguishes the following categories of generic algorithms:
    \begin{itemize}
    \item  Comparators: comparing (ranges of) elements:
        \begin{quote}
            all\_of; any\_of;
            equal;
            includes;
            lexicographical\_compare;
            mismatch;
            none\_of;
        \end{quote}
    \item  Copiers / movers: performing copy / move operations:
        \begin{quote}
            copy;
            copy\_backward;
            copy\_if;
            move; move\_backward;
            partition\_copy;
            partial\_sort\_copy;
            remove\_copy; remove\_copy\_if;
            replace\_copy; replace\_copy\_if;
            reverse\_copy;
            rotate\_copy;
            sample;
            shift\_left; shift\_right;
            unique\_copy;
        \end{quote}
    \item  Counters: performing count operations:
        \begin{quote}
            count; count\_if;
        \end{quote}
    \item  Heap operators: manipulating a \index{max-heap}max-heap:
        \begin{quote}
            make\_heap;
            pop\_heap;
            push\_heap;
            sort\_heap;
        \end{quote}
    \item  Initializers: initializing data:
        \begin{quote}
            fill; fill\_n;
            generate; generate\_n;
            iota;
            uninitialized (raw) memory;
        \end{quote}
    \item  Limiters: determining boundaries of data:
        \begin{quote}
            begin; end;
        \end{quote}
    \item  Operators: performing some kind of (arithmetic?) operations:
        \begin{quote}
            accumulate;
            adjacent\_difference;
            exclusive\_scan; inclusive\_scan;
            inner\_product;
            partial\_sum;
            reduce;
            transform\_reduce;
        \end{quote}
    \item  Searchers: performing search (and find) operations:
        \begin{quote}
            adjacent\_find;
            binary\_search;
            equal\_range;
            find;
            find\_end;
            find\_first\_of;
            find\_if; find\_if\_not;
            lower\_bound;
            max;
            max\_element; min\_element;
            min;
            minmax;
            minmax\_element;
            partition\_point;
            search; search\_n;
            set\_difference;
            set\_intersection;\ \\ 
            set\_symmetric\_difference;
            set\_union;
            upper\_bound;
        \end{quote}
    \item  Shufflers: performing reordering operations (\index{sorting}sorting,
            \index{merging}merging, \index{permuting}permuting, \index{swapping}swapping):
        \begin{quote}
            inplace\_merge;
            iter\_swap;
            merge;
            next\_permutation;
            nth\_element;
            partial\_sort;
            partition;
            prev\_permutation;
            remove; remove\_copy; remove\_copy\_if; remove\_if;
            reverse; reverse\_copy;
            rotate; rotate\_copy;
            shuffle;
            sort;
            stable\_partition;
            stable\_sort;
            swap; swap\_ranges;
            unique;
        \end{quote}
    \item  Verifiers: checking for specific conditions:
        \begin{quote}
            is\_partitioned;
            is\_permutation;
            is\_sorted;
            is\_sorted\_until;
        \end{quote}
    \item  Visitors: visiting elements in a range:
        \begin{quote}
            for\_each;
            replace; replace\_copy; replace\_copy\_if; replace\_if;
            transform;
            unique\_copy;
        \end{quote}
    \end{itemize}

\subsection{Execution policies}\label{EXEC}
    \typeout{Original Yodl file: generic/execpol}Many of the following generic algorithms could very well be parallized. E.g.,
one of the following algorithms is \texttt{generate} (section \ref{GEN}), filling
the elements with values produced by a generating function. If those values
are randomly generated values then \texttt{generated} could very well be
parallized, where each parallel thread handles a separate section of the range
to be filled. Another example where parallel execution may be useful is when
sorting series of values. For this the the \texttt{sort} generic algorithm can be
used (section \ref{SORT}, which also contains an example of parallelized
sorting).

These (and many other) generic algorithms can be executed in parallel,
depending on the specified \index{execution policy}\emph{execution policy}. When no execution policy is
specified then the algorithms operated in their standard, sequential, way. The
generic algorithms supporting execution policies have overloaded versions
where the first parameter specifies the execution policy to use, followed by
their remaining parameters. Function prototypes listed the following sections
showing a first parameter \index{[ExecPol,]}\texttt{{[}ExecPol,{]}} may specify one of the execution
policies introduced in this section as their first arguments. E.g., one of the
\texttt{sort} generic algorithm's prototypes is 
    \begin{verbatim}
   void sort([ExecPol,] 
        RandomAccessIterator first, RandomAccessIterator last);
\end{verbatim}
and to sort, e.g., a vector if strings (\texttt{vs}), it can be called as
    \begin{verbatim}
   sort(vs.bgin(), vs.end());
\end{verbatim}
or as (see below)
    \begin{verbatim}
   sort(execution::par, vs.bgin(), vs.end());
\end{verbatim}
In order to use execution policies the \index{execution: header file}\texttt{$<$execution$>$} header file must be
included, and the linking option \index{-ltbb}\texttt{-ltbb} must be specified with linking the
compiled object files(s).

There are four types of execution policies (all defined in the \texttt{std}
namespace):
    \begin{itemize}
    \item \index{execution::sequenced\_policy: header file}\texttt{$<$execution::sequenced\_policy$>$}, whose predefined object
        \index{execution::seq}\texttt{execution::seq} is used to specify this execution policy when
        calling generic algorithms.

When calling a generic algorithm specifying this policy it will not 
        be using parallel execution.

\item \index{execution::parallel\_policy: header file}\texttt{$<$execution::parallel\_policy$>$}, whose predefined object
        \index{execution::par}\texttt{execution::par} is used to specify this execution policy when
        calling generic algorithms.

When calling a generic algorithm specifying this policy it may 
        be using parallel execution: the generic algorithm may decide not to
        use parallel execution when it decides that the overhead of parallel
        execution is in fact reducing the efficiency of non-parallel
        execution. E.g., when sorting 100 elements sequential execution is
        faster than parallel execution and an algorithm like \texttt{sort} won't
        use parallel execution.

\item \index{execution::parallel\_unsequenced\_policy: header file}\texttt{$<$execution::parallel\_unsequenced\_policy$>$}, whose predefined object
        \index{execution::par\_unseq}\texttt{execution::par\_unseq} is used to specify this execution policy when
        calling generic algorithms.

When calling a generic algorithm specifying this policy it may be
        using parallel execution, execution may be migrated across threads
        (using a so-called \emph{parent-stealing scheduler}), or execution may be
        \index{vectorized execution}vectorized (i.e., a single thread is used
        accessing data items at completely different locations (like swapping
        the first and middle elements of vectors)). When using this
        policy the order in which processed elements are accessed and the
        threads from which these elements are accessed is undefined.

\item \index{execution::unsequenced\_policy: header file}\texttt{$<$execution::unsequenced\_policy$>$}, whose predefined object
        \index{execution::unseq}\texttt{execution::unseq} is used to specify this execution policy when
        calling generic algorithms. 

When calling a generic algorithm specifying this policy the algorithm
        uses vectorized execution.
    \end{itemize}

Whenever algorithms are called using the above policy specifications and
during the execution of these algorithms functions are called generating
uncaught exceptions \texttt{std::terminate} is called.

When using parallel execution the objects or functions passed to the generic
algorithms might access data defined elsewhere. If those data are modified
then it is possible that modifications are requested from different execution
threads, which could result in \index{data race}\emph{data races} or 
\index{deadlock}\emph{deadlocks}. The programmer should ensure that data races and/or
dadlocks cannot occur when using parallel execution.

\subsection{accumulate}\label{ACCU}
    \typeout{Original Yodl file: generic/accumulate}    \index{accumulate}
    \begin{itemize}
    \item  Header file: \texttt{$<$numeric$>$}
    \item  Function prototypes:
        \begin{itemize}
        \item \texttt{Type accumulate(InputIterator first, InputIterator last,
            Type init);}
        \item \texttt{Type accumulate(InputIterator first, InputIterator
            last, Type init, BinaryOperation op);}
        \end{itemize}
    \item  Description:
        \begin{itemize}
        \item  The first prototype: \index{operator+}\texttt{operator+} is applied to the initial
value \texttt{init} (lhs argument) and, in sequence, all elements reached from
the iterator range (rhs argument). The resulting value is returned.
        \item  The second prototype: the binary operator \texttt{op} is applied to
the initial value \texttt{init} (lhs argument) and, in sequence, all elements
reached from the iterator range. The resulting value is returned.
        \end{itemize}
       At each step the initial value receives the result of that step's
        computation. E.g., if \texttt{minus$<$int$>$} is used with the intial value 1,
        and the iterators refer to 2 and 3, then at step 1: 1 - 2 = -1 is
        computed and at step 2: -1 - 3 = -4. So \texttt{accumulate} returns -4.

(See also the \texttt{reduce} algorithm (section \ref{REDUCE})).

\item  Example:
        \begin{verbatim}
    #include <numeric>
    #include <vector>
    #include <iostream>
    using namespace std;

    int main()
    {
        int         ia[] = {1, 2, 3, 4};
        vector<int> iv(ia, ia + 4);

        cout <<
            "Sum: " << accumulate(iv.begin(), iv.end(), int()) << "\n"
            "Product: " << accumulate(iv.begin(), iv.end(), int(1),
                                            multiplies<int>{}) << '\n';
    }
    //  Displays:
    //      Sum: 10
    //      Product: 24
\end{verbatim}
    \end{itemize}

\subsection{adjacent\_difference}\label{ADJDIFF}
    \typeout{Original Yodl file: generic/adjacentdifference}    \index{adjacent\_difference}
    \begin{itemize}
    \item  Header file: \texttt{$<$numeric$>$}
    \item  Function prototypes:
        \begin{itemize}
        \item \texttt{OutputIterator adjacent\_difference({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator result);}
        \item \texttt{OutputIterator adjacent\_difference({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator result, BinaryOperation op);}
        \end{itemize}
        \item  Description:
            All operations are performed on the original values, all computed
values are returned values.
            \begin{itemize}
            \item  The first prototype: the first returned element is equal to
the first element of the input range. The remaining returned elements are
equal to the difference of the corresponding element in the input range and
its previous element.
            \item  The second prototype: the first returned element is equal to
    the first element of the input range. The remaining returned elements are
equal to the result of the binary operator \texttt{op} applied to the
corresponding element in the input range (left operand) and its previous
element (right operand).
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <numeric>
    #include <vector>
    #include <iterator>
    #include <iostream>
    using namespace std;

    int main()
    {
        int             ia[] = {1, 2, 5, 10};
        vector<int>     iv(ia, ia + 4);
        vector<int>     ov(iv.size());

        adjacent_difference(iv.begin(), iv.end(), ov.begin());

        copy(ov.begin(), ov.end(), ostream_iterator<int>(cout, " "));
        cout << '\n';

        adjacent_difference(iv.begin(), iv.end(), ov.begin(), minus<int>());

        copy(ov.begin(), ov.end(), ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      1 1 3 5
    //      1 1 3 5
\end{verbatim}
    \end{itemize}

\subsection{adjacent\_find}\label{ADJFIND}
    \typeout{Original Yodl file: generic/adjacentfind}    \index{adjacent\_find}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator adjacent\_find({[}ExecPol,{]} 
ForwardIterator first, ForwardIterator last);}
            \item \texttt{OutputIterator adjacent\_find({[}ExecPol,{]} ForwardIterator first,
ForwardIterator last, Predicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the iterator pointing to the first
element of the first pair of two adjacent equal elements is returned. If no
such element exists, \texttt{last} is returned.
            \item  The second prototype: the iterator pointing to the first
element of the first pair of two adjacent elements for which the binary
predicate \texttt{pred} returns \texttt{true} is returned. If no such element exists,
\texttt{last} is returned.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    using namespace std;

    bool squaresDiff10(size_t first, size_t second)
    {
        return second * second - first * first >= 10;
    }

    int main()
    {
        string sarr[] =
            {
                "Alpha", "bravo", "charley", "delta", "echo", "echo",
                "foxtrot", "golf"
            };
        auto last = end(sarr);          // see the 'begin / end' section
        string *result = adjacent_find(sarr, last);

        cout << *result << '\n';
        result = adjacent_find(++result, last);

        cout << "Second time, starting from the next position:\n" <<
            (
                result == last ?
                    "** No more adjacent equal elements **"
                :
                    "*result"
            ) << '\n';

        size_t iv[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
        size_t *ires = adjacent_find(iv, end(iv), squaresDiff10);

        cout <<
            "The first numbers for which the squares differ at least 10: "
            << *ires << " and " << *(ires + 1) << '\n';
    }
    // Displays:
    //
    //   echo
    //   Second time, starting from the next position:
    //   ** No more adjacent equal elements **
    //   The first numbers for which the squares differ at least 10: 5 and 6
\end{verbatim}
    \end{itemize}

\subsection{all\_of / any\_of / none\_of}\label{XOF}
    \typeout{Original Yodl file: generic/allof}    \index{all\_of} \index{any\_of} \index{none\_of}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool all\_of({[}ExecPol,{]} InputIterator first,
                     InputIterator last, Predicate pred);}
            \item \texttt{bool any\_of({[}ExecPol,{]} InputIterator first,
                     InputIterator last, Predicate pred);}
            \item \texttt{bool none\_of({[}ExecPol,{]} InputIterator first,
                     InputIterator last, Predicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype returns \texttt{true} if the unary predicate
\texttt{pred} returns \texttt{true} for all elements reached from the iterator range
\texttt{[first, last)}; otherwise \texttt{false} is returned.
            \item  The second prototype returns \texttt{true} if the unary predicate
\texttt{pred} returns \texttt{true} for at least on of the elements reached from the
iterator range \texttt{[first, last)}; otherwise \texttt{false} is returned.
            \item  The third prototype returns \texttt{true} if the unary predicate
\texttt{pred} returns \texttt{true} for none of the elements reached from the iterator
range \texttt{[first, last)}; otherwise \texttt{false} is returned.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    using namespace std;

    bool contains_a(string const &str)
    {
        return str.find('a') != string::npos;
    }

    int main()
    {
        string sarr[] =
            { "Alpha", "Bravo", "Charley", "Delta", "Echo" };
        auto past = end(sarr);      // see the next section

        cout << "All elements contain 'a': " <<
            all_of(sarr, past, contains_a) << "\n"
            "At least one element contains 'a': " <<
            any_of(sarr, past, contains_a) << "\n"
            "None of the elements contains 'a': " <<
            none_of(sarr, past, contains_a) << '\n';
    }
    //  Displays:
    //      All elements contain 'a': 0
    //      At least one element contains 'a': 1
    //      None of the elements contains 'a': 0
\end{verbatim}
    \end{itemize}

\subsection{begin / end}\label{BEGEND}     
    \typeout{Original Yodl file: generic/beginend}    \index{begin} \index{end} \index{cbegin} \index{cend} 
    \begin{itemize}
        \item  Header file: \texttt{$<$iterator$>$} (also available when including
                \texttt{$<$algorithm$>$})
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{auto begin({[}const{]} \&obj);}
            \item \texttt{auto end({[}const{]} \&obj);}
            \item \texttt{Type {[}cons{]} $*$begin(Type {[}const{]} (\&array){[}N{]});}
            \item \texttt{Type {[}cons{]} $*$end(Type {[}const{]} (\&array){[}N{]});}
            \item \texttt{auto cbegin(const \&obj);}
            \item \texttt{auto cend(const \&obj);}
        \end{itemize}
        \item  Description:
        The \texttt{begin} and \texttt{end} functions return, respectively, the begin-
and end-iterators or pointers of objects offering \texttt{begin()} and \texttt{end()}
members or of arrays of (compile-time) available sizes.
        \begin{itemize}
            \item  The first two prototypes return, respectively,
                \texttt{obj.begin()} and \texttt{obj.end()} of (possibly \texttt{const})
                references to \texttt{obj}
            \item  Prototypes three and four return (possibly \texttt{const})
                pointers to, respectively, the first and beyond the last
                element of the \texttt{array} argument, which must be an array of
                (compile-time) known size.
            \item  The lastt two prototypes return, respectively,
                \texttt{obj.begin()} and \texttt{obj.end()} of \texttt{const}
                references to \texttt{obj}
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <iterator>
    #include <iostream>
    #include <string>
    using namespace std;

    int main()
    {
        string sarr[] =
            { "Alpha", "Bravo", "Charley", "Delta", "Echo" };

        // since sarr == begin(sarr), begin(...) is not used here
        auto next = end(sarr);

        cout << "sarr has " << size(sarr) <<
                " (== " << (next - sarr) << ") elements\n"
                "the last char. of the first element is " <<
                *(end(sarr[0]) - 1) << '\n';
    }
    //  Displays:
    //    sarr has 5 (== 5) elements
    //    the last char. of the first element is a
\end{verbatim}
    \end{itemize}

\subsection{binary\_search}\label{BINSRCH}
    \typeout{Original Yodl file: generic/binarysearch}    \index{binary\_search}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool binary\_search(ForwardIterator first, ForwardIterator
last, Type const \&value);}
            \item \texttt{bool binary\_search(ForwardIterator first, ForwardIterator
last, Type const \&value, Comparator comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: \texttt{value} is searched for using binary
search in the elements reached from the iterator range \texttt{[first,
last)}. The elements must have been sorted by the \texttt{Type::operator$<$}
function. \texttt{True} is returned if the element was found, \texttt{false} otherwise.
            \item  The second prototype: \texttt{value} is searched for using binary
search in the elements reached from the iterator range \texttt{[first,
last)}. The elements in the range must have been sorted by the \texttt{Comparator}
function object. \texttt{True} is returned if the element was found, \texttt{false}
otherwise. As illustrated by the following example, the function object
function's first parameter refers to an element in the iterator range, while
the function object's second parameter refers to \texttt{value}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <functional>
    using namespace std;

    int main()
    {
        string sarr[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel"
            };
        auto past = end(sarr);
        bool result = binary_search(sarr, past, "foxtrot");
        cout << (result ? "found " : "didn't find ") << "foxtrot" << '\n';

        reverse(sarr, past);                // reverse the order of elements
                                            // binary search now fails:
        result = binary_search(sarr, past, "foxtrot");
        cout << (result ? "found " : "didn't find ") << "foxtrot" << '\n';
                                            // ok when using appropriate
                                            // comparator:
        result = binary_search(sarr, past, "foxtrot", greater<string>());
        cout << (result ? "found " : "didn't find ") << "foxtrot" << '\n';

        // alternatively, using a lambda expression showing the used 'sarr'
        // indices and the value of the second parameter:

        result = binary_search(sarr, past, "foxtrot",
            [&](string const &sarrEl, string const &value)
            {
                cout << "comparing element " << (&sarrEl - sarr) <<
                        " (" << sarrEl << ") to " << value << '\n';
                return sarrEl > value;
            }
        );
        cout << "found it: " << result << '\n';
    }
    //  Displays:
    //      found foxtrot
    //      didn't find foxtrot
    //      found foxtrot
    //      comparing element 4 (delta) to foxtrot
    //      comparing element 2 (foxtrot) to foxtrot
    //      comparing element 1 (golf) to foxtrot
    //      comparing element -3 (foxtrot) to foxtrot
    //      found it: 1
\end{verbatim}
    \end{itemize}

If \texttt{value} is in fact present in the range of values, then this generic
algorithm doesn't answer the question where \texttt{value} is located. If that
question must be answered the generic algorithms lower\_bound
and upper\_bound can be used. Refer to sections
\ref{LOWERBOUND} and \ref{UPPERBOUND} for examples illustrating the use of these
latter two algorithms.

\subsection{copy / copy\_if}\label{COPY}
    \typeout{Original Yodl file: generic/copy}    \index{copy} \index{copy\_if}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator copy({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator destination);}
            \item \texttt{OutputIterator copy\_if({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator destination, Predicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  First prototype: the elements reached from the iterator range
\texttt{[first, last)} are copied (assigned) to the \texttt{destination} output
range. The return value is the OutputIterator pointing just beyond the last
element that was copied to the destination range (so, `last' in the
destination range is returned).
            \item  Second prototype: same as the first prototype but the
function ends after copying \texttt{n} elements, returning an iterator pointing
just beyond the last element that was copied to the destination range.
        \end{itemize}
        \item  Example:\ \\ 
    Note the second call to \texttt{copy}. It uses an \texttt{ostream\_iterator} for
\texttt{string} objects. This iterator writes the \texttt{string} values to the
specified \texttt{ostream} (i.e., \texttt{cout}), separating the values by the specified
separation string (i.e., \texttt{" "}).
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <iterator>
    using namespace std;

    bool pred(std::string const &str)
    {
        return "aceg"s.find(str.front()) == string::npos;
    }

    int main()
    {
        string sarr[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel"
            };
        auto last = end(sarr);

        copy(sarr + 2, last, sarr); // move all elements two positions left

                     // copy to cout using an ostream_iterator for strings
        copy(sarr, last, ostream_iterator<string>(cout, " "));
        cout << '\n';

                    // using copy_if:
        copy_if(sarr, sarr + size(sarr), sarr, pred);
        copy(sarr, sarr + size(sarr), ostream_iterator<string>(cout, " "));
        cout << '\n';

    }
    //  Displays:
    //  charley delta echo foxtrot golf hotel golf hotel
    //  delta foxtrot hotel hotel golf hotel golf hotel
\end{verbatim}
        \item  See also:
            \texttt{unique\_copy}
    \end{itemize}

\subsection{copy\_backward}\label{COPYBACK}
    \typeout{Original Yodl file: generic/copybackward}    \index{copy\_backward}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{BidirectionalIterator copy\_backward(InputIterator first,
InputIterator last, BidirectionalIterator last2);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The series of elements reached from the iterator range
\texttt{[first, last)} are copied from the element at position \texttt{last - 1}
until (and including) the element at position \texttt{first} to the element range,
\emph{ending} at position \texttt{last2 - 1} using the assignment operator of the
underlying data type. The destination range is therefore \texttt{[last2 - (last
- first), last2)}.

Note that this algorithm does \emph{not} reverse the order of the elements when
copying them to the destination range.

The return value is the BidirectionalIterator pointing to the last element
that was copied to the destination range (so, `first' in the destination
range, pointed to by \texttt{last2 - (last - first)}, is returned).
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <iterator>
    using namespace std;

    int main()
    {
        string sarr[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel"
            };
        auto past = end(sarr);

        copy
        (
            copy_backward(sarr + 3, past, past - 3),
            past,
            ostream_iterator<string>(cout, " ")
        );
        cout << '\n';
    }
    // Displays:    golf hotel foxtrot golf hotel foxtrot golf hotel
\end{verbatim}
    \end{itemize}

\subsection{count / count\_if}\label{COUNT}
    \typeout{Original Yodl file: generic/count}    \index{count}     \index{count\_if}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{size\_t count({[}ExecPol,{]} InputIterator first, 
                InputIterator last, Type const \&value);}
            \item \texttt{size\_t count\_if({[}ExecPol,{]} InputIterator first,
                InputIterator last, Predicate predicate);}

\end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: returns the number of times \texttt{value}
occurs in the elements reached from the iterator range \texttt{[first, last)}.
Uses \texttt{Type::operator==} to determine whether \texttt{value} is equal to an
element in the iterator range.
            \item  The second prototype: returns the number of times
    \index{unary predicate}unary predicate `\texttt{predicate}' returns \texttt{true} when applied to the
elements reached from the iterator range \texttt{[first, last)}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    using namespace std;

    bool pred(int value)
    {
        return value & 1;
    }

    int main()
    {
        int ia[] = {1, 2, 3, 4, 3, 4, 2, 1, 3};

        cout << "Number of times the value 3 is available: " <<
                count(ia, ia + size(ia), 3) << "\n"
                "Number of odd values in the array is: " <<
                count_if(ia, ia + size(ia), pred) << '\n';

    }
    // Displays:    Number of times the value 3 is available: 3
    //              Number of odd values in the array is: 5
\end{verbatim}
    \end{itemize}

\subsection{equal}\label{EQUAL}
    \typeout{Original Yodl file: generic/equal}    \index{equal}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool equal({[}ExecPol,{]} InputIterator first, InputIterator
                last, InputIterator otherFirst);}
            \item \texttt{bool equal({[}ExecPol,{]} InputIterator first, InputIterator last,
                InputIterator otherFirst, BinaryPredicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the elements in the range \texttt{[first,
last)} are compared to a range of equal length starting at \texttt{otherFirst}. The
function returns \texttt{true} if the visited elements in both ranges are equal
pairwise. The ranges need not be of equal length, only the elements in the
indicated range are considered (and must be available).
            \item  The second prototype: the elements in the range
\texttt{[first, last)} are compared to a range of equal length starting at
\texttt{otherFirst}. The function returns \texttt{true} if the binary predicate, applied
to all corresponding elements in both ranges returns \texttt{true} for every pair
of corresponding elements.  The ranges need not be of equal length, only the
elements in the indicated range are considered (and must be available).
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <cstring>
    #include <iostream>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) == 0;
    }

    int main()
    {
        string first[] =
            {
                "Alpha", "bravo", "Charley", "delta", "Echo",
                "foxtrot", "Golf", "hotel"
            };
        string second[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel"
            };
        auto past = end(first);

        cout << "The elements of `first' and `second' are pairwise " <<
            (equal(first, past, second) ? "equal" : "not equal") <<
            '\n' <<
            "compared case-insensitively, they are " <<
            (
                equal(first, past, second, caseString) ?
                    "equal" : "not equal"
            ) << '\n';
    }
    //  Displays:
    //      The elements of `first' and `second' are pairwise not equal
    //      compared case-insensitively, they are equal
\end{verbatim}
    \end{itemize}

\subsection{equal\_range}\label{EQUALRANGE}
    \typeout{Original Yodl file: generic/equalrange}    \index{equal\_range}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{pair$<$ForwardIterator, ForwardIterator$>$
            equal\_range(ForwardIterator first, ForwardIterator last, Type
const \&value);}
            \item \texttt{pair$<$ForwardIterator, ForwardIterator$>$
            equal\_range(ForwardIterator first, ForwardIterator last, Type
const \&value, Compare comp);}
        \end{itemize}
        \item  Description (see also identically named member functions of,
e.g., the \texttt{map} (section \ref{MAP}) and \texttt{multimap} (section
\ref{MULTIMAP})):
        \begin{itemize}
            \item  The first prototype: starting from a sorted sequence (where
the \texttt{operator$<$} of the data type to which the iterators point was used to
sort the elements in the provided range), a pair of iterators is returned
representing the return value of, respectively, \texttt{lower\_bound} (returning
the first element that is not smaller than the provided reference value, see
section \ref{LOWERBOUND}) and \texttt{upper\_bound} (returning the first element
beyond the provided reference value, see section \ref{UPPERBOUND}).
            \item  The second prototype: starting from a sorted sequence (where
the \texttt{comp} function object was used to sort the elements in the provided
range), a pair of iterators is returned representing the return values of,
respectively, the functions \texttt{lower\_bound} (section \ref{LOWERBOUND}) and
\texttt{upper\_bound} (section \ref{UPPERBOUND}).
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <functional>
    #include <iterator>
    #include <iostream>
    using namespace std;

    int main()
    {
        int    range[] = {1, 3, 5, 7, 7, 9, 9, 9};
        auto past = end(range);

        pair<int *, int *>  pi;

        pi = equal_range(range, past, 6);

        cout << "Lower bound for 6: " << *pi.first << "\n"
                "Upper bound for 6: " << *pi.second << '\n';

        pi = equal_range(range, past, 7);

        cout << "Lower bound for 7: ";
        copy(pi.first, past, ostream_iterator<int>(cout, " "));
        cout << '\n';

        cout << "Upper bound for 7: ";
        copy(pi.second, past, ostream_iterator<int>(cout, " "));
        cout << '\n';

        sort(range, past, greater<int>());

        cout << "Sorted in descending order\n";

        copy(range, past, ostream_iterator<int>(cout, " "));
        cout << '\n';

        pi = equal_range(range, past, 7, greater<int>());

        cout << "Lower bound for 7: ";
        copy(pi.first, past, ostream_iterator<int>(cout, " "));
        cout << '\n';

        cout << "Upper bound for 7: ";
        copy(pi.second, past, ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      Lower bound for 6: 7
    //      Upper bound for 6: 7
    //      Lower bound for 7: 7 7 9 9 9
    //      Upper bound for 7: 9 9 9
    //      Sorted in descending order
    //      9 9 9 7 7 5 3 1
    //      Lower bound for 7: 7 7 5 3 1
    //      Upper bound for 7: 5 3 1
\end{verbatim}
    \end{itemize}

\subsection{exchange}\label{EXCHANGE}
    \typeout{Original Yodl file: generic/exchange}\index{exchange}
\begin{itemize}
    \item  Header file: \texttt{$<$utility$>$}
    \item  Function prototype:
    \begin{itemize}
        \item \texttt{Type exchange(Type \&object1, ValueType \&\&newValue);}
    \end{itemize}
    \item  Description:
    \begin{itemize}
        \item  \texttt{newValue} is assigned to \texttt{object1}, and \texttt{object1's}
                previous value is returned.
    \end{itemize}
    \item  Example:
    \begin{verbatim}
    #include <utility>
    #include <iostream>
    using namespace std;

    int main(int argc, char **argv)
    {
        bool more = argc > 5;

        cout << "more than 5: " << exchange(more, argc > 2) <<
                ", more than 2: " << more << '\n';
    }
    //  With `a.out one two three' displays:
    //
    //  more than 5: 0, more than 2: 1
\end{verbatim}
\end{itemize}

\subsection{fill / fill\_n}\label{FILL}
    \typeout{Original Yodl file: generic/fill}    \index{fill}     \index{fill\_n}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void fill({[}ExecPol,{]} ForwardIterator first,
ForwardIterator last, Type const \&value);}
            \item \texttt{void fill\_n({[}ExecPol,{]} ForwardIterator first, Size n, Type
                const \&value);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: all elements reached from the iterator
range \texttt{[first, last)} are initialized to \texttt{value}, overwriting
previously stored values.
            \item  The second prototype: \texttt{n} elements starting at the element
pointed to by \texttt{first} are initialized to \texttt{value}, overwriting previously
stored values.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <vector>
    #include <iterator>
    #include <iostream>
    using namespace std;

    int main()
    {
        vector<int> iv(8);

        fill(iv.begin(), iv.end(), 8);
        copy(iv.begin(), iv.end(), ostream_iterator<int>(cout, " "));
        cout << '\n';

        fill_n(iv.begin() + 2, 4, 4);
        copy(iv.begin(), iv.end(), ostream_iterator<int>(cout, " "));
        cout << '\n';
     }
    // Displays:    8 8 8 8 8 8 8 8
    //              8 8 4 4 4 4 8 8
\end{verbatim}
    \end{itemize}

\subsection{find / find\_if / find\_if\_not}\label{FIND}
    \typeout{Original Yodl file: generic/find}    \index{find}  \index{find\_if}  \index{find\_if\_not}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{InputIterator find({[}ExecPol,{]} InputIterator first,
    InputIterator last, Type const \&value);}
            \item \texttt{InputIterator find\_if({[}ExecPol,{]} InputIterator first,
    InputIterator last, Predicate pred);}
            \item \texttt{InputIterator find\_if\_not({[}ExecPol,{]} InputIterator first,
    InputIterator last, Predicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: element \texttt{value} is searched for in the
elements reached from the iterator range \texttt{[first, last)}. An iterator
pointing to the first element found is returned. If the element was not found,
\texttt{last} is returned. The \texttt{operator==} of the underlying data type is used
to compare the elements.
            \item  The second prototype returns an iterator pointing to the
first element reached from the iterator range \texttt{[first, last)} for which
the (unary) predicate \texttt{pred} returns \texttt{true}. If the element was not found,
\texttt{last} is returned.
            \item  The third prototype returns an iterator pointing to the first
element reached from the iterator range \texttt{[first, last)} for which the
(unary) predicate \texttt{pred} returns \texttt{false}. If the element was not found,
\texttt{last} is returned. Thus, \texttt{pred} defines what is considered acceptable, in
which case \texttt{find\_if\_not} returns an iterator to the first element that
isn't.
         \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <cstring>
    #include <iterator>
    #include <iostream>
    using namespace std;

    class CaseName
    {
        std::string  d_string;

        public:
            CaseName(char const *str): d_string(str)
            {}
            bool operator()(std::string const &element) const
            {
                return strcasecmp(element.c_str(), d_string.c_str()) == 0;
            }
    };

    void show(string const *begin, string const *end)
    {
        if (begin == end)
            cout << "No elements were found";
        else
            copy(begin, end, ostream_iterator<string>{ cout, " " });
        cout << '\n';
    }

    int main()
    {
        string sarr[] =
            {
                "Alpha", "Bravo", "Charley", "Delta", "Echo"
            };
        auto past = end(sarr);

        show(find(sarr, past, "Delta"), past);
        show(find(sarr, past, "India"), past);

        show(find_if(sarr, sarr + size(sarr), CaseName{ "charley" }), past);

        if (find_if(sarr, sarr + size(sarr), CaseName{ "india" }) == past)
            cout << "`india' was not found in the range\n";

        show(find_if_not(sarr, sarr + size(sarr), CaseName{ "alpha" }), past);
    }
    //  Displays:
    //      Delta Echo
    //      No elements were found
    //      Charley Delta Echo
    //      `india' was not found in the range
    //      Bravo Charley Delta Echo
\end{verbatim}
    \end{itemize}

\subsection{find\_end}\label{FINDEND}
    \typeout{Original Yodl file: generic/findend}    \index{find\_end}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator1 find\_end({[}ExecPol,{]} ForwardIterator1 first1,
    ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2)}
            \item \texttt{ForwardIterator1 find\_end({[}ExecPol,{]} ForwardIterator1 first1,
    ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2,
                                            BinaryPredicate pred)}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the sequence of elements in the range
\texttt{[first1, last1)} is searched for the last occurrence of the sequence of
elements in the range \texttt{[first2, last2)}. If the sequence
\texttt{[first2, last2)} is not found, \texttt{last1} is returned, otherwise an
iterator pointing to the first element of the matching sequence is
returned. The \texttt{operator==} of the underlying data type is used to compare
the elements in the two sequences.
            \item  The second prototype: the sequence of elements in the range
\texttt{[first1, last1)} is searched for the last occurrence of the sequence of
elements in the range \texttt{[first2, last2)}. If the sequence \texttt{[first2,
last2)} is not found, \texttt{last1} is returned, otherwise an iterator pointing to
the first element of the matching sequence is returned. The provided binary
predicate is used to compare the elements in the two sequences.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iterator>
    #include <iostream>
    using namespace std;

    bool twice(size_t first, size_t second)
    {
        return first == (second << 1);
    }

    int main()
    {
        string sarr[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel",
                "foxtrot", "golf", "hotel",
                "india", "juliet", "kilo"
            };
        string search[] =
            {
                "foxtrot",
                "golf",
                "hotel"
            };
        auto past = end(sarr);

        copy
        (
            find_end(sarr, past, search, search + 3),   // sequence starting
            past, ostream_iterator<string>{ cout, " " } // at 2nd 'foxtrot'
        );
        cout << '\n';

        size_t range[] = { 2, 4, 6, 8, 10, 4, 6, 8, 10 };
        size_t nrs[]   = { 2, 3, 4 };

        copy                // sequence of values starting at last sequence
        (                   // of range[] that are twice the values in nrs[]
            find_end(range, range + 9, nrs, nrs + 3, twice),
            range + 9, ostream_iterator<size_t>{ cout, " " }
        );
        cout << '\n';
    }
    //  Displays:
    //      foxtrot golf hotel india juliet kilo
    //      4 6 8 10
\end{verbatim}
    \end{itemize}

\subsection{find\_first\_of}\label{FINDFIRST}
    \typeout{Original Yodl file: generic/findfirstof}    \index{find\_first\_of}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator1 find\_first\_of({[}ExecPol,{]} 
ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, 
ForwardIterator2 last2)}
            \item \texttt{ForwardIterator1 find\_first\_of({[}ExecPol,{]} 
ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2,
ForwardIterator2 last2, BinaryPredicate pred)}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the sequence of elements in the range
\texttt{[first1, last1)} is searched for the first occurrence of an element in
the sequence of elements in the range \texttt{[first2, last2)}. If no
element in the sequence \texttt{[first2, last2)} is found, \texttt{last1} is
returned, otherwise an iterator pointing to the first element in
\texttt{[first1, last1)} that is equal to an element in \texttt{[first2, last2)}
is returned. The \texttt{operator==} of the underlying data type is used to compare
the elements in the two sequences.
            \item  The second prototype: the sequence of elements in the range
\texttt{[first1, last1)} is searched for the first occurrence of an element in
the sequence of elements in the range \texttt{[first2, last2)}. Each element in
the range \texttt{[first1, last1)} is compared to each element in the range
\texttt{[first2, last2)}, and an iterator to the first element in
\texttt{[first1, last1)} for which the binary predicate \texttt{pred} (receiving an
the element out of the range \texttt{[first1, last1)} and an element from the
range \texttt{[first2, last2)}) returns \texttt{true} is returned. Otherwise,
\texttt{last1} is returned.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iterator>
    #include <iostream>
    using namespace std;

    bool twice(size_t first, size_t second)
    {
        return first == (second << 1);
    }
    int main()
    {
        string sarr[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel",
                "foxtrot", "golf", "hotel",
                "india", "juliet", "kilo"
            };
        string search[] =
            {
                "foxtrot",
                "golf",
                "hotel"
            };
        auto past = end(sarr);

        copy
        (                                                 // sequence starting
            find_first_of(sarr, past, search, search + 3),// at 1st 'foxtrot'
            past, ostream_iterator<string>{ cout, " " }
        );
        cout << '\n';

        size_t range[] = {2, 4, 6, 8, 10, 4, 6, 8, 10};
        size_t nrs[]   = {2, 3, 4};

            // copy the sequence of values in 'range', starting at the
            // first element in 'range' that is equal to twice one of the
            // values in 'nrs', and ending at the past element of 'range'
        copy
        (
            find_first_of(range, range + 9, nrs, nrs + 3, twice),
            range + 9, ostream_iterator<size_t>{ cout, " " }
        );
        cout << '\n';
    }
    //  Displays:
    //      foxtrot golf hotel foxtrot golf hotel india juliet kilo
    //      4 6 8 10 4 6 8 10
\end{verbatim}
    \end{itemize}

\subsection{for\_each}\label{FOREACH}
    \typeout{Original Yodl file: generic/foreach}    \index{for\_each}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{Function for\_each({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last, Function func);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The elements reached from the iterator range
\texttt{[first, last)} are passed in sequence as a reference to the function (or
function object) \texttt{func}. The function may modify the elements it receives
(as the used iterator is a forward iterator). Alternatively, if the elements
should be transformed, \texttt{transform} (see section \ref{TRANSFORM}) can be
used. The function itself or a copy of the provided function object is
returned: see the example below, in which an extra argument list is added to
the \texttt{for\_each} call, which argument is eventually also passed to the
function given to \texttt{for\_each}. Within \texttt{for\_each} the return value of the
function that is passed to it is ignored. The \texttt{for\_each} generic algorithm
looks a lot like the range-based for loop, but different from the range-based
for-loop the \texttt{for\_each} algorithm can also be used with sub-ranges and with
reverse-iterators.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <cctype>
    using namespace std;

    void lowerCase(char &ch)                     // `ch' *is* modified
    {
        ch = tolower(static_cast<unsigned char>(ch));
    }

    void capitalizedOutput(string const &str)   // `str' is *not* modified
    {
        char *tmp = new char[str.size() + 1]();
        str.copy(tmp, str.size());

        for_each(tmp + 1, tmp + str.size(), lowerCase);

        tmp[0] = toupper(*tmp);
        cout << tmp << ' ';
        delete[] tmp;
    }

    int main()
    {
        string sarr[] =
            {
                "alpha", "BRAVO", "charley", "DELTA",  "echo",
                "FOXTROT", "golf", "HOTEL"
            };

        for_each(sarr, end(sarr), capitalizedOutput)("that's all, folks");
        cout << '\n';
    }
    // Displays:
    // Alpha Bravo Charley Delta Echo Foxtrot Golf Hotel That's all, folks
\end{verbatim}
        \item  Here is another example using a function object:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <cctype>
    using namespace std;

    void lowerCase(char &c)
    {
        c = tolower(static_cast<unsigned char>(c));
    }
    class Show
    {
        int d_count;

        public:
            Show()
            :
                d_count(0)
            {}
            void operator()(std::string &str)
            {
                std::for_each(str.begin(), str.end(), lowerCase);
                str[0] = toupper(str[0]);   // assuming str is not empty
                std::cout << ++d_count << " " << str << "; ";
            }
            int count() const
            {
                return d_count;
            }
    };
    int main()
    {
        string sarr[] =
            {
                "alpha", "BRAVO", "charley", "DELTA", "echo",
                "FOXTROT", "golf", "HOTEL"
            };
        string *last = sarr + sizeof(sarr) / sizeof(string);

        cout << for_each(sarr, last, Show{}).count() << '\n';
    }
    /*
    Displays (all on one line):

    1 Alpha; 2 Bravo; 3 Charley; 4 Delta; 5 Echo; 6 Foxtrot;
                                              7 Golf; 8 Hotel; 8
    */
\end{verbatim}
    \end{itemize}
    The example also shows that the \texttt{for\_each} algorithm may be used with
functions defining \texttt{const} and non-\texttt{const} parameters. Also, see section
\ref{TRANSFORM} for differences between the \texttt{for\_each} and \texttt{transform}
generic algorithms.

The \texttt{for\_each} algorithm cannot directly be used (i.e., by passing
\texttt{$*$this} as the function object argument) inside a member function to modify
its own object as the \texttt{for\_each} algorithm first creates its own copy of the
passed function object. A \index{lambda function}\emph{lambda function} or a \emph{wrapper class} whose
constructor accepts a pointer or reference to the current object and possibly
to one of its member functions solves this problem.

\subsection{generate / generate\_n}\label{GEN}
    \typeout{Original Yodl file: generic/generate}    \index{generate} \index{generate\_n}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{void generate({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last, Generator generator);}
            \item \texttt{void generate\_n({[}ExecPol,{]} ForwardIterator first, Size n,
                Generator generator);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: all elements reached from the iterator
range \texttt{[first, last)} are initialized by the return value of
\texttt{generator}, which can be a function or function
object. \texttt{Generator::operator()} does not receive any arguments. The example
uses a well-known fact from algebra: in order to obtain the square of \texttt{n +
1}, add \texttt{1 + 2 $*$ n} to \texttt{n $*$ n}.
            \item  The second prototype: \texttt{n} elements starting at the element
pointed to by iterator \texttt{first} are initialized by the return value of
\texttt{generator}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <vector>
    #include <iterator>
    #include <iostream>
    using namespace std;

    class NaturalSquares
    {
        size_t d_newsqr;
        size_t d_last;

        public:
            NaturalSquares(): d_newsqr(0), d_last(0)
            {}
            size_t operator()()
            {                   // using: (a + 1)^2 == a^2 + 2*a + 1
                return d_newsqr += (d_last++ << 1) + 1;
            }
    };
    int main()
    {
        vector<size_t> uv(10);

        generate(uv.begin(), uv.end(), NaturalSquares{});

        copy(uv.begin(), uv.end(), ostream_iterator<int>{ cout, " " });
        cout << '\n';

        uv = vector<size_t>(10);
        generate_n(uv.begin(), 5, NaturalSquares{});

        copy(uv.begin(), uv.end(), ostream_iterator<int>{ cout, " " });
        cout << '\n';

    }
    // Displays:   1 4 9 16 25 36 49 64 81 100
    //             1 4 9 16 25 0 0 0 0 0
\end{verbatim}
    \end{itemize}

\subsection{includes}\label{INCLUDES}
    \typeout{Original Yodl file: generic/includes}    \index{includes}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool includes({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2);}
            \item \texttt{bool includes({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,
Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: both sequences of elements in
the ranges \texttt{[first1, last1)} and \texttt{[first2, last2)} should have been
sorted using the \texttt{operator$<$} of the data type to which the iterators
point. The function returns \texttt{true} if every element in the second sequence
\texttt{[first2, last2)} is contained in the first sequence \texttt{[first1,
last1)} (the second range is a subset of the first range).
            \item  The second prototype: both sequences of elements in
the ranges \texttt{[first1, last1)} and \texttt{[first2, last2)} should have been
sorted using the \texttt{comp} function object. The function returns \texttt{true} if
every element in the second sequence \texttt{[first2, last2)} is contained in
the first sequence \texttt{[first1, last1)} (the second range is a subset of
the first range).
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <cstring>
    #include <iostream>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) == 0;
    }

    int main()
    {
        string first1[] =
            {
                "alpha", "bravo", "charley", "delta",  "echo",
                "foxtrot", "golf", "hotel"
            };
        auto past1 = end(first1);

        string first2[] =
            {
                "Alpha", "bravo", "Charley", "delta",  "Echo",
                "foxtrot", "Golf", "hotel"
            };
        auto past2 = end(first2);

        string second[] = { "charley", "foxtrot", "hotel" };

        cout << "The elements of `second' are " <<
            (includes(first1, past1, second, second + 3) ? "" : "not") <<
               " contained in the first sequence:\n"
               "second is a subset of first1\n"

            "The elements of `first1' are " <<
            (includes(second, second + 3, first1, past1) ? "" : "not") <<
            " contained in the second sequence\n"

            "The elements of `second' are " <<
            (includes(first2, past2, second, second + 3) ? "" : "not") <<
            " contained in the first2 sequence\n"

            "Using case-insensitive comparison,\n"
            "the elements of `second' are " <<
            (includes(first2, past2, second, second + 3, caseString) ?
                                                           "" : "not") <<
            " contained in the first2 sequence\n";
    }
    //  Displays:
    //     The elements of `second' are  contained in the first sequence:
    //     second is a subset of first1
    //     The elements of `first1' are not contained in the second sequence
    //     The elements of `second' are not contained in the first2 sequence
    //     Using case-insensitive comparison,
    //     the elements of `second' are  contained in the first2 sequence
\end{verbatim}
    \end{itemize}

\subsection{inner\_product}\label{INNERPROD}
    \typeout{Original Yodl file: generic/innerproduct}    \index{inner\_product}
    \begin{itemize}
        \item  Header file: \texttt{$<$numeric$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{Type inner\_product(InputIterator1 first1,
                InputIterator1 last1, InputIterator2 first2, Type init);}
            \item \texttt{Type inner\_product(InputIterator1 first1,
                InputIterator1 last1, InputIterator2 first2, Type init,
                BinaryOperator1 op1, BinaryOperator2 op2);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the sum of all pairwise products of the
elements in the range \texttt{[first1, last1)} and the same number of
elements starting at the element pointed to by \texttt{first2} are added to
\texttt{init}, and this sum is returned. The function uses the \texttt{operator+} and
\texttt{operator$*$} of the data type to which the iterators point.
            \item  The second prototype: binary operator \texttt{op1} instead of the
default addition operator, and binary operator \texttt{op2} instead of the default
multiplication operator are applied to all pairwise elements in the
range \texttt{[first1, last1)} and the same number of elements starting at the
element pointed to by \texttt{first2}. The results of the binary operator calls are
added to \texttt{init} and \texttt{init}'s  final value is returned.
        \end{itemize}
        (See also section \ref{TRANSRED}.)
        \item  Example:
        \begin{verbatim}
    #include <numeric>
    #include <algorithm>
    #include <iterator>
    #include <iostream>
    #include <string>
    using namespace std;

    class Cat
    {
        std::string  d_sep;
        public:
            Cat(string const &sep)
            :
                d_sep(sep)
            {}
            string operator()
                (string const &s1, string const &s2) const
            {
                return s1 + d_sep + s2;
            }
    };
    int main()
    {
        size_t ia1[] = { 1, 2, 3, 4, 5, 6, 7 };

        cout << "The sum of all squares in ";
        copy(ia1, ia1 + 7, ostream_iterator<size_t>{ cout, " " });
        cout << "is " << inner_product(ia1, ia1 + 7, ia1, 0) << '\n';

        size_t ia2[] = { 7, 6, 5, 4, 3, 2, 1 };

        cout << "The sum of all cross-products in ";
        copy(ia1, ia1 + 7, ostream_iterator<size_t>{ cout, " " });
        cout << "and ";
        copy(ia2, ia2 + 7, ostream_iterator<size_t>{ cout, " " });
        cout << "is " << inner_product(ia1, ia1 + 7, ia2, 0) << '\n';

        string names1[] = { "Frank", "Karel", "Piet" };
        string names2[] = { "Brokken", "Kubat", "Plomp"};

        cout << "All combined names of ";
        copy(names1, names1 + 3, ostream_iterator<string>{ cout, " " });
        cout << "and\n";
        copy(names2, names2 + 3, ostream_iterator<string>{ cout, " " });
        cout << "are:" <<
            inner_product(names1, names1 + 3, names2, string{ "\t" },
                Cat{ "\n\t"}, Cat{ " " }) << '\n';
    }
    // Displays:
    //  The sum of all squares in 1 2 3 4 5 6 7 is 140
    //  The sum of all cross-products in 1 2 3 4 5 6 7 and 7 6 5 4 3 2 1 is 84
    //  All combined names of Frank Karel Piet and Brokken Kubat Plomp are:
    //          Frank Brokken
    //          Karel Kubat
    //          Piet Plomp
\end{verbatim}
    \end{itemize}

\subsection{inplace\_merge}\label{INMERGE}
    \typeout{Original Yodl file: generic/inplacemerge}    \index{inplace\_merge}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void inplace\_merge({[}ExecPol,{]} BidirectionalIterator first,
                BidirectionalIterator middle, BidirectionalIterator last);}
            \item \texttt{void inplace\_merge({[}ExecPol,{]} BidirectionalIterator first,
                BidirectionalIterator middle, BidirectionalIterator last,
                Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the two (sorted) ranges \texttt{[first,
middle)} and \texttt{[middle, last)} are merged, keeping a sorted list (using the
\texttt{operator$<$} of the data type to which the iterators point). The final
series is stored in the range \texttt{[first, last)}.
            \item  The second prototype: the two (sorted) ranges \texttt{[first,
middle)} and \texttt{[middle, last)} are merged, keeping a sorted list (using the
boolean result of the binary comparison operator \texttt{comp}). The final series
is stored in the range \texttt{[first, last)}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <cstring>
    #include <iterator>
    #include <iostream>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) == 0;
    }

    int main()
    {
        string range[] =
            {
                "alpha", "charley", "echo", "golf",
                "bravo", "delta", "foxtrot",
            };

        inplace_merge(range, range + 4, range + 7);
        copy(range, range + 7, ostream_iterator<string>{ cout, " " });
        cout << '\n';

        string range2[] =
            {
                "ALPHA", "CHARLEY", "DELTA", "foxtrot", "hotel",
                "bravo", "ECHO", "GOLF"
            };

        inplace_merge(range2, range2 + 5, range2 + 8, caseString);
        copy(range2, range2 + 8, ostream_iterator<string>{ cout, " " });
        cout << '\n';
    }
    //  Displays:
    //      alpha bravo charley delta echo foxtrot golf
    //      ALPHA bravo CHARLEY DELTA ECHO foxtrot GOLF hotel
\end{verbatim}
    \end{itemize}

\subsection{iota}\label{IOTA}
    \typeout{Original Yodl file: generic/iota}    \index{iota}
    \begin{itemize}
        \item  Header file: \texttt{$<$numeric$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{void iota(ForwardIterator first,
                ForwardIterator last, Type value);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  All elements reached from the iterator range \texttt{[first,
last)} are assigned the values of the incremented sequence of values starting at
\texttt{value}. \texttt{$*$first} receives \texttt{value}, \texttt{$*$(first + 1)} receives
\texttt{++value}, etc.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <numeric>
    #include <algorithm>
    #include <vector>
    #include <iostream>
    #include <iterator>

    using namespace std;

    int main()
    {
        vector<size_t> uv(10);

        iota(uv.begin(), uv.end(), 0);

        copy(uv.begin(), uv.end(), ostream_iterator<int>{ cout, " " });
        cout << '\n';
    }
    // Displays:   0 1 2 3 4 5 6 7 8 9
\end{verbatim}
    \end{itemize}

\subsection{is\_partitioned}\label{ISPART}
    \typeout{Original Yodl file: generic/ispartitioned}    \index{is\_partitioned}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{bool is\_partitioned({[}ExecPol,{]} InputIterator first,
                            InputIterator last, UnaryPred pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  Returns \texttt{true} if \texttt{pred}, receiving all elements reached
from the iterator range \texttt{[first, last)}, returns \texttt{true} until it
returns \texttt{false}, and if \texttt{pred}, receiving the remaining elements, returns
\texttt{false}. It also returns \texttt{true} if the range is empty.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iterator>
    #include <vector>
    #include <iostream>
    using namespace std;

    bool pCheck(int value)
    {
        return value < 3;
    }

    int main()
    {
        vector<int> uv = { 1, -2, 3, -4, 5, -6, 7, -8, 9};

        cout << "partitioned before: " <<
                is_partitioned(uv.begin(), uv.end(), pCheck) << "\n"

                "first value returning 'false' when partitioning: " <<
                *partition(uv.begin(), uv.end(), pCheck) << '\n';

        copy(uv.begin(), uv.end(), ostream_iterator<int>{ cout, " " });
        cout << '\n';

        cout << "partitioned after: " <<
                is_partitioned(uv.begin(), uv.end(), pCheck) <<'\n';

    }
    // Displays:   1 4 9 16 25 36 49 64 81 100
    //             1 4 9 16 25 0 0 0 0 0
\end{verbatim}
    \end{itemize}

\subsection{is\_permutation}\label{ISPERM}
    \typeout{Original Yodl file: generic/ispermutation}    \index{is\_permutation}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool is\_permutation(ForwardIterator first1,
                ForwardIterator last1, ForwardIterator first2);}
            \item \texttt{bool is\_permutation(ForwardIterator first1,
                ForwardIterator last1, ForwardIterator first2,
                ForwardIterator last2);}
            \item \texttt{bool is\_permutation(ForwardIterator first1,
                ForwardIterator last1, ForwardIterator firs2,
                BinaryPred pred);}
            \item \texttt{bool is\_permutation(ForwardIterator first1,
                ForwardIterator last1, ForwardIterator first2,
                ForwardIterator last2, BinaryPred pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: returns \texttt{true} if the elements in the
iterator range \texttt{[first1, last1)}, are a permutation of the elements in
the identically sized range starting at \texttt{first2}.
            \item  The second prototype: like the first prototype but the ending
iterator of the second range is provided as the fourth argument.
            \item  The third prototype: like the first prototype but using the
result of \texttt{pred} to determine whether two elements are equal.
            \item  The fourth prototype: like the second prototype but using the
result of \texttt{pred} to determine whether two elements are equal.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    using namespace std;

    int main()
    {
        int one[] = { 1, -2, 3, -4, 5, -6, 7, -8, 9};
        int two[] = { -8, -2, -4, -6, 3, 1, 5, 9, 7};
        int three[] = { -8, -8, -4, -6, 3, 1, 5, 9, 7};

        cout << "one is a permutation of two: " <<
            is_permutation(one, end(one), two) << "\n"

            "one is a permutation of three: " <<
            is_permutation(one, end(one), three, end(three)) << '\n';
    }
    // Displays: one is a permutation of two: 1
    //           one is a permutation of three: 0
\end{verbatim}
    \end{itemize}

\subsection{is\_sorted}\label{ISSORTED} 
    \typeout{Original Yodl file: generic/issorted}    \index{is\_sorted}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool is\_sorted({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last);}
            \item \texttt{bool is\_sorted({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last, BinaryPredicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: returns \texttt{true} if the elements in the
iterator range \texttt{[first, last)}, are sorted using the elements'
\texttt{operator$<$} comparison operator.
            \item  The second prototype: returns \texttt{true} if the elements in the
iterator range \texttt{[first, last)}, are sorted using the binary predicate
\texttt{pred}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <vector>
    #include <iostream>
    using namespace std;

    int main()
    {
        vector<int> uv = { 1, -2, 3, -4, 5, -6, 7, -8, 9};

        cout << "sorted before: " <<
                is_sorted(uv.begin(), uv.end()) << '\n';

        sort(uv.begin(), uv.end());

        cout << "sorted after " <<
                is_sorted(uv.begin(), uv.end()) << '\n';
    }
    // Displays:
    //    sorted before: 0
    //    sorted after 1
\end{verbatim}
    \end{itemize}

\subsection{is\_sorted\_until}\label{ISSORTEDUNT}
    \typeout{Original Yodl file: generic/issorteduntil}    \index{is\_sorted\_until}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator is\_sorted\_until({[}ExecPol,{]} 
                ForwardIterator first, ForwardIterator last);}
            \item \texttt{ForwardIterator is\_sorted\_until({[}ExecPol,{]} 
                ForwardIterator first, ForwardIterator last, 
                BinaryPredicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: returns an iterator to the end of range,
starting at \texttt{first} whose elements are sorted using the elements'
\texttt{operator$<$} comparison operator.
            \item  The second prototype: returns an iterator to the end of
range, starting at \texttt{first} whose elements using the binary predicate
\texttt{pred}.
        \end{itemize}
        The functions return at least \texttt{first + 1}.
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <vector>
    #include <iostream>
    using namespace std;

    int main()
    {
        vector<int> uv = { 1, -2, 3, -4, 5, -6, 7, -8, 9};

        cout << "sorted before: " <<
                is_sorted(uv.begin(), uv.end()) << '\n';

        sort(uv.begin(), uv.end());

        cout << "sorted after " <<
                is_sorted(uv.begin(), uv.end()) << '\n';
    }
    // Displays:
    //    sorted before: 0
    //    sorted after 1
\end{verbatim}
    \end{itemize}

\subsection{iter\_swap}\label{ITERSWAP}  
    \typeout{Original Yodl file: generic/iterswap}    \index{iter\_swap}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{void iter\_swap(ForwardIterator1 iter1,
                ForwardIterator2 iter2);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The elements pointed to by \texttt{iter1} and \texttt{iter2} are
                swapped.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iterator>
    #include <iostream>
    #include <string>
    using namespace std;

    int main()
    {
        string first[] = { "alpha", "bravo", "charley" };
        string second[] = { "echo", "foxtrot", "golf" };

        cout << "Before:\n";
        copy(first, first + 3, ostream_iterator<string>(cout, " "));
        cout << '\n';
        copy(second, second + 3, ostream_iterator<string>(cout, " "));
        cout << '\n';

        for (size_t idx = 0; idx != 3; ++idx)
            iter_swap(first + idx, second + idx);

        cout << "After:\n";
        copy(first, first + 3, ostream_iterator<string>(cout, " "));
        cout << '\n';
        copy(second, second + 3, ostream_iterator<string>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      Before:
    //      alpha bravo charley
    //      echo foxtrot golf
    //      After:
    //      echo foxtrot golf
    //      alpha bravo charley
\end{verbatim}
    \end{itemize}

\subsection{lexicographical\_compare}\label{LEXCOMP}
    \typeout{Original Yodl file: generic/lexicographicalcompare}    \index{lexicographical\_compare}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool lexicographical\_compare({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2);}
            \item \texttt{bool lexicographical\_compare({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, Compare
comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the corresponding pairs of elements in
the ranges pointed to by the ranges \texttt{[first1, last1)} and \texttt{[first2,
last2)} are compared. The function returns \index{true}\texttt{true}
            \begin{itemize}
                \item  at the first element in the first range which is less
than the corresponding element in the second range (using \texttt{operator$<$}
of the underlying data type),
                \item  if \texttt{last1} is reached, but \texttt{last2} isn't reached yet.
            \end{itemize}
False is returned in the other cases, which indicates that the first sequence
is not lexicographically less than the second sequence. So, \index{false}\texttt{false} is
returned:
            \begin{itemize}
                \item  at the first element in the first range which is greater
than the corresponding element in the second range (using \texttt{operator$<$}
of the data type to which the iterators point, reversing the  operands),
                \item  if \texttt{last2} is reached, but \texttt{last1} isn't reached yet,
                \item  if \texttt{last1} and \texttt{last2} are reached.
            \end{itemize}
            \item  The second prototype: with this function the binary
comparison operation as defined by \texttt{comp} is used instead of
\texttt{operator$<$} of the data type to which the iterators point.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iterator>
    #include <iostream>
    #include <string>
    #include <cstring>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) < 0;
    }

    void compare(string const &word1, string const &word2)
    {
        cout << '`' << word1 << "' is " <<
            (
                lexicographical_compare(word1.begin(), word1.end(),
                                        word2.begin(), word2.end()) ?
                    "before `" : "beyond or at `"
            ) <<
            word2 << "' in the alphabet\n";
    }

    int main()
    {
        string word1 = "hello";
        string word2 = "help";

        compare(word1, word2);
        compare(word1, word1);
        compare(word2, word1);

        string one[] = {"alpha", "bravo", "charley"};
        string two[] = {"ALPHA", "BRAVO", "DELTA"};

        copy(one, one + 3, ostream_iterator<string>{ cout, " " });
        cout << " is ordered " <<
            (
                lexicographical_compare(one, one + 3,
                                        two, two + 3, caseString) ?
                    "before " : "beyond or at "
            );
        copy(two, two + 3, ostream_iterator<string>{ cout, " " });
        cout << "\n"
            "using case-insensitive comparisons.\n";
    }
    //   Displays:
    //      `hello' is before `help' in the alphabet
    //      `hello' is beyond or at `hello' in the alphabet
    //      `help' is beyond or at `hello' in the alphabet
    //      alpha bravo charley  is ordered before ALPHA BRAVO DELTA
    //      using case-insensitive comparisons.
\end{verbatim}
    \end{itemize}

\subsection{lower\_bound}\label{LOWERBOUND}
    \typeout{Original Yodl file: generic/lowerbound}    \index{lower\_bound}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator lower\_bound(ForwardIterator first,
                ForwardIterator last, const Type \&value);}
            \item \texttt{ForwardIterator lower\_bound(ForwardIterator first,
                ForwardIterator last, const Type \&value, BinaryPredicate 
                pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the sorted elements (using ascending
sort) reached from the iterator range \texttt{[first, last)} are searched for
the first element that is not less than (i.e., greater than or equal to)
\texttt{value}. The returned iterator marks the location in the sequence where
\texttt{value} can be inserted without breaking the sorted order of the
elements. The \texttt{operator$<$} of the data type to which the iterators point is
used. If no such element is found, \texttt{last} is returned.
            \item  The second prototype: the elements reached from the iterator
range \texttt{[first, last)} must have been sorted using the \texttt{comp} function
(-object). Each element in the range is compared to \texttt{value} using the
\texttt{comp} function, receiving an element from the iterator range as its first
argument and \texttt{type} as its second argument. An iterator to the first element
for which the binary predicate \texttt{comp}, applied to the elements of the range
and \texttt{value}, returns \texttt{false} is returned.  If no such element is found,
\texttt{last} is returned.

As illustrated by the following example, the function object
function's first parameter refers to an element in the iterator range, while
the function object's second parameter refers to \texttt{value}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <iterator>
    #include <vector>
    #include <functional>
    using namespace std;

    int main()
    {
        int     ia[] = { 10, 20, 30 };

        cout << "Sequence: ";
        copy(ia, ia + 3, ostream_iterator<int>(cout, " "));
        cout << "\n"
                "15 can be inserted before " <<
                *lower_bound(ia, ia + 3, 15) << "\n"
                "35 can be inserted after " <<
                (lower_bound(ia, ia + 3, 35) == ia + 3 ?
                                    "the last element" : "???") << '\n';

        cout << "Sequence: ";
        copy(ia, ia + 3, ostream_iterator<int>(cout, " "));
        cout << "\n"
                "15 can be inserted before " <<
                *lower_bound(ia, ia + 3, 15, less<int>()) << "\n"
                "35 can be inserted before " <<
                (lower_bound(ia, ia + 3, 35, less<int>()) == ia ?
                                    "the first element " : "???") << '\n';

        vector<int> array{ 5, 10, 20, 20, 20, 30 };
        auto iter = lower_bound(array.begin(), array.end(), 20,
                        [&](int &arrayEl, int value)
                        {
                            cout << "Comparing " << arrayEl <<
                                " (index: " << (&arrayEl - &array[0]) << ")"
                                " to " << value << '\n';
                            return arrayEl < value;
                        }
                    );
        cout << "New 20 to insert at idx " << (iter - array.begin()) << '\n';
    }
    //  Displays:
    //      Sequence: 10 20 30
    //      15 can be inserted before 20
    //      35 can be inserted after the last element
    //      Sequence: 10 20 30
    //      15 can be inserted before 20
    //      35 can be inserted before ???
    //      Comparing 20 (index: 3) to 20
    //      Comparing 10 (index: 1) to 20
    //      Comparing 20 (index: 2) to 20
    //      New 20 to insert at idx 2
\end{verbatim}
    \end{itemize}

The \texttt{binary\_search} generic algorithm (cf. section \ref{BINSRCH})can be used
to determine whether or not \texttt{value} is present in the iterator range. The
\texttt{upper\_bound} algorithm can be used to find the last element of a series of
values equal to \texttt{value}. The \texttt{upper\_bound} section (\ref{UPPERBOUND}) also
contains an extensive example illustrating the use of \texttt{lower\_bound} and as
\texttt{upper\_bound}.

\subsection{max / min}\label{MAX}   
    \typeout{Original Yodl file: generic/max}    \index{max} \index{min}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{Type const \&max(Type const \&one, Type const \&two);}
            \item \texttt{Type const \&max(Type const \&one, Type const \&two, Comparator
                comp);}
            \item \texttt{Type const \&min(Type const \&one, Type const \&two);}
            \item \texttt{Type const \&min(Type const \&one, Type const \&two, Comparator
                comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the larger of the two elements \texttt{one}
and \texttt{two} is returned, using the \texttt{operator$>$} of the data type to which
the iterators point to determine which element is the larger one.
            \item  The second prototype: \texttt{one} is returned if the binary
predicate \texttt{comp(one, two)} returns \texttt{true}, otherwise \texttt{two} is returned.
            \item  Prototypes three and four act identically to, respectively,
prototypes one and two, using \texttt{std::min} instead of \texttt{std::max},
returning the smaller of the two arguments.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cstring>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) <= 0;
    }

    string const &call(bool first, string const &lhs, string const &rhs)
    {
        return first? max(lhs, rhs) : min(lhs, rhs);
    }

    string const &call(bool first, string const &lhs, string const &rhs,
                bool (*cmp)(string const &, string const &))
    {
        return first? max(lhs, rhs, cmp) : min(lhs, rhs, cmp);
    }

    int main(int argc, char **argv) // no args: use max, else min
    {
        bool fun = argc == 1;
        char const *where = fun ? "last\n" : "first\n";

        cout << "Word '" << call(fun, "first", "second") <<
                            "' is lexicographically " << where <<

                "Word '" << call(fun, "first", "SECOND") <<
                            "' is lexicographically " << where <<

                "Word '" << call(fun, "first", "SECOND", caseString) <<
                            "' is lexicographically " << where;
    }
    //  Displays when calling without args:
    //      Word 'second' is lexicographically last
    //      Word 'first' is lexicographically last
    //      Word 'SECOND' is lexicographically last
    //  and with an argument:
    //      Word 'first' is lexicographically first
    //      Word 'SECOND' is lexicographically first
    //      Word 'first' is lexicographically first
\end{verbatim}
    \end{itemize}

\subsection{max\_element / min\_element / minmax\_element}\label{MAXEL}
    \typeout{Original Yodl file: generic/maxelement}    \index{max\_element} \index{min\_element} \index{minmax\_element}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator max\_element({[}ExecPol,{]} ForwardIterator first,
                            ForwardIterator last);}
            \item \texttt{ForwardIterator max\_element({[}ExecPol,{]} ForwardIterator first,
                            ForwardIterator last, BinaryPredicate pred);}
            \item \texttt{ForwardIterator min\_element({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last);}
            \item \texttt{ForwardIterator min\_element({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last, BinaryPredicate pred);}

\item \texttt{pair$<$ForwardIterator, ForwardIterator$>$ max\_element({[}ExecPol,{]} 
                ForwardIterator first,ForwardIterator last);}
            \item \texttt{pair$<$ForwardIterator, ForwardIterator$>$ max\_element({[}ExecPol,{]} 
                ForwardIterator first,ForwardIterator last, 
                BinaryPredicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: an iterator pointing to the largest
element reached from the iterator range \texttt{[first, last)} is returned. The
\index{operator\textless{}}\texttt{operator$<$} of the data type to which the iterators point is used to decide
which of the elements is the largest.
            \item  The second prototype: rather than using \texttt{operator$<$}, the
binary predicate \texttt{pred} is used to make the comparisons between the elements
reached from the iterator range \texttt{[first, last)}. The element for which
\texttt{pred} returns most often \texttt{true}, compared with other elements, is
returned.
            \item  Prototypes three and four act identically to, respectively,
prototypes one and two, using \texttt{std::min\_element} instead of
\texttt{std::max\_element}, returning iterators to the smallest elements in the 
iterator ranges \texttt{[first, last)}.
            \item  The final two prototypes act identically to, respectively,
prototypes one and two, but return \texttt{std::pair} objects whose \texttt{first}
members contain the iterators returned by the \texttt{min} generic algorithms and
whose \texttt{second} members contain the iterators returned by the \texttt{max} generic
algorithms.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    using namespace std;

    bool absCompare(int first, int second)
    {
        return abs(first) < abs(second);
    };

    int *maxMin(bool high, int *begin, int *end)
    {
        return high ? max_element(begin, end) : min_element(begin, end);
    }

    int *maxMin(bool high, int *begin, int *end, bool (*comp)(int, int))
    {
        return high ? max_element(begin, end, comp)
                    : min_element(begin, end, comp);
    }

                // no args: calls max_element, else min_element
    int main(int argc, char **argv)
    {
        bool max = argc == 1;
        char const *type = max? "max" : "min";

        int     ia[] = {-4, 7, -2, 10, -12};

        cout << "The " << type << ". int value is " <<
                *maxMin(max, ia, ia + 5) << "\n"
                "The max. absolute int value is " <<
                *maxMin(max, ia, ia + 5, absCompare) << '\n';
    }
    //  Displays, when called without arguments:
    //      The max. int value is 10
    //      The max. absolute int value is -12
    //  otherwise:
    //      The minimum int value is -12
    //      The minimum absolute int value is -2
\end{verbatim}
    \end{itemize}

\subsection{merge}\label{MERGE}
    \typeout{Original Yodl file: generic/merge}    \index{merge}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator merge({[}ExecPol,{]} InputIterator1 first1, 
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, 
OutputIterator result);}
            \item \texttt{OutputIterator merge({[}ExecPol,{]} InputIterator1 first1, 
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, 
OutputIterator result, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the two (sorted) ranges \texttt{[first1,
last1)} and \texttt{[first2, last2)} are merged, keeping a sorted list (using the
\index{operator\textless{}}\texttt{operator$<$} of the data type to which the iterators point). The final
series is stored in the range starting at \texttt{result} and ending just before
the \texttt{OutputIterator} returned by the function.
            \item  The second prototype: the two (sorted) ranges \texttt{[first1,
last1)} and \texttt{[first2, last2)} are merged, keeping a sorted list (using the
boolean result of the binary comparison operator \texttt{comp}). The final series
is stored in the range starting at \texttt{result} and ending just before the
\texttt{OutputIterator} returned by the function.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <cstring>
    #include <iterator>
    #include <iostream>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) < 0;
    }

    int main()
    {
        string range1[] =                           // 5 elements
                { "alpha", "bravo", "foxtrot", "hotel", "zulu" };
        string range2[] =                           // 4 elements
                { "delta", "echo", "golf", "romeo" };
        string result[5 + 4];

        copy(result,
            merge(range1, range1 + 5, range2, range2 + 4, result),
            ostream_iterator<string>{ cout, " " });
        cout << '\n';

        string range3[] =
                { "ALPHA", "bravo", "foxtrot", "HOTEL", "ZULU" };
        string range4[] = { "delta", "ECHO", "GOLF", "romeo" };

        copy(result,
            merge(range3, range3 + 5, range4, range4 + 4, result,
                                                    caseString),
            ostream_iterator<string>{ cout, " " });
        cout << '\n';
    }
    //  Displays:
    //      alpha bravo delta echo foxtrot golf hotel romeo zulu
    //      ALPHA bravo delta ECHO foxtrot GOLF HOTEL romeo ZULU
\end{verbatim}
    \end{itemize}

\subsection{minmax}\label{MINMAX} 
    \typeout{Original Yodl file: generic/minmax}    \index{minmax} \index{minmax\_element}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{pair$<$Type const \&, Type const \&$>$ minmax(
                                Type const \&t1, Type const \&t2);}
            \item \texttt{pair$<$Type const \&, Type const \&$>$ minmax(Type const \&t1, 
                                Type const \&t2, BinaryPred pred);}
            \item \texttt{pair$<$Type const \&, Type const \&$>$ minmax(
                                std:initializer$<$list$<$Type$>$ values);}
            \item \texttt{pair$<$Type const \&, Type const \&$>$ minmax(
                        std:initializer$<$list$<$Type$>$ values, BinaryPred pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: return a \texttt{std::pair} whose \texttt{first}
and \texttt{second} members contain, respectively, the smaller and the larger value
of the function's arguments, using \texttt{Type's operator$<$} to compare the two
values.
            \item  The second prototype: identical to the first prototype, but
deciding that \texttt{t1} is the smaller element if \texttt{pred(t1, t2)} returns
\texttt{true}. 
            \item  Prototypes three and four act identically to, respectively,
prototypes one and two, but return, the smallest and largest values found in
the provided \texttt{iterator\_range} objects.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <functional>

    using namespace std;

    int main()
    {
        vector<size_t> uv(10);

        auto values = minmax(5, 2, less<int>{});
        cout << values.first << " is smaler than " << values.second << '\n';
    }
    // Displays:   2 is smaler than 5
\end{verbatim}
    \end{itemize}

\subsection{mismatch}\label{MISMATCH}
    \typeout{Original Yodl file: generic/mismatch}    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{pair$<$InputIterator1, InputIterator2$>$
                mismatch({[}ExecPol,{]} InputIterator1 first1, 
InputIterator1 last1, InputIterator2 first2);}
            \item \texttt{pair$<$InputIterator1, InputIterator2$>$
                mismatch({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the two sequences of elements starting
at \texttt{first1} and \texttt{first2} are compared using the equality operator of the
data type to which the iterators point. Comparison stops if the compared
elements differ (i.e., \texttt{operator==} returns false) or \texttt{last1} is
reached. A \texttt{pair} containing iterators pointing to the final positions is
returned. The second sequence may contain more elements than the first
sequence. The behavior of the algorithm is undefined if the second sequence
contains fewer elements than the first sequence.
            \item  The second prototype: the two sequences of elements starting
at \texttt{first1} and \texttt{first2} are compared using the binary comparison
operation as defined by \texttt{comp}, instead of
\texttt{operator==}. Comparison stops if the \texttt{comp} function returns \texttt{false}
or \texttt{last1} is reached. A \texttt{pair} containing iterators pointing to the final
positions is returned. The second sequence may contain more elements than the
first sequence. The behavior of the algorithm is undefined if the second
sequence contains fewer elements than the first sequence.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <cstring>
    #include <iostream>
    #include <utility>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) == 0;
    }

    int main()
    {
        string range1[] = { "alpha", "bravo", "foxtrot", "hotel", "zulu" };
        string range2[] = { "alpha", "bravo", "foxtrot", "Hotel", "zulu" };
        pair<string *, string *> pss = mismatch(range1, range1 + 5, range2);

        cout << "The elements " << *pss.first << " and " << *pss.second <<
                " differ at index " << (pss.first - range1) << '\n';
        if
        (
            mismatch(range1, range1 + 5, range2, caseString).first
            ==
            range1 + 5
        )
            cout << "When compared case-insensitively they match\n";
    }
    /*
        Displays:
            The elements hotel and Hotel at offset 3 differ
            When compared case-insensitively they match
    */
\end{verbatim}
    \end{itemize}

\subsection{move / move\_backward}\label{MOVEFWD}
    \typeout{Original Yodl file: generic/move}    \index{move} \index{move\_backward} \index{shift\_left} \index{shift\_right}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{OutputIter move({[}ExecPol,{]} InputIter first, InputIter last, 
                OutputIter dest);}
            \item \texttt{BidirIter move\_backward(BidirIter first, BidirIter last, 
                BidirIter lastDest);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: all elements reached from the iterator
range \texttt{[first, last)} are moved to the range starting at \texttt{dest},
returning the iterator pointing just past the last element in the range
starting at \texttt{dest}. 
            \item  The Second prototype: all elements reached from the iterator
range \texttt{[first, last)} are moved in reverse order to the range starting,
\emph{iterating backward}, at \texttt{lastDest}, returning the iterator pointing to the
beginning of the range \emph{ending} at \texttt{lastDest}. The destination iterator
\texttt{lastDest} may not point to elements within the range \texttt{[first, last)}.
        \end{itemize}
        Following \texttt{move(\_backward)} the elements in the iterator range
\texttt{[first, last)} are still valid, but may have changed.

See also \index{shift\_left}\texttt{shift\_left} and \index{shift\_right}\texttt{shift\_right}:
            (\texttt{cppreference}\footnote{https://en.cppreference.com}).
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <iterator>
    using namespace std;

    void show(string const *begin, string const *end)
    {
        copy(begin, end, ostream_iterator<string>(cout, ", "));
        cout << '\n';
    }

    int main()
    {
        string sarr[] = { "alpha", "bravo", "charley", "delta" };
        string dest[4] = { "", };

        auto last = end(sarr);

        auto lastDest = move(sarr, last, dest); // move all elements to dest

        cout << "sarr after move:\n";
        show(sarr, last);

        cout << "dest after move:\n";
        show(dest, lastDest);

        move_backward(dest, lastDest, last); // move_backward to sarr
        cout << "sarr after move_backward:\n";
        show(sarr, last);

        cout << "dest after move_backward:\n";
        show(dest, lastDest);
    }
    //  Displays:
    //    sarr after move:
    //    , , , ,
    //    dest after move:
    //    alpha, bravo, charley, delta,
\end{verbatim}
    \end{itemize}

\subsection{next\_permutation / prev\_permutation}\label{NEXTPERM}
    \typeout{Original Yodl file: generic/nextpermutation}    \index{next\_permutation} \index{prev\_permutation}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{bool next\_permutation(BidirectionalIterator first,
                BidirectionalIterator last);}
            \item \texttt{bool next\_permutation(BidirectionalIterator first,
                BidirectionalIterator last, Comp comp);}
            \item \texttt{bool prev\_permutation(BidirectionalIterator first,
                BidirectionalIterator last);}
            \item \texttt{bool prev\_permutation(BidirectionalIterator first,
                BidirectionalIterator last, Comp comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the next permutation, given the sequence
of elements in the range \texttt{[first, last)}, is determined. For example, if
the elements \texttt{1, 2} and \texttt{3} are the range for which \texttt{next\_permutation}
is called, then subsequent calls of \texttt{next\_permutation} reorders the
following series:
        \begin{verbatim}
        1 2 3
        1 3 2
        2 1 3
        2 3 1
        3 1 2
        3 2 1
\end{verbatim}
This example shows that the elements are reordered such that each new
permutation represents the next bigger value (132 is bigger than 123, 213 is
bigger than 132, etc.) using \index{operator\textless{}}\texttt{operator$<$} of the data type to which the
iterators point.  The value \index{true}\texttt{true} is returned if a reordering took place,
the value \index{false}\texttt{false} is returned if no reordering took place, which is the case
if the sequence represents the last (biggest) value. In that case, the
sequence is also sorted using \texttt{operator$<$}.
        \item  The second prototype: the next permutation given the sequence of
elements in the range \texttt{[first, last)} is determined, using the binary
predicate \texttt{comp} to compare elements. The elements in the range are
reordered. The value \texttt{true} is returned if a reordering took place, the
value \texttt{false} is returned if no reordering took place, which is the case if
the resulting sequence would haven been ordered using the binary predicate
\texttt{comp} to compare elements.
        \item  The final two prototypes act identically to the first two
prototypes, but instead of determining the next permutation the previous
permutation is computed. 
        \end{itemize}
    \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iterator>
    #include <iostream>
    #include <string>
    #include <cstring>
    using namespace std;

    bool caseString(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) < 0;
    }

    // to obtain previous permutations change 'next_' to 'prev_'

    int main()
    {
        string saints[] = {"Oh", "when", "the", "saints"};

        cout << "All permutations of 'Oh when the saints':\n"
                "Sequences:\n";
        do
        {
            copy(saints, saints + 4, ostream_iterator<string>{ cout, " " });
            cout << '\n';
        }
        while (next_permutation(saints, saints + 4, caseString));

        cout << "After first sorting the sequence:\n";
        sort(saints, saints + 4, caseString);
        cout << "Sequences:\n";
        do
        {
            copy(saints, saints + 4, ostream_iterator<string>{ cout, " " });
            cout << '\n';
        }
        while (next_permutation(saints, saints + 4, caseString));
    }
    //  Displays (partially):
    //      All permutations of 'Oh when the saints':
    //      Sequences:
    //      Oh when the saints
    //      saints Oh the when
    //      saints Oh when the
    //      saints the Oh when
    //      ...
    //      After first sorting the sequence:
    //      Sequences:
    //      Oh saints the when
    //      Oh saints when the
    //      Oh the saints when
    //      Oh the when saints
    //      ...
\end{verbatim}
    \end{itemize}

\subsection{nth\_element}\label{NTHEL}
    \typeout{Original Yodl file: generic/nthelement}    \index{nth\_element}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void nth\_element({[}ExecPol,{]} RandomAccessIterator first,
                RandomAccessIterator nth, RandomAccessIterator last);}
            \item \texttt{void nth\_element({[}ExecPol,{]} RandomAccessIterator first,
                RandomAccessIterator nth, RandomAccessIterator last, Compare
                comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: all elements in the range \texttt{[first,
last)} are sorted relative to the element pointed to by \texttt{nth}: all elements
in the range \texttt{[left, nth)} are smaller than the element pointed to by
\texttt{nth}, and alle elements in the range \texttt{[nth + 1, last)} are greater
than the element pointed to by \texttt{nth}. The two subsets themselves are not
sorted. The \texttt{operator$<$} of the data type to which the iterators point is
used to compare the elements.
            \item  The second prototype: all elements in the range \texttt{[first,
last)} are sorted relative to the element pointed to by \texttt{nth}: all elements
in the range \texttt{[left, nth)} are smaller than the element pointed to by
\texttt{nth}, and alle elements in the range \texttt{[nth + 1, last)} are greater
than the element pointed to by \texttt{nth}. The two subsets themselves are not
sorted. The \texttt{comp} function object is used to compare the elements.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <iterator>
    #include <functional>
    using namespace std;

    int main()
    {
        int ia[] = {1, 3, 5, 7, 9, 2, 4, 6, 8, 10};

        nth_element(ia, ia + 3, ia + 10);

        cout << "sorting with respect to " << ia[3] << '\n';
        copy(ia, ia + 10, ostream_iterator<int>(cout, " "));
        cout << '\n';

        nth_element(ia, ia + 5, ia + 10, greater<int>());

        cout << "sorting with respect to " << ia[5] << '\n';
        copy(ia, ia + 10, ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      sorting with respect to 4
    //      1 2 3 4 9 7 5 6 8 10
    //      sorting with respect to 5
    //      10 8 7 9 6 5 3 4 2 1
\end{verbatim}
    \end{itemize}

\subsection{partial\_sort / partial\_sort\_copy}\label{PARTSORT}
    \typeout{Original Yodl file: generic/partialsort}    \index{partial\_sort} \index{partial\_sort\_copy}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void partial\_sort({[}ExecPol,{]} RandomAccessIterator begin,
    RandomAccessIterator middle, RandomAccessIterator end);}
            \item \texttt{void partial\_sort({[}ExecPol,{]} RandomAccessIterator begin,
    RandomAccessIterator middle, RandomAccessIterator end, 
    BinaryPredicate pred);}

\item \texttt{void partial\_sort\_copy({[}ExecPol,{]} InputIterator begin, 
    InputIterator end, 
    RandomAccessIterator dest\_begin, RandomAccessIterator dest\_end);}
            \item \texttt{void partial\_sort\_copy({[}ExecPol,{]} InputIterator begin, 
    InputIterator end, 
    RandomAccessIterator dest\_begin, RandomAccessIterator dest\_end, 
    BinaryPredicate pred);}
        \end{itemize}
        \item  Description:
            \begin{itemize}
            \item  The first prototype: the (\texttt{middle - begin}) smallest
elements are sorted and stored in the range \texttt{[begin, middle)} using the
\index{operator\textless{}}\texttt{operator$<$} of the data type to which the iterators point to compare
elements. The remaining elements of the series remain unsorted, and are stored
in the range \texttt{[middle, end)}.
            \item  The second prototype: the (\texttt{middle - begin}) smallest
elements (according to the provided binary predicate \texttt{pred}) are sorted and
stored in the range \texttt{[begin, middle)}. The remaining elements of the
series remain unsorted.
            \item  The last two prototypes act like, respectively, the first two
prototypes, but instead of reordering the elements in the source iterator
range the selected elements are copied to the destination iterator range. The
number of elements that are copies is the smaller of the number of
source-iterators and the number of destination iterators.
            \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <functional>
    #include <iterator>
    using namespace std;

    int main()
    {
        int ia[] = { 1, 9, 5, 3, 7, 2, 4, 6, 8, 10 };
        int ia2[6];

        partial_sort_copy(ia, ia + 10, ia2, ia2 + 6);
        cout << "the 6 smallest elements: ";
        copy(ia2, ia2 + 6, ostream_iterator<int>(cout, " "));
        cout << '\n';

        partial_sort(ia, ia + 3, ia + 10);

        cout << "find the 3 smallest elements:\n";
        copy(ia, ia + 3, ostream_iterator<int>(cout, " "));
        cout << '\n';

        cout << "find the 5 largest elements:\n";
        partial_sort(ia, ia + 5, ia + 10, greater<int>());
        copy(ia, ia + 5, ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      the 6 smallest elements: 1 2 3 4 5 6
    //      find the 3 smallest elements:
    //      1 2 3
    //      find the 5 biggest elements:
    //      10 9 8 7 6
\end{verbatim}
    \end{itemize}

\subsection{partial\_sum}\label{PARTSUM} 
    \typeout{Original Yodl file: generic/partialsum}    \index{partial\_sum} \index{inclusive\_scan} \index{exclusive\_scan}
    \begin{itemize}
        \item  Header file: \texttt{$<$numeric$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator partial\_sum(InputIterator first,
InputIterator last, OutputIterator result);}
            \item \texttt{OutputIterator partial\_sum(InputIterator first, InputIterator
last, OutputIterator result, BinaryOperation op);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
        \item  The first prototype: each element in the range
\texttt{[result, $<$returned OutputIterator$>$)} receives a value which is obtained
by adding the elements in the corresponding range of the range \texttt{[first,
last)}. The first element in the resulting range will be equal to the element
pointed to by \texttt{first}.
        \item  The second prototype: the value of each element in the range
\texttt{[result, $<$returned OutputIterator$>$)} is obtained by applying the binary
operator \texttt{op} to the previous element in the resulting range and the
corresponding element in the range \texttt{[first, last)}. The first
element in the resulting range will be equal to the element pointed to by
\texttt{first}.
        \end{itemize}
        See also \index{inclusive\_scan}\texttt{inclusive\_scan} and \index{exclusive\_scan}\texttt{exclusive\_scan}, supporting
        execution policies:
            (\texttt{cppreference}\footnote{https://en.cppreference.com}).
        \item  Example:
        \begin{verbatim}
    #include <numeric>
    #include <algorithm>
    #include <iostream>
    #include <functional>
    #include <iterator>
    using namespace std;

    int main()
    {
        int ia[] = {1, 2, 3, 4, 5};
        int ia2[5];

        copy(ia2,
            partial_sum(ia, ia + 5, ia2),
            ostream_iterator<int>(cout, " "));
        cout << '\n';

        copy(ia2,
            partial_sum(ia, ia + 5, ia2, multiplies<int>()),
            ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    /*
        Displays:
            1 3 6 10 15
            1 2 6 24 120
    */
\end{verbatim}
    \end{itemize}

\subsection{partition / partition\_point / stable\_partition}\label{PARTIT}
    \typeout{Original Yodl file: generic/partition}    \index{partition} \index{stable\_partition} \index{partition\_point}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{BidirectionalIterator partition({[}ExecPol,{]} 
BidirectionalIterator first, BidirectionalIterator last, 
UnaryPredicate pred);}
            \item \texttt{BidirectionalIterator stable\_partition({[}ExecPol,{]}
BidirectionalIterator first, BidirectionalIterator last, UnaryPredicate
pred);}
            \item \texttt{ForwardIterator partition\_point( ForwardIterator first, 
ForwardIterator last, UnaryPredicate pred );}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: all elements in the range \texttt{[first,
last)} for which the unary predicate \texttt{pred} evaluates as \texttt{true} are placed
before the elements which evaluate as \texttt{false}.
            \item  The second prototype: identical to the first prototype, but
the relative order of all elements for which the predicate evaluates to
\texttt{false} and the relative order of all elements for which the predicate
evaluates to \texttt{true} is kept.  
            \item  The third prototype: does not reorder the elements in the
\texttt{[first, last)} range, but returns an iterator to the first element for
which \texttt{pred} returns \texttt{false}. If \texttt{pred} returns \texttt{true} for all
elements then \texttt{last} is returned.
        \end{itemize}
        The return value points just beyond the last element in the
partitioned range for which \texttt{pred} evaluates as \texttt{true}.
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <iterator>
    using namespace std;

    void show(int *begin, int *end)
    {
        copy(begin, end, ostream_iterator<int>{ cout, " " });
        cout << '\n';
    }

    int main()
    {
        int org[] = { 1, 3, 5, 7, 9, 10, 2, 8, 6, 4 };
        int ia[10];

        copy(org, org + 10, ia);

        auto lessThan4 = [=](int value)
                        {
                            return value <= 4;
                        };

        int *split = partition(ia, ia + 10, lessThan4);

        cout << "Last ia[]- element <= 4 is ia[" << split - ia - 1 << "]\n";
        show(ia, end(ia));

        copy(org, org + 10, ia);
        split = stable_partition(ia, ia + 10, lessThan4);
        cout << "Last org[]-element <= 4 is ia[" << split - ia - 1 << "]\n";
        show(ia, end(ia));

        cout << "org[]-elements up to the partition point 4 are:\n";
        show(org, partition_point(org, org + 10, lessThan4));
    }
    //  Displays:
    //    Last ia[]- element <= 4 is ia[3]
    //    1 3 4 2 9 10 7 8 6 5
    //    Last org[]-element <= 4 is ia[3]
    //    1 3 2 4 5 7 9 10 8 6
    //    org[]-elements up to the partition point 4 are:
    //    1 3
\end{verbatim}
    \end{itemize}

\subsection{partition\_copy}\label{PARTCP}
    \typeout{Original Yodl file: generic/partitioncopy}    \index{partition\_copy}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}    
            \item \texttt{std::pair$<$ForwardIter2, ForwardIter3$>$
    partition\_copy({[}ExecPol,{]} ForwardIter1 first, ForwardIter1 last,
                    ForwardIter2 trueDest, ForwardIter3 falseDest,
                    UnaryPredicate pred );}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  All elements reached from the iterator range \texttt{[first,
last)} for which \texttt{pred} returns \texttt{true} are copied to the range starting at
\texttt{trueDest}, while the remaining elements are copied to the range starting at
\texttt{falseDest}. the range  \texttt{[first, last)} may not overlap with the ranges
starting at \texttt{trueDest} or \texttt{falseDest}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <string>
    #include <iostream>
    #include <iterator>
    using namespace std;

    bool pred(std::string const &str)
    {
        return "aeiou"s.find(str.front()) != string::npos;
    }

    void show(string const *begin, string const *end)
    {
        copy(begin, end, ostream_iterator<string>(cout, ", "));
        cout << '\n';
    }

    int main()
    {
        string sarr[] =
            {
                "alpha", "bravo", "charley", "delta", "echo",
                "foxtrot", "golf", "hotel"
            };
        string trueDest[size(sarr)];
        string falseDest[size(sarr)];

        pair<string *, string *> lastTF =   // lastTrue, lastFalse
            partition_copy(sarr, end(sarr), trueDest, falseDest, pred);

        cout << "pred() == true elements:\n";
        show(trueDest, lastTF.first);

        cout << "pred() == false elements:\n";
        show(falseDest, lastTF.second);

    }
    //  Displays:
    //    pred() == true elements:
    //    alpha, echo,
    //    pred() == false elements:
    //    bravo, charley, delta, foxtrot, golf, hotel,
\end{verbatim}
    \end{itemize}

\subsection{reduce}\label{REDUCE}
    \typeout{Original Yodl file: generic/reduce}    \index{reduce}
    \begin{itemize}
    \item  Header file: \texttt{$<$numeric$>$}
    \item  Function prototypes:
        \begin{itemize}
        \item \texttt{Type reduce({[}ExecPol,{]} InputIterator first, InputIterator last);}
        \item \texttt{Type reduce({[}ExecPol,{]} InputIterator first, InputIterator last, 
                    Type init);}
        \item \texttt{Type reduce({[}ExecPol,{]} InputIterator first, InputIterator last,
                BinaryOperation op);} 
        \item \texttt{Type reduce({[}ExecPol,{]} InputIterator first, InputIterator last,
                Type init, BinaryOperation op);}
        \end{itemize}
    \item  Description:
        This algorithm acts like \texttt{accumulate}
(cf. accumulate), but the algorithm requires that the used
operator is both associative and commutative: regrouping and rearranging the
elements in any order may not affect the final outcome. E.g., the numeric
addition operator satisfies both requirements.
        \begin{itemize}
        \item  The first prototype: \index{operator+}\texttt{operator+} is applied to the elements in
the range \texttt{[first, last)}, returning the resulting sum.
        \item  The second prototype: the binary operator \texttt{op} is applied to
the initial value \texttt{init} (lhs argument) and, respectively, the elements from
the iterator range \texttt{[first, last)}. The resulting sum value is returned.
        \item  The last two prototypes act like, respectively, the first two
prototypes but instead of using \texttt{operator+} the binary operator \texttt{op} is
used, receiving the variable that's eventually returned from the function as
its lhs argument and the elements in the iterator range as its rhs argument,
assigning the operator's returned values to the variable that's eventually
returned. 
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    // compile as: g++ -O2 reduce.cc -ltbb
    #include <numeric>
    #include <vector>
    #include <execution>
    #include <iostream>
    using namespace std;

    int main()
    {
        int         ia[] = {1, 2, 3, 4};
        vector<int> iv(ia, ia + 4);

                            // for demonstration purpose: it's unlikely that
        cout <<             // for 4 values parallel execution is used
            "Sum: " << reduce(execution::par,
                        iv.begin(), iv.end(), int()) << "\n"
            "Product: " << reduce(iv.begin(), iv.end(), int(1),
                                            multiplies<int>{}) << '\n';
    }
    //  Displays:
    //      Sum: 10
    //      Product: 24
\end{verbatim}
    \end{itemize}

\subsection{remove / remove\_if / remove\_copy / remove\_copy\_if}\label{REMOVE}
    \typeout{Original Yodl file: generic/remove}\index{remove} \index{remove\_copy} \index{remove\_copy\_if}  \index{remove\_if}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{ForwardIterator remove({[}ExecPol,{]} ForwardIterator first, 
                ForwardIterator last, Type const \&value);}

\item \texttt{OutputIterator remove\_copy({[}ExecPol,{]} InputIterator first, 
                InputIterator last, OutputIterator dest, Type const \&value);}

\item \texttt{OutputIterator remove\_copy\_if({[}ExecPol,{]} 
                InputIterator first, InputIterator last, 
                OutputIterator dest, 
                UnaryPredicate pred);}

\item \texttt{ForwardIterator remove\_if({[}ExecPol,{]} ForwardIterator first,
                ForwardIterator last, UnaryPredicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: elements in the range pointed to by
\texttt{[first, last)} are reordered such that all values unequal to \texttt{value}
are placed at the beginning of the range. The returned forward iterator points
to the first element that can be removed after reordering. The range
\texttt{[returnvalue, last)} is called the \index{leftover}\emph{leftover} of the algorithm. Note
that the leftover may contain elements different from \texttt{value}, but these
elements can be removed safely, as such elements are also present in the range
\texttt{[first, returnvalue)}. The function uses \texttt{operator==} of the data type
to which the iterators point to determine which elements to remove.
            \item  The second prototype: elements in the range pointed to by
\texttt{[first, last)} not matching \texttt{value} are copied to the range
\texttt{[dest, returnvalue)}, where \texttt{returnvalue} is the value returned by
the function. The range \texttt{[first, last)} is not modified.  The function
uses \texttt{operator==} of the data type to which the iterators point to determine
which elements not to copy.
            \item  The third prototype: the elements in the range pointed to by
\texttt{[first, last)} for which the unary predicate \texttt{pred} returns \texttt{true}
are not inserted into the \texttt{result} iterator. All other elements are copied
to the range \texttt{[dest, returnvalue)}, where \texttt{returnvalue} is the value
returned by the function. The range \texttt{[first, last)} is not modified.
            \item  The fourth prototype: the elements in the range pointed to by
\texttt{[first, last)} are reordered such that all values for which the unary
predicate \texttt{pred} returns \texttt{false} are placed at the beginning of the
range, keeping their relative order. The returned forward iterator
points to the first element, after reordering, for which \texttt{pred} returned
\texttt{true}. The range \texttt{[returnvalue, last)} is called the \emph{leftover} of
the algorithm. The leftover \emph{may} contain elements for which the predicate
\texttt{pred} returns \texttt{false}, but these can safely be removed, as such elements
are also present in the range \texttt{[first, returnvalue)}. Such duplication is
the result of the fact that the algorithm \emph{copies}, rather than \emph{moves}
elements into new locations.
        \end{itemize}
        Note that the \texttt{copy}-overloads expect output iterators. If the
kept elements are to be stored in, e.g., a vector \texttt{kept} then
\texttt{kept.begin()} could be passed as the function's \texttt{dest} argument. However,
that requires that \texttt{size(kept)} is large enough to contain all the kept
elements, which must therefore be known before the function is
called. Alternatively, \texttt{back\_insert\_iterator} could be used ensuring that
\texttt{kept} merely contains the kept elements once the function has
returned. This approach is used in the example program.
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <iterator>
    #include <vector>
    using namespace std;
    using StrVect = vector<string>;

    bool judge(string const &word)
    {
        return count(word.begin(), word.end(), 'a') > 1;
    }

    void show(auto const &begin, auto const &end)
    {
        copy(begin, end, ostream_iterator<string>(cout, ", "));
        cout << "\n";
    }

    int main()
    {
        StrVect words =
            {
                "kilo", "alpha", "lima", "mike", "alpha", "november",
                "alpha", "alpha", "alpha", "papa", "quebec"
            };

        auto src{ words };

        cout << "Removing all \"alpha\"s:\n";
        auto end = remove(src.begin(), src.end(), "alpha");
        show(src.begin(), end);
        cout << "Leftover elements are:\n";
        show(end, src.end());

        src = words;
        cout << "Remove_copy_if removes words having > 1 'a' chars:\n";
        StrVect kept;
        remove_copy_if(src.begin(), src.end(), back_inserter(kept), judge);
        show(kept.begin(), kept.end());

    }
    //  Displays:
    //    Removing all "alpha"s:
    //    kilo, lima, mike, november, papa, quebec,
    //    Leftover elements are:
    //    alpha, alpha, alpha, , ,
    //    Remove_copy_if removes words having > 1 'a' chars:
    //    kilo, lima, mike, november, quebec,
\end{verbatim}
    \end{itemize}

\subsection{replace / replace\_if / replace\_copy / replace\_copy\_if}\label{REPLACE}
    \typeout{Original Yodl file: generic/replace}\index{replace} \index{replace\_copy} \index{replace\_copy\_if} \index{replace\_if}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{void replace({[}ExecPol,{]} ForwardIterator first, 
    ForwardIterator last, Type const \&oldvalue, Type const \&newvalue);}
            \item \texttt{ForwardIterator replace\_if({[}ExecPol,{]} ForwardIterator first,
    ForwardIterator last, UnaryPredicate pred, Type const \&value);}
            \item \texttt{OutputIterator replace\_copy({[}ExecPol,{]} InputIterator first, 
InputIterator last, OutputIterator result, Type const \&oldvalue, 
Type const \&newvalue);}
            \item \texttt{OutputIterator replace\_copy\_if({[}ExecPol,{]} 
ForwardIterator first, ForwardIterator last, OutputIterator result, 
UnaryPredicate pred, Type const \&value);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first predicate: all elements equal to \texttt{oldvalue} in
the range pointed to by \texttt{[first, last)} are replaced by a copy of
\texttt{newvalue}. The algorithm uses \texttt{operator==} of the data type to which the
iterators point.
            \item  The second prototype: elements in the range pointed to by
\texttt{[first, last)} for which the unary predicate \texttt{pred} evaluates as
\texttt{true} are replaced by \texttt{value}.
            \item  The third prototype: all elements equal to \texttt{oldvalue} in
the range pointed to by \texttt{[first, last)} are sent to the \texttt{result} output
iterator, replacing elements equal to \texttt{oldValue} by \texttt{newValue}, using
\texttt{operator==} of the data type to which the iterators point.
            \item  The fourth prototype: the elements in the range pointed to by
\texttt{[first, last)} for which the unary predicate \texttt{pred} returns \texttt{false}
are sent to the \texttt{result} output iterator, and \texttt{value} is sent to
\texttt{result} if \texttt{pred} returns \texttt{true}. The range \texttt{[first, last)} is not
modified.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <vector>
    #include <iterator>
    using namespace std;
    using StrVect = vector<string>;

    void show(StrVect const &vect)
    {
        copy(vect.begin(), vect.end(), ostream_iterator<string>(cout, " "));
        cout.put('\n');
    }

    bool isAlpha(string const &str)
    {
        return str == "alpha";
    }

    int main()
    {
        StrVect words =
            {
                "kilo", "alpha", "lima", "mike", "alpha", "november",
                "alpha", "oscar", "alpha", "alpha", "papa"
            };

        // replace(words.begin(), words.end(), "alpha"s, "ALPHA"s);
        // show(words);

        // or, using replace_if:
        //
        // replace_if(words.begin(), words.end(), isAlpha, "ALPHA"s);
        // show(words);

        // or, using replace_copy:
        //
        // StrVect result;
        // replace_copy(words.begin(), words.end(), result.begin(),
        //              "alpha"s, "ALPHA"s);
        // show(result);

        // or, using replace_copy_if:
        //
        //StrVect result;
        replace_copy_if(words.begin(), words.end(), back_inserter(result),
                     isAlpha, "ALPHA"s);
         show(result);
    }
    /*
        Displays
            kilo ALPHA lima mike ALPHA november ALPHA oscar ALPHA ALPHA papa
    */
\end{verbatim}
    \end{itemize}

\subsection{reverse / reverse\_copy}\label{REVERSE}
    \typeout{Original Yodl file: generic/reverse}\index{reverse} \index{reverse\_copy}
\begin{itemize}
    \item  Header file:
    \texttt{$<$algorithm$>$}
    \item  Function prototype:
    \begin{itemize}
        \item \texttt{void reverse({[}ExecPol,{]} BidirectionalIterator first,
            BidirectionalIterator last);}
        \item \texttt{OutputIterator reverse\_copy({[}ExecPol,{]} BidirectionalIterator first,
            BidirectionalIterator last, OutputIterator dest);}
    \end{itemize}
    \item  Description:
    \begin{itemize}
        \item  The first prototype: the order of the elements in the range
pointed to by \texttt{[first, last)} are reversed.
        \item  The second prototype: elements in the range pointed to by
\texttt{[first, last)} are inserted in reversed order into \texttt{dest}, returning
the output iterator following the last insertion.
    \end{itemize}
    \item  Example:
    \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <vector>
    #include <iterator>
    using namespace std;
    using StrVect = vector<string>;

    void show(StrVect const &vect)
    {
        copy(vect.begin(), vect.end(), ostream_iterator<string>(cout, " "));
        cout.put('\n');
    }

    int main(int argc, char **argv)
    {
        StrVect words =
            {
                "alpha", "kilo", "lima", "mike",
                "november", "oscar", "papa"
            };

        if (argc == 1)          // no args: plain reverse
        {
            reverse(words.begin(), words.end());
            show(words);
            return 0;
        }

        using StrVect = vector<string>;
        StrVect dest;

        reverse_copy(words.begin(), words.end(),
                     back_inserter(dest));
        show(dest);
    }
    // Displays:
    //    papa oscar november mike lima kilo alpha
\end{verbatim}
\end{itemize}

\subsection{rotate / rotate\_copy}\label{ROTATE}                
    \typeout{Original Yodl file: generic/rotate}\index{rotate} \index{rotate\_copy}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{void rotate({[}ExecPol,{]} ForwardIterator first, ForwardIterator
                middle, ForwardIterator last);}
            \item \texttt{OutputIterator rotate\_copy({[}ExecPol,{]} ForwardIterator first,
ForwardIterator middle, ForwardIterator last, OutputIterator result);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: elements in the range \texttt{[first,
middle)} are moved to the end of the container, the elements in the range
\texttt{[middle, last)} are moved to the beginning of the container, keeping the
order of the elements in the two sub-ranges intact.
            \item  The elements in the range \texttt{[middle, last)} and
then the elements in the range \texttt{[first, middle)} are inserted into
\texttt{result}, returning the output iterator following the last insertion.
The order of the elements in the source ranges is not altered.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <iterator>
    #include <vector>
    using namespace std;
    using StrVect = vector<string>;

    void show(StrVect const &vect)
    {
        copy(vect.begin(), vect.end(), ostream_iterator<string>(cout, " "));
        cout.put('\n');
    }

    int main(int argc, char **argv)
    {
        StrVect words =
            {
                "kilo", "lima", "mike", "november", "oscar",
                "foxtrot", "golf", "hotel", "india", "juliet"
            };

        if (argc == 1)          // no args: plain rotate
        {
            rotate(words.begin(), words.begin() + words.size() / 2,
                   words.end());
            show(words);
            return 0;
        }

        using StrVect = vector<string>;
        StrVect dest;

        rotate_copy(words.begin(), words.begin() + words.size() / 2,
                    words.end(), back_inserter(dest));
        show(dest);
    }
    //  Displays:
    //      foxtrot golf hotel india juliet kilo lima mike november oscar
\end{verbatim}
    \end{itemize}

\subsection{sample}\label{SAMPLE}
    \typeout{Original Yodl file: generic/sample}    \index{sample} \index{shuffle}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototype:
        \begin{itemize}
            \item \texttt{OutputIterator sample(InputIterator first, InputIterator last,
                       OutputIterator out, size\_t sampleSize,
                       Generator \&\&generator);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  \texttt{sampleSize} elements are randomly selected (without
replacement) from the input range \texttt{[first, last)}, and copied to the
destination range starting at \texttt{out} and ending at the function's return
value. If \texttt{sampleSize $>$= (last - first)} all elements are selected. The
\texttt{generator} is a (uniform) random number generator, like the \index{mt19937}\texttt{mt19937}
mercenne twister.
        \end{itemize}
        See also \index{shuffle}\texttt{shuffle}:
            (\texttt{cppreference}\footnote{https://en.cppreference.com}).

\item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <random>
    #include <string>

    using namespace std;

    int main()
    {
        string src{ "abcdefghijklmnopqrstuvwxyz" };
        string dest;

        sample(src.begin(), src.end(), back_inserter(dest), 7, mt19937{});

        std::cout << "Seven random letters out of " << src << " : " <<
                                                       dest << '\n';
    }
    //  Could display:
    //    Seven random letters out of abcdefghijklmnopqrstuvwxyz : bciorux
\end{verbatim}
    \end{itemize}

\subsection{search / search\_n}\label{SEARCH}
    \typeout{Original Yodl file: generic/search}\index{search} \index{search\_n}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator search({[}ExecPol,{]} ForwardIterator first1,
ForwardIterator last1, ForwardIterator first2, ForwardIterator last2);}
            \item \texttt{ForwardIterator1 search({[}ExecPol,{]} ForwardIterator first1,
ForwardIterator last1, ForwardIterator first2, ForwardIterator last2,
BinaryPredicate pred);}
            \item \texttt{constexpr ForwardIterator1 search({[}ExecPol,{]} 
ForwardIterator first, ForwardIterator last, Searcher const \&searcher);}

\item \texttt{ForwardIterator search\_n({[}ExecPol,{]} ForwardIterator first,
ForwardIterator last, Size count, Type const \&value);}
            \item \texttt{ForwardIterator search\_n({[}ExecPol,{]} ForwardIterator first1,
ForwardIterator last1, Size count, Type const \&value, 
BinaryPredicate pred);}

\end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: an iterator into the first range
\texttt{[first1, last1)} is returned where the elements in the range
\texttt{[first2, last2)} are found using \index{operator==}\texttt{operator==} of the data
type to which the iterators point. If no such location exists, \texttt{last1} is
returned.
            \item  The second prototype: an iterator into the first range
\texttt{[first1, last1)} is returned where the elements in the range
\texttt{[first2, last2)} are found using the provided binary predicate \texttt{pred}
to compare the elements in the two ranges. If no such location exists,
\texttt{last1} is returned.
            \item  The third prototype: returns \texttt{searcher(first, last).first}:
\texttt{searcher} receives the range of elements, and returns an iterator into this
range (or \texttt{last} if \texttt{searcher} found no match) as \texttt{searcher(first,
last).first}.
            \item  The final two prototypes inspect the elements in the range
\texttt{[first, last)} for the first series of \texttt{count} elements equal to
\texttt{value}, returning the first iterator to those \texttt{count} elements. If no
such series exists then \texttt{last} is returned. The last protottype calls
\texttt{pred} to determine whether an element is equal to \texttt{value}.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <iterator>
    using namespace std;

    bool absEq(int i1, int i2)
    {
        return abs(i1) == abs(i2);
    }

    int main()
    {
        int range1[] =  {-2, -4, -6, -8, 2, 4, 4, 6, 8};
        int range2[] =  {6, 8};

        copy
        (
            search(range1, end(range1), range2, range2 + 2),
            end(range1), ostream_iterator<int>(cout, " ")
        );
        cout << '\n';

        copy
        (
            search(range1, end(range1), range2, range2 + 2, absEq),
            end(range1), ostream_iterator<int>(cout, " ")
        );
        cout << '\n';

        copy
        (
            search_n(range1, end(range1), 2, 4, absEq),
            end(range1), ostream_iterator<int>(cout, " ")
        );
        cout << '\n';
    }
    //  Displays:
    //      6 8
    //      -6 -8 2 4 4 6 8
    //      4 4 6 8
\end{verbatim}
    \end{itemize}

\subsection{set\_difference}\label{SETDIF}
    \typeout{Original Yodl file: generic/setdifference}\index{set\_difference}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator set\_difference({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,
OutputIterator result);}
            \item \texttt{OutputIterator set\_difference({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,
OutputIterator result, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: a sorted sequence of the elements
pointed to by the range \texttt{[first1, last1)} that are not present in the
range \texttt{[first2, last2)} is returned, starting at \texttt{result}, and ending
at the \texttt{OutputIterator} returned by the function. The elements in the two
ranges must have been sorted using \index{operator\textless{}}\texttt{operator$<$} of the data type to which
the iterators point.
            \item  The second prototype: a sorted sequence of the elements
pointed to by the range \texttt{[first1, last1)} that are not present in the
range \texttt{[first2, last2)} is returned, starting at \texttt{result}, and ending
at the \texttt{OutputIterator} returned by the function. The elements in the two
ranges must have been sorted using the \texttt{comp} function object.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cstring>
    #include <iterator>
    using namespace std;

    bool caseless(string const &left, string const &right)
    {
        return strcasecmp(left.c_str(), right.c_str()) < 0;
    }
    int main()
    {
        string set1[] = { "kilo", "lima", "mike", "november",
                          "oscar", "papa", "quebec" };
        string set2[] = { "papa", "quebec", "romeo"};
        string result[7];

        copy(result,
            set_difference(set1, set1 + 7, set2, set2 + 3, result),
            ostream_iterator<string>(cout, " "));
        cout << '\n';

        string set3[] = { "PAPA", "QUEBEC", "ROMEO"};

        copy(result,
            set_difference(set1, set1 + 7, set3, set3 + 3, result,
            caseless),
            ostream_iterator<string>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      kilo lima mike november oscar
    //      kilo lima mike november oscar
\end{verbatim}
    \end{itemize}

\subsection{set\_intersection}\label{SETINT}
    \typeout{Original Yodl file: generic/setintersection}\index{set\_intersection}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator set\_intersection({[}ExecPol,{]} 
InputIterator1 first1, InputIterator1) linebreak() tt(last1, InputIterator2
first2, InputIterator2 last2, OutputIterator result);} 
            \item \texttt{OutputIterator set\_intersection({[}ExecPol,{]} InputIterator1
first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,
OutputIterator result, Compare comp);} 
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: a sorted sequence of the elements
pointed to by the range \texttt{[first1, last1)} that are also present in the
range \texttt{[first2, last2)} is returned, starting at \texttt{result}, and ending
at the \texttt{OutputIterator} returned by the function. The elements in the two
ranges must have been sorted using \index{operator\textless{}}\texttt{operator$<$} of the data type to which
the iterators point.
            \item  The second prototype: a sorted sequence of the elements
pointed to by the range \texttt{[first1, last1)} that are also present in the
range \texttt{[first2, last2)} is returned, starting at \texttt{result}, and ending
at the \texttt{OutputIterator} returned by the function. The elements in the two
ranges must have been sorted using the \texttt{comp} function object.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cstring>
    #include <iterator>
    using namespace std;

    bool caseless(string const &left, string const &right)
    {
        return strcasecmp(left.c_str(), right.c_str()) < 0;
    }
    int main()
    {
        string set1[] = { "kilo", "lima", "mike", "november",
                          "oscar", "papa", "quebec" };
        string set2[] = { "papa", "quebec", "romeo"};
        string result[7];

        copy(result,
            set_intersection(set1, set1 + 7, set2, set2 + 3, result),
            ostream_iterator<string>(cout, " "));
        cout << '\n';

        string set3[] = { "PAPA", "QUEBEC", "ROMEO"};

        copy(result,
            set_intersection(set1, set1 + 7, set3, set3 + 3, result,
                                                             caseless),
            ostream_iterator<string>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      papa quebec
    //      papa quebec
\end{verbatim}
    \end{itemize}

\subsection{set\_symmetric\_difference}\label{SETSYM}
    \typeout{Original Yodl file: generic/setsymmetricdifference}\index{set\_symmetric\_difference}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator set\_symmetric\_difference({[}ExecPol,{]}
InputIterator1 first1, InputIterator1 last1, InputIterator2 first2,
InputIterator2 last2, OutputIterator result);}
            \item \texttt{OutputIterator set\_symmetric\_difference({[}ExecPol,{]}
InputIterator1 first1, InputIterator1 last1, InputIterator2 first2,
InputIterator2 last2, OutputIterator result, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: a sorted sequence of the elements
pointed to by the range \texttt{[first1, last1)} that are not present in the
range \texttt{[first2, last2)} and those in the range \texttt{[first2, last2)}
that are not present in the range \texttt{[first1, last1)} is returned, starting
at \texttt{result}, and ending at the \texttt{OutputIterator} returned by the
function. The elements in the two ranges must have been sorted using
\index{operator\textless{}}\texttt{operator$<$} of the data type to which the iterators point.
            \item  The second prototype: a sorted sequence of the elements
pointed to by the range \texttt{[first1, last1)} that are not present in the
range \texttt{[first2, last2)} and those in the range \texttt{[first2, last2)}
that are not present in the range \texttt{[first1, last1)} is returned, starting
at \texttt{result}, and ending at the \texttt{OutputIterator} returned by the
function. The elements in the two ranges must have been sorted using the
\texttt{comp} function object.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cstring>
    #include <iterator>
    using namespace std;

    bool caseless(string const &left, string const &right)
    {
        return strcasecmp(left.c_str(), right.c_str()) < 0;
    }
    int main()
    {
        string set1[] = { "kilo", "lima", "mike", "november",
                          "oscar", "papa", "quebec" };
        string set2[] = { "papa", "quebec", "romeo"};
        string result[7];

        copy(result,
            set_symmetric_difference(set1, set1 + 7, set2, set2 + 3,
                                                           result),
            ostream_iterator<string>(cout, " "));
        cout << '\n';

        string set3[] = { "PAPA", "QUEBEC", "ROMEO"};

        copy(result,
            set_symmetric_difference(set1, set1 + 7, set3, set3 + 3,
                                                     result, caseless),
            ostream_iterator<string>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      kilo lima mike november oscar romeo
    //      kilo lima mike november oscar ROMEO
\end{verbatim}
    \end{itemize}

\subsection{set\_union}\label{SETUNI}
    \typeout{Original Yodl file: generic/setunion}\index{set\_union}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator set\_union({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,
OutputIterator result);}
            \item \texttt{OutputIterator set\_union({[}ExecPol,{]} InputIterator1 first1,
InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,
OutputIterator result, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: a sorted sequence of the elements that
are present in either the range \texttt{[first1, last1)} or the range
\texttt{[first2, last2)} or in both ranges is returned, starting at \texttt{result},
and ending at the \texttt{OutputIterator} returned by the function. The elements in
the two ranges must have been sorted using \index{operator\textless{}}\texttt{operator$<$} of the data type to
which the iterators point;
            \item  The second prototype: a sorted sequence of the elements that
are present in either the range \texttt{[first1, last1)} or the range
\texttt{[first2, last2)} or in both ranges is returned, starting at \texttt{result},
and ending at the \texttt{OutputIterator} returned by the function. The elements in
the two ranges must have been sorted using \texttt{comp} function object.  
        \end{itemize} 
       Note that in the final range each element appears only once, unless
        there are already duplicate elements in the sources, in which case they
        will also appear multiple times in the result;
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cstring>
    #include <iterator>
    #include <vector>
    using namespace std;

    bool caseless(string const &left, string const &right)
    {
        return strcasecmp(left.c_str(), right.c_str()) < 0;
    }

    int main()
    {
        string set1[] =
            {
                "kilo", "lima", "mike", "november",
                "oscar", "papa", "quebec"
            };
        string set2[] = { "papa", "quebec", "romeo"};
        string result[8];

        copy(result,
            set_union(set1, set1 + 7, set2, set2 + 3, result),
            ostream_iterator<string>(cout, " "));
        cout << '\n';

        string set3[] = { "PAPA", "QUEBEC", "ROMEO"};

        copy(result,
            set_union(set1, set1 + 7, set3, set3 + 3, result, caseless),
            ostream_iterator<string>(cout, " "));
        cout << '\n';

        std::vector<int> v1 = {1, 2, 3,        4, 5, 5, 5};
        std::vector<int> v2 = {      3, 3, 3,  4, 5,       6, 7};

        set_union(v1.begin(), v1.end(), v2.begin(), v2.end(),
                   ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    //  Displays:
    //      kilo lima mike november oscar papa quebec romeo
    //      kilo lima mike november oscar papa quebec ROMEO
    //      1 2 3 3 3 4 5 5 5 6 7
\end{verbatim}
    \end{itemize}

\subsection{sort / stable\_sort }\label{SORT}
    \typeout{Original Yodl file: generic/sort}\index{sort} \index{stable\_sort}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void sort({[}ExecPol,{]} RandomAccessIterator first,
                RandomAccessIterator last);}
            \item \texttt{void sort({[}ExecPol,{]} RandomAccessIterator first,
                RandomAccessIterator last, Compare comp);}
            \item \texttt{void stable\_sort({[}ExecPol,{]} RandomAccessIterator first,
                RandomAccessIterator last);}
            \item \texttt{void stable\_sort({[}ExecPol,{]} RandomAccessIterator first,
                RandomAccessIterator last, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
           \item  The first prototype: the elements in the range \texttt{[first,
last)} are sorted in ascending order using \index{operator\textless{}}\texttt{operator$<$} of the data type to
which the iterators point.
            \item  The second prototype: the elements in the range
\texttt{[first, last)} are sorted in ascending order using the \texttt{comp}
function object to compare the elements. The binary predicate \texttt{comp}
should return \texttt{true} if its first argument should be placed earlier in the
sorted sequence than its second argument.
           \item  The last two prototypes are used identically to the first two
prototypes, but use stable-sorting, keeping the initial order of equal
elements. 
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    // compile as: g++ -O2 sort.cc -ltbb
    #include <algorithm>
    #include <cstdlib>
    #include <execution>
    #include <functional>
    #include <iostream>
    #include <iterator>
    #include <string>
    using namespace std;

    int main()
    {
        string words[] =
                {
                    "november", "kilo", "mike", "lima",
                    "oscar", "quebec", "papa"
                };

        sort(words, words + 7);
        copy(words, words + 7, ostream_iterator<string>(cout, " "));
        cout << '\n';

        sort(words, words + 7, greater<string>());
        copy(words, words + 7, ostream_iterator<string>(cout, " "));
        cout << '\n';

        int *vect = new int[10'000];
        generate(execution::par, vect, vect + 10'000, random);
        cout << "sorted: " << is_sorted(vect, vect + 10'000) << '\n';

        sort(execution::par, vect, vect + 10'000);
        cout << "sorted: " << is_sorted(vect, vect + 10'000) << '\n';

        delete[] vect;

        // stable-sorting:

        using Pair = pair<size_t, string>;  // days & nrs of the months
        vector<Pair> months =
        {
            { 31, "Jan." }, { 28, "Feb." }, { 31, "Mar." }, { 30, "Apr." },
            { 31, "May." }, { 30, "Jun." }, { 31, "Jul." }, { 31, "Aug." },
            { 30, "Sep." }, { 31, "Oct." }, { 30, "Nov." }, { 31, "Dec." },
        };

        stable_sort(months.begin(), months.end(),
                    [&](Pair const &lhs, Pair const &rhs)
                    {
                        return lhs.first > rhs.first;
                    }
        );

        for (size_t idx = 0; auto const &month: months)
            cout << month.first << ": " << month.second <<
                (++idx % 4 == 0 ? "\n" : "  ");

    }
    //  Displays:
    //      kilo lima mike november oscar papa quebec
    //      quebec papa oscar november mike lima kilo
    //      unordered sequence
    //      sorted sequence
    //      31: Jan.  31: Mar.  31: May.  31: Jul.
    //      31: Aug.  31: Oct.  31: Dec.  30: Apr.
    //      30: Jun.  30: Sep.  30: Nov.  28: Feb.
\end{verbatim}
        The example also shows two generic algorithms using the
\texttt{execution::par} execution policy: first \texttt{generate} is used to fill an
array with randomly determined \texttt{int}-values, then \texttt{sort} is used to sort
those values.
    \end{itemize}

\subsection{swap / swap\_ranges}\label{SWAP}
    \typeout{Original Yodl file: generic/swap}\index{swap} \index{swap\_ranges}
\begin{itemize}
    \item  Header file: \texttt{$<$algorithm$>$}
    \item  Function prototypes:
    \begin{itemize}
        \item \texttt{void swap(Type \&object1, Type \&object2) noexcept;}
        \item \texttt{void swap(Type (\&object1){[}N{]}, Type (\&object2)){[}N{]} noexcept;}
        \item \texttt{ForwardIterator2 swap\_ranges({[}ExecPol,{]} ForwardIterator1 first1,
            ForwardIterator1 last1, ForwardIterator2 result);}
    \end{itemize}
    \item  Description:
    \begin{itemize}
        \item  The first prototype: the elements \texttt{object1} and \texttt{object2}
exchange their values.  They do so by either cyclic copy assignment or cyclic
move assignment (if available).
        \item  The second prototype: the elements of the (compile-time) known
sizes of the \texttt{object1} and \texttt{object2} arrays exchange their values.
        \item  The third prototype: elements in the range pointed to by
\texttt{[first1, last1)} are swapped with that number of elements in the range
\texttt{[result, returnvalue)}, where \texttt{returnvalue} is the value returned by
the function. The two ranges must be disjoint.
    \end{itemize}
    \item  Example:
    \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <iterator>
    using namespace std;

    void show(string const *begin, string const *end)
    {
        copy(begin, end, ostream_iterator<string>(cout, " "));
        cout << '\n';
    }

    int main()
    {
        string first[] = { "alpha", "bravo", "charley" };
        string second[] = { "echo", "foxtrot", "golf" };

        cout << "Before:\n";
        show(first, end(first));
        show(second, end(second));

        for (size_t idx = 0; idx < size(first); ++idx)
            swap(first[idx], second[idx]);

        cout << "After:\n";
        show(first, end(first));
        show(second, end(second));

        swap_ranges(first, end(first), second);

        cout << "After swap_ranges:\n";
        show(first, end(first));
        show(second, end(second));

    }
    //  Displays:
    //    Before:
    //    alpha bravo charley
    //    echo foxtrot golf
    //    After:
    //    echo foxtrot golf
    //    alpha bravo charley
    //    After swap_ranges:
    //    alpha bravo charley
    //    echo foxtrot golf
\end{verbatim}
\end{itemize}

\subsection{transform}\label{TRANSFORM}
    \typeout{Original Yodl file: generic/transform}\index{transform}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator transform({[}ExecPol,{]} InputIterator first, 
InputIterator last, OutputIterator result, UnaryOperator op);}
            \item \texttt{OutputIterator transform({[}ExecPol,{]} InputIterator1 first1, 
InputIterator1 last1, InputIterator2 first2, OutputIterator result,
BinaryOperator op);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the unary operator \texttt{op} is applied to
each of the elements in the range \texttt{[first, last)}, and the resulting
values are stored in the range starting at \texttt{result}. The return value points
just beyond the last generated element.
            \item  The second prototype: the binary operator \texttt{op} is applied
to each of the elements in the range \texttt{[first1, last1)} and the
corresponding element in the second range starting at \texttt{first2}. The
resulting values are stored in the range starting at \texttt{result}. The return
value points just beyond the last generated element.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <functional>
    #include <vector>
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cctype>
    #include <iterator>
    using namespace std;

    string caps(string const &src)
    {
        string tmp;
        tmp.resize(src.length());

        transform(src.begin(), src.end(), tmp.begin(), ::toupper);
        return tmp;
    }
    int main()
    {
        string words[] = {"alpha", "bravo", "charley"};

        copy(words, transform(words, words + 3, words, caps),
                                ostream_iterator<string>(cout, " "));
        cout << '\n';

        int         values[] = {1, 2, 3, 4, 5};
        vector<int> squares;

        transform(values, values + 5, values,
                                back_inserter(squares), multiplies<int>());

        copy(squares.begin(), squares.end(),
                                ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    /*
        Displays:
            ALPHA BRAVO CHARLEY
            1 4 9 16 25
    */
\end{verbatim}
    \end{itemize}
    the following differences between the \texttt{for\_each} (section
\ref{FOREACH}) and \texttt{transform} generic algorithms should be noted:
    \index{for\_each: vs. transform}\index{transform: vs. for\_each}
    \begin{itemize}
        \item  With \texttt{transform} the \emph{return value} of the function
object's \texttt{operator()} member is used; the argument that is passed to the
\texttt{operator()} member itself is not changed.
        \item  With \texttt{for\_each} the function object's \texttt{operator()}
receives a reference to an argument, which itself may be changed by the
function object's \texttt{operator()}.
    \end{itemize}
    Also note that the range-based for loop can often be used instead of the
\texttt{transform} generic algorithm. However, but different from the
range-based for-loop the \texttt{transform} algorithm can also be used width
sub-ranges and with reverse-iterators.

\subsection{transform\_reduce}\label{TRANSRED}
    \typeout{Original Yodl file: generic/transformreduce}\index{transform}
    \begin{itemize}
        \item  Header file: \texttt{$<$numeric$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{Type transform\_reduce({[}ExecPol,{]} 
                InputIterator first1, InputIterator last1, 
                InputIterator first2,
                Type value);}

\item \texttt{Type transform\_reduce({[}ExecPol,{]} 
                InputIterator first1, InputIterator last1, 
                InputIterator first2,
                Type value,
                BinaryOperation reduce,
                BinaryOperation transform);}

\item \texttt{Type transform\_reduce({[}ExecPol,{]} 
                InputIterator first1, InputIterator last1, 
                Type value,
                BinaryOperation reduce,
                UnaryOperation transform);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: equals the second prototype using
\texttt{std::plus$<$$>$} for the \texttt{reduce} binary operator and \texttt{std::mutiplies$<$$>$}
for the \texttt{transform} binary operator. It's also equivalent to a parallelized
version of \texttt{inner\_product} (cf. section \ref{INNERPROD}).
            \item  The second prototype: applies the \texttt{transform} binary
operation to, as left-hand side operand, each element in the \texttt{[first1,
end1)} range and as right-hand side operand the corresponding element of the
range starting at \texttt{first2}. Each thus computed value is passed as right-hand
side operand, using \texttt{value} as left-hand side operand to the \texttt{reduce}
binary operation, returning the final value returned by \texttt{reduce}.
            \item  The third prototype: applies \texttt{transform} to each element of
the range \texttt{[first1, end1)}, and then passes \texttt{value} and each of the
values returned by \texttt{transform} to \texttt{reduce}, returning the final value
returned by \texttt{reduce}.

\end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <numeric>
    #include <algorithm>
    #include <iterator>
    #include <iostream>
    #include <string>
    using namespace std;

    class Cat
    {
        std::string  d_sep;
        public:
            Cat(string const &sep)
            :
                d_sep(sep)
            {}
            string operator()
                (string const &s1, string const &s2) const
            {
                return s1 + d_sep + s2;
            }
    };
    int main()
    {
        size_t ia1[] = { 1, 2, 3, 4, 5, 6, 7 };

                    // instead of inner_product:
        cout << "The sum of all squares in ";
        copy(ia1, ia1 + 7, ostream_iterator<size_t>{ cout, " " });
        cout << "is " << transform_reduce(ia1, ia1 + 7, ia1, 0) << '\n';

        size_t ia2[] = { 7, 6, 5, 4, 3, 2, 1 };

        cout << "The sum of all cross-products in ";
        copy(ia1, ia1 + 7, ostream_iterator<size_t>{ cout, " " });
        cout << "and ";
        copy(ia2, ia2 + 7, ostream_iterator<size_t>{ cout, " " });
        cout << "is " << transform_reduce(ia1, ia1 + 7, ia2, 0) << '\n';

        string names1[] = { "Frank", "Karel", "Piet" };
        string names2[] = { "Brokken", "Kubat", "Plomp"};

        cout << "All combined names of ";
        copy(names1, names1 + 3, ostream_iterator<string>{ cout, " " });
        cout << "and ";
        copy(names2, names2 + 3, ostream_iterator<string>{ cout, " " });
        cout << "are:" <<
            transform_reduce(names1, names1 + 3, names2, "\t"s,
                Cat{ "\n\t"}, Cat{ " " }) << '\n';
    }
    // Displays:
    //  The sum of all squares in 1 2 3 4 5 6 7 is 140
    //  The sum of all cross-products in 1 2 3 4 5 6 7 and 7 6 5 4 3 2 1 is 84
    //  All combined names of Frank Karel Piet and Brokken Kubat Plomp are:
    //          Frank Brokken
    //          Karel Kubat
    //          Piet Plomp
\end{verbatim}
    \end{itemize}

\subsection{handling uninitialized memory}\label{UNINIT}
    \typeout{Original Yodl file: generic/uninitialized}\index{placement new: generic algorithms}\index{uninitialized... algorithms}
Section \ref{PLACEMENT} covers the placement new operator. The placement new
operator is used to install values or objects in 'raw memory', i.e., memory
that is already available, but hasn't yet been initialized for the intended
object types.

As covered before, when calling something like \texttt{auto ptr = new string\{
"hello" \}} the string is constructed in memory specifically allocated to
contain the object, and the object type's constructor initializes the object
in that memory. Likewise, when calling \texttt{delete ptr} the string's destructor
is called, followed by returning the memory allocated by \texttt{new} to the common
pool. 

When using placement new the memory to contain the object is already
available, and the construction \texttt{auto ptr = new (storageAddress) string\{
"hello" \}} is used to merely construct the string at the location specified by
\texttt{storageAddress}. That string can then (as usual) be accessed via \texttt{ptr},
but \texttt{delete ptr} cannot be used, since the memory at \texttt{storageAddress} was
already available before invoking the placement new operator. Therefore, in
these cases the remarkable situation is encountered where the object's
destructor must explicitly be called (using \texttt{ptr-$>$\textasciitilde{}string()}) and using
\texttt{delete ptr} is completely wrong, causing a memory error which aborts the
program. 

Several generic algorithms, all supporting execution policies, are available
simplifying the use of \texttt{placement new}. To use these algorithm the
\index{memory: header file}\texttt{$<$memory$>$} header file must be included. 

Facilities are available to copy, fill, initialize, and move objects to/in
uninitialized (raw) memory, as well as facilities to delete the objects stored
in raw memory. Here is an overvieuw of the available facilities (cf.
\texttt{cppreference}\footnote{https://en.cppreference.com} for more details
about the algorithms handling uninitialized memory):
    \begin{itemize}
    \item \texttt{uninitialized\_copy({[}ExecPol,{]} 
            ForwardIterator first, ForwardIterator last,
            ForwardIterator dest);}\ \\ 
        copies the elements in the \texttt{[first, last)} to the raw memory
        starting at \texttt{dest}, returning the location beyond the last copied
        element.
    \item \texttt{uninitialized\_copy\_n({[}ExecPol,{]} 
            ForwardIterator first, size\_t nObjects,
            ForwardIterator dest);}\ \\ 
       same as the previous algorithm, but copies \texttt{nObjects}.
    \item \texttt{uninitialized\_default\_construct({[}ExecPol,{]} 
            ForwardIterator first, ForwardIterator last);}\ \\ 
       installs default constructed values at the raw memory locations reached
        by the iterator range \texttt{[first, last)}. The algorithm requires
        that the types referred to by the iterators are either trivial types
        (like built-in types) or define \texttt{value\_type} returning their type
        names. When using trivial types the installed do not assume that the
        installed values are 0-initialized.
    \item \texttt{uninitialized\_default\_construct\_n({[}ExecPol,{]} 
            ForwardIterator first, size\_t nObjects);}\ \\ 
       same as the previous algorithm, but installs \texttt{nObjects} in the
        uninitialized memory.
    \item \texttt{uninitialized\_fill({[}ExecPol,{]} 
            ForwardIterator first, ForwardIterator last, 
            Type const \&value);}\ \\ 
      like the first algorithm, but installing copies of \texttt{value} in the
        uninitialized memory.
    \item \texttt{uninitialized\_fill({[}ExecPol,{]} 
            ForwardIterator first, size\_t nObjects,Type const \&value);}\ \\ 
       same as the previous algorithm, but copies \texttt{value} to the
        \texttt{nObjects} subsequent locations in the uninitialized memory.
    \item \texttt{ uninitialized\_move({[}ExecPol,{]} 
            ForwardIterator first, ForwardIterator last,
            ForwardIterator dest);}\ \\ 
        same as the first algorithm, but the elements in the \texttt{[first,
        last)} are moved to the raw memory.
    \item \texttt{uninitialized\_move\_n({[}ExecPol,{]} 
            ForwardIterator first, size\_t nObjects, 
            ForwardIterator dest);}\ \\ 
        same as the previous algorithm, but \texttt{nObjects} are moved.
    \item \texttt{uninitialized\_value\_construct({[}ExecPol,{]} 
            ForwardIterator first, ForwardIterator last);}\ \\ 
       same as \texttt{uninitialized\_default\_construct}, but requires that the
        types referred to by the iterators define \texttt{value\_type} returning
        their type names.
    \item \texttt{uninitialized\_value\_construct\_n({[}ExecPol,{]} 
            ForwardIterator first, size\_t nObjects);}\ \\ 
       same as the previous algorithm, but installs \texttt{nObjects} in the
        uninitialized memory.
    \end{itemize}

The algorithm \index{construct\_at} \texttt{Type $*$construct\_at(Type $*$raw, Args
\&\&...args)} constructs an object of type \texttt{Type} in the raw memory at
\texttt{raw}, passing \texttt{args...} to \texttt{Type's} constructor.

To delete the objects installed in raw memory the following facilities are
available:
    \begin{itemize}
    \item \texttt{void destroy({[}ExecPol,{]} ForwardIterator first, 
        ForwardIterator last);}\ \\ 
       assuming the the types to which \texttt{first} refers: it calls
        \texttt{iterator-$>$\textasciitilde{}Type()} for all elements in the range \texttt{[first,
        last)}. 
    \item \texttt{void destroy({[}ExecPol,{]} ForwardIterator first, size\_t nObjects);}\ \\ 
       same as the previous algorithm, but calls the destructors of
        \texttt{nObjects} objects.
    \item \texttt{void destroy\_at(Type $*$raw);}\ \\ 
       calls the destructor of the object installed at \texttt{raw} using placement
        new. If the \texttt{raw} pointer points to an array of placement new
        allocated objects then the destructors of the elements of the array
        are called.
    \end{itemize}

Here is an example:
    \begin{verbatim}
    #include <memory>
    #include <vector>
    #include <iostream>
    #include <string>
    using namespace std;

    int main()
    {
        char raw[4 * sizeof(string)];       // raw memory to receive strings
        string *ptr = reinterpret_cast<string *>(raw);  // pointer to strings

                                            // construct 4 strings in raw
        uninitialized_default_construct_n(ptr, 4);
        destroy(ptr, ptr + 4);              // call the strings' destructors

        vector<string> vs(4, "string");     // move 4 strings to raw memory
        uninitialized_move(vs.begin(), vs.end(), ptr);

        cout << vs.front() << ", " << vs.back() << '\n' <<
                ptr[0] << ", " << ptr[3] << '\n';

        destroy(ptr, ptr + 4);              // call the strings' destructors
    }
    //  Displays:
    //      ,
    //      string, string
\end{verbatim}
\subsection{unique}\label{UNIQUE}
    \typeout{Original Yodl file: generic/unique}\index{unique}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator unique({[}ExecPol,{]} ForwardIterator first,
ForwardIterator last);}
            \item \texttt{ForwardIterator unique({[}ExecPol,{]} ForwardIterator first,
ForwardIterator last, BinaryPredicate pred);}
            \item \texttt{OutputIterator unique\_copy({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator result);}
            \item \texttt{OutputIterator unique\_copy({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator result, BinaryPredicate pred);}
        \end{itemize}
        \item  Description:\ \\ 
    The \texttt{std::unique} generic algorithm assumes that the elements in the
range have previously been sorted (cf. section \ref{SORT}).
        \begin{itemize}
            \item  The first prototype: using \index{operator==}\texttt{operator==} of the data type to
which the iterators point, all but the first of consecutively equal elements
in the range pointed to by \texttt{[first, last)} are relocated to the end of
the range. The returned forward iterator marks the beginning of the
\index{leftover}\emph{leftover}. All elements in the range \texttt{[first, return-value)} are
unique, all elements in the range \texttt{[return-value, last)} have
undetermined (but valid) values.
            \item  The second prototype: all but the first of consecutive
elements in the range pointed to by \texttt{[first, last)} for which the binary
predicate \texttt{pred} returns \texttt{true} are relocated to the end of the range. The
predicate \texttt{pred} expects two arguments of the data type to which the
iterators point. The returned forward iterator marks the beginning of the
\index{leftover}\emph{leftover}. For all pairs of elements in the range \texttt{[first,
return-value)} \texttt{pred} returns \texttt{false} (i.e., they are \emph{unique}).  All
elements in the \emph{leftover} (i.e., the range \texttt{[return-value, last)})
have undetermined (but valid) values.
            \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <cstring>
    #include <iterator>
    using namespace std;

    bool casestring(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) == 0;
    }

    int main()
    {
        string words[] = {"alpha", "alpha", "Alpha", "papa", "quebec" };
        size_t const size = sizeof(words) / sizeof(string);

        string *removed = unique(words, words + size);
        copy(words, removed, ostream_iterator<string>(cout, " "));
        cout << '\n'
             << "Trailing elements are:\n";
        copy(removed, words + size, ostream_iterator<string>(cout, " "));
        cout << '\n';

        removed = unique(words, words + size, casestring);
        copy(words, removed, ostream_iterator<string>(cout, " "));
        cout << '\n'
             << "Trailing elements are:\n";
        copy(removed, words + size, ostream_iterator<string>(cout, " "));
        cout << '\n';
    }
    /*
        Displays:
            alpha Alpha papa quebec
            Trailing elements are:
            quebec
            alpha papa quebec
            Trailing elements are:
            quebec quebec
    */
\end{verbatim}
    \end{itemize}

\subsection{unique\_copy}\label{UNIQUECP}
    \typeout{Original Yodl file: generic/uniquecopy}\index{unique\_copy}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{OutputIterator unique\_copy({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator result);}
            \item \texttt{OutputIterator unique\_copy({[}ExecPol,{]} InputIterator first,
InputIterator last, OutputIterator result, BinaryPredicate pred);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the elements in the range \texttt{[first,
last)} are copied to the resulting container, starting at \texttt{result}.
Consecutively equal elements (using \index{operator==}\texttt{operator==} of the data type to which
the iterators point) are copied only once (keeping the first of a series of
equal elements). The returned output iterator points
just beyond the last copied element.
            \item  The second prototype: the elements in the range
\texttt{[first, last)} are copied to the resulting container, starting at
\texttt{result}.  Consecutive elements in the range pointed to by \texttt{[first,
last)} for which the binary predicate \texttt{pred} returns \texttt{true} are copied only
once (keeping the first of a series of equal elements). The returned output
iterator points just beyond the last copied element.
        \end{itemize}
        \item  Example:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <string>
    #include <vector>
    #include <iterator>
    #include <cstring>
    using namespace std;

    bool casestring(string const &first, string const &second)
    {
        return strcasecmp(first.c_str(), second.c_str()) == 0;
    }
    int main()
    {
        string words[] = {"oscar", "Alpha", "alpha", "alpha",
                                                        "papa", "quebec" };
        size_t const size = sizeof(words) / sizeof(string);
        vector<string> remaining;

        unique_copy(words, words + size, back_inserter(remaining));

        copy(remaining.begin(), remaining.end(),
                ostream_iterator<string>(cout, " "));
        cout << '\n';

        vector<string> remaining2;

        unique_copy(words, words + size,
                                back_inserter(remaining2), casestring);

        copy(remaining2.begin(), remaining2.end(),
                ostream_iterator<string>(cout, " "));
        cout << '\n';
    }
    /*
        Displays:
            oscar Alpha alpha papa quebec
            oscar Alpha papa quebec
    */
\end{verbatim}
    \end{itemize}

\subsection{upper\_bound}\label{UPPERBOUND}
    \typeout{Original Yodl file: generic/upperbound}\index{upper\_bound}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{ForwardIterator upper\_bound(ForwardIterator first,
ForwardIterator last, Type const \&value);}
            \item \texttt{ForwardIterator upper\_bound(ForwardIterator first,
ForwardIterator last, Type const \&value, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}

\item  The first prototype: the sorted elements (using ascending sort)
reached from the iterator range \texttt{[first, last)} are searched for the first
element that is greater than \texttt{value}. The returned iterator marks the first
location in the sequence where \texttt{value} can be inserted without breaking the
sorted order of the elements using \index{operator\textless{}}\texttt{operator$<$} of the data type to which the
iterators point. If no such element is found, \texttt{last} is returned.

\item  The second prototype: the elements reached from the iterator
range \texttt{[first, last)} must have been sorted using the \texttt{comp} function
or function object. Each element in the range is compared to \texttt{value} using
the \texttt{comp} function. An iterator is returned pointing to the first element
for which the binary predicate \texttt{comp}, applied to the elements of the range
and \texttt{value}, returns \texttt{true}.  The \texttt{comp} function object function's
first parameter refers to \texttt{value} and the function object's second parameter
refers to an element in the iterator range.

Caveat: note that the \texttt{comp} object's parameters when using
\texttt{upper\_bound} are swapped compared to the parameters expected by
\texttt{lower\_bound}. 

\item  When the values in the iterator range were sorted in ascending
order (i.e., using \texttt{operator$<$}) then \texttt{upper\_bound} returns an iterator
pointing beyond the last of a series of values equal to \texttt{value}, while
\texttt{lower\_bound} returns an iterator pointing to the first of such a series of
equal values.

When the iterator range contains a series of values which are, according to
\texttt{comp}, equal to \texttt{value} then \texttt{upper\_bound} returns an iterator to the
first element beyond that series, while \texttt{lower\_bound} returns an iterator to
the first element of that series.

The following program illustrates the various possibilities. Th program
illustrates both \texttt{lower\_bound} and \texttt{upper\_bound} and also illustrates the
situation where \texttt{value' Type} is unequal to the types of the values in the
iterator range. Specific comment is provided below the program's code.
        \end{itemize}

\item  Example:
        \begin{verbatim}
 1: #include <algorithm>
 2: #include <iostream>
 3: using namespace std;
 4: 
 5: int main()
 6: {
 7:     using pic =  pair<int, char>;
 8: 
 9:     pic picArr[] =
10:         { {1, 'f'}, {5, 'r'}, {5, 'a'}, {7, 'n'}, {8, 'k'} };
11:     pic *picArrEnd = picArr + size(picArr);
12: 
13:     cout << "Sequence: ";
14:     for (auto &pair: picArr)
15:         cout << '{' << pair.first << ',' << pair.second << "}, ";
16:     cout << '\n';
17: 
18:     auto iter = lower_bound(picArr, picArrEnd, 5,
19:                     [&](pic const &range, int value)
20:                     {
21:                         return range.first < value;
22:                     }
23:                 );
24:     cout << "  lower bound, <,  {5,?} can be inserted before {" <<
25:                 iter->first << ',' << iter->second << "}\n";
26: 
27:     iter = upper_bound(picArr, picArrEnd, 5,
28:                     [&](int value, pic const &range)
29:                     {
30:                         return value < range.first;
31:                     }
32:                 );
33:     cout << "  upper_bound, <,  {5,?} can be inserted before {" <<
34:                 iter->first << ',' << iter->second << "}\n";
35: 
36:     iter = upper_bound(picArr, picArrEnd, 9,
37:                     [&](int value, pic const &range)
38:                     {
39:                         return value < range.first;
40:                     }
41:                 );
42:     cout << "  upper_bound, <,  {9,?} can be inserted " <<
43:                 ( &*iter == picArrEnd ? "at the end" : "???") << '\n';
44: 
45:     sort(picArr, picArrEnd,
46:         [](pic const &lhs, pic const &rhs)
47:         {
48:             return lhs.first > rhs.first;
49:         }
50:     );
51: 
52:     cout << "\nSequence: ";
53:     for (auto &pair: picArr)
54:         cout << '{' << pair.first << ',' << pair.second << "}, ";
55:     cout << '\n';
56: 
57:     iter = lower_bound(picArr, picArrEnd, 5,
58:                     [&](pic const &range, int value)
59:                     {
60:                         return range.first > value;
61:                     }
62:                 );
63:     cout << "  lower_bound, >,  {5,?} can be inserted before {" <<
64:                 iter->first << ',' << iter->second << "}\n";
65: 
66:     iter = upper_bound(picArr, picArrEnd, 5,
67:                     [&](int value, pic const &range)
68:                     {
69:                         return value > range.first;
70:                     }
71:                 );
72:     cout << "  upper_bound, >,  {5,?} can be inserted before {" <<
73:                 iter->first << ',' << iter->second << "}\n";
74: 
75:     iter = upper_bound(picArr, picArrEnd, 0,
76:                     [&](int value, pic const &range)
77:                     {
78:                         return value > range.first;
79:                     }
80:                 );
81:     cout << "  upper_bound, >,  {0,?} can be inserted " <<
82:                 ( &*iter == picArrEnd ? "at the end" : "???") << '\n';
83: }
84: // Displays:
85: // Sequence: {1,f}, {5,r}, {5,a}, {7,n}, {8,k},
86: //   lower bound, <,  {5,?} can be inserted before {5,r}
87: //   upper_bound, <,  {5,?} can be inserted before {7,n}
88: //   upper_bound, <,  {9,?} can be inserted at the end
89: //
90: // Sequence: {8,k}, {7,n}, {5,r}, {5,a}, {1,f},
91: //   lower_bound, >,  {5,?} can be inserted before {5,r}
92: //   upper_bound, >,  {5,?} can be inserted before {1,f}
93: //   upper_bound, >,  {0,?} can be inserted at the end
\end{verbatim}
\begin{itemize}
        \item  Lines 7 thru 12: the iterator range consists of a series of
            \texttt{pairs}, sorted by their \texttt{first} members.
        \item  Lines 18 thru 23: \texttt{lower\_bound} is called using a lambda
            expression to define the \texttt{Compare} function object. Note (line
            19) that a reference to a value in the iterator range is the
            lambda expression's first parameter, while the target value is its
            second parameter. 
        \item  Lines 27 thru 32: here \texttt{upper\_bound} is called, also using a
            lambda expression. With \texttt{upper\_bound} the target value is the
            lambda expression's first parameter, while a reference to a value
            in the iterator range is its second parameter. 
        \item  Lines 57 thru 62, 66 thru 71, and 75 thru 80: after sorting the
            values in the \texttt{picArr} array in descending order \texttt{lower\_bound}
            and \texttt{upper\_bound} are again used. This time instead of using the
            \texttt{$<$} operator the \texttt{$>$} operator should be used.
        \end{itemize}
    \end{itemize}

The binary\_search generic algorithm can be used to simply
determine whether or nog \texttt{value} is present in the iterator range. The
lower\_bound generic algorithm can be used to find the first
element of a series of values equal to \texttt{value}.

\subsection{Heap algorithms}
    \typeout{Original Yodl file: generic/heap}A \index{heap}heap is a kind of \index{binary tree}binary tree which can be represented by an array. In
the standard heap, the key of an element is not smaller than the key of its
children. This kind of heap is called a \emph{max heap}.  A tree in which
numbers are keys could be organized as shown in figure \ref{heaptree}.
    \begin{figure}[tbp]
\centerline{\epsffile{stl/heap.eps}}
\caption{\label{heaptree}A binary tree representation of a heap}
\end{figure}
    Such a tree may also be organized in an array:
        \begin{verbatim}
        12, 11, 10, 8, 9, 7, 6, 1, 2, 4, 3, 5
\end{verbatim}
In the following description, keep two pointers into this array in mind:
a  pointer \texttt{node} indicates the location of the next node of the tree, a
pointer \texttt{child} points to the next element which is a child of the \texttt{node}
pointer. Initially, \texttt{node} points to the first element, and \texttt{child} points
to the second element.
    \begin{itemize}
    \item \texttt{$*$node++ (== 12)}. 12 is the top node. its children are \texttt{$*$child++}
(11) and \texttt{$*$child++} (10), both less than 12.
    \item  The next node (\texttt{$*$node++ (== 11)}), in turn, has \texttt{$*$child++} (8)
and \texttt{$*$child++} (9) as its children.
    \item  The next node (\texttt{$*$node++ (== 10)}) has \texttt{$*$child++} (7)
and \texttt{$*$child++} (6) as its children.
    \item  The next node (\texttt{$*$node++ (== 8)}) has \texttt{$*$child++} (1)
and \texttt{$*$child++} (2) as its children.
    \item  Then, node (\texttt{$*$node++ (== 9)}) has children \texttt{$*$child++} (4)
and \texttt{$*$child++} (3).
    \item  Finally (as far as children are concerned) (\texttt{$*$node++ (== 7)}) has
one child \texttt{$*$child++} (5)
    \end{itemize}
    Since \texttt{child} now points beyond the array, the remaining nodes have no
children. So, nodes 6, 1, 2, 4, 3 and 5 don't have children.

Note that the left and right branches are not ordered: 8 is less than 9, but 7
is larger than 6.

A heap is created by traversing a binary tree level-wise, starting from the
top node. The top node is 12, at the zeroth level. At the first level we find
11 and 10. At the second level 8, 9, 7 and 6 are found, etc.

Heaps can be constructed in containers supporting random access. So, a list is
not an appropriate data structure for a heap. Heaps can be constructed from an
(unsorted) array (using \texttt{make\_heap}). The top-element can
be pruned from a heap, followed by reordering the heap (using
\texttt{pop\_heap}), a new element can be added to the heap,
followed by reordering the heap (using \texttt{push\_heap}), and
the elements in a heap can be sorted (using \texttt{sort\_heap},
which, of course, invalidates the heap).

\subsubsection{The `make\_heap' function}\label{MAKEHEAP}
        \typeout{Original Yodl file: generic/makeheap}\index{make\_heap}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void make\_heap(RandomAccessIterator first,
RandomAccessIterator last);}
            \item \texttt{void make\_heap(RandomAccessIterator first,
RandomAccessIterator last, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the elements in the range \texttt{[first,
last)} are reordered to form a \index{max-heap}max-heap using \index{operator\textless{}}\texttt{operator$<$} of the data
type to which the iterators point.
            \item  The second prototype: the elements in the range \texttt{[first,
last)} are reordered to form a max-heap using the binary comparison function
object \texttt{comp} to compare elements.
        \end{itemize}
        
    \end{itemize}

\subsubsection{The `pop\_heap' function}\label{POPHEAP}
        \typeout{Original Yodl file: generic/popheap}\index{pop\_heap}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void pop\_heap(RandomAccessIterator first,
RandomAccessIterator last);}
            \item \texttt{void pop\_heap(RandomAccessIterator first,
RandomAccessIterator last, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: the first element in the range
\texttt{[first, last)} is moved to \texttt{last - 1}. Then, the elements in the range
\texttt{[first, last - 1)} are reordered to form a max-heap using the
\texttt{operator$<$} of the data type to which the iterators point.
            \item  The second prototype: the first element in the range
\texttt{[first, last)} is moved to \texttt{last - 1}. Then, the elements in the range
\texttt{[first, last - 1)} are reordered to form a max-heap using the binary
comparison function object \texttt{comp} to compare elements.
        \end{itemize}
        
    \end{itemize}

\subsubsection{The `push\_heap' function}\label{PUSHHEAP}
        \typeout{Original Yodl file: generic/pushheap}\index{push\_heap}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void push\_heap(RandomAccessIterator first,
RandomAccessIterator last);}
            \item \texttt{void push\_heap(RandomAccessIterator first,
RandomAccessIterator last, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: assuming that the range \texttt{[first,
last - 1)} contains a valid heap, and the element at \texttt{last - 1} contains an
element to be added to the heap, the elements in the range \texttt{[first, last
- 1)} are reordered to form a max-heap using the \texttt{operator$<$} of the data
type to which the iterators point.
            \item  The second prototype: assuming that the range \texttt{[first,
last - 1)} contains a valid heap, and the element at \texttt{last - 1} contains an
element to be added to the heap, the elements in the range \texttt{[first, last
- 1)} are reordered to form a max-heap using the binary comparison function
object \texttt{comp} to compare elements.
        \end{itemize}
        
    \end{itemize}

\subsubsection{The `sort\_heap' function}\label{SORTHEAP}
        \typeout{Original Yodl file: generic/sortheap}\index{sort\_heap}
    \begin{itemize}
        \item  Header file: \texttt{$<$algorithm$>$}
        \item  Function prototypes:
        \begin{itemize}
            \item \texttt{void sort\_heap(RandomAccessIterator first,
RandomAccessIterator last);}
            \item \texttt{void sort\_heap(RandomAccessIterator first,
RandomAccessIterator last, Compare comp);}
        \end{itemize}
        \item  Description:
        \begin{itemize}
            \item  The first prototype: assuming the elements in the range
\texttt{[first, last)} form a valid max-heap, the elements in the range
\texttt{[first, last)} are sorted using \index{operator\textless{}}\texttt{operator$<$} of the data type to
which the iterators point.
            \item  The second prototype: assuming the elements in the range
\texttt{[first, last)} form a valid heap, the elements in the range
\texttt{[first, last)} are sorted using the binary comparison function
object \texttt{comp} to compare elements.
        \end{itemize}
        
    \end{itemize}

\subsubsection{An example using the heap functions}\label{HEAPDEMO}
        \typeout{Original Yodl file: generic/heapdemo}Here is an example showing the various generic algorithms manipulating heaps:
        \begin{verbatim}
    #include <algorithm>
    #include <iostream>
    #include <functional>
    #include <iterator>
    using namespace std;

    void show(int *ia, char const *header)
    {
        cout << header << ":\n";
        copy(ia, ia + 20, ostream_iterator<int>(cout, " "));
        cout << '\n';
    }
    int main()
    {
        int ia[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
                    11, 12, 13, 14, 15, 16, 17, 18, 19, 20};

        make_heap(ia, ia + 20);
        show(ia, "The values 1-20 in a max-heap");

        pop_heap(ia, ia + 20);
        show(ia, "Removing the first element (now at the end)");

        push_heap(ia, ia + 20);
        show(ia, "Adding 20 (at the end) to the heap again");

        sort_heap(ia, ia + 20);
        show(ia, "Sorting the elements in the heap");


        make_heap(ia, ia + 20, greater<int>());
        show(ia, "The values 1-20 in a heap, using > (and beyond too)");

        pop_heap(ia, ia + 20, greater<int>());
        show(ia, "Removing the first element (now at the end)");

        push_heap(ia, ia + 20, greater<int>());
        show(ia, "Re-adding the removed element");

        sort_heap(ia, ia + 20, greater<int>());
        show(ia, "Sorting the elements in the heap");
    }
    /*
        Displays:
            The values 1-20 in a max-heap:
            20 19 15 18 11 13 14 17 9 10 2 12 6 3 7 16 8 4 1 5
            Removing the first element (now at the end):
            19 18 15 17 11 13 14 16 9 10 2 12 6 3 7 5 8 4 1 20
            Adding 20 (at the end) to the heap again:
            20 19 15 17 18 13 14 16 9 11 2 12 6 3 7 5 8 4 1 10
            Sorting the elements in the heap:
            1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
            The values 1-20 in a heap, using > (and beyond too):
            1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
            Removing the first element (now at the end):
            2 4 3 8 5 6 7 16 9 10 11 12 13 14 15 20 17 18 19 1
            Re-adding the removed element:
            1 2 3 8 4 6 7 16 9 5 11 12 13 14 15 20 17 18 19 10
            Sorting the elements in the heap:
            20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1
    */
\end{verbatim}
\cleardoublepage\chapter{Multi Threading}\label{THREADING}
\typeout{Original Yodl file: threading}\typeout{Original Yodl file: threading/intro}The 98 \textbf{C++} standard did not acknowledge the existence of
multi-threading. Between then and the release of the current \textbf{C++} standard
computers have evolved to multi-core machines, and using multi-threading by
now is a real option to consider when developing software.

\label{PTHREADS}
Multi-threading is an extensive and complex subject, and many
good reference texts on the subject exist. The \textbf{C++} multi-threading is
built upon the facilities offered by the \index{pthreads}\emph{pthreads} library (cf. 
    \index{Nichols, B}Nichols, B, \emph{et al.}'s
        \texttt{Pthreads Programming}\footnote{http://oreilly.com/catalog/}, O'Reilly
        \index{Pthreads Programming}\index{http://oreilly.com/catalog/}). However,
in line with \textbf{C++}'s current-day philosophy the multi-threading
implementation offered by the language offers a high level interface to
multi-threading, and using the raw pthread building blocks is hardly ever
necessary (cf. \index{Williams, A.}Williams, A. (2019): \textbf{C++ Concurrency in action}).  

This chapter covers the facilities for multi-threading as supported by
\textbf{C++}. Although the coverage aims at providing the tools and examples
allowing you to create your own multi-threaded programs, coverage necessarily
is far from complete. The topic of multi threading is too extensive for
that. The mentioned reference texts provide a good starting point for any
further study of multi threading.

A \index{thread of execution}\emph{thread of execution} (commonly abbreviated to a \index{thread}\emph{thread}) is a single
flow of control within a program. It differs from a separately executed
program, as created by the \index{fork}\textbf{fork}(1) system call in the sense that threads
all run inside one program, while \textbf{fork}(1) creates independent copies of a
running program. Multi-threading means that multiple tasks are being executed
in parallel inside one program, and no assumptions can be made as to which
thread is running first or last, or at what moment in time. Especially when
the number of threads does not exceed the number of cores, each thread may be
active at the same time. If the number of threads exceed the number of cores,
the operating system will resort to \index{task switching}\emph{task switching}, offering each thread
time slices in which it can perform its tasks. Task switching takes time, and
the law of diminishing returns applies here as well: if the number of threads
greatly exceeds the number of available cores (also called
\index{overpopulation}\emph{overpopulation}), then the overhead incurred may exceed the benefit of
being able to run multiple tasks in parallel.

Since all threads are running inside one single program, all threads share the
program's data and code. When the same data are accessed by multiple threads,
and at least one of the threads is modifying these data, access must be
synchronized to avoid that threads read data while these data are being
modified by other threads, and to avoid that multiple threads modify the same
data at the same time.

So how do we run a multi-threaded program in \textbf{C++}? Let's look at \emph{hello
world}, the multi-threaded way:
        \begin{verbatim}
     1: #include <iostream>
     2: #include <thread>
     3: 
     4: void hello()
     5: {
     6:     std::cout << "hello world!\n";
     7: }
     8: 
     9: int main()
    10: {
    11:     std::thread hi(hello);
    12:     hi.join();
    13: }
\end{verbatim}
    \begin{itemize}
    \item  At line 2 the header \texttt{thread} is included, informing the compiler
about the existence of the class \texttt{std::thread} (cf. section \ref{THREAD});

\item  At line 11 the \texttt{std::thread hi} object is created. It is provided
with the name of a function (hello) which will be called in a separate
thread. Actually, the second thread, running \texttt{hello}, is immediately started
when a \texttt{std::thread} is defined this way;

\item  The \texttt{main} function itself also represents a thread: the program's
first thread. It should wait until the second thread has finished. This
is realized in line 12, where \texttt{hi.join()} waits until the thread \texttt{hi}
has finished its job. Since there are no further statements in \texttt{main}, the
program itself ends immediately thereafter.

\item  The function \texttt{hello} itself, defined in lines 4 through 7, is
trivial: it simply inserts the text `\texttt{hello world}' into \texttt{cout}, and 
terminates, thus ending the second thread.
    \end{itemize}

\section{Multi Threading}\label{THREADS}
\typeout{Original Yodl file: threading/threading}In \textbf{C++} multi threading may be implemented at various levels of abstraction. In
general the highest level of abstraction which is available to implement a
multi-threaded problem should be used. Not so much because it's often simpler
than using lower levels of abstraction, but because higher levels of
abstraction are usually semantically closer to the original problem
description, resulting in code which is easier to understand and therefore
easier to maintain.  Also, high-abstraction classes also provide exception
safety and prevent the occurrence of memory leaks.

\textbf{C++}'s main tool for creating multi-threaded programs is the class
\texttt{std::thread}, and some examples of its use have already been shown at the
beginning of this chapter. 

Characteristics of individual threads can be queried from the
\texttt{std::this\_thread} namespace. Also, \texttt{std::this\_thread} offers some control
over the behavior of an individual thread.

To synchronize access to shared data \textbf{C++} offers \emph{mutexes} (implemented
by the class \texttt{std::mutex}) and \emph{condition variables} (implemented by the
class \texttt{std::condition\_variable}).

Members of these classes may throw \texttt{system\_error} objects (cf. section
\ref{SYSTEMERROR}) when encountering a low-level error condition.

\subsection{The namespace std::this\_thread}
    \typeout{Original Yodl file: threading/thisthread}The \index{namespace this\_thread}\index{this\_thread} \texttt{namespace std::this\_thread}
contains functions that are uniquely associated with the currently running
thread.

Before using the namespace \texttt{this\_thread} the \index{thread: header file}\texttt{$<$thread$>$} header file must
be included.

Inside the \texttt{std::this\_thread} namespace several free functions are defined,
providing information about the current thread or that can be used to control
its behavior:
    \begin{itemize}
    \item \index{get\_id}\texttt{thread::id this\_thread::get\_id() noexcept}:\ \\ returns an object of type \texttt{thread::id} that identifies the currently
active thread of execution. For an active thread the returned \texttt{id} is unique
in the sense that it maps 1:1 to the currently active thread, and is not
returned by any other thread. If the thread is currently not running then the
default \index{id}\texttt{thread::id} object is returned by the \texttt{std::thread}
object's \texttt{get\_id} member.

\item \index{yield}\texttt{void yield() noexcept}:\ \\ when a thread calls \texttt{this\_thread::yield()} the current thread is
briefly suspended, allowing other (waiting) threads to start.

\item \index{sleep\_for}\texttt{void sleep\_for(chrono::duration$<$Rep, Period$>$ const \&relTime)
            noexcept}:\ \\ when a thread calls \texttt{this\_thread::sleep\_for(...)} it is suspended
for the amount of time that's specified in its argument. E.g.,
   \begin{verbatim}
std::this_thread::sleep_for(std::chrono::seconds(5));
\end{verbatim}
\item \index{sleep\_until}\texttt{void sleep\_until(chrono::time\_point$<$Clock, Duration$>$ const \&absTime)
            noexcept}:\ \\ when a thread calls this member it is suspended until the specified
\texttt{absTime} is in the past. The next example has the same effect as the
previous example:
   \begin{verbatim}
// assume using namespace std
this_thread::sleep_until(chrono::system_clock().now() + chrono::seconds(5));
\end{verbatim}
Conversely, the \texttt{sleep\_until} call in the next example immediately
returns:
   \begin{verbatim}
this_thread::sleep_until(chrono::system_clock().now() - chrono::seconds(5));
\end{verbatim}
\end{itemize}

\subsection{The class std::thread}\label{THREAD}
    \typeout{Original Yodl file: threading/thread}Multi threading in \textbf{C++} starts off with objects of the class
\index{thread}\texttt{std::thread}. Each object of this class handles a separate
thread.

Before using \texttt{Thread} objects the \index{thread: header file}\texttt{$<$thread$>$} header file must be included.

Thread objects can be constructed in various ways:
    \begin{itemize}
    \item \texttt{thread() noexcept}:\ \\ The default constructor creates a \texttt{thread} object. As it receives no
function to execute, it does not start a separate thread of execution. It is
used, e.g., as a data member of a class, allowing class objects to start a
separate thread at some later point in time;

\item \texttt{thread(thread \&\&tmp) noexcept}:\ \\ The move constructor takes ownership of the thread controlled by
\texttt{tmp}, while \texttt{tmp}, if it runs a thread, loses control over its
thread. Following this, \texttt{tmp} is in its default state, and the newly created
thread is responsible for calling, e.g., \texttt{join}.

\item \texttt{explicit thread(Fun \&\&fun, Args \&\&...args)}:\ \\ This \emph{member template} (cf. section \ref{MEMTEMP}) expects a function
(or functor) as its first argument. The function is immediately started as a
separate thread. If the function (or functor) expects arguments, then these
arguments can be passed to the \texttt{thread's} constructor immediately following
its first (function) argument. Additional arguments are passed with their
proper types and values to \texttt{fun}. Following the \texttt{thread} object's
construction, a separately running thread of execution is started.

The notation \texttt{Arg \&\&...args} indicates that any additional arguments are
passed as is to the function. The types of the arguments that are passed to
the \texttt{thread} constructor and that are expected by the called function must
match: values must be values, references must be reference, r-value references
must be r-value references (or move construction must be supported). The
following example illustrates this requirement:
    \begin{verbatim}
     1: #include <iostream>
     2: #include <thread>
     3: 
     4: using namespace std;
     5: 
     6: struct NoMove
     7: {
     8:     NoMove() = default;
     9:     NoMove(NoMove &&tmp) = delete;
    10: };
    11: 
    12: struct MoveOK
    13: {
    14:     int d_value = 10;
    15: 
    16:     MoveOK() = default;
    17:     MoveOK(MoveOK const &) = default;
    18: 
    19:     MoveOK(MoveOK &&tmp)
    20:     {
    21:         d_value = 0;
    22:         cout << "MoveOK move cons.\n";
    23:     }
    24: };
    25: 
    26: void valueArg(int value)
    27: {}
    28: void refArg(int &ref)
    29: {}
    30: void r_refArg(int &&tmp)
    31: {
    32:     tmp = 100;
    33: }
    34: void r_refNoMove(NoMove &&tmp)
    35: {}
    36: void r_refMoveOK(MoveOK &&tmp)
    37: {}
    38: 
    39: int main()
    40: {
    41:     int value = 0;
    42: 
    43:     std::thread(valueArg,   value).join();
    44:     std::thread(refArg,     ref(value)).join();
    45:     std::thread(r_refArg,   move(value)).join();
    46: 
    47: //  std::thread(refArg,     value);
    48: 
    49:     std::thread(r_refArg,   value).join();
    50:     cout << "value after r_refArg: " << value << '\n';
    51: 
    52: //  std::thread(r_refNoMove, NoMove());
    53: 
    54:     NoMove noMove;
    55: //  std::thread(r_refNoMove, noMove).join();
    56: 
    57:     MoveOK moveOK;
    58:     std::thread(r_refMoveOK, moveOK).join();
    59:     cout << moveOK.d_value << '\n';
    60: }
\end{verbatim}
    \begin{itemize}
    \item  At lines 43 through 45 we see a value, reference, and and r-value
reference being passed to a \texttt{std::thread}: with 
the functions running the threads expecting matching argument types.

\item  Line 47 fails to compile, as a value argument doesn't match the
reference expected by \texttt{refArg}. Note that this problem was solved in line 43
by using the \texttt{std::ref} function.

\item  On the other hand lines 49 and 58 compile OK, as \texttt{int} values and
class-types supporting move operations can be passed as values to functions
expecting r-value references. In this case notice that the functions expecting
the r-value references do not access the provided arguments (except for the
actions performed by their move constructors), but use move construction to
create temporary values or objects on which the functions operate.

\item  Lines 52 and 55 won't compile as the \texttt{NoMove} struct doesn't offer
a move constructor.

\item  Member functions of classes can also be used as thread functions. In
those cases the constructor's first argument must be the address of the member
function, the second argument must be a pointer (or reference, or object) for
which the member function is called as thread function, while subsequent
arguments are passed as arguments to the member function. Here is a simple
example illustrating these options:
    \begin{verbatim}
struct Demo
{
    int d_value = 0;

    void fun(int value)
    {
        d_value = value;
        cout << "fun sets value to " << value << "\n";
    }
};

int main()
{
    Demo demo;

    thread thr{&Demo::fun, ref(demo), 12 };
    thr.join();
    cout << "demo's value: " << demo.d_value << '\n';   // 12

    thr = thread{&Demo::fun, &demo, 42 };
    thr.join();
    cout << "demo's value: " << demo.d_value << '\n';   // 42

    thr = thread{&Demo::fun, demo, 77 };
    thr.join();
    cout << "demo's value: " << demo.d_value << '\n';   // 42: the thread
                                                        // copied demo
}
\end{verbatim}
\end{itemize}

Be careful when passing local variables as arguments to thread objects: if
the thread continues to run when the function whose local variables are used
terminates, then the thread suddenly uses wild pointers or wild references, as
the local variables no longer exist. To prevent this from happening
(illustrated by the next example) do as follows:
        \begin{itemize}
        \item  pass an anonymous copy of the local variable as argument to the
\texttt{thread} constructor, or

\item  call \texttt{join} on the thread object to ensure that the thread has
finished within the local variable's lifetime.
        \end{itemize}

\begin{verbatim}
     1: #include <iostream>
     2: #include <thread>
     3: #include <string>
     4: #include <chrono>
     5: 
     6: void threadFun(std::string const &text)
     7: {
     8:     for (size_t iter = 1; iter != 6; ++iter)
     9:     {
    10:         std::cout << text << '\n';
    11:         std::this_thread::sleep_for(std::chrono::seconds(1));
    12:     }
    13: }
    14: 
    15: std::thread safeLocal()
    16: {
    17:     std::string text = "hello world";
    18:     return std::thread(threadFun, std::string{ text });
    19: }
    20: 
    21: int main()
    22: {
    23:     std::thread local(safeLocal());
    24:     local.join();
    25:     std::cout << "safeLocal has ended\n";
    26: }
\end{verbatim}
    In line 18 be sure not to call \texttt{std::ref(text)} instead of
\texttt{std::string\{ text \}}.

If the thread cannot be created a \texttt{std::system\_error} exception is
thrown.

Since this constructor not only accepts functions but also function objects as
its first argument, a \index{local context}\emph{local context} may be passed to the function
object's constructor. Here is an example of a thread receiving a function
object using a local context:
        \begin{verbatim}
    #include <iostream>
    #include <thread>
    #include <array>

    using namespace std;

    class Functor
    {
        array<int, 30> &d_data;
        int d_value;

        public:
            Functor(array<int, 30> &data, int value)
            :
                d_data(data),
                d_value(value)
            {}
            void operator()(ostream &out)
            {
                for (auto &value: d_data)
                {
                    value = d_value++;
                    out << value << ' ';
                }
                out << '\n';
            }
    };

    int main()
    {
        array<int, 30> data;
        Functor functor{ data, 5 };
        thread funThread{ functor, ref(cout) };
        funThread.join();
    };
\end{verbatim}
\end{itemize}
    The class \texttt{std::thread} does not provide a copy constructor.

The following members are available:
    \begin{itemize}
    \item \texttt{thread \&operator=(thread \&\&tmp) noexcept}:
       \begin{quote}If the operator's left-hand side operand (lhs) is a joinable
thread, then \texttt{terminate} is called. Otherwise, \texttt{tmp} is assigned to the
operator's lhs and \texttt{tmp's} state is changed to the thread's default state
(i.e., \texttt{thread()}).\end{quote}

\item \index{detach}\texttt{void detach()}:\ \\ Requires \texttt{joinable} (see below) to return \texttt{true}.  The thread for
which \texttt{detach} is called continues to run. The (e.g., parent) thread calling
\texttt{detach} continues immediately beyond the \texttt{detach}-call.  After calling
\texttt{object.detach()}, `\texttt{object}' no longer represents the (possibly still
continuing but now detached) thread of execution. It is the detached thread's
implementation's responsibility to release its resources when its execution
ends.

Since \texttt{detach} disconnects a thread from the running program, e.g.,
\texttt{main} no longer can wait for the thread's completion.  As a program
ends when \texttt{main} ends, its still running detached threads also stop, and
a program may not properly finish all its threads, as demonstrated by
the following example: 
            \begin{verbatim}
    #include <thread>
    #include <iostream>
    #include <chrono>

    void fun(size_t count, char const *txt)
    {
        for (; count--; )
        {
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
            std::cout << count << ": " << txt << std::endl;
        }
    }

    int main()
    {
        std::thread first(fun, 5, "hello world");
        first.detach();

        std::thread second(fun, 5, "a second thread");
        second.detach();

        std::this_thread::sleep_for(std::chrono::milliseconds(400));
        std::cout << "leaving" << std::endl;
    }
\end{verbatim}
A detached thread may very well continue to run after the function that
launched it has finished. Here, too, you should be very careful not to pass
local variables to the detached thread, as their references or pointers will
be undefined once the function defining the local variables terminates:
            \begin{verbatim}
#include <iostream>
#include <thread>
#include <chrono>

using namespace std;
using namespace chrono;

void add(int const &p1, int const &p2)
{
    this_thread::sleep_for(milliseconds(200));
    cerr << p1 << " + " << p2 << " = " << (p1 + p2) << '\n';
}

void run()
{
    int v1 = 10;
    int v2 = 20;

//  thread(add, ref(v1), ref(v2)).detach();     // DON'T DO THIS
    thread(add, int(v1), int(v2)).detach();     // this is OK: own copies
}

int main()
{
    run();
    this_thread::sleep_for(seconds(1));
}
\end{verbatim}
\item \index{get\_id}\texttt{id get\_id() const noexcept}:\ \\ If the current object does not represent a running thread 
\index{id}\texttt{thread::id()} is returned. Otherwise, the thread's unique ID
(also obtainable from within the thread via \texttt{this\_thread::get\_id()}) is
returned.

\item \index{hardware\_concurrency}\texttt{unsigned thread::hardware\_concurrency() noexecpt}:\ \\ This static member returns the number of threads that can run at the
same time on the current computer. On a stand-alone multi-core computer it
(probably) returns the number of cores.

\item \index{join}\texttt{void join()}:\ \\ Requires \texttt{joinable} to return \texttt{true}.  If the thread for which
\texttt{join} is called hasn't finished yet then the thread calling \texttt{join} will
be suspended (also called \emph{blocked}) until the thread for which \texttt{join} is
called has completed. Following its completion the object whose \texttt{join}
member was called no longer represents a running thread, and its \texttt{get\_id}
member will return \texttt{std::thread::id()}.

This member was used in several examples shown so far. As noted: when
\texttt{main} ends while a joinable thread is still running, \texttt{terminate} is
called, aborting the program.

\item \index{joinable}\texttt{bool joinable() const noexcept}:\ \\ returns \texttt{object.get\_id() != id()}, where \texttt{object} is the
\texttt{thread} object for which \texttt{joinable} was called.

\item \index{native\_handle}\texttt{native\_handle\_type  native\_handle()}:\ \\ returns the thread's \emph{handle} (implementation defined). This handle
can be passed to functions like \index{pthread\_getschedparam}\texttt{pthread\_getschedparam} and
\index{pthread\_setschedparam}\texttt{pthread\_setschedparam} to get/set the thread's scheduling policy and
parameters.

\item \index{swap}\texttt{void swap(thread \&other) noexcept}:\ \\ The states of the \texttt{thread} object for which \texttt{swap} was called and
\texttt{other} are swapped. Note that threads may always be swapped, even when
their thread functions are currently being executed.
    \end{itemize}

Things to note:
    \begin{itemize}
    \item  When intending to define an anonymous thread it may appear not to
start, unless you immediately also call \texttt{join}. E.g.,
            \begin{verbatim}
void doSomething();
int main()
{
    thread(doSomething);        // nothing happens??
    thread(doSomething).join(); // doSomething is executed??
}
\end{verbatim}
This similar to the situation we encountered in section \ref{UNIFORMINIT}:
the first statement doesn't define an anonymous \texttt{thread} object at all. It
simply defines the \texttt{thread} object \texttt{doSomething}. Consequently,
compilation of the second statement fails, as there is no \texttt{thread(thread \&)}
constructor. When the first statement is omitted, the \texttt{doSomething} function
is executed by the second statement. If the second statement is omitted, a
default constructed \texttt{thread} object by the name of \texttt{doSomething} is
defined.

\item  A thread only starts after its construction has completed. This
includes move constructions or move assignments. E.g., in a statement like
        \begin{verbatim}
    thread object(thread(doSomething));
\end{verbatim}
the move constructor is used to transfer control from an anonymous thread
executing \texttt{doSomething} to the thread \texttt{object}. Only after \texttt{object}'s
construction has completed \texttt{doSomething} is started in the separate thread.

\item  Exceptions thrown from the thread (e.g., by the function defining the
thread's actions) are local to the executed thread. Either they must be caught
by the executing thread (as each running thread has its own execution stack),
or they can be passed to the starting thread using a \texttt{packaged\_task} and a
\texttt{future} (cf., respectively, sections \ref{PACKAGE} and \ref{FUTURE}).
    \end{itemize}

A thread ends when the function executing a thread finishes. When a
\texttt{thread} object is destroyed while its thread function is still running,
\texttt{terminate} is called, aborting the program's end. Bad news: the destructors
of existing objects aren't called and exceptions that are thrown are left
uncaught. This happens in the following program as the thread is still active
when \texttt{main} ends:
        \begin{verbatim}
    #include <iostream>
    #include <thread>

    void hello()
    {
        while (true)
            std::cout << "hello world!\n";
    }

    int main()
    {
        std::thread hi(hello);
    }
\end{verbatim}
    There are several ways to solve this problem. One of them is discussed in
the next section.

\subsubsection{Static data and threads: thread\_local}
        \typeout{Original Yodl file: threading/threadlocal}With multi-threaded programs the well-known distinction between global and
local data is somewhat too coarse. For single- and multi-threaded programs
alike, global data are available to all of the program's code, and local data
are available to the function (or compound statement) in which the local data
are defined. But multi-threaded programs may feel the need for an intermediate
type of data, uniquely available to the different threads.

The \index{thread\_local}\texttt{thread\_local} keyword provides this intermediate data level. Global
variables declared as \texttt{thread\_local} are global within each individual
thread. Each thread owns a copy of the \texttt{thread\_local} variables, and may
modify them at will. A \texttt{thread\_local} variable in one thread is completely
separated from that variable in another thread. Here is an example:
        \begin{verbatim}
     1: #include <iostream>
     2: #include <thread>
     3: 
     4: using namespace std;
     5: 
     6: thread_local int t_value = 100;
     7: 
     8: void modify(char const *label, int newValue)
     9: {
    10:     cout << label << " before: " << t_value << ". Address: " <<
    11:                                                     &t_value << '\n';
    12:     t_value = newValue;
    13:     cout << label << " after: " << t_value << '\n';
    14: }
    15: 
    16: int main()
    17: {
    18:     thread(modify, "first", 50).join();
    19:     thread(modify, "second", 20).join();
    20:     modify("main", 0);
    21: }
\end{verbatim}
    \begin{itemize}
    \item  At line 6 the \texttt{thread\_local} variable \texttt{t\_value} is defined. It is
initialized to 100, and that becomes the initial value for each separately
running thread;

\item  In lines 8 through 14 the function \texttt{modify} is defined. It assigns
a new value to \texttt{t\_value};

\item  At lines 18 and 19 two threads are started, which are immediately
joining the main thread again. 

\item  The main thread itself is also a thread, and it directly calls
\texttt{modify}. 
    \end{itemize}
    Running this program shows that each separate thread starts with
\texttt{t\_value} being 100, and then modifies it without affecting the values of
\texttt{t\_value} used by other threads. 

Note that, although the \texttt{t\_value} variables are unique to each thread,
identical addresses may be shown for them. Since each thread uses its own
stack, these variables may occupy the same relative locations within their
respective stacks, giving the illusion that their physical addresses are
identical.

\subsubsection{Exceptions and join()}
        \typeout{Original Yodl file: threading/joining}Once a thread starts and it isn't detached it must eventually join
its starting (parent) thread, or the program aborts. Usually, once a thread
has started the parent thread continues to do some work by itself:
        \begin{verbatim}
    void childActions();
    void doSomeWork();

    void parent()
    {
        thread child(childActions);
        doSomeWork();
        child.join();
    }
\end{verbatim}
However, maybe \texttt{doSomeWork} can't complete its work, and throws an
exception, to be caught outside of \texttt{parent}. This, unfortunately, ends
\texttt{parent}, and \texttt{child.join()} is missed. Consequently, the program aborts
because of a thread that hasn't been joined.

Clearly, all exceptions must be caught, \texttt{join} must be called, and the
exception must be rethrown. But \texttt{parent} cannot use a function try-block, as
the thread object is already out of scope once execution reaches the matching
\texttt{catch}-clause. So we get:
        \begin{verbatim}
    void childActions();
    void doSomeWork();

    void parent()
    {
        thread child(childActions);
        try
        {
            doSomeWork();
            child.join();
        }
        catch (...)
        {
            child.join();
            throw;
        }
    }
\end{verbatim}
This is ugly: suddenly the function's code is clobbered with a
\texttt{try-catch} clause, as well as some unwelcome code-duplication.

This situation can be avoided using object based programming. Like, e.g.,
unique pointers, which use their destructors to encapsulate the destruction of
dynamically allocated memory, we can use a comparable technique to encapsulate
thread joining in an object's destructor.

By defining the \texttt{thread} object inside a class we're sure that by the time
the our object goes out of scope, even if the \texttt{childActions} function
throws an exception, the thread's \texttt{join} member is called. Here are the bare
essentials of our \texttt{JoinGuard} class, providing the join-guarantee (using
in-line member implementations for brevity):
        \begin{verbatim}
     1: #include <thread>
     2: 
     3: class JoinGuard
     4: {
     5:     std::thread d_thread;
     6: 
     7:     public:
     8:         JoinGuard(std::thread &&threadObj)
     9:         :
    10:             d_thread(std::move(threadObj))
    11:         {}
    12:         ~JoinGuard()
    13:         {
    14:             if (d_thread.joinable())
    15:                 d_thread.join();
    16:         }
    17: };
\end{verbatim}
    \begin{itemize}
    \item  At line 8 its only constructor starts: it receives a temporary
\texttt{thread} object, which is moved, in line 10, to \texttt{JoinGuard's d\_thread}
data member. 

\item  When the \texttt{JoinGuard} object ceases to exist, its destructor (line
12) makes sure the thread is joined if it's still joinable (lines 14 and 15).
    \end{itemize}
    Here is an example how \texttt{JoinGuard} could be used:
        \begin{verbatim}
     1: #include <iostream>
     2: #include "joinguard.h"
     3: 
     4: void childActions();
     5: 
     6: void doSomeWork()
     7: {
     8:     throw std::runtime_error("doSomeWork throws");
     9: }
    10: 
    11: void parent()
    12: {
    13:     JoinGuard{std::thread{childActions}};
    14:     doSomeWork();
    15: }
    16: 
    17: int main()
    18: try
    19: {
    20:     parent();
    21: }
    22: catch (std::exception const &exc)
    23: {
    24:     std::cout << exc.what() << '\n';
    25: }
\end{verbatim}
    \begin{itemize}
    \item  At line 4 \texttt{childActions} is declared. Its implementation (not
provided here) defines the child thread's actions.

\item  The \texttt{main} function (lines 17 through 25) provides the function 
try-block to catch the exception thrown by \texttt{parent};

\item  The \texttt{parent} function defines (line 13) an anonymous \texttt{JoinGuard},
receiving  an anonymous \texttt{thread} object. Anonymous objects are used, as the
parent function doesn't need to access them anymore.

\item  In line 14 \texttt{doSomeWork} is called, which throws an exception. This
ends \texttt{parent}, but just before that \texttt{JoinGuard's} destructor makes sure
that the child-thread has been joined.
    \end{itemize}

\subsection{The class std::jthread}\label{JTHREAD}
    \typeout{Original Yodl file: threading/jthread}\index{jthread} In addition to \texttt{std::thread} the class \texttt{std::jthread} can be
used. 

Before using \texttt{jthread} objects the \index{thread: header file}\texttt{$<$thread$>$} header file must be
included.

Objects of the class \texttt{jthread} act like \texttt{thread} objects, but a
\texttt{jthread} thread automatically joins the thread that activated
\texttt{jthread}. Moreover, in some situations \texttt{jthread} threads can directly 
be ended.

Once a \texttt{jthread} object receiving a function defining the thread's actions
has been constructed that function immediately starts as a separate thread.
If that function ends by returning a value then that value is ignored. If the
function throws an exception the program ends by calling
\texttt{std::terminate}. Alternatively, if the function should communicate a return
value or an exception to, e.g., the function starting the \texttt{jthread} a
\texttt{std::promise} (cf. section (\ref{PROMISE})) can be used or it can modify
variables which are shared with other threads (see also sections \ref{MUTEX}
and \ref{ATOMIC}).

The class \texttt{jthread} offers these constructors:
    \begin{itemize}
    \item \texttt{jthread() noexcept}:\ \\ The default constructor creates a \texttt{jthread} object that doesn't
start a thread. It could be used as a data member of a class, allowing class
objects to start the \texttt{jthread} at some later point in time;

\item \texttt{explicit jthread(Function \&\&function, Args \&\&...args)}:\ \\ This constructor (which is a \emph{member template}, cf. section
\ref{MEMTEMP}) expects a function (or functor) as its first argument, starting
the thread defined by \texttt{function}. The function receives as its first
argument the return value of \texttt{jthread's} member \texttt{get\_stop\_token} (see
below), followed by the \texttt{args} parameters (if present). If \texttt{function's}
first argument is not a \texttt{std::stop\_token} then \texttt{function}, merely
receiving the \texttt{args} parameter values as its arguments. Arguments are passed
to \texttt{function} with their proper types and values (see the example shown
below at the description of the \texttt{jthread} member \texttt{request\_stop};)

\item  The class \texttt{jthread} supports move construction and move assignment,
but does not offer copy construction and copy assignment.
    \end{itemize}

The following members are available and operate like the identically named
\texttt{std::thread} members. Refer to section \ref{THREAD} for their descriptions:
    \begin{itemize}
    \item \index{detach}\texttt{void detach();}
    \item \index{get\_id}\texttt{id get\_id() const noexcept;}
    \item \index{hardware\_concurrency}\texttt{unsigned thread::hardware\_concurrency() noexecpt}
    \item \index{join}\texttt{void join();}
    \item \index{joinable}\texttt{bool joinable() const noexcept;}
    \item \index{native\_handle}\texttt{native\_handle\_type  native\_handle();}
    \item \index{swap}\texttt{void swap(thread \&other) noexcept.}
    \end{itemize}

The following members are specific to \texttt{jthread}, allowing other threads to
end the thread started by \texttt{jthread}:

\begin{itemize}
    \item \index{get\_stop\_source}\texttt{std::stop\_source get\_stop\_source() noexcept}:\ \\ returns the \index{stop\_token} \texttt{jthread's std::stop\_source}.

\item \index{get\_stop\_token}\texttt{std::get\_stop\_token get\_stop\_token() const noexcept}:\ \\ returns the \index{stop\_token} \texttt{jthread's std::stop\_token}.

\item \index{request\_stop}\texttt{bool request\_stop() noexcept}:\ \\ attempts to end the thread started by the \texttt{jthread} object. The
        function operates atomically: it can be called from multiple threads
        without causing race conditions. It returns \texttt{true} if the stop
        request was successfully issued. It returns \texttt{false} if a stop
        request has already been issued, which may also happen if
        \texttt{request\_stop} was issued by different threads, and another thread
        is still in the process of ending \texttt{jthread's} thread.\ \\  When
        issuing \texttt{request\_stop} then \texttt{std::stop\_callback} functions (see
        the next section) that were registered for the thread's stop state are
        synchroneously called. If those callback functions throw exceptions
        then \texttt{std::terminate} is called. Also, any waiting condition
        variables that are associated with the \texttt{jthread's} stop state end
        their waiting states.
    \end{itemize}

Here is a short program illustrating \texttt{request\_stop}:
        \begin{verbatim}
     1: #include <iostream>
     2: #include <thread>
     3: #include <chrono>
     4: using namespace std;
     5: 
     6: void fun(std::stop_token stop)
     7: {
     8:     while (not stop.stop_requested())
     9:     {
    10:         cout << "next\n";
    11:         this_thread::sleep_for(1s);
    12:     }
    13: }
    14: 
    15: int main()
    16: {
    17:     jthread thr(fun);
    18: 
    19:     this_thread::sleep_for(3s);
    20: 
    21:     thr.request_stop();
    22: 
    23:     // thr.join() not required.
    24: }
\end{verbatim}
\begin{itemize}
    \item  at line 17 the \texttt{jthread} thread starts, receiving function \texttt{fun}
        as its argument;
    \item  as \texttt{fun} defines a \texttt{std::stop\_token} parameter, \texttt{jthread} will
        start that function. It performs (line 8) a \texttt{while} loop that
        continues until \texttt{stop's stop\_requested} returns \texttt{true}. The loop
        itself shows a brief output line (line 10) followed by a one-second
        sleep (line 11);
    \item  the \texttt{main} function, having started the thread, sleeps for three
        seconds (line 19), and then (line 21) issues a stop-request, 
        ending the thread.
    \end{itemize}

When running the program three lines containing \texttt{next} are displayed.

\subsubsection{std::stop\_callback}
        \typeout{Original Yodl file: threading/stopcallback}Before using \index{stop\_callback}\texttt{std::stop\_callback} objects the
\index{stop\_token: header file}\texttt{$<$stop\_token$>$} header file must be included.

In addition to merely ending thread functions via \texttt{jthread's request\_stop}
member function it's also possible to associate \index{callback} \emph{callback
functions} with \texttt{request\_stop}, which are executed when \texttt{request\_stop} is
called. In situations where callback functions are registered when the
thread function has already been stopped the callback functions are
immediately called when they are being registered (registering callback
functions is covered below). 

Note that multiple callback functions can be registered. However, the order in
which these callback functions are run once the thread is stopped is not
defined. Moreover, exceptions may not leave callback functions or the program
ends by calling \texttt{std::terminate}.

Callback functions are registered by objects of the class
\texttt{std::stop\_callback}. The class \texttt{stop\_callback} offers the following
constructors:
    \begin{itemize}
    \item \texttt{explicit stop\_callback(std::stop\_token const \&st, 
                               Function \&\&cb) noexcept;}
    \item \texttt{explicit stop\_callback(std::stop\_token \&\&st, Function \&\&cb) noexcept;}
    \end{itemize}

Notes:
    \begin{itemize}
    \item \texttt{Function} can be the name of a (void) function without parameters or
        it can be an (anonymous or existing) object offering a parameter-less
        (void) function call operator. The functions do not necessarily have
        to be void functions, but their return values are ignored;
    \item  The \texttt{noexcept} is only used if \texttt{Function} is also declared as
        \texttt{noexcept} (if \texttt{Function} is the name of a functor-class then
        \texttt{noexcept} is used if its constructor is declared with
        \texttt{noexcept});
    \item  The class \texttt{stop\_callback} does not offer copy/move construction and
        assignment. 
    \end{itemize}

Here is the example used in the previous section, this time defining a
callback function. When running this program its output is
        \begin{verbatim}
    next
    next
    next
    stopFun called via stop_callback
\end{verbatim}
\begin{verbatim}
     1: void fun(std::stop_token stop)
     2: {
     3:     while (not stop.stop_requested())
     4:     {
     5:         cout << "next\n";
     6:         this_thread::sleep_for(1s);
     7:     }
     8: }
     9: 
    10: void stopFun()
    11: {
    12:     cout << "stopFun called via stop_callback\n";
    13: }
    14: 
    15: int main()
    16: {
    17:     jthread thr(fun);
    18: 
    19:     stop_callback sc{ thr.get_stop_token(), stopFun };
    20: 
    21:     this_thread::sleep_for(3s);
    22: 
    23:     thr.request_stop();
    24:     thr.join();
    25: }
\end{verbatim}
The function \texttt{fun} is identical to the one shown in the previous
section, but \texttt{main} defines (line 19) the \texttt{stop\_callback} object \texttt{sc},
passing it \texttt{thr's get\_stop\_token's} return value and the address of the
function \texttt{stopFun}, defined in lines 10 thru 13. In this case once
\texttt{request\_stop} is called (line 23) the callback function \texttt{stopFun} is
called as well.

\section{Synchronization (mutexes)}\label{MUTEX}
\typeout{Original Yodl file: threading/mutex}Objects of \index{mutex}mutex classes are used to protect shared data.

Before using mutexes the \index{mutex: header file}\texttt{$<$mutex$>$} header file must be included.

One of the key characteristics of multi-threaded programs is that threads may
share data. Functions running as separate threads have access to all global
data, and may also share the local data of their parent threads. However,
unless proper measures are taken, this may easily result in data corruption,
as illustrated by the following simulation of some steps that could be
encountered in a multi-threaded program:
        \begin{verbatim}
---------------------------------------------------------------------------
Time step:    Thread 1:     var        Thread 2:       description
---------------------------------------------------------------------------
    0                        5
    1           starts                                  T1 active
    2           writes var                              T1 commences writing
    3           stopped                                 Context switch
    4                                   starts          T2 active
    5                                   writes var      T2 commences writing
    6                       10          assigns 10      T2 writes 10
    7                                   stopped         Context switch
    8           assigns 12                              T1 writes 12
    9                       12
----------------------------------------------------------------------------
\end{verbatim}
In this example, threads 1 and 2 share variable \texttt{var}, initially having
the value 5. At step 1 thread 1 starts, and starts to write a value into
\texttt{var}. However, it is interrupted by a context switch, and thread 2 is
started (step 4). Thread 2 \emph{also} wants to write a value into \texttt{var}, and
succeeds until time step 7, when another context switch takes place. By now
\texttt{var} is 10. However, thread 1 was also in the process of writing a value
into \texttt{var}, and it is given a chance to complete its work: it assigns 12
to \texttt{var} in time step 8. Once time step 9 is reached, thread 2 proceeds on
the (erroneous) assumption that \texttt{var} must be equal to 10. Clearly, from the
point of view of thread 2 its data have been corrupted.

In this case data corruption was caused by multiple threads accessing the same
data in an uncontrolled way. To prevent this from happening, access to shared
data should be protected in such a way that only one thread at a time may
access the shared data.

\emph{Mutexes} are used to prevent the abovementioned kinds of problems by
offering a guarantee that data are only accessed by the thread that could lock
the mutex that is used to synchronize access to those data.

Exclusive data access completely depends on cooperation between the
threads. If thread 1 uses mutexes, but thread 2 doesn't, then thread 2 may
freely access the common data. Of course that's bad practice, which should be
avoided.

It is stressed that although \emph{using} mutexes is the programmer's
responsibility, their \emph{implementation} isn't: mutexes offer the necessary
atomic calls. When requesting a mutex-lock the thread is blocked (i.e., the
mutex statement does not return) until the lock has been obtained by the
requesting thread.

Apart from the class \texttt{std::mutex} the class \index{recursive\_mutex}
\texttt{std::recursive\_mutex} is available.  When a \texttt{recursive\_mutex} is called
multiple times by the same thread it increases its lock-count. Before other
threads may access the protected data the recursive mutex must be unlocked
again that number of times. Moreover, the classes 
        \index{timed\_mutex}\texttt{std::timed\_mutex} 
    and 
        \index{recursive\_timed\_mutex}\texttt{std::recursive\_timed\_mutex} 
    are available. Their locks expire when released, but also after a certain
amount of time.

The members of the mutex classes perform \index{atomic actions}\emph{atomic actions}: no context
switch occurs while they are active. So when two threads are trying to
\emph{lock} a mutex only one can succeed. In the above example: if both threads
would use a mutex to control access to \texttt{var} thread 2 would not have been
able to assign 12 to \texttt{var}, with thread 1 assuming that its value was 10. We
could even have two threads running purely parallel (e.g., on two separate
cores). E.g.:
        \begin{verbatim}
-------------------------------------------------------------------------
Time step:    Thread 1:        Thread 2:        description
-------------------------------------------------------------------------
    1         starts           starts           T1 and T2 active
    2         locks            locks            Both threads try to 
                                                lock the mutex
    3         blocks...        obtains lock     T2 obtains the lock,
                                                and T1 must wait
    4         (blocked)        processes var    T2 processes var,
                                                T1 still blocked
    5         obtains lock     releases lock    T2 releases the lock,
                                                and T1 immediately 
                                                obtains the lock
    6         processes var                     now T1 processes var
    7         releases lock                     T1 also releases the lock
-------------------------------------------------------------------------
\end{verbatim}
Although mutexes can directly be used in programs, this rarely happens. It is
more common to embed mutex handling in locking classes that make sure that the
mutex is automatically unlocked again when the mutex lock is no longer
needed. Therefore, this section merely offers an overview of the interfaces of
the mutex classes. Examples of their use will be given in the upcoming
sections (e.g., section \ref{LOCKS}).

All mutex classes offer the following constructors and members:
    \begin{itemize}
    \item \texttt{mutex() constexpr}:\ \\ The default \texttt{constexpr} constructor is the only available
constructor; 

\item \texttt{\textasciitilde{}mutex()}:\ \\ The destructor does \emph{not} unlock a locked mutex. If locked it must
explicitly be unlocked using the mutex's \texttt{unlock} member;

\item \index{lock}\texttt{void lock()}:\ \\ The calling thread blocks until it owns the mutex. Unless \texttt{lock} is
called for a recursive mutex a \emph{system\_error} is thrown if the thread
already owns the lock. Recursive mutexes increment their internal 
    \index{lock count}\emph{lock count};

\item \index{try\_lock}\texttt{bool try\_lock() noexcept}:\ \\ The calling thread tries to obtain ownership of the mutex. If
ownership is obtained, \texttt{true} is returned, otherwise \texttt{false}. If the
calling thread already owns the lock \texttt{true} is also returned, and in this
case a recursive mutex also increments its internal \index{lock count}\emph{lock count};

\item \index{unlock}\texttt{void unlock() noexcept}:\ \\ The calling thread releases ownership of the mutex.  A
\texttt{system\_error} is thrown if the thread does not own the
lock. A recursive mutex decrements its interal lock count, releasing
ownership of the mutex once the lock count has decayed to zero;
    \end{itemize}

The timed-mutex classes (\texttt{timed\_mutex, recursive\_timed\_mutex}) also offer
these members:
    \begin{itemize}
    \item \index{try\_lock\_for}\texttt{bool try\_lock\_for(chrono::duration$<$Rep, Period$>$ const 
            \&relTime) noexcept}:\ \\ The calling thread tries to obtain ownership of the mutex within the
specified time interval. If ownership is obtained, \texttt{true} is returned,
otherwise \texttt{false}. If the calling thread already owns the lock \texttt{true} is
also returned, and in this case a recursive timed mutex also increments its
internal \index{lock count}\emph{lock count}. The \texttt{Rep} and \texttt{Duration} types are inferred from
the actual \texttt{relTime} argument. E.g.,
       \begin{verbatim}
std::timed_mutex timedMutex;
timedMutex.try_lock_for(chrono::seconds(5));
\end{verbatim}
\item \index{try\_lock\_until}\texttt{bool try\_lock\_until(chrono::time\_point$<$Clock,
            Duration$>$ const \&absTime) noexcept}:\ \\ The calling thread tries to obtain ownership of the mutex until
\texttt{absTime} has passed. If ownership is obtained, \texttt{true} is returned,
otherwise \texttt{false}. If the calling thread already owns the lock \texttt{true} is
also returned, and in this case a recursive timed mutex also increments its
internal \index{lock count}\emph{lock count}. The \texttt{Clock} and \texttt{Duration} types are inferred
from the actual \texttt{absTime} argument. E.g.,
       \begin{verbatim}
std::timed_mutex timedMutex;
timedMutex.try_lock_until(chrono::system_clock::now() + chrono::seconds(5));
\end{verbatim}
\end{itemize}

\subsection{Initialization in multi-threaded programs}
    \typeout{Original Yodl file: threading/initialization}Before using the \index{once\_flag}\texttt{std::once\_flag} and the
\index{call\_once}\texttt{std::call\_once} function, introduced in this section, the
\index{mutex: header file}\texttt{$<$mutex$>$} header file must be included.

In single threaded programs the initialization of global data does not
necessarily occur at one point in code. An example is the initialization of
the object of a singleton class (cf. \emph{Gamma et al.} (1995), Design Patterns,
Addison-Wesley). Singleton classes may define a single static pointer data
member \texttt{Singleton $*$s\_object}, pointing to the singleton's object, and may
offer a static member \texttt{instance}, implemented something like this:
        \begin{verbatim}
    Singleton &Singleton::instance()
    {
        return s_object ? 
                    s_object 
                : 
                    (s_object = new Singleton);
    }
\end{verbatim}
With multi-threaded programs this approach immediately gets complex. For
example, if two threads call \texttt{instance} at the same time, while \texttt{s\_object}
still equals 0, then both may call \texttt{new Singleton}, resulting in one
dynamically allocated \texttt{Singleton} object becoming unreachable. Other
threads, called after \texttt{s\_object} was initialized for the first time, may
either return a reference to that object, or may return a reference to the
object initialized by the second thread. Not exactly the expected behavior of
a singleton.

Mutexes (cf. section \ref{MUTEX}) can be used to solve these kinds of problems,
but they result in some overhead and inefficiency, as the mutex must be
inspected at each call of \texttt{Singleton::instance}. 

When variables must dynamically be initialized, and the initialization should
take place only once the \texttt{std::once\_flag} type and the \texttt{std::call\_once}
function should be used.

The \texttt{call\_once} function expects two or three arguments:
    \begin{itemize}
    \item   The first argument is a \texttt{once\_flag} variable, keeping track of the
actual initialization status. The \texttt{call\_once} function simply returns if
the \texttt{once\_flag} indicates that initialization already took place;

\item  The second argument is the address of a function which must be called
only once. This function may be a free function or it may be the address of a
class member function;

\item  If the second argument is the address of a class member function,
then the object for which the member function should be called must be
provided as \texttt{call\_once's} third argument.
    \end{itemize}
    A thread-safe implementation of the singleton's \texttt{instance} function can
now easily be designed (using in-class implementations for brevity):
        \begin{verbatim}
    class Singleton
    { 
        static std::once_flag s_once;
        static Singleton *s_singleton;
        ...
        public:
            static Singleton *instance()
            {
                std::call_once(s_once, []{s_singleton = new Singleton;} );
                return s_singleton;
            }
        ...
    };
\end{verbatim}
However, there are additional ways to initialize data, even for multi-threaded programs:
    \begin{itemize}
    \item  First, suppose a constructor is declared with the \index{constexpr}\texttt{constexpr}
keyword (cf. section \ref{CONSTEXPR}), satisfying the requirements for constant
initialization. In this case, a static object, initialized using that
constructor, is guaranteed to be initialized before any code is run as part of
the static initialization phase. This is used by \texttt{std::mutex}, as it
eliminates the possibility of race conditions when global mutexes are
initialized.

\item  Second, a static variable defined within a compound statement may be
used (e.g., a static local variable within a function body).  Static
variables \index{static variable: initialization} defined within a compound
statement are initialized the first time the function is called at the point
in the code where the static variable is defined. Here is an example:
        \begin{verbatim}
        #include <iostream>

        struct Cons
        {
            Cons()
            {
                std::cout << "Cons called\n";
            }
        };
        void called(char const *time)
        {
            std::cout << time << "time called() activated\n";
            static Cons cons;
        }
        int main()
        {
            std::cout << "Pre-1\n";
            called("first");
            called("second");
            std::cout << "Pre-2\n";
            Cons cons;
        }
    /*
        Displays:
            Pre-1
            firsttime called() activated
            Cons called
            secondtime called() activated
            Pre-2
            Cons called
    */
\end{verbatim}
    This feature causes a thread to wait automatically if another thread is
still initializing the static data (note that \emph{non-static} data never cause
problems, as non-static local variables only exist within their own thread of
execution).
    \end{itemize}

\subsection{Shared mutexes}
    \typeout{Original Yodl file: threading/sharedmutex}Shared mutexes (via the type \texttt{std::shared\_mutex}) are available after
including the \index{shared\_mutex: header file}\texttt{$<$shared\_mutex$>$} header file.  Shared mutex types behave like
\texttt{timed\_mutex} types and optionally have the characteristics described below.

The class \texttt{shared\_mutex} provides a non-recursive mutex with shared
ownership semantics, comparable to, e.g., the \texttt{shared\_ptr} type.
A program using \texttt{shared\_mutexes} is undefined if:
    \begin{itemize}
    \item  it destroys a shared\_mutex object owned by any thread;
    \item  a thread recursively attempts to gain ownership of a
        \texttt{shared\_mutex};   
    \item  a thread terminates while owning a \texttt{shared\_mutex}.
    \end{itemize}

Shared mutex types provide a shared lock ownership mode. Multiple threads can
simultaneously hold a shared lock ownership of a \texttt{shared\_mutex} type of
object. But no thread can hold a shared lock while another thread holds an
exclusive lock on the same \texttt{shared\_mutex} object, and vice-versa.

Shared mutexes are useful in situations where multiple threads (consumers)
want to access information for reading: the consumers don't want to change the
data, but merely want to retrieve them. At some point another thread (the
producer) wants to modify the data. At that point the producer requests
exclusive access to the data, and is forced to wait until all consumers have
released their locks. While the producer waits for the exclusive lock, new
consumers' requests for shared locks remain pending until the producer has
released the exclusive lock. Thus, reading is possible for many threads, but
for writing the exclusive lock guarantees that no other threads can access the
data.

The type \texttt{shared\_mutex} offers the following members providing shared lock
ownership. To obtain exclusive ownership omit the \texttt{\_shared} from the
following member functions:
    \begin{itemize}
    \item \index{lock\_shared}\texttt{void lock\_shared()}:\ \\ Blocks the calling thread until shared ownership of the mutex can be
obtained by the calling thread. An exception is thrown if the current thread
already owns the lock, if it is not allowed to lock the mutex, or if the mutex
is already locked and blocking is not possible;

\item \index{unlock\_shared}\texttt{void unlock\_shared()}:\ \\ Releases a shared lock on the mutex held by the calling thread. Nothing
happens if the current thread does not already own the lock;

\item \index{try\_lock\_shared}\texttt{bool try\_lock\_shared()}:\ \\ The current thread attempts to obtain shared ownership of the mutex
without blocking. If shared ownership is not obtained, there is no effect and
\texttt{try\_lock\_shared} immediately returns.  Returns \texttt{true} if the shared
ownership lock was acquired, \texttt{false} otherwise.  An implementation may fail
to obtain the lock even if it is not held by any other thread. Initially the
calling thread may not yet own the mutex;

\item \index{try\_lock\_shared\_for}\texttt{bool try\_lock\_shared\_for(rel\_time)}:\ \\ Attempts to obtain shared lock ownership for the calling thread within
the relative time period specified by \texttt{rel\_time}. If the time specified by
\texttt{rel\_time} is less than or equal to \texttt{rel\_time.zero()}, the member attempts
to obtain ownership without blocking (as if by calling
\texttt{try\_lock\_shared()}). The member shall return within the time interval
specified by \texttt{rel\_time} only if it has obtained shared ownership of the mutex
object.  Returns \texttt{true} if the shared ownership lock was acquired, \texttt{false}
otherwise. Initially the calling thread may not yet own the mutex;

\item \index{try\_lock\_shared\_until}\texttt{bool try\_lock\_shared\_until(abs\_time)}:\ \\ Attempts to obtain shared lock ownership for the calling thread until the
time specified by \texttt{abs\_time} has passed. If the time specified by
\texttt{abs\_time} has already passed then the member attempts to obtain ownership
without blocking (as if by calling \texttt{try\_lock\_shared()}).  Returns \texttt{true}
if the shared ownership lock was acquired, \texttt{false} otherwise. Initially the
calling thread may not yet own the mutex;
    \end{itemize}

\section{Locks and lock handling}\label{LOCKS}
\typeout{Original Yodl file: threading/locks}Locks are used to simplify the use of mutexes. Before locks can be used the
\index{mutex: header file}\texttt{$<$mutex$>$} header file must be included.

Whenever threads share data, and at least one of the threads may change common
data, mutexes should be used to prevent threads from using the same data
synchronously.

Usually locks are released at the end of action blocks. This requires explicit
calls to the mutexes' \texttt{unlock} function, which introduces comparable
problems as we've seen with the thread's \texttt{join} member.

To simplify locking and unlocking two mutex wrapper classes are available:
    \begin{itemize}
    \item \index{lock\_guard}\texttt{std::lock\_guard}:\ \\ objects of this class offer the basic unlock-guarantee: their
destructors call the member \texttt{unlock} of the mutexes they control;

\item \index{unique\_lock}\texttt{std::unique\_lock}:\ \\ objects of this class offer a more extensive interface, allowing
explicit unlocking and locking of the mutexes they control, while their
destructors preserve the unlock-guarantee also offered by \texttt{lock\_guard};
    \end{itemize}

The class \texttt{lock\_guard} offers a limited, but useful interface:
    \begin{itemize}

\item \texttt{lock\_guard$<$Mutex$>$(Mutex \&mutex)}:\ \\ when defining a \texttt{lock\_guard} object the mutex type (e.g.,
\texttt{std::mutex, std::timed\_mutex, std::shared\_mutex}) is specified, and a mutex
of the indicated type is provided as its argument. The construction blocks
until the \texttt{lock\_guard} object owns the lock. The \texttt{lock\_guard's} destructor
automatically releases the mutex lock.

\item \texttt{lock\_guard$<$Mutex$>$(Mutex \&mutex, std::adopt\_lock\_t)}:\ \\ this constructor is used to transfer control over the mutex from the
calling thread to the \texttt{lock\_guard}.  The mutex lock is released again by the
\texttt{lock\_guard's} destructor. At construction time the mutex must already be
owned by the calling thread. Here is an illustration of how it can be used:
        \begin{verbatim}
 1: void threadAction(std::mutex &mut, int &sharedInt)
 2: {
 3:     std::lock_guard<std::mutex> lg{mut, std::adopt_lock_t()};
 4:     // do something with sharedInt
 5: }
\end{verbatim}
            \begin{itemize}
            \item  At line 1 \texttt{threadAction} receives a reference to a
mutex. Assume the mutex owns the lock;

\item  At line 3 control is transferred to the \texttt{lock\_guard}. Even
though we don't explicitly use the \texttt{lock\_guard} object, an object should be
defined to prevent the compiler from destroying an anonymous object before the
function ends;

\item  When the function ends, at line 5, the mutex's lock is
released by the \texttt{lock\_guard's} destructor.
            \end{itemize}

\item \texttt{mutex\_type}:\ \\ in \index{mutex\_type} addition to the constructors and destructor,
\texttt{lock\_guard$<$Mutex$>$} types also define the type \index{mutex\_type}\texttt{mutex\_type}: it is a
synonym of the \texttt{Mutex} type that is passed to the \texttt{lock\_guard}'s
constructor.
    \end{itemize}

Here is a simple example of a multi-threaded program using \texttt{lock\_guards}
to prevent information inserted into \texttt{cout} from getting mixed.
        \begin{verbatim}
    bool oneLine(istream &in, mutex &mut, int nr)
    {
       lock_guard<mutex> lg(mut);
    
        string line;
        if (not getline(in, line))
            return false;
    
        cout << nr << ": " << line << endl;
    
        return true;
    }
    
    void io(istream &in, mutex &mut, int nr)
    {
        while (oneLine(in, mut, nr))
            this_thread::yield();
    }
    
    int main(int argc, char **argv)
    {
        ifstream in(argv[1]);
        mutex ioMutex;
    
        thread t1(io, ref(in), ref(ioMutex), 1);
        thread t2(io, ref(in), ref(ioMutex), 2);
        thread t3(io, ref(in), ref(ioMutex), 3);
    
        t1.join();
        t2.join();
        t3.join();
    }
\end{verbatim}
As with \texttt{lock\_guard}, a mutex-type must be specified when defining
objects of the class \index{unique\_lock}\texttt{std::unique\_lock}.  The class
\texttt{unique\_lock} is much more elaborate than the basic \texttt{lock\_guard} class
template.  Its interface does not define a copy constructor or overloaded
assignment operator, but it \emph{does} define a move constructor and a move
assignment operator. In the following overview of \texttt{unique\_lock}'s interface
\texttt{Mutex} refers to the mutex-type that is specified when defining a
\texttt{unique\_lock}:
    \begin{itemize}
    \item \texttt{unique\_lock() noexcept}:\ \\ the default constructor is not yet associated with a \texttt{mutex}
object. It must be assigned a \texttt{mutex} (e.g., using move-assignment) before
it can do anything useful;

\item \texttt{explicit unique\_lock(Mutex \&mutex)}:\ \\ initializes a \texttt{unique\_lock} with an existing \texttt{Mutex} object, and
calls \texttt{mutex.lock()};

\item \texttt{unique\_lock(Mutex \&mutex, defer\_lock\_t) noexcept}:\ \\ initializes a \texttt{unique\_lock} with an existing \texttt{Mutex} object, but
does not call \texttt{mutex.lock()}. Call it by passing a \texttt{defer\_lock\_t} object
as the constructor's second argument, e.g.,
            \begin{verbatim}
unique_lock<mutex> ul(mutexObj, defer_lock_t())
\end{verbatim}
\item \texttt{unique\_lock(Mutex \&mutex, try\_to\_lock\_t) noexcept}:\ \\ initializes a \texttt{unique\_lock} with an existing \texttt{Mutex} object, and
calls \texttt{mutex.try\_lock()}: the constructor won't block if the mutex cannot be
locked;

\item \texttt{unique\_lock(Mutex \&mutex, adopt\_lock\_t) noexcept}:\ \\ initializes a \texttt{unique\_lock} with an existing \texttt{Mutex} object,
and assumes that the current thread has already locked the mutex;

\item \texttt{unique\_lock(Mutex \&mutex, chrono::duration$<$Rep, Period$>$ const
        \&relTime) noexcept}:\ \\ this constructor tries to obtain ownership of the \texttt{Mutex} object by
calling \texttt{mutex.try\_lock\_for(relTime)}. The specified mutex type must
therefore support this member (e.g., it is a \texttt{std::timed\_mutex}). It could
be called like this:
           \begin{verbatim}
std::unique_lock<std::timed_mutex> ulock(timedMutex, 
                                         std::chrono::seconds(5));
\end{verbatim}
\item \texttt{unique\_lock(Mutex \&mutex, chrono::time\_point$<$Clock, Duration$>$ const
        \&absTime) noexcept}:\ \\ this constructor tries to obtain ownership of the \texttt{Mutex} object by
calling \texttt{mutex.try\_lock\_until(absTime)}. The specified mutex type must
therefore support this member (e.g., it is a \texttt{std::timed\_mutex}). 
This constructor could be called like this:
            \begin{verbatim}
std::unique_lock<std::timed_mutex> ulock(
                timedMutex, 
                std::chrono::system_clock::now() + std::chrono::seconds(5)
            );
\end{verbatim}
\item \index{lock}\texttt{void lock()}:\ \\ blocks the current thread until ownership of the mutex that is managed
by the \texttt{unique\_lock} is obtained. If no mutex is currently managed, then a
\texttt{system\_error} exception is thrown.

\item \index{mutex}\texttt{Mutex $*$mutex() const noexcept}:\ \\ returns a pointer to the mutex object stored inside the
\texttt{unique\_lock} (a \texttt{nullptr} is returned if no mutex object is currently
associated with the \texttt{unique\_lock} object.)

\item \texttt{explicit operator bool() const noexcept}:\ \\ returns \texttt{true} if the \texttt{unique\_lock} owns a locked mutex, otherwise
\texttt{false} is returned;

\item \texttt{unique\_lock\& operator=(unique\_lock \&\&tmp) noexcept}:\ \\ if the left-hand operand owns a lock, it will call its mutex's
\texttt{unlock} member, whereafter \texttt{tmp's} state is transferred to the left-hand
operand;

\item \index{owns\_lock}\texttt{bool owns\_lock() const noexcept}:\ \\ returns \texttt{true} if the \texttt{unique\_lock} owns the mutex, otherwise
\texttt{false} is returned;

\item \index{release}\texttt{Mutex $*$release() noexcept}:\ \\ returns a pointer to the mutex object that is associated with the
\texttt{unique\_lock} object, discarding that association;

\item \index{swap}\texttt{void swap(unique\_lock\& other) noexcept}:\ \\ swaps the states of the current \texttt{unique\_lock} and \texttt{other};

\item \index{try\_lock}\texttt{bool try\_lock()}:\ \\ tries to obtain ownership of the mutex that is associated with the
\texttt{unique\_lock}, returning \texttt{true} if this succeeds, and \texttt{false}
otherwise. If no mutex is currently associated with the \texttt{unique\_lock}
object, then a \texttt{system\_error} exception is thrown;

\item \index{try\_lock\_for}\texttt{bool try\_lock\_for(chrono::duration$<$Rep, Period$>$ const
        \&relTime)}:\ \\ this member function tries to obtain ownership of the \texttt{Mutex} object
managed by the \texttt{unique\_lock} object by calling the mutex's
\texttt{try\_lock\_for(relTime)} member. The specified mutex type must therefore
support this member (e.g., it is a \texttt{std::timed\_mutex});

\item \index{try\_lock\_until}\texttt{bool try\_lock\_until(chrono::time\_point$<$Clock,
        Duration$>$ const \&absTime)}:\ \\ this member function tries to obtain ownership of the \texttt{Mutex} object
managed by the \texttt{unique\_lock} object by calling the mutex's
\texttt{mutex.try\_lock\_until(absTime)} member. The specified mutex type must
therefore support this member (e.g., it is a \texttt{std::timed\_mutex});

\item \index{unlock}\texttt{void unlock()}:\ \\ releases ownership of the mutex (or reduces the mutex's lock count). A
\texttt{system\_error} exception is thrown if the \texttt{unique\_lock} object does not
own the mutex.
    \end{itemize}

In addition to the members of the classes \texttt{std::lock\_guard} and
\texttt{std::unique\_lock} the functions \texttt{std::lock}\index{lock (function)} and
\texttt{std::try\_lock}\index{try\_lock (function)} are available. These functions can be
used to prevent \emph{deadlocks}, the topic of the next section.

\subsection{Name-independent declarations}\label{INDEP}
    \typeout{Original Yodl file: threading/nameindep}A common error when using \texttt{lock\_guards} is defining it as an anonymous
object:
        \begin{verbatim}
    void Class::notLocked()
    {
        lock_guard<mutex>{d_mutex};

        // using data available to multiple threads
    }
\end{verbatim}
    In cases like these, since the \texttt{lock\_guard} is defined as an anonymous
object, it's immediately destroyed after its construction offering no guard
against multiple threads using the shared data.

Traditionally this situation is solved by explicitly defining an object. The
object's name is irrelevant, because it's used nowhere else, resulting in
constructions like
        \begin{verbatim}
    void Class::lockedOK()
    {
        lock_guard<mutex> guard{d_mutex};

        // using data available to multiple threads
    }
\end{verbatim}
    But in this context the name's irrelevant and not used nowhere elsew in
the function.

Since the C++26 standard, however, a generalized alternative approach
is available. It's called 
        \index{\_ variable name}\index{name-independent declaration}\emph{name-independent declaration}
    Very simple (and broadly applicable), requiring \texttt{+NOTRANS(-\{\}-\{\})std=c++26} or
beyond, which is supported since \texttt{g++-14}.

The 'name' \textbf{\_} (a single underscore) results in a name-independent
declaration. It's definitely \emph{not} a name we would use for 'common'
variables, but starting with the C++26 standard a variable named `\_' implies a
name-independent declaration. So in '\texttt{lockedOK}' we can now do:
        \begin{verbatim}
    void Class::lockedOK()
    {
        lock_guard<mutex> _{d_mutex};

        // using data available to multiple threads
    }
\end{verbatim}
    and we never have to think again about how to name a required (but not
used by us) variable or object. As long as there's no ambiguity it's even
possible to define multiple `\_' variables or objects. As long as they're not
being used by name it's possible to define, e.g.,
        \begin{verbatim}
    void neverUsed()
    {
        int _{12};
        int _{43};      // a different int because of the initialization
        auto _ = 42;            // 'auto' also works fine
        auto _("hello world");  // a string...
    }
\end{verbatim}
    But in practice, use name independent declarations as illustrated in the
above \texttt{lockedOK} function.

\subsection{Deadlocks}\label{DEADLOCKS}
    \typeout{Original Yodl file: threading/deadlocks}A deadlock occurs when two locks are required to process data, but one thread
obtains the first lock and another thread obtains the second lock. \textbf{C++}
defines the generic
    \index{lock}\texttt{std::lock} and \index{try\_lock}\texttt{std::try\_lock} functions that can
be used to help preventing such situations.

Before these functions  can be used the \index{mutex: header file}\texttt{$<$mutex$>$} header file must be
included

In the following overview \texttt{L1 \&l1, ...} represents one or more
references to objects of lockable types:
    \begin{itemize}
    \item \texttt{void std::lock(L1 \&l1, ...)}:\ \\ When the function returns locks were obtained on all \texttt{li}
        objects. If a lock could not be obtained for at least one of the
        objects, then all locks obtained so far are relased, even if the
        object for which no lock could be obtained threw an exception;
    \item \texttt{int std::try\_lock(L1 \&l1, ...)}:\ \\ This function calls the lockable objects' \texttt{try\_lock} members. If all
        locks could be obtained, then -1 is returned. Otherwise the (0-based)
        index of the first argument which could not be locked is returned,
        releasing all previously obtained locks.
    \end{itemize}

As an example consider the following little multi-threaded program: The
threads use mutexes to obtain unique access to \texttt{cout} and to an \texttt{int
value}. However, \texttt{fun1} first locks \texttt{cout} (line 7), and then \texttt{value}
(line 10); \texttt{fun2} first locks \texttt{value} (line 16) and then \texttt{cout} (line
19). Clearly, if \texttt{fun1} has locked \texttt{cout} \texttt{fun2} can't obtain the lock
until \texttt{fun1} has released it. Unfortunately, \texttt{fun2} has locked \texttt{value},
and the functions only release their locks when returning. But in order to
access the information in \texttt{value} \texttt{fun1} it must have obtained a lock on
\texttt{value}, which it can't, as \texttt{fun2} has already locked \texttt{value}: the
threads are waiting for each other, and neither thread gives in.
        \begin{verbatim}
     1: 
     2: int value;
     3: mutex valueMutex;
     4: mutex coutMutex;
     5: 
     6: void fun1()
     7: {
     8:     lock_guard<mutex> lg1(coutMutex);
     9:     cout << "fun 1 locks cout\n";
    10: 
    11:     lock_guard<mutex> lg2(valueMutex);
    12:     cout << "fun 1 locks value\n";
    13: }
    14: 
    15: void fun2()
    16: {
    17:     lock_guard<mutex> lg1(valueMutex);
    18:     cerr << "fun 2 locks value\n";
    19: 
    20:     lock_guard<mutex> lg2(coutMutex);
    21:     cout << "fun 2 locks cout\n";
    22: }
    23: 
    24: int main()
    25: {
    26:     thread t1(fun1);
    27:     fun2();
    28:     t1.join();
    29: }
    30: 
\end{verbatim}
A good recipe for avoiding deadlocks is to prevent nested (or multiple) mutex
lock calls. But if multiple mutexes must be used, always obtain the locks in
the same order. Rather than doing this yourself, \texttt{std::lock} and
\texttt{std::try\_lock} should be used whenever possible to obtain multiple mutex
locks. These functions accept multiple arguments, which must be lockable types
like \texttt{lock\_guard, unique\_lock,} or even a plain \texttt{mutex}. The previous
deadlocking program, can be modified to call \texttt{std::lock} to lock both
mutexes. In this example using one single mutex would also work, but the
modified program now looks as similar as possible to the previous
program. Note how in lines 10 and 21 a different
ordering of the \texttt{unique\_locks} arguments was used: it is not necessary to
use an identical argument order when calling \texttt{std::lock} or
\texttt{std::try\_lock}. 
        \begin{verbatim}
     1: int value;
     2: mutex valueMutex;
     3: mutex coutMutex;
     4: 
     5: void fun1()
     6: {
     7:     scoped_lock sl{ coutMutex, valueMutex };
     8:     cout << "fun 1 locks cout\n";
     9:     sleep(1);
    10:     cout << "fun 1 locks value\n";
    11: }
    12: 
    13: void fun2()
    14: {
    15:     scoped_lock sl{ valueMutex, coutMutex };
    16:     cout << "fun 2 locks value\n";
    17:     sleep(1);
    18:     cout << "fun 2 locks cout\n";
    19: }
    20: 
    21: int main()
    22: {
    23:     thread t1(fun1);
    24:     fun2();
    25:     t1.join();
    26: }
    27: //  Displays:
    28: //    fun 2 locks value
    29: //    fun 2 locks cout
    30: //    fun 1 locks cout
    31: //    fun 1 locks value
\end{verbatim}
\subsection{Shared locks}
    \typeout{Original Yodl file: threading/sharedlock}\emph{Shared locks} are available through the type
    \index{shared\_lock}\texttt{std::shared\_lock}, after including the
    \index{shared\_mutex: header file}\texttt{$<$shared\_mutex$>$} header file.

An object of the type \texttt{std::shared\_lock} controls the shared ownership of a
lockable object within a scope. Shared ownership of the lockable object may be
acquired at construction time or thereafter, and once acquired, it may be
transferred to another \texttt{shared\_lock} object. Objects of type \texttt{shared\_lock}
cannot be copied, but move construction and assignment is supported. 

The behavior of a program is undefined if the contained pointer to a mutex
(\texttt{pm}) has a non-zero value and the lockable object pointed to by \texttt{pm} does
not exist for the entire remaining lifetime of the \texttt{shared\_lock}
object. The supplied mutex type must be a \texttt{shared\_mutex} or a type having
the same characteristics.

The type \texttt{shared\_lock} offers the following constructors, destructor and
operators:
    \begin{itemize}
    \item \texttt{shared\_lock() noexcept}:\ \\ The default constructor creates a \texttt{shared\_lock} which is not owned
by a thread and for which \texttt{pm == 0};

\item \texttt{explicit shared\_lock(mutex\_type \&mut)}:\ \\ This constructor locks the mutex, calling \texttt{mut.lock\_shared()}. The
calling thread may not already own the lock. Following the construction \texttt{pm
== \&mut}, and the lock is owned by the current thread;

\item \texttt{shared\_lock(mutex\_type \&mut, defer\_lock\_t) noexcept}:\ \\ This constructor assigns \texttt{pm} to \texttt{\&mut}, but the calling thread 
does not own the lock;

\item \texttt{shared\_lock(mutex\_type \&mut, try\_to\_lock\_t)}:\ \\ This constructor tries to locks the mutex, calling
\texttt{mut.try\_lock\_shared()}. The calling thread may not already own the
lock. Following the construction \texttt{pm == \&mut}, and the lock may or may not
be owned by current thread, depending on the return value of
\texttt{try\_lock\_shared;}

\item \texttt{shared\_lock(mutex\_type \&mut, adopt\_lock\_t)}:\ \\ This constructor can be called if the calling thread has shared
ownership of the mutex. Following the construction \texttt{pm == \&mut}, and the
lock is owned by the current thread;

\item \texttt{shared\_lock(mutex\_type \&mut,
                chrono::time\_point$<$Clock, Duration$>$ const \&abs\_time)}:\ \\ This constructor is a member template, where \texttt{Clock} and
\texttt{Duration} are types specifying a clock and absolute time (cf. section
\ref{TIMESPEC}). It can be called if the calling thread does not already own
the mutex. It calls \texttt{mut.try\_lock\_shared\_until(abs\_time)}. Following the
construction \texttt{pm == \&mut}, and the lock may or may not be owned by current
thread, depending on the return value of \texttt{try\_lock\_shared\_until;}

\item \texttt{shared\_lock(mutex\_type \&mut, 
                chrono::duration$<$Rep, Period$>$ const \&rel\_time)}:\ \\ This constructor is a member template, where \texttt{Clock} and
\texttt{Period} are types specifying a clock and relative time (cf. section
\ref{TIMESPEC}). It can be called if the calling thread does not already own
the mutex. It calls \texttt{mut.try\_lock\_shared\_for(abs\_time)}. Following the
construction \texttt{pm == \&mut}, and the lock may or may not be owned by current
thread, depending on the return value of \texttt{try\_lock\_shared\_for;}

\item \texttt{shared\_lock(shared\_lock \&\&tmp) noexcept}:\ \\ The move constructor transfers the information in \texttt{tmp} to the
newly constructed \texttt{shared\_lock}. Following the construction \texttt{tmp.pm == 0}
and \texttt{tmp} no longer owns the lock;

\item \texttt{\textasciitilde{}shared\_lock()}:\ \\ If the lock is owned by the current thread, 
\texttt{pm-$>$unlock\_shared()} is called;

\item \texttt{shared\_lock \&operator=(shared\_lock \&\&tmp) noexcept}
        (The move assignment operator calls \texttt{pm-$>$unlock\_shared} and then
transfers the information in \texttt{tmp} to the
current \texttt{shared\_lock} object. Following this \texttt{tmp.pm == 0}
and \texttt{tmp} no longer owns the lock;)

\item \index{operator bool}\texttt{explicit operator bool () const noexcept}:\ \\ Returns whether or not the \texttt{shared\_lock} object owns the lock.
    \end{itemize}

The following members are provided:

\begin{itemize}
    \item \index{lock}\texttt{void lock()}:\ \\ Calls \texttt{pm-$>$lock\_shared()}, after which the current tread owns the
shared lock. Exceptions may be thrown from \texttt{lock\_shared}, and otherwise if
\texttt{pm == 0} or if the current thread already owns the lock;

\item \index{mutex}\texttt{mutex\_type $*$mutex() const noexcept}:\ \\ Returns \texttt{pm};

\item \index{release}\texttt{mutex\_type $*$release() noexcept}:\ \\ Returns the previous value of \texttt{pm}, which is equal to zero after
calling this member. Also, the current object no longer owns the lock;

\item \index{swap}\texttt{void swap(shared\_lock \&other) noexcept}:\ \\ Swaps the data members of the current and the \texttt{other} \texttt{shared\_lock}
objects. There is also a free member \texttt{swap}, a function template, swapping
two \texttt{shared\_lock$<$Mutex$>$} objects, where \texttt{Mutex} represents the mutex type
for which the shared lock objects were instantiated: \texttt{void
swap(shared\_lock$<$Mutex$>$ \&one, shared\_lock$<$Mutex$>$ \&two) noexcept};

\item \index{try\_lock}\texttt{bool try\_lock()}:\ \\ Calls \texttt{pm-$>$try\_lock\_shared()}, returning this call's return value.
Exceptions may be thrown from \texttt{try\_lock\_shared}, and
otherwise if \texttt{pm == 0} or if the current thread already owns the lock;

\item \index{try\_lock\_for}\texttt{bool try\_lock\_for(const chrono::duration$<$Rep, Period$>$\&
rel\_time)}:\ \\ A member template, where \texttt{Clock} and \texttt{Period} are types specifying a
clock and relative time (cf. section \ref{TIMESPEC}). It calls
\texttt{mut.try\_lock\_shared\_for(abs\_time)}. Following the call the lock may or may
not be owned by current thread, depending on the return value of
\texttt{try\_lock\_shared\_until}.  Exceptions may be thrown from
\texttt{try\_lock\_shared\_for}, and otherwise if \texttt{pm == 0} or if the current thread
already owns the lock;

\item \index{try\_lock\_until}\texttt{bool try\_lock\_until(const chrono::time\_point$<$Clock,
Duration$>$\& abs\_time)}:\ \\ A member template, where \texttt{Clock} and \texttt{Duration} are types specifying
a clock and absolute time (cf. section \ref{TIMESPEC}). It calls
\texttt{mut.try\_lock\_shared\_until(abs\_time)}, returning its return value. Following
the call the lock may or may not be owned by current thread, depending on the
return value of \texttt{try\_lock\_shared\_until}.  Exceptions may be thrown from
\texttt{try\_lock\_shared\_until}, and otherwise if \texttt{pm == 0} or if the current
thread already owns the lock;

\item \index{unlock}\texttt{void unlock()}:\ \\ Unlocks the shared mutex lock, releasing its ownership. Throws an
exception if the shared mutex was not owned by the current thread.
    \end{itemize}

\subsection{Scoped locks}
    \typeout{Original Yodl file: threading/scopedlock}Deadlocks can be avoided using the principles described in the previous
section. However, instead of placing the responsibility for avoiding deadlocks
on the shoulders of the software engineer, an alternative approach is
available: a \index{scoped\_lock}\texttt{scoped\_lock} can be used to lock multiple semaphores at once,
where the \texttt{scoped\_lock} ensures that deadlocks are avoided.

The \texttt{scoped\_lock} also has a default constructor, performing no actions, so
it's up to the software engineer to define \texttt{scoped\_lock} objects with at
least one \texttt{mutex}. Before using \texttt{scoped\_lock} objects the \index{mutex: header file}\texttt{$<$mutex$>$}
header file must be included. Adapting the example from section
\ref{DEADLOCKS}: both functions define a \texttt{scoped\_lock} (note that the order
in which the mutexes are specified isn't relevant), and deadlocks are do not
occur: 
        \begin{verbatim}
     1: 
     2: int value;
     3: mutex valueMutex;
     4: mutex coutMutex;
     5: 
     6: void fun1()
     7: {
     8:     unique_lock<mutex> lg1(coutMutex, defer_lock);
     9:     unique_lock<mutex> lg2(valueMutex, defer_lock);
    10: 
    11:     lock(lg1, lg2);
    12: 
    13:     cout << "fun 1 locks cout\n";
    14:     cout << "fun 1 locks value\n";
    15: }
    16: 
    17: void fun2()
    18: {
    19:     unique_lock<mutex> lg1(coutMutex, defer_lock);
    20:     unique_lock<mutex> lg2(valueMutex, defer_lock);
    21: 
    22:     lock(lg2, lg1);
    23: 
    24:     cout << "fun 2 locks cout\n";
    25:     cout << "fun 2 locks value\n";
    26: }
    27: 
    28: int main()
    29: {
    30:     thread t1(fun1);
    31:     thread t2(fun2);
    32:     t1.join();
    33:     t2.join();
    34: }
    35: 
\end{verbatim}
Thus, instead of using \texttt{lock\_guard} objects, \texttt{scoped\_lock} objects can be
used. It's a matter of taste whether \texttt{lock\_guards} or \texttt{scoped\_locks}
should be preferred when only one mutex is used. Maybe \texttt{scoped\_lock} should
be preferred, since it always works....

\section{Event handling (condition variables)}
\typeout{Original Yodl file: threading/events}This section introduces \emph{condition variables}. Condition variables allow
programs to synchronize threads using the \emph{states} of data, rather than
simply locking the \emph{access} to data (which is realized using mutexes).

Before condition variables can be used the \index{condition\_variable: header file}\texttt{$<$condition\_variable$>$} header
file must be included.

To start our discussion, consider a classic producer-consumer scenario: the
producer generates items which are consumed by a consumer. The producer can
only produce a certain number of items before its storage capacity has filled
up and the client cannot consume more items than the producer has produced.

At some point the producer's storage capacity has filled to the brim, and the
producer has to wait until the client has at least consumed some items,
thereby creating space in the producer's storage. Similarly, the consumer
cannot start consuming until the producer has at least produced some items.

Implementing this scenario only using mutexes (data locking) is not an
attractive option, as merely using mutexes forces a program to implement the
scenario using \emph{polling}: processes must continuously (re)acquire the
mutex's lock, determine whether they can perform some action, followed by the
release of the lock. Often there's no action to perform, and the process is
busy acquiring and releasing the mutex's lock. Polling forces threads to wait
until they can lock the mutex, even though continuation might already be
possible. The polling interval could be reduced, but that too isn't an
attractive option, as that increases the overhead associated with handling the
mutexes (also called `busy waiting').

Condition variables can be used to prevent polling. Threads can use condition
variables to \emph{notify} waiting threads that there is something for them to
do. This way threads can synchronize on data values (\emph{states}).

As data values may be modified by multiple threads, threads still need to use
mutexes, but only for controlling access to the data.  In addition, condition
variables allow threads to \emph{release} ownership of mutexes until a certain
value has been obtained, until a preset amount of time has been passed, or
until a preset point in time has been reached.

The prototypical setup of threads using condition variables looks like this:
    \begin{itemize}
    \item  consumer thread(s) act like this:
        \begin{verbatim}
    lock the mutex
    while the required condition has not yet been attained (i.e., is false):
        wait until being notified 
         (this automatically releasing the mutex's lock).
    once the mutex's lock has been reacquired, and the required condition
    has been attained:
        process the data
    release the mutex's lock.
\end{verbatim}
\item  producer thread(s) act similarly:
        \begin{verbatim}
    lock the mutex
    while the required condition has not yet been attained:
        do something to attain the required condition
    notify waiting threads (that the required condition has been attained)
    release the mutex's lock.
\end{verbatim}
\end{itemize} 
    No matter which thread starts, the thread holding the mutex's lock will at
some point release the lock, allowing the other process to (re)acquire it. If
the consumer starts it immediately releases the lock once it enters its
waiting state; if the producer starts it releases the lock once the condition
is true. 

This protocol hides a subtle initial synchronization requirement. The consumer
will miss the producer's notification if it (i.e., the consumer) hasn't yet
entered its waiting state. So \emph{waiting (consumer) threads should start
before notifying (producer) threads}. Once threads have started, no
assumptions can be made anymore about the order in which any of the condition
variable's members (\texttt{notify\_one, notify\_all, wait, wait\_for}, and
\texttt{wait\_until}) are called.

Condition variables come in two flavors: objects of the class 
    \index{condition\_variable}\texttt{std::condition\_variable} are used in combination
with objects of type \texttt{unique\_lock$<$mutex$>$}. Because of 
optimizations which are available for this specific combination using 
\texttt{condition\_variables} is somewhat more efficient than using the more
generally applicable class
    \index{condition\_variable\_any}\texttt{std::condition\_variable\_any}, which may be
used with any (e.g., user supplied) lock type.

Condition variable classes (covered in detail in the next two sections) offer
members like \texttt{wait, wait\_for, wait\_until, notify\_one} and \texttt{notify\_all}
that may concurrently be called.  The notifying members are always atomically
executed. Execution of the \texttt{wait} members consists of three atomic parts:
    \begin{itemize}
    \item  the mutex is released, and the thread is suspended until its
        notification; 
    \item  Once the notification has been received, the lock is reacquired
    \item  The wait state ends (and processing continues beyond the \texttt{wait}
        call). 
    \end{itemize}
    So, returning from \texttt{wait}-members the previously waiting thread 
has reacquired the mutex's lock.

In addition to the condition variable classes the following free function and
\texttt{enum} type is provided:
    \begin{itemize}
    \item \index{notify\_all\_at\_thread\_exit}\texttt{void
        std::notify\_all\_at\_thread\_exit(condition\_variable \&cond,
        unique\_lock$<$mutex$>$ lockObject)}:\ \\ once the current thread has ended, all other threads waiting on
        \texttt{cond} are notified. It is good practice to exit the thread as
        soon as possible after calling \texttt{notify\_all\_at\_thread\_exit}.

Waiting threads must verify that the thread they were waiting for has
        indeed ended. This is usually realized  by first obtaining the lock on
        \texttt{lockObject}, followed by verifying that the condition
        they were waiting for is true and that the lock was not
        reacquired before \texttt{notify\_all\_at\_thread\_exit} was called.

\item \index{cv\_status}\texttt{std::cv\_status}:\ \\ the \texttt{cv\_status} enum is used by several member functions of the
        condition variable classes (cf. sections \ref{CONDVAR1} and
        \ref{CONDVAR2}): 
       \begin{verbatim}
namespace std
{
    enum class cv_status 
    { 
        no_timeout, 
        timeout 
    };
}
\end{verbatim}
\end{itemize}

\subsection{The class std::condition\_variable}\label{CONDVAR1}
    \typeout{Original Yodl file: threading/conditionvar}The class \texttt{std::condition\_variable}\index{condition\_variable} merely offers a
default constructor. No copy constructor or overloaded assignment operator is
provided.

Before using the class \texttt{condition\_variable} the \index{condition\_variable: header file}\texttt{$<$condition\_variable$>$}
header file must be included.

The class's destructor requires that no thread is blocked by the thread
destroying the \texttt{condition\_variable}. So all threads waiting on a
\texttt{condition\_variable} must be notified before a \texttt{condition\_variable}
object's lifetime ends. Calling \texttt{notify\_all} (see below) before a
\texttt{condition\_variable's} lifetime ends takes care of that, as the
\texttt{condition\_variable's} thread releases its lock of the \texttt{mutex} variable,
allowing one of the notified threads to lock the mutex.

In the following member-descriptions a type \texttt{Predicate} indicates that a
provided \texttt{Predicate} argument can be called as a function without arguments,
returning a \texttt{bool}. Also, other member functions are frequently referred
to. It is tacitly assumed that all member referred to below were called using
the same condition variable object.

The class \texttt{condition\_variable} supports several \texttt{wait} members, which
block the thread until notified by another thread (or after a configurable
waiting time). However, \texttt{wait} members may also spuriously unblock, without
having reacquired the lock. Therefore, returning from \texttt{wait} members threads
should verify that the required condition is actually true. If not,
again calling \texttt{wait} may be appropriate.  The next piece of pseudo code
illustrates this scheme:
       \begin{verbatim}
    while (conditionNotTrue())
        condVariable.wait(&uniqueLock);
\end{verbatim}
The class \texttt{condition\_variable}'s members are:
    \begin{itemize}
    \item \index{notify\_one}\texttt{void notify\_one() noexcept}:\ \\ one \texttt{wait} member called by other threads returns. Which one
        actually returns cannot be predicted.

\item \index{notify\_all}\texttt{void notify\_all() noexcept}:\ \\ all \texttt{wait} members called by other threads unblock their wait
        states. Of course, only one of them will subsequently succeed in
        reacquiring the condition variable's lock object.

\item \index{wait}\texttt{void wait(unique\_lock$<$mutex$>$\& uniqueLock)}:\ \\ before calling \texttt{wait} the current thread must have acquired the lock
        of \texttt{uniqueLock}. Calling \texttt{wait} releases the lock, and the current
        thread is blocked until it has received a notification from another
        thread, and has reacquired the lock.

\item \texttt{void wait(unique\_lock$<$mutex$>$\& uniqueLock, Predicate pred)}:\ \\ this is a member template, using the template header \texttt{template
        $<$typename Predicate$>$}. 
       The template's type is automatically derived from the function's
        argument type and does not have to be specified explicitly.

Before calling \texttt{wait} the current thread must have acquired the lock
        of \texttt{uniqueLock}. As long as `\texttt{pred}' returns \texttt{false}
        \texttt{wait(lock)} is called.

\item \index{wait\_for}\texttt{cv\_status wait\_for(unique\_lock$<$mutex$>$ \&uniqueLock,
                      std::chrono::duration$<$Rep, Period$>$ const \&relTime)}:\ \\ this member is defined as a member template, using the template header
        \texttt{template $<$typename Rep, typename Period$>$}.  
       The template's types are automatically derived from the types of the
        function's arguments and do not have to be specified explicitly.
       E.g., to wait for at most 5 seconds \texttt{wait\_for} can be called like
        this:
       \begin{verbatim}
cond.wait_for(&unique_lock, std::chrono::seconds(5));
\end{verbatim}
This member returns when being notified or when the time interval
        specified by \texttt{relTime} has passed.

When returning due to a timeout, \texttt{std::cv\_status::timeout} is
        returned, otherwise \texttt{std::cv\_status::no\_timeout} is
        returned.

Threads should verify that the required data condition has been met
        after \texttt{wait\_for} has returned.

\item \texttt{bool wait\_for(unique\_lock$<$mutex$>$ \&uniqueLock,
                      chrono::duration$<$Rep, Period$>$ const \&relTime, Predicate
                       pred)}:\ \\ this member is defined as a member template, using the template
        header \texttt{template $<$typename Rep, typename Period, typename
        Predicate$>$}. 
       The template's types are automatically derived from the types of the
        function's arguments and do not have to be specified explicitly.

As long as \texttt{pred} returns false, the previous \texttt{wait\_for} member is
        called. If the previous member returns \texttt{cv\_status::timeout}, then
        \texttt{pred} is returned, otherwise \texttt{true}.

\item \index{wait\_until}\texttt{cv\_status wait\_until(unique\_lock$<$mutex$>$\& uniqueLock,
                        chrono::time\_point$<$Clock, Duration$>$ const \&absTime)}:\ \\ this member is defined as a member template, using the template
        header \texttt{template $<$typename Clock, typename Duration$>$}. 
       The template's types are automatically derived from the types of the
        function's arguments and do not have to be specified explicitly.
       E.g., to wait until 5 minutes after the current time \texttt{wait\_until} can
        be called like this:
       \begin{verbatim}
cond.wait_until(&unique_lock, chrono::system_clock::now() +
                              std::chrono::minutes(5));
\end{verbatim}
This function acts identically to the \texttt{wait\_for(unique\_lock$<$mutex$>$
        \&uniqueLock, chrono::duration$<$Rep, Period$>$ const \&relTime)} member
        described earlier, but uses an absolute point in time, rather than a
        relative time specification. 

This member returns when being notified or when the time interval
        specified by \texttt{relTime} has passed.\linebreak 
       When returning due to a timeout, \texttt{std::cv\_status::timeout} is
        returned, otherwise \texttt{std::cv\_status::no\_timeout} is
        returned.

\item \texttt{bool wait\_until(unique\_lock$<$mutex$>$ \&lock,
                  chrono::time\_point$<$Clock, Duration$>$ const \&absTime,
                  Predicate pred)}:\ \\ this member is defined as a member template, using the template header
        \texttt{template $<$typename Clock, typename Duration, typename Predicate$>$}.
       The template's types are automatically derived from the types of the
        function's arguments and do not have to be specified explicitly.

As long as \texttt{pred} returns false, the previous \texttt{wait\_until} member
        is called. If the previous member returns \texttt{cv\_status::timeout}, then
        \texttt{pred} is returned, otherwise \texttt{true}.
    \end{itemize} 
    Threads should verify that the required condition is \texttt{true} when
wait-members of condition variables return.

\subsection{The class std::condition\_variable\_any}\label{CONDVAR2}
    \typeout{Original Yodl file: threading/conditionany}Different from the class \texttt{condition\_variable} the class
    \index{condition\_variable\_any}\texttt{std::condition\_variable\_any} can be used with
any (e.g., user supplied) lock type, and not just with the stl-provided
\texttt{unique\_lock$<$mutex$>$}.

Before using the class \texttt{condition\_variable\_any} the \index{condition\_variable: header file}\texttt{$<$condition\_variable$>$}
header file must be included.

The functionality that is offered by \texttt{condition\_variable\_any} is identical
to the functionality offered by the class \texttt{condition\_variable}, albeit that
the lock-type that is used by \texttt{condition\_variable\_any} is not
predefined. The class \texttt{condition\_variable\_any} therefore requires the
specification of the lock-type that must be used by its objects.

In the interface shown below this lock-type is referred to as
\index{lock}\texttt{Lock}. Most of \texttt{condition\_variable\_any's} members are defined as
member templates, defining a \texttt{Lock} type as one of its parameters. The
requirements of these lock-types are identical to those of the stl-provided
\texttt{unique\_lock}, and user-defined lock-type implementations should provide at
least the interface and semantics that is also provided by \texttt{unique\_lock}.

This section merely presents the interface of the class
\texttt{condition\_variable\_any}. As its interface offers the same members as
\texttt{condition\_variable} (allowing, where applicable, passing any lock-type
instead of just \texttt{unique\_lock} to corresponding members), the reader is
referred to the previous section for a description of the semantics of the
class members.

Like \texttt{condition\_variable}, the class \texttt{condition\_variable\_any} only
offers a default constructor. No copy constructor or overloaded assignment
operator is provided.

Also, like \texttt{condition\_variable}, the class's destructor requires that no
thread is blocked by the current thread. This implies that all other (waiting)
threads must have been notified; those threads may, however, subsequently
block on the lock specified in their \texttt{wait} calls.

Note that, in addition to \texttt{Lock}, the types \texttt{Clock, Duration, Period,
Predicate,} and \texttt{Rep} are template types, defined just like the identically
named types mentioned in the previous section.

Assuming that \texttt{MyMutex} is a user defined mutex type, and that \texttt{MyLock} is
a user defined lock-type (cf. section \ref{LOCKS} for details about
lock-types), then a \texttt{condition\_variable\_any} object can be defined and used
like this:
        \begin{verbatim}
    MyMutex mut;
    MyLock<MyMutex> ul(mut);
    condition_variable_any cva;

    cva.wait(ul);
\end{verbatim}
These are the class \texttt{condition\_variable\_any's} members:
    \begin{itemize}
    \item \index{notify\_one}\texttt{void notify\_one() noexcept;}
    \item \index{notify\_all}\texttt{void notify\_all() noexcept;}
    \item \index{wait}\texttt{void wait(Lock\& lock);}
    \item \texttt{void wait(Lock\& lock, Predicate pred);}
    \item \index{wait\_until}\texttt{cv\_status wait\_until(Lock\& lock, const
        chrono::time\_point$<$Clock, Duration$>$\& absTime);}
    \item \texttt{bool wait\_until(Lock\& lock, const chrono::time\_point$<$Clock, Duration$>$\&
        absTime, Predicate pred);} 
    \item \index{wait\_for}\texttt{cv\_status wait\_for(Lock\& lock, const chrono::duration$<$Rep,
        Period$>$\& relTime);} 
    \item \texttt{bool wait\_for(Lock\& lock, const chrono::duration$<$Rep, Period$>$\&
        relTime,)}\linebreak  \texttt{Predicate pred}; 
    \end{itemize}

\subsection{An example using condition variables}\label{CONDEX}
    \typeout{Original Yodl file: threading/conditionex}Condition variables are used to synchronize threads on the values of data,
rather than on the mere access to data (for which plain mutex-objects can be
used). Using condition variables, a thread simply sleeps until it is notified
by another thread. In a producer-consumer type of program this is usually
accomplished like this:
        \begin{verbatim}
    consumer loop:
        - wait until there's an item in store,
            then reduce the number of stored items
        - remove the item from the store
        - increment the number of available storage locations
        - do something with the retrieved item

    producer loop:
        - produce the next item
        - wait until there's room to store the item,
            then reduce the number of available storage locations
        - store the item
        - increment the number of stored items
\end{verbatim}
It is important that the two storage administrative tasks (registering the
number of available items and available storage locations) are either
performed by the client or by the producer. For the consumer `waiting' means:
    \begin{itemize}
    \item  Get a lock on the variable containing the actual count
    \item  As long as the count is zero: wait, releasing the lock until another
        thread has increased the count, then re-acquire the lock.
    \item  Reduce the count
    \item  Release the lock.
    \end{itemize}
    This scheme is implemented in a class \index{Semaphore}\texttt{Semaphore}, offering members
\texttt{wait} and \texttt{notify\_all}. For a more extensive discussion of semaphores see
\emph{\index{Tanenbaum, A.S.}Tanenbaum, A.S.} (2016)
    \index{Structured Computer Organization}Structured Computer Organization, Pearson Prentice-Hall.

As a brief summary: semaphores restrict the number of threads that can access
a resource of limited size. It ensures that the number of threads that add
items to the resource (the producers) can never exceed the resource's maximum
size, or it ensures that the number of threads that retrieve items from the
resource (the consumers) can never exceed the resource's current size. Thus,
in a producer/consumer design two semaphores are used: one to control access
to the resource by the producers, and one to control access to the resource by
the consumers.

For example, say we have ten producing threads, as well as ten consumers, and
a lockable queue that must not grow bigger than 1000 items.
Producers try to push one item at a time; consumers try to pop one.

The data member containing the actual count is called \texttt{d\_available}. It is
protected by \texttt{mutex d\_mutex}.  In addition a \texttt{condition\_variable
d\_condition} is defined:
        \begin{verbatim}
    mutable std::mutex d_mutex;     // mutable because of its use in
                                    // 'size_t size() const'
    std::condition_variable d_condition;
    size_t d_available;
\end{verbatim}
The waiting process is implemented through its member function \texttt{wait}:
        \begin{verbatim}
     1: void Semaphore::wait()
     2: {
     3:     std::unique_lock<std::mutex> lk(d_mutex);   // get the lock
     4:     while (d_available == 0)
     5:         d_condition.wait(lk);   // internally releases the lock
     6:                                 // and waits, on exit
     7:                                 // acquires the lock again
     8:     --d_available;              // dec. available
     9: }   // the lock is released
\end{verbatim}
    In line 5 \texttt{d\_condition.wait} releases the lock. It waits until receiving
a notification, and re-acquires the lock just before returning. Consequently,
\texttt{wait's} code always has complete and unique control over \texttt{d\_available}.

What about notifying a waiting thread? This is handled in lines 4 and
5 of the  member function \texttt{notify\_all}:
        \begin{verbatim}
     1: void Semaphore::notify_all()
     2: {
     3:     std::lock_guard<std::mutex> lk(d_mutex);    // get the lock
     4:     if (d_available++ == 0)
     5:         d_condition.notify_all();   // use notify_one to notify one other
     6:                                     // thread
     7: }   // the lock is released
\end{verbatim}
    At line 4 \texttt{d\_available} is always incremented; by using a postfix
increment it can simultaneously be tested for being zero. If it was initially
zero then \texttt{d\_available} is now one. A thread waiting until \texttt{d\_available}
exceeds zero may now continue. A waiting thread is notified by calling
\texttt{d\_condition.notify\_one}. In situations where multiple threads are waiting
`\index{notify\_all}\texttt{notify\_all}' can also be used.

Using the facilities of the class \texttt{Semaphore} whose constructor expects
an initial value of its \texttt{d\_available} data member, the classic
consumer-producer paradigm can now be implemented using
multi-threading\footnote{A more elaborate example of the producer-consumer
program is found in the \texttt{yo/threading/examples/events.cc} file in the
\textbf{C++} Annotations's source archive}:
        \begin{verbatim}
    Semaphore available(10);
    Semaphore filled(0);
    std::queue<size_t> itemQueue;
    std::mutex qMutex;

    void consumer()
    {
        while (true)
        {
            filled.wait();
            // mutex lock the queue:
            {
                std::lock_guard lg(qMutex);
                size_t item = itemQueue.front();
                itemQueue.pop();
            }
            available.notify_all();
            process(item);      // not implemented here
        }
    }

    void producer()
    {
        size_t item = 0;
        while (true)
        {
            ++item;
            available.wait();
            // mutex lock the queue with multiple consumers
            {
                std::lock_guard lg(qMutex);
                itemQueue.push(item);
            }
            filled.notify_all();
        }
    }
    int main()
    {
        thread consume(consumer);
        thread produce(producer);

        consume.join();
        produce.join();
    }
\end{verbatim}
    Note that a \texttt{mutex} is used to avoid simultaneous access to the queue by
multiple threads. Consider the situation where the queue contains 5 items: in
that situation the semaphores allow the consumer and the producer to access
the queue, but to avoid currupting the queue only one of them may modify the
queue at a time. This is realized by both threads obtaining the \texttt{std::mutex
qMutex} lock before modifying the queue.

\section{Atomic actions: mutexes not required}\label{ATOMIC}
\typeout{Original Yodl file: threading/atomic}Before using the facilities introduced in this section the \index{atomic: header file}\texttt{$<$atomic$>$} header
file must be included.

When data are shared among multiple threads, data corruption is usually
prevented using mutexes. To increment a simple \texttt{int} using this strategy
code as shown below is commonly used:
        \begin{verbatim}
    {
        lock_guard<mutex> lk{ intVarMutex };
        ++intVar;
    }
\end{verbatim}
The compound statement is used to limit the \texttt{lock\_guard's} lifetime, so
that \texttt{intVar} is only locked for a short little while.

This scheme is not complex, but at the end of the day having to define a
\texttt{lock\_guard} for every single use of a simple variable, and having to define
a matching mutex for each simple variable is a bit annoying and cumbersome.

\textbf{C++} offers a way out through the use of \index{atomic data types}\emph{atomic data types}.
Atomic data types are available for all basic types, and also for (trivial)
user defined types. Trivial types are (see also section \ref{TYPETRAITS}) all
scalar types, arrays of elements of a trivial type, and classes whose
constructors, copy constructors, and destructors all have default
implementations, and their non-static data members are themselves of trivial
types.

The class template \index{atomic\textless{}Type\textgreater{}}\texttt{std::atomic$<$Type$>$} is available for all
built-in types, including pointer types. E.g., \texttt{std::atomic$<$bool$>$} defines
an atomic \texttt{bool} type. For many types alternative somewhat shorter
type names are available. E.g, instead of \texttt{std::atomic$<$unsigned short$>$} the
type \texttt{std::atomic\_ushort} can be used. Refer to the \texttt{atomic} header file
for a complete list of alternate names.

If \texttt{Trivial} is a user-defined trivial type then
        \index{atomic\textless{}Trivial\textgreater{}}\texttt{std::atomic$<$Trivial$>$}
defines an atomic variant of \texttt{Trivial}: such a type does not require 
a separate \texttt{mutex} to synchronize access by multiple threads.

Objects of the class template \texttt{std::atomic$<$Type$>$} cannot directly be copied
or assigned to each other. However, they can be initialized by values of type
\texttt{Type}, and values of type \texttt{Type} can also directly be assigned to
\texttt{std::atomic$<$Type$>$} objects. Moreover, since \texttt{atomic$<$Type$>$} types offer
conversion operators returning their \texttt{Type} values, an \texttt{atomic$<$Type$>$}
objects can also be assigned to or initialized by another \texttt{atomic$<$Type$>$}
object using a \texttt{static\_cast}:
        \begin{verbatim}
    atomic<int> a1 = 5;
    atomic<int> a2{ static_cast<int>(a1) };
\end{verbatim}
The class \texttt{std::atomic$<$Type$>$} provides several public members, shown
below. Non-member (free) functions operating on \texttt{atomic$<$Type$>$} objects are
also available.

The \texttt{std::memory\_order} enumeration defines the following symbolic
constants, which are used to specify ordering constraints of atomic operations:
    \begin{itemize}
    \item \texttt{memory\_order\_acq\_rel:} the operation must be a read-modify-write
        operation, combining \texttt{memory\_order\_acquire} and
        \texttt{memory\_order\_release}; 
    \item \texttt{memory\_order\_acquire:} the operation is an acquire operation. It
        synchronizes with a release operation that wrote the same memory
        location; 
    \item \texttt{memory\_order\_consume:} the operation is a consume operation on the
        involved memory location;
    \item \texttt{memory\_order\_relaxed:} no ordering constraints are provided by the
        operation;
    \item \texttt{memory\_order\_release:} the operation is a release operation. It
        synchronizes with acquire operations on the same location;
    \item \texttt{memory\_order\_sec\_cst:} the default memory order specification for all
        operations. Memory storing operations use \texttt{memory\_order\_release},
        memory load operations use \texttt{memory\_order\_acquire}, and
        read-modify-write operations use \texttt{memory\_order\_acq\_rel}.
    \end{itemize}

The memory order cannot be specified for the overloaded operators provided by
\texttt{atomic$<$Type$>$}. Otherwise, most \texttt{atomic} member functions may also be
given a final \texttt{memory\_order} argument. Where this is not available it is
explictly mentioned at the function's description.

Here are the standard available \texttt{std::atomic$<$Type$>$} member functions:
    \begin{itemize}
    \item \index{compare\_exchange\_strong}\texttt{bool compare\_exchange\_strong(Type
        \&currentValue, Type newValue) noexcept}:\ \\ The value in the atomic object is compared to \texttt{newValue} using
        byte-wise comparisons. If equal (and \texttt{true} is returned) then
        \texttt{newValue} is stored in the atomic object; if unequal (and \texttt{false}
        is returned) the object's current value is stored in
        \texttt{currentValue};

\item \index{compare\_exchange\_weak}\texttt{bool compare\_exchange\_weak(Type \&oldValue,
        Type newValue) noexcept}:\ \\ The value in the atomic object is compared to \texttt{newValue} using
        byte-wise comparisons. If equal (and \texttt{true} is returned),
        then \texttt{newValue} is stored in the atomic object; if unequal, or
        \texttt{newValue} cannot be atomically assigned to the current object
        \texttt{false} is returned and the object's current value is stored in
        \texttt{currentValue};

\item \index{exchange}\texttt{Type exchange(Type newValue) noexcept}:\ \\ The object's current value is returned, and \texttt{newValue} is assigned
        to the current object;

\item \index{is\_lock\_free}\texttt{bool is\_lock\_free() const noexept}:\ \\ If the operations on the current object can be performed lock-free
        \texttt{true} is returned, otherwise \texttt{false}.
        This member has no \texttt{memory\_order} parameter;

\item \index{load}\texttt{Type load() const noexcept}:\ \\ The object's value is returned;

\item \texttt{operator Type() const noexcept}:\ \\ The object's value is returned;

\item \index{store}\texttt{void store(Type newValue) noexcept}:\ \\ \texttt{NewValue} is assigned to the current object. Note that the standard
        assignment operator can also be used.
    \end{itemize}

In addition to the above members, integral atomic types `\texttt{Integral}'
(essentially the atomic variants of all built-in integral types) also offer
the following member functions:
    \begin{itemize}
    \item \index{fetch\_add}\texttt{Integral fetch\_add(Integral value) noexcept}:\ \\ \texttt{Value} is added to the object's value, and the object's
        value at the time of the call is returned;

\item \index{fetch\_sub}\texttt{Integral fetch\_sub(Integral value) noexcept}:\ \\ \texttt{Value} is subtracted from the object's value, and the object's
        value at the time of the call is returned;

\item \index{fetch\_and}\texttt{Integral fetch\_and(Integral mask) noexcept}:\ \\ The \texttt{bit-and} operator is applied to the object's value and
        \texttt{mask}, assigning the resulting value to the current object. The
        object's value at the time of the call is returned;

\item \index{fetch\_|=}\texttt{Integral fetch\_\textbar{}=(Integral mask) noexcept}:\ \\ The \texttt{bit-or} operator is applied to the object's value and \texttt{mask},
        assigning the resulting value to the current object. The object's
        value at the time of the call is returned;

\item \index{fetch\_\^=}\texttt{Integral fetch\_\textasciicircum{}=(Integral mask) noexcept}:\ \\ The \texttt{bit-xor} operator is applied to the object's value and
        \texttt{mask}, assigning the resulting value to the current object. The
        object's value at the time of the call is returned;

\item \index{operator++}\texttt{Integral operator++() noexcept}:\ \\ The prefix increment operator, returning object's new value;

\item \index{operator++}\texttt{Integral operator++(int) noexcept}:\ \\ The postfix increment operator, returning the object's value before it
        was incremented;

\item \index{operator-{}-{}}\texttt{Integral operator-{}-{}() noexcept}\begin{quote}The prefix decrement operator, returning object's new value;\end{quote}

\item \index{operator-{}-{}}\texttt{Integral operator-{}-{}(int) noexcept}\begin{quote}The postfix decrement operator, returning the object's value
            before it was decremented;\end{quote}

\item \index{operator+=}\texttt{Integral operator+=(Integral value) noexcept}:\ \\ \texttt{Value} is added to the object's current value and the object's
        new value is returned;

\item \index{operator-=}\texttt{Integral operator-=(Integral value) noexcept}:\ \\ \texttt{Value} is subtracted from the object's current value and the
        object's new value is returned;

\item \index{operator\&=}\texttt{Integral operator\&=(Integral mask) noexcept}:\ \\ The \texttt{bit-and} operator is applied to the object's current value and
        \texttt{mask}, assigning the resulting value to the current object. The
        object's new value is returned;

\item \index{operator|=}\texttt{Integral operator\textbar{}=(Integral mask) noexcept}:\ \\ The \texttt{bit-or} operator is applied to the object's current value and
        \texttt{mask}, assigning the resulting value to the current object. The
        object's new value is returned;

\item \index{operator\^=}\texttt{Integral operator\textasciicircum{}=(Integral mask) noexcept}:\ \\ The \texttt{bit-xor} operator is applied to the object's current value and
        \texttt{mask}, assigning the resulting value to the current object. The
        object's new value is returned;
    \end{itemize}

Some of the free member functions have names ending in \texttt{\_explicit}. The
\texttt{\_explicit} functions define an additional parameter `\index{memory\_order}\texttt{memory\_order}
\texttt{order}', which is not available for the non-\texttt{\_explicit} functions (e.g.,
\texttt{atomic\_load(atomic$<$Type$>$ $*$ptr)} and \texttt{atomic\_load\_explicit(atomic$<$Type$>$
$*$ptr, memory\_order order)})

Here are the free functions that are available for all atomic types:
    \begin{itemize}
    \item \index{atomic\_compare\_exchange\_strong(\_explicit)}\texttt{bool
        std::atomic\_compare\_exchange\_strong(\_explicit)(std::atomic$<$Type$>$ $*$ptr,
        Type $*$oldValue, Type newValue) noexept}:\ \\ returns \texttt{ptr-$>$compare\_exchange\_strong($*$oldValue, newValue)};

\item \index{atomic\_compare\_exchange\_weak(\_explicit)}\texttt{bool
        std::atomic\_compare\_exchange\_weak(\_explicit)(std::atomic$<$Type$>$ $*$ptr,
        Type $*$oldValue, Type newValue) noexept}:\ \\ returns \texttt{ptr-$>$compare\_exchange\_weak($*$oldValue, newValue)};

\item \index{atomic\_exchange(\_explicit)}\texttt{Type
        std::atomic\_exchange(\_explicit)(std::atomic$<$Type$>$ $*$ptr, Type newValue)
        noexept}:\ \\ returns \texttt{ptr-$>$exchange(newValue)};

\item \index{atomic\_init}\texttt{void std::atomic\_init(std::atomic$<$Type$>$ $*$ptr, Type
        init) noexept}:\ \\ Stores \texttt{init} \emph{non}-atomically in \texttt{$*$ptr}. The object pointed to
        by \texttt{ptr} must have been default constructed, and as yet no member
        functions must have been called for it.
        This function has no \texttt{memory\_order} parameter;

\item \index{atomic\_is\_lock\_free}\texttt{bool std::atomic\_is\_lock\_free(std::atomic$<$Type$>$
        const $*$ptr) noexept}:\ \\ returns \texttt{ptr-$>$is\_lock\_free()}.
        This function has no \texttt{memory\_order} parameter;

\item \index{atomic\_load(\_explicit)}\texttt{Type
        std::atomic\_load(\_explicit)(std::atomic$<$Type$>$ $*$ptr) noexept}:\ \\ returns \texttt{ptr-$>$load()};

\item \index{atomic\_store(\_explicit)}\texttt{void
        std::atomic\_store(\_explicit)(std::atomic$<$Type$>$ $*$ptr, Type value)
        noexept}:\ \\ calls \texttt{ptr-$>$store(value)}.
    \end{itemize}    

In addition to the abovementioned free functions \texttt{atomic$<$Integral$>$} types
also offer the following free member functions:
    \begin{itemize}
    \item \index{atomic\_fetch\_add(\_explicit)}\texttt{Integral
        std::atomic\_fetch\_add(\_explicit)(std::atomic$<$Integral$>$ $*$ptr, Integral
        value) noexcept}:\ \\ returns \texttt{ptr-$>$fetch\_add(value)};

\item \index{atomic\_fetch\_sub(\_explicit)}\texttt{Integral
        std::atomic\_fetch\_sub(\_explicit)(std::atomic$<$Integral$>$ $*$ptr, Integral
        value) noexcept}:\ \\ returns \texttt{ptr-$>$fetch\_sub(value)};

\item \index{atomic\_fetch\_and}\texttt{Integral
        std::atomic\_fetch\_and(\_explicit)(std::atomic$<$Integral$>$ $*$ptr, Integral
        mask) noexcept}:\ \\ returns \texttt{ptr-$>$fetch\_and(value)};

\item \index{atomic\_fetch\_or}\texttt{Integral
        std::atomic\_fetch\_or(\_explicit)(std::atomic$<$Integral$>$ $*$ptr, Integral
        mask) noexcept}:\ \\ returns \texttt{ptr-$>$fetch\_or(value)};

\item \index{atomic\_fetch\_xor}\texttt{Integral
        std::atomic\_fetch\_xor(\_explicit)(std::atomic$<$Integral$>$ $*$ptr, Integral
        mask) noexcept}:\ \\ returns \texttt{ptr-$>$fetch\_xor(mask)}.
    \end{itemize}

\section{An example: threaded quicksort}
\typeout{Original Yodl file: threading/quicksort}The quicksort sorting algorithm (Hoare, 1962) is a well-known sorting
algorithm. Given an array of \texttt{n} elements, it works like this:
    \begin{itemize}
    \item  Pick an element from the array, and partition the array with respect
        to this element (call it the \emph{pivot element}) (in the example below,
        assume a function \texttt{partition} performing the partition is
        available). This leaves us with two (possibly empty) sub-arrays: one
        to the left of the pivot element, and one to the right of the pivot
        element;
    \item  Recursively perform quicksort on the left-hand sub-array;
    \item  Recursively perform quicksort on the right-hand sub-array.
    \end{itemize}

To convert this algorithm to a multi-threaded algorithm appears to be be a
simple task: 
        \begin{verbatim}
    void quicksort(Iterator begin, Iterator end)
    {
        if (end - begin < 2)            // less than 2 elements are left
            return;                     // and we're done

        Iter pivot = partition(begin, end); // determine an iterator pointing
                                            // to the pivot element

        thread lhs(quicksort, begin, pivot);// start threads on the left-hand
                                            // side sub-arrays
        thread rhs(quicksort, pivot + 1, end);  // and on the right-hand side
                                                // sub-arrays
        lhs.join();
        rhs.join();                         // and we're done
    }
\end{verbatim}
Unfortunately, this translation to a multi-threaded approach won't work for 
reasonably large arrays because of a phenomenon called \index{overpopulation}\emph{overpopulation}:
more threads are started than the operating system is prepared to give us. In
those cases a \emph{Resource temporarily unavailable} exception is thrown, and
the program ends.

Overpopulation can be avoided by using a \emph{pool of workers}, where each
`worker' is a thread, which in this case is responsible for handling one (sub)
array, but not for the nested calls. The pool of workers is controlled by a
scheduler, receiving the requests to sort sub-arrays, and passing these
requests on to the next available worker. 

The main data structure of the example program developed in this section is a
queue of \texttt{std::pairs} containing iterators of the array to be sorted
(cf. Figure \ref{sorting}, the sources of the program are found in the \textbf{C++} Annotations's
\texttt{yo/threading/examples/multisort} directory). Two queues are being used: one
queue is a task-queue, receiving the iterators of sub-arrays to be
partitioned. Instead of immediately launching new threads (the \texttt{lhs} and
\texttt{rhs} threads in the above example), the ranges to be sorted are pushed on
the task-queue. The other queue is the work-queue: elements are moved from the
task-queue to the work-queue, where they will be processed by one of the
worker threads.

\begin{figure}[tbp]
\centerline{\epsffile{threading/sorting.eps}}
\caption{\label{sorting}Data structure used for multi-threading quicksort}
\end{figure}

The program's \texttt{main} function starts the workforce, reads the data, pushes
the arrays \texttt{begin} and \texttt{end} iterators on the task queue and then starts
the scheduler. Once the scheduler ends the sorted array is displayed:
        \begin{verbatim}
    int main()
    {
        workForce();            // start the worker threads
        readData();             // read the data into vector<int> g_data
        g_taskQ.push(           // prepare the main task
                    Pair(g_data.begin(), g_data.end())
                ); 
        scheduler();            // sort g_data
        display();              // show the sorted elements
    }
\end{verbatim}
The workforce consists of a bunch of detached threads. Each thread represents
a worker, implemented in the function \texttt{void worker}. Since the number of
worker threads is fixed, overpopulation doesn't occur. Once the array has been
sorted and the program stops these detached threads simply end:
        \begin{verbatim}
    for (size_t idx = 0; idx != g_sizeofWorkforce; ++idx)
        thread(worker).detach();
\end{verbatim}
The scheduler continues for as long as there are sub-arrays to sort. When this
is the case the task queue's front element is moved to the work queue. This
reduces the work queue's size, and prepares an assignment for the next
available worker. The scheduler now waits until a worker is available. Once 
workers are available one of them is informed of the waiting assignment, and
the scheduler waits for the next task:
        \begin{verbatim}
    void scheduler()
    {
        while (newTask())
        {
            g_workQ.rawPushFront(g_taskQ);
    
            g_workforce.wait();           // wait for a worker to be available
            g_worker.notify_all();            // activate a worker
        }
    }
\end{verbatim}
The function \texttt{newTask} simply checks whether the task queue is empty. If so,
and none of the workers is currently busy sorting a sub-array then the array
has been sorted, and \texttt{newTask} can return \texttt{false}.  When the task queue is
empty but a worker is still busy, it may be that new sub-array dimensions are
going to be placed on the task queue by an active worker. Whenever a worker is
active the \texttt{Semaphore g\_workforce's} size is less than the size of the work
force:
        \begin{verbatim}
    bool wip()
    {
        return g_workforce.size() != g_sizeofWorkforce;
    }
\end{verbatim}
        \begin{verbatim}
    bool newTask()
    {
        bool done;
    
        unique_lock<mutex> lk(g_taskMutex);
        while ((done = g_taskQ.empty()) && wip())
            g_taskCondition.wait(lk);
    
        return not done;
    }
\end{verbatim}
Each detached worker thread performs a continuous loop. In the loop it waits
for a notification by the scheduler. Once it receives a notification it
retrieves its assignment from the work queue, and partitions the sub-array
specified in its assignment. Partitioning may result in new tasks. Once this
has been completed the worker has completed its assignment: it increments the
available workforce and notifies the scheduler that it should check whether
all tasks have been performed:
        \begin{verbatim}
    void worker()
    {
        while (true)
        {
            g_worker.wait();      // wait for action
    
            partition(g_workQ.popFront());
            g_workforce.notify_all();
    
            lock_guard<mutex> lk(g_taskMutex);
            g_taskCondition.notify_one();
        }
    }
\end{verbatim}
Sub-arrays smaller than two elements need no partitioning. All larger
sub-arrays are partitioned relative to their first element. The
\texttt{std::partition} generic algorithm does this well, but if the pivot is
itself an element of the array to partition then the pivot's eventual location
is undetermined: it may be found anywhere in the series of elements which are
at least equal to the pivot. The two required sub-arrays, however, can easily
be constructed:
    \begin{itemize}
    \item  First call \texttt{std::partition} relative to an array's first element, 
        partitioning the array's remaining elements, returning \texttt{mid},
        pointing to the first element of the series of elements that are at
        least as large as the array's first element;
    \item  Then swap the array's first element with element to which \texttt{mid - 1}
        points;
    \item  The two sub-arrays range from, respectively, \texttt{array.begin()} to
        \texttt{mid - 1} (elements all smaller than the pivot), and from \texttt{mid} to
        \texttt{array.end()} (elements all at least as large as the pivot).
    \end{itemize}
    The two iterator pairs defining these two sub-arrays are thereupon added
to the task queue, creating two new tasks to be dealt with by the scheduler:
        \begin{verbatim}
    void partition(Pair const &range)
    {
        if (range.second - range.first < 2)
            return;
    
        auto rhsBegin = partition(range.first + 1, range.second,
                                      [=](int value)
                                      {
                                          return value < *range.first;
                                      }
                                  );
        auto lhsEnd = rhsBegin - 1;
    
        swap(*range.first, *lhsEnd);
    
        pushTask(range.first, lhsEnd);
        pushTask(rhsBegin, range.second);
    }
\end{verbatim}
\section{Shared States}
\typeout{Original Yodl file: threading/shared}Just before a thread ends it may have produced some results. These results may
have to to be communicated to other threads. In multi threaded programs
several classes and functions can be used that produce 
    \index{shared state}\emph{shared states}, making it easy to communicate results
to other threads. Results could be values, objects or exceptions.

Objects that contain such shared states are called 
    \index{asynchronous return object}\emph{asynchronous return objects}. However,
due to the nature of multi threading, a thread may request the results of an
asynchronous return object before these result are actually available. In
those cases the requesting thread blocks, waiting for the results to become
available. Asynchronous return objects offer \texttt{wait} and \texttt{get} members
which, respectively, \emph{wait} until the results have become available, and
\emph{produce} the asynchronous results once they are available. The phrase that
is used to indicate that the results are available is `the shared state has
been made ready'.

Shared states are made ready by 
    \index{asynchronous provider}\emph{asynchronous providers}. Asynchronous
providers are simply objects or functions providing results to shared
states. Making a shared state ready means that an asynchronous provider
    \begin{itemize}
    \item  marks its shared state as being ready, and
    \item  unblocks any waiting threads (e.g., by allowing blocking members,
        like \texttt{wait}, to return).
    \end{itemize}

Once a shared state has been made ready it contains a value, object, or
exception which can be retrieved by objects having access to the shared
state. While code is waiting for a shared state to become ready the value or
exception that is going to be stored in the shared state may be computed. When
multiple threads try to access the same shared state they must use
synchronizing mechanisms (like mutexes, cf. section \ref{MUTEX}) to prevent
access-conflicts.

Shared states use reference counting to keep track of the number of
asynchronous return objects or asynchronous providers that hold references to
them. These return objects and providers may release their references to these
shared states \index{shared state: releasing} (which is called `releasing the
shared state). This happens when a return object or provider holds the last
reference to the shared state, and
    \index{shared state: destruction} the shared state is destroyed.

On the other hand, an asynchronous provider may also 
    \index{shared state: abandon}\emph{abandon} its shared state. In that case the
provider, in sequence,
    \begin{itemize}
    \item  stores an exception object of type 
            \index{future\_error}\texttt{std::future\_error}, holding the error condition
            \texttt{std::broken\_promise} in its shared state;
    \item  makes its shared data ready; and
    \item  releases its shared data.
    \end{itemize}

Objects of the class \texttt{std::future} (see the next section) are asynchronous
return objects. They can be produced by the \texttt{std::async} (section
\ref{ASYNC}) family of functions, and by objects of the classes
\texttt{std::packaged\_task} (section \ref{PACKAGE}), and \texttt{std::promise} (section
\ref{PROMISE}).

\section{Asynchronous return objects: std::future}\label{FUTURE}
\typeout{Original Yodl file: threading/future}Condition variables allow threads to wait until data have obtained certain
values. A thread may also have to wait until a sub-thread has finished when
calling a sub-thread's \texttt{join} member. 

Waiting may be unwelcome: instead of just waiting our thread might also be
doing something useful. It might as well pick up the results produced by a
sub-thread at some point in the future. 

In fact, exchanging data among threads always poses some difficulties, as it
requires shared variables, and the use of locks and mutexes to prevent data
corruption. Rather than waiting and using locks it would be nice if some
asynchronous task could be started, allowing the initiating thread (or even
other threads) to pick up the result at some point in the future, when the
results are needed, without having to worry about data locks or waiting times.
For situations like these \textbf{C++} provides the class \texttt{std::future}.

Before using the class \index{future} \texttt{std::future} the \index{future: header file}\texttt{$<$future$>$} header file
must be included.

Objects of the class template \index{future}\texttt{std::future} harbor the results
produced by asynchronously executed tasks. The class \texttt{std::future} is a
class template. Its template type parameter specifies the type of the result
returned by the asynchronously executed task. This type may be \texttt{void}.

On the other hand, the asynchronously executed task may throw an exception
(ending the task). In that case the \texttt{future} object catches the exception,
and rethrows it once its return value (i.e., the value returned by the
asynchronously executed task) is requested.

In this section the members of the class template \texttt{future} are
described. \texttt{Future} objects are commonly initialized through anonymous
\texttt{future} objects returned by the factory function \texttt{std::async} or by the
\texttt{get\_future} members of the classes \texttt{std::promise}, and
\texttt{std::packaged\_task} (introduced in upcoming sections). Examples of the use
of \texttt{std::future} objects are provided in those sections.

Some of \texttt{future}'s members return a value of the strongly typed
enumeration \index{future\_status}\texttt{std::future\_status}. This enumeration defines
three symbolic constants: \texttt{future\_status::ready, future\_status::timeout,}
and \texttt{future\_status::deferred}. 

Error conditions are returned through \texttt{std::future\_error}
exceptions. These error conditions are represented by the values of the
strongly typed enumeration \texttt{std::future\_errc} (covered in the next section).

The class \texttt{future} itself provides the following constructors:
    \begin{itemize}
    \item \texttt{future()}:\ \\ The default constructor constructs an \texttt{future} object that does not
        refer to shared results. Its \texttt{valid} member returns \texttt{false}.

\item \texttt{future(future \&\&tmp) noexcept}:\ \\ The move constructor is available. Its \texttt{valid} member returns what
        \texttt{tmp.valid()} would haved returned prior to the constructor
        invocation. After calling the move constructor \texttt{tmp.valid()} returns
        \texttt{false}.
    \end{itemize}
    The class \texttt{future} does not offer a copy constructor or an overloaded
assignment operator. 

Here are the members of the class \texttt{std::future}:
    \begin{itemize}
    \item \texttt{future \&operator=(future \&\&tmp)}:\ \\ The move assignment operator grabs the information from the \texttt{tmp}
        object; following this, \texttt{tmp.valid()} returns \texttt{false}.

\item \texttt{std::shared\_future$<$ResultType$>$ share() \&\&}:\ \\ Returns a \texttt{std::shared\_future$<$ResultType$>$} (see section
        \ref{SHAREDFUTURE}). After calling this function, the \texttt{future's
        valid} member returns \texttt{false}.

\item \texttt{ResultType get()}:\ \\ First \texttt{wait} (see below) is called. Once \texttt{wait} has returned the
        results produced by the associated asynchronous task
        are returned. With \texttt{future$<$Type$>$} specifications the returned value
        is the moved shared value if \texttt{Type} supports move assignment,
        otherwise a copy is returned.  With \texttt{future$<$Type \&$>$} specifications
        a \texttt{Type \&} is returned, with \texttt{future$<$void$>$} specifications nothing
        is returned. If the shared value is an exception, it is thrown instead
        of returned. After calling this member the \texttt{future} object's
        \texttt{valid} member returns \texttt{false}.

\item \texttt{bool valid() const}:\ \\ Returns \texttt{true} if the (\texttt{future}) object for which \texttt{valid} is
        called refers to an object returned by an asynchronous task.  If
        \texttt{valid} returns \texttt{false}, the \texttt{future} object exists, but in
        addition to \texttt{valid} only its destructor and move constructor can
        safely be called. When other members are called while \texttt{valid}
        returns \texttt{false} a \index{future\_error}\texttt{std::future\_error} exception is
        thrown (having the value \index{no\_state}\texttt{future\_errc::no\_state}).

\item \texttt{void wait() const}:\ \\ The thread is blocked until the results produced by the associated
        asynchronous task are available.

\item \texttt{std::future\_status wait\_for(chrono::duration$<$Rep, Period$>$ const
        \&rel\_time) const}:\ \\ This member template derives the template types \texttt{Rep} and \texttt{Period}
        from the actually specified duration (cf. section \ref{DURATION}). If
        the results contain a deferred function nothing happens. Otherwise
        \texttt{wait\_for} blocks
 
        until the results are available or until the amount of time
        specified by \texttt{rel\_time} has expired. Possible return values are:
            \begin{itemize}
            \item \texttt{future\_status::deferred} if the results contains a
                deferred function;
            \item \texttt{future\_status::ready} if the results are available;
            \item \texttt{future\_status::timeout} if the function is returning because
                the amount of time specified by \texttt{rel\_time} has expired. 
            \end{itemize}

\item \texttt{future\_status wait\_until(chrono::time\_point$<$Clock, Duration$>$ const
                                                        \&abs\_time) const}:\ \\ This member template derives the template types \texttt{Clock} and
        \texttt{Duration} from the actually specified \texttt{abs\_time} (cf. section
        \ref{TIMEPOINT}). If the results contain a deferred function nothing
        happens. Otherwise \texttt{wait\_until} blocks until the results are
        available or until the point in time specified by \texttt{abs\_time} has
        expired. Possible return values are:
           \begin{itemize}
            \item \texttt{future\_status::deferred} if the results contain a
                deferred function;
            \item \texttt{future\_status::ready} if the results are available;
            \item \texttt{future\_status::timeout} if the function is returning because
                the point in time specified by \texttt{abs\_time} has expired. 
            \end{itemize}
    \end{itemize}
    The class \texttt{std::future$<$ResultType$>$} declares the following friends:
        \begin{verbatim}
    std::promise<ResultType>
\end{verbatim}
(sf. section \ref{PROMISE}), and
        \begin{verbatim}
    template<typename Function, typename... Args>
        std::future<typename result_of<Function(Args...)>::type> 
        std::async(std::launch, Function &&fun, Args &&...args);
\end{verbatim}
(cf. section \ref{ASYNC}).

\subsection{The std::future\_error exception and the std::future\_errc enum}
    \typeout{Original Yodl file: threading/futureerrc}Members of the class \texttt{std::future} may return errors by throwing
\texttt{std::future\_error} exceptions. These error conditions are represented by
the values of the strongly typed enumeration
    \index{future\_errc}\texttt{std::future\_errc} which defines the following symbolic
constants:
    \begin{itemize}
    \item \index{broken\_promise}\texttt{broken\_promise}
        \begin{quote} 
   \texttt{Broken\_promise} is thrown when a \texttt{future} object was received whose
    value was never assigned by a \texttt{promise} or \texttt{packaged\_task}. For
    example, an object of the class \texttt{promise$<$int$>$} should set the value of
    the \texttt{future$<$int$>$} object returned by its \texttt{get\_future} member
    (cf. section \ref{PROMISE}), but if it doesn't do so, then a
    \texttt{broken\_promise} exception is thrown, as illustrated by the following
    program:
   \begin{verbatim}
 1: std::future<int> fun()
 2: {
 3:     return std::promise<int>().get_future();
 4: }
 5: 
 6: int main()
 7: try
 8: {
 9:     fun().get();
10: }
11: catch (std::exception const &exc)
12: {
13:     std::cerr << exc.what() << '\n';
14: }
\end{verbatim}
   At line 3 a \texttt{promise} object is created, but its value is never
    set. Consequently, it `breaks its promise' to produce a value: when
    \texttt{main} tries to retrieve its value (in line 9) a \texttt{std::futue\_error}
    exception is thrown containing the \texttt{future\_errc::broken\_promise}
    value\end{quote}

\item \index{future\_already\_retrieved}\texttt{future\_already\_retrieved} 
        \begin{quote}
   \texttt{Future\_already\_retrieved} is thrown when multiple attempts are made to
    retrieve the \texttt{future} object from, e.g., a \texttt{promise} or
    \texttt{packaged\_task} object that (eventually) should be ready. For example:
   \begin{verbatim}
 1: int main()
 2: {
 3:     std::promise<int> promise;
 4:     promise.get_future();
 5:     promise.get_future();
 6: }
\end{verbatim}
   Note that after defining the \texttt{std::promise} object in line 3 it has
    merely been defined: no value is ever assigned to its \texttt{future}. Even
    though no value is assigned to the \texttt{future} object, it \emph{is} a valid
    object. I.e., after some time the future \emph{should} be ready, and the
    future's \texttt{get} member should produce a value. Hence, line 4 succeeds,
    but then, in line 5, the exception is thrown as `the future has already
    been retrieved'.\end{quote}

\item \index{promise\_already\_satisfied}\texttt{promise\_already\_satisfied} 
        \begin{quote}
   \texttt{Promise\_already\_satisfied} is thrown when multiple attempts are made to
    assign a value to a \texttt{promise} object. Assigning a value or
    \texttt{exception\_ptr} to the \texttt{future} of a \texttt{promise} object may happen
    only once.  For example:
   \begin{verbatim}
 1: int main()
 2: {
 3:     std::promise<int> promise;
 4:     promise.set_value(15);
 5:     promise.set_value(155);
 6: }
\end{verbatim}
        \end{quote}

\item \index{no\_state}\texttt{no\_state} 
        \begin{quote}
   \texttt{No\_state} is thrown when a member function (other than \texttt{valid}, see
    below) of a \texttt{future} object is called when its \texttt{valid} member returns
    \texttt{false}. This happens, e.g., when calling members of a default
    constructed \texttt{future} object. \texttt{No\_state} is not thrown for \texttt{future}
    objects returned by the \texttt{async} factory function or returned by the
    \texttt{get\_future} members of \texttt{promise} or \texttt{packaged\_task} type
    of objects. Here is an example:
   \begin{verbatim}
 1: int main()
 2: {
 3:     std::future<int> fut;
 4:     fut.get();
 5: }
\end{verbatim}
        \end{quote}
    \end{itemize}

The class   \index{future\_error}\texttt{std::future\_error} is derived from the class
\texttt{std::exception}, and offers, in addition to the \texttt{char const $*$what()
const} member also the member \index{code}\texttt{std::error\_code const \&code() const},
returning an \index{error\_code}\texttt{std::error\_code} object associated
with the thrown exception. 

\section{Shared asynchronous return objects: std::shared\_future}\label{SHAREDFUTURE}
\typeout{Original Yodl file: threading/sharedfuture}When a thread activates an asynchronous provider (e.g., a \texttt{std::async}) then
the return value of the asynchronously called function becomes available in
its activating thread through a \texttt{std::future} object. The
\texttt{future} object cannot be used by another thread. If this is required (e.g.,
see this chapter's final section) the \texttt{future} object must be converted to a
    \index{shared\_future}\texttt{std::shared\_future} object. 

Before using the class \texttt{std::shared\_future} the \index{future: header file}\texttt{$<$future$>$} header file
must be included.

Once a \texttt{shared\_future} object is available, its \texttt{get} member (see below)
can repeatedly be called to retrieve the results of the original \texttt{future}
object. This is illustrated by the next small example:
    \begin{verbatim}
     1: int main()
     2: {
     3:     std::promise<int> promise;
     4:     promise.set_value(15);
     5: 
     6:     auto fut = promise.get_future();
     7:     auto shared1 = fut.share();
     8: 
     9:     std::cerr << "Result: " << shared1.get() << "\n"
    10:                  "Result: " << shared1.get() << "\n"
    11:                  "Valid: " << fut.valid() << '\n';
    12: 
    13:     auto shared2 = fut.share();
    14: 
    15:     std::cerr << "Result: " << shared2.get() << "\n"
    16:                  "Result: " << shared2.get() << '\n';
    17: }
\end{verbatim}
    In lines 9 and 10 the \texttt{promise's} results are retrieved multiple times,
but having obtained the \texttt{shared\_future} in line 7, the original \texttt{future}
object no longer has an associated shared state. Therefore, when another
attempt is made (in line 13) to obtain the \texttt{shared\_future}, a \emph{no
associated state} exception is thrown and the program aborts.

However, multiple copies of \texttt{shared\_future} objects may co-exist.  When
multiple copies of \texttt{shared\_future} objects exist (e.g. in different
threads), the results of the associated asynchronous task are made ready
(become available) at exactly the same moment in time.

The relationship between the classes \texttt{future} and \texttt{shared\_future}
resembles the relationship between the classes \texttt{unique\_ptr} and
\texttt{shared\_ptr}: there can only be one instance of a \texttt{unique\_pointer},
pointing to data, whereas there can be many instances of a \texttt{shared\_pointer},
each pointing to the same data. 

The effect of calling any member of a \texttt{shared\_future} object for which
\texttt{valid() == false} other than the destructor, the move-assignment operator,
or \texttt{valid} is undefined.

The class \texttt{shared\_future} supports the following constructors:
    \begin{itemize}
    \item \texttt{shared\_future() noexcept}
        \begin{quote}an empty \texttt{shared\_future} object is constructed that does not
            refer to shared results. After using this constructor the object's
            \texttt{valid} member returns \texttt{false}.\end{quote}

\item \texttt{shared\_future(shared\_future const \&other)}
        \begin{quote}a \texttt{shared\_future} object is constructed that refers to the
            same results as \texttt{other} (if any). After using this constructor
            the object's \texttt{valid} member returns the same value as
            \texttt{other.valid()}.\end{quote}

\item \texttt{shared\_future(shared\_future$<$Result$>$ \&\&tmp) noexcept}
        \begin{quote} Effects: move constructs a shared\_future object that refers to
            the results that were originally referred to by \texttt{tmp} (if
            any). After using this constructor the object's \texttt{valid} member
            returns the same value as \texttt{tmp.valid()} returned prior to the
            constructor invocation, and \texttt{tmp.valid()} returns \texttt{false}.\end{quote}

\item \texttt{shared\_future(future$<$Result$>$ \&\&tmp) noexcept}
        \begin{quote} Effects: move constructs a shared\_future object that refers to
            the results that were originally referred to by \texttt{tmp} (if
            any). After using this constructor the object's \texttt{valid} member
            returns the same value as \texttt{tmp.valid()} returned prior to the
            constructor invocation, and \texttt{tmp.valid()} returns \texttt{false}.\end{quote}
    \end{itemize}

The class's destructor destroys the \texttt{shared\_future} object for which it is
called. If the object for which the destructor is called is the last
\texttt{shared\_future} object, and no \texttt{std::promise} or
\texttt{std::packaged\_task} is associated with the results associated
with the current object, then the results are also destroyed.

Here are the members of the class \texttt{std::shared\_future}:
    \begin{itemize}
    \item \texttt{shared\_future\& operator=(shared\_future \&\&tmp)}:\ \\ The move assignment operator releases the current object's shared
        results, and move assigns \texttt{tmp's} results to the current
        object. After calling the move assignment operator the current
        object's \texttt{valid} member returns the same value as \texttt{tmp.valid()}
        returned prior to the invocation of the move assignment operator, and
        \texttt{tmp.valid()} returns \texttt{false};

\item \texttt{shared\_future\& operator=(shared\_future const \&rhs)}:\ \\ The assignment operator releases the current object's shared results,
        and \texttt{rhs}'s results are shared with the current object. After
        calling the assignment operator the current object's \texttt{valid} member
        returns the same value as \texttt{tmp.valid()};

\item \texttt{Result const \&shared\_future::get() const}:\ \\ (Specializations for \texttt{shared\_future$<$Result \&$>$} and
        \texttt{shared\_future$<$void$>$} are also available). This member waits until
        the shared results are available, and subsequently returns \texttt{Result
        const \&}. Note that access to the data stored in \texttt{Results}, accessed
        through \texttt{get} is not synchronized. It is the responsibility of the
        programmer to avoid race conditions when accessing \texttt{Result's}
        data. If \texttt{Result} holds an exception, it is thrown when \texttt{get} is
        called;

\item \texttt{bool valid() const}:\ \\ Returns \texttt{true} if the current object refers to shared
            results;

\item \texttt{void wait() const}:\ \\ Blocks until shared results are available (i.e., the associated
        asynchronous task has produced results);

\item \texttt{future\_status wait\_for(const chrono::duration$<$Rep, Period$>$\& rel\_time)
            const}:\ \\ (The template types \texttt{Rep} and \texttt{Period} normally are derived by the
        compiler from the actual \texttt{rel\_time} specification.) If the shared
        results contain a deferred function (cf. section \ref{ASYNC}) nothing
        happens. Otherwise \texttt{wait\_for} blocks until the results of the
        associated asynchronous task has produced results, or until the
        relative time specified by \texttt{rel\_time} has expired. The member
        returns 
           \begin{itemize} 
           \item \texttt{future\_status::deferred} if the shared results contain a
            deferred function; \item \texttt{future\_status::ready} if the shared results
            are available;
           \item \texttt{future\_status::timeout} if the function is returning because
            the amount of time specified by \texttt{rel\_time} has expired;\end{itemize}

\item \texttt{future\_status wait\_until(const chrono::time\_point$<$Clock, Duration$>$\&
            abs\_time) const}:\ \\ (The template types \texttt{Clock} and \texttt{Duration} normally are derived by
        the compiler from the actual \texttt{abs\_time} specification.) If the
        shared results contain a deferred function nothing happens. Otherwise
        \texttt{wait\_until} blocks until the shared results are available or until
        the point in time specified by \texttt{abs\_time} has expired. Possible
        return values are:
           \begin{itemize}
            \item \texttt{future\_status::deferred} if the shared results contain a
                deferred function;
            \item \texttt{future\_status::ready} if the shared results are available;
            \item \texttt{future\_status::timeout} if the function is returning because
                the point in time specified by \texttt{abs\_time} has expired. 
            \end{itemize}

\end{itemize}

\section{Starting a new thread: std::async}\label{ASYNC}
\typeout{Original Yodl file: threading/async}In this section the function template \index{async}\texttt{std::async} is
covered. \texttt{Async} is used to start asynchronous tasks, returning values (or
\texttt{void}) to the calling thread, which is hard to realize merely using the
\texttt{std::thread} class.

Before using the function \texttt{async} the \index{future: header file}\texttt{$<$future$>$} header file must be
included. 

When starting a thread using the facilities of the class \texttt{std::thread} the
initiating thread at some point commonly calls the thread's \texttt{join}
method. At that point the thread must have finished or execution blocks until
\texttt{join} returns. While this often is a sensible course of action, it may not
always be: maybe the function implementing the thread has a return value, or
it could throw an exception.

In those cases \texttt{join} cannot be used: if an exception leaves a thread, then
your program ends. Here is an example:
    \begin{verbatim}
     1: void thrower()
     2: {
     3:     throw std::exception();
     4: }
     5: 
     6: int main()
     7: try
     8: {
     9:    std::thread subThread(thrower);
    10: }
    11: catch (...)
    12: {
    13:     std::cerr << "Caught exception\n";
    14: }
\end{verbatim}
    In line 3 \texttt{thrower} throws an exception, leaving the thread. This
exception is not caught by \texttt{main}'s try-block (as it is defined in another
thread). As a consequence, the program terminates.

This scenario doesn't occur when \texttt{std::async} is used. \texttt{Async} may start a
new asynchronous task, and the activating thread may retrieve the return value
of the function implementing the asynchronous task or any exception leaving
that function from a \texttt{std::future} object returned by the \texttt{async}
function. Basically, \texttt{async} is called similarly to the way a thread is
started using \texttt{std::thread}: it is passed a function and optionally
arguments which are forwarded to the function.

Although the function implementing the asynchronous task may be passed as
first argument, \texttt{async's} first argument may also be a value of the strongly
typed enumeration \index{deferred}\index{async}\index{launch}\texttt{std::launch}:
        \begin{verbatim}
    enum class launch
    {
        async,
        deferred
    };
\end{verbatim}
When passing \texttt{launch::async} the asynchronous task immediately starts;
when passing \texttt{launch::deferred} the asynchronous task is deferred. When 
\texttt{std::launch} is not specified the default value \texttt{launch::async \textbar{}
launch::deferred} is used, giving the implementation freedom of choice, 
usually resulting in deferring execution of the asynchronous task.

So, here is the first example again, this time using \texttt{async} to start the
sub-thread:
    \begin{verbatim}
     1: bool fun()
     2: {
     3:     return std::cerr << "    hello from fun\n";
     4: }
     5: int exceptionalFun()
     6: {
     7:     throw std::exception();
     8: }
     9: 
    10: int main()
    11: try
    12: {
    13:     auto fut1 = std::async(std::launch::async, fun);
    14:     auto fut2 = std::async(std::launch::async, exceptionalFun);
    15: 
    16:     std::cerr << "fun returned " << std::boolalpha << fut1.get() << '\n';
    17:     std::cerr << "exceptionalFun did not return " << fut2.get() << '\n';
    18: }
    19: catch (...)
    20: {
    21:     std::cerr << "caught exception thrown by exceptionalFun\n";
    22: }
\end{verbatim}
    Now the threads immediately start, but although the results are
available around line 13, the thrown exception isn't terminating the
program. The first thread's return value is made available in line 16, the
exception thrown by the second thread is simply caught by main's try-block
(line 19).

The function template \texttt{async} has several overloaded versions:
    \begin{itemize}
    \item  The basic form expects a function or functor as its first argument,
returning a \texttt{std::future} holding the function's return value or exception
thrown by the function (\index{invoke\_result}\texttt{invoke\_result} is declared in the header file
\index{functional: header file}\texttt{$<$functional$>$}):
        \begin{verbatim}
    template <typename Function, class ...Args>
    std::future< std::invoke_result< Function, Args ...>::type > 
        std::async(Function &&fun, Args &&...args);
\end{verbatim}
\item  Alternatively, the first argument may be the address of a member
function. In that case the (required) second argument is an object (or a
pointer to an object) of that member function's class. Any remaining arguments
are passed to the member function (see also the remarks below).

\item  The first argument may also be a combination (using the \texttt{bit\_or}
operator) of the enumeration values of the \texttt{std::launch} enumeration:
        \begin{verbatim}
    template <class Function, class ...Args>
    std::future<std::invoke_result<Function, Args ...>::type> 
        std::async(std::launch policy, Function &&fun, Args &&...args);
\end{verbatim}
\item  If the first argument specifies \texttt{std::launch} values, the second
argument may also be the address of a member function.  In that case the
(required) third argument is an object (or a pointer to an object) of that
member function's class. Any remaining arguments are passed to the member
function (see also the remarks below).
    \end{itemize}
    When calling \texttt{async} all arguments except for the \texttt{std::launch}
argument must be references, pointers or move-constructible objects:
   \begin{itemize}
   \item  When a
    member function is specified, then the object for which the member
    function is called must be a named object, an anonymous object, or a
    pointer to a named object. 
   \item  When a named object is passed to the \texttt{async} function template then
    copy construction is used to construct a copy of the argument which is
    then forwarded to the thread-launcher. 
   \item  When an anonymous object is passed to the \texttt{async} function template
    then move construction is used to forward the anonymous object to the
    thread launcher. 
   \end{itemize}
 Once the thread itself starts another move construction is used to construct
an object for the duration of the thread. When a pointer to an object is
passed, the sub-thread uses the object referred to by the pointer, and neither
copy- nor move-construction is required. However, when using a pointer to an
object the programmer should make sure that the object's lifetime exceeds the
duration of the thread (note that this is not automatically guaranteed, as the
asynchronous task may not actually start before the future's \texttt{get} member is
called).

Because of the default \texttt{std::launch::deferred \textbar{} std::launch::async} argument
used by the basic \texttt{async} call it is likely that the function which is
passed to \texttt{async} doesn't immediately start. The \texttt{launch::deferred} policy
allows the implementor to defer its execution until the program explicitly
asks for the function's results. Consider the following program:
        \begin{verbatim}
     1: void fun()
     2: {
     3:     std::cerr << "    hello from fun\n";
     4: }
     5: 
     6: std::future<void> asyncCall(char const *label)
     7: {
     8:     std::cerr << label << " async call starts\n";
     9:     auto ret = std::async(fun);
    10:     std::cerr << label << " async call ends\n";
    11:     return ret;
    12: }
    13: 
    14: int main()
    15: {
    16:     asyncCall("First");
    17:     asyncCall("Second");
    18: }
\end{verbatim}
    Although \texttt{async} is called in line 9, the program's output may not show
\texttt{fun's} output line when it is run.  This is a result of the (default) use
of \texttt{lauch::deferred}: the system simply defers \texttt{fun's} execution until
requested, which doesn't happen. But the \texttt{future} object that's returned by
\texttt{async} has a member \texttt{wait}. Once \texttt{wait} returns the shared state must
be available. In other words: \texttt{fun} must have finished. Here is what happens
when after line 9 the line \texttt{ret.wait()} is inserted:
        \begin{verbatim}
    First async call starts
        hello from fun
    First async call ends
    Second async call starts
        hello from fun
    Second async call ends
\end{verbatim}
Actually, evaluation of \texttt{fun} can be requested at the point where we
need its results, maybe even after calling \texttt{asyncCall}, as shown in the next
example:
        \begin{verbatim}
     1: int main()
     2: {
     3:     auto ret1 = asyncCall("First");
     4:     auto ret2 = asyncCall("Second");
     5: 
     6:     ret1.get();
     7:     ret2.get();
     8: }
\end{verbatim}
    Here the \texttt{ret1} and \texttt{ret2 std::future} objects are created, but their
\texttt{fun} functions aren't evaluated yet. Evaluation occurs at lines 6 and 7,
resulting in the following output:
        \begin{verbatim}
    First async call starts
    First async call ends
    Second async call starts
    Second async call ends
        hello from fun
        hello from fun
\end{verbatim}
The \texttt{std::async} function template is used to start a thread, making its
results available to the calling thread. On the other hand, we may only be
able to \emph{prepare} (package) a task (a thread), but may have to leave the
completion of the task to another thread. Scenarios like this are realized
through objects of the class \texttt{std::packaged\_task}, which is the topic of the
next section.

\section{Preparing a task for execution: std::packaged\_task}\label{PACKAGE}
\typeout{Original Yodl file: threading/packagedtask}The class template \index{packaged\_task}\texttt{std::packaged\_task} allows a program to
`package' a function or functor and pass the package to a thread for further
processing. The processing thread then calls the packaged function, passing it
its arguments (if any). After completing the function the \texttt{packaged\_task's}
future is ready, allowing the program to retrieve the results produced by
the function. Thus, functions and the results of function calls can be
transferred between threads.

Before using the class template \texttt{packaged\_task} the \index{future: header file}\texttt{$<$future$>$} header file
must be included.

Before describing the class's interface, let's first look at an example to get
an idea about how a \texttt{packaged\_task} can be used. Remember that the essence
of \texttt{packaged\_task} is that part of your program prepares (packages) a task
for another thread to complete, and that the program at some point needs the
result of the completed task. 

To clarify what's happening here, let's first look at a real-life
analogon. Every now and then I make an appointment with my garage to have my
car serviced. The `package' in this case are the details about my car: its
make and type determine the kind of actions my garage performs when servicing
it. My neighbor also has a car, which also needs to be serviced every now and
then. This also results in a `package' for the garage. At the appropriate time
me and my neighbor take our cars to the garage (i.e., the packages are passed
to another thread). The garage services the cars (i.e., calls the functions
stored in the \texttt{packaged\_tasks} {[}note that the tasks differ, depending on the
types of the cars{]}), and performs some actions that are associated with it
(e.g., registering that my or my neighbor's car has been serviced, or order
replacement parts). In the meantime my neighbor and I perform our own
businesses (the program continues while a separate thread runs as well). But
by the end of the day we'd like to use our cars again (i.e., get the results
associated with the \texttt{packaged\_task}). A common result in this example is the
garage's bill, which we have to pay (the program obtains the
\texttt{packaged\_task's} results).

Here is a little \textbf{C++} program illustrating the use of a \texttt{packaged\_task}
(assuming the required headers and \texttt{using namespace std} have been
specified):
    \begin{verbatim}
     1: mutex carDetailsMutex;
     2: condition_variable condition;
     3: string carDetails;
     4: packaged_task<size_t (std::string const &)> serviceTask;
     5: 
     6: size_t volkswagen(string const &type)
     7: {
     8:     cout << "performing maintenance by the book for a " << type << '\n';
     9:     return type.size() * 75;            // the size of the bill
    10: }
    11: 
    12: size_t peugeot(string const &type)
    13: {
    14:     cout << "performing quick and dirty maintenance for a " << type << '\n';
    15:     return type.size() * 50;             // the size of the bill
    16: }
    17: 
    18: void garage()
    19: {
    20:     while (true)
    21:     {
    22:         unique_lock<mutex> lk(carDetailsMutex);
    23:         while (carDetails.empty())
    24:             condition.wait(lk);
    25: 
    26:         cout << "servicing a " << carDetails << '\n';
    27:         serviceTask(carDetails);
    28:         carDetails.clear();
    29:     }
    30: }
    31: 
    32: int main()
    33: {
    34:     thread(garage).detach();
    35: 
    36:     while (true)
    37:     {
    38:         string car;
    39:         if (not getline(cin, car) || car.empty())
    40:             break;
    41:         {
    42:             lock_guard<mutex> lk(carDetailsMutex);
    43:             carDetails = car;
    44:         }
    45:         serviceTask =  packaged_task<size_t (string const &)>(
    46:                     car[0] == 'v' ? volkswagen : peugeot
    47:                 );
    48:         auto bill = serviceTask.get_future();
    49:         condition.notify_one();
    50:         cout << "Bill for servicing a " << car <<
    51:                                 ": EUR " << bill.get() << '\n';
    52:     }
    53: }
\end{verbatim}
    \begin{itemize}
    \item  Lines 1-3 define the variables used for synchronization;
    \item  Line 4 defines a \texttt{packaged\_task: serviceTask} is initialized with a
        function (or functor) expecting a \texttt{string}, returning a \texttt{size\_t};
    \item  Lines 6-10 and 12-16 define such functions: \texttt{volkswagen} and
        \texttt{peugeot} represent the tasks to perform when cars of the provided
        types come in for service; presumably they return the bill.
    \item  Lines 18-30 define the function \texttt{void garage}, defining the actions
        performed by the garage when cars come in for service. These actions
        are performed by a separate detached thread, starting in line 34. In a
        continuous loop it waits until it obtains a lock on the
        \texttt{carDetailsMutex} and \texttt{carDetails} is no longer empty. Then, at
        line 27, it passes \texttt{carDetails} to the \texttt{packaged\_task
        `serviceTask'}. By itself this is not identical to calling the
        \texttt{packaged\_task's} function, but eventually its function will be
        called. At this point the \texttt{packaged\_task} receives its function's
        arguments, which it eventually will forward to its configured
        function. Finally, at line 28 it clears \texttt{carDetails}, thus preparing
        itself for the next request.
    \item  Lines 32-53 define \texttt{main}:
        \begin{itemize}
        \item  First, at line 34 the anonymous detached thread running
            \texttt{garage} is started.
        \end{itemize}
        Then the program's main loop starts (lines 36-52):
        \begin{itemize}
        \item  The main thread reads commands from the standard input until an
            empty or no line is received (lines 38-40).
        \item  By convention the line's first letter starts the car's brand
            (\texttt{volkswagen} or \texttt{peugeot}), and the \texttt{packaged\_task}, provided with
            the right servicing function, is constructed
            next (line 45).
        \item  Then, at line 48 the results, stored in a \texttt{future}, are
            retrieved. Although at this point the \texttt{future} might not be
            ready, the \texttt{future} object itself \emph{is}, and it is simply
            returned as the bill.
        \item  Now we're ready to inform the garage that it can service a car:
            the garage is notified in line 49.
        \end{itemize}
       Anything may happen next: the program may perform any actions,
        but eventually it requests the results produced by the garage.
       \begin{itemize}
        \item  The main thread obtains the results by calling \texttt{bill.get()}
            in line 51. If, by this time, the car is still being serviced, the
            bill isn't ready yet, and \texttt{bill.get()} blocks until it is, and
            the bill for servicing a car is shown.
        \end{itemize}
    \end{itemize}
    Now that we've seen an example of a program using a \texttt{packaged\_task},
let's have a look at its interface. Note that the class \texttt{packaged\_task} is a
class template: its template type parameter specifies the prototype of a
function or function object implementing the task performed by the
\texttt{packaged\_task} object.

Constructors and destructor:
    \begin{itemize}
    \item \texttt{packaged\_task() noexcept}:\ \\ The default constructor constructs a \texttt{packaged\_task} object which is
        not associated with a function or shared state;

\item \texttt{explicit packaged\_task$<$ReturnType(Args...)$>$ task(fun)}:\ \\ A \texttt{packaged\_task} is constructed for a function or functor \texttt{fun}
        expecting arguments of types \texttt{Args...}, and returning a value of
        type \texttt{ReturnType}. The \texttt{packaged\_task} class template specifies
        \texttt{ReturnType (Args...)} as its template type parameter. The
        constructed object contains a shared state, and a (move constructed)
        copy of \texttt{function}.

Optionally an \texttt{Allocator} may be specified as second template type
        parameter, in which case the first two arguments are
        \index{allocator\_arg\_t}\texttt{std::allocator\_arg\_t, Allocator const
        \&alloc}. The type \texttt{std::allocator\_arg\_t} is a type introduced to
        disambiguate constructor selections, and can simply be specified as
        \texttt{std::allocator\_arg\_t()}.

This constructor may throw a \texttt{std::bad\_alloc} exception or
        exceptions thrown by \texttt{function's} copy or move constructors.

\item \texttt{packaged\_task(packaged\_task \&\&tmp) noexcept}:\ \\ The move constructor moves  any existing shared state from \texttt{tmp} to
        the newly constructed object, removing the shared state from \texttt{tmp}.

\item \texttt{\textasciitilde{}packaged\_task()}:\ \\ The object's shared state (if any) is abandoned
    \end{itemize}

Member functions:
    \begin{itemize}
    \item \index{get\_future}\texttt{future$<$ReturnType$>$ get\_future()}:\ \\ A \texttt{std::future} object is returned holding the results of the
        separately executed thread. When \texttt{get\_future} is incorrectly called
        a \texttt{future\_error} exception is thrown, containing one of the
        following values:
       \begin{itemize}
       \item \texttt{future\_already\_retrieved} if \texttt{get\_future} was already called on a
            \texttt{packaged\_task} object containing the same shared state as the
            current object;
        \item \texttt{no\_state} if the current object has no shared state.
       \end{itemize}
       Note: Any \texttt{futures} that share the object's shared state may access
        the result returned by the object's task.

\item \texttt{void make\_ready\_at\_thread\_exit(Args... args)}:\ \\ Calls \texttt{void operator()(Args... args)} (see below) when the current
        thread exits, once all objects of thread storage duration associated
        with the current thread have been destroyed.

\item \texttt{packaged\_task \&operator=(packaged\_task \&\&tmp)}:\ \\ The move assignment operator first releases the current object's
        shared state (if available), after which the current object and
        \texttt{tmp} are swapped;

\item \texttt{void operator()(Args... args)}:\ \\ The \texttt{args} arguments are forwarded to the current object's
        stored task. When the stored task returns its return value is stored
        in the current object's shared state. Otherwise any exception thrown
        by the task is stored in the object's shared state. Following this the
        object's shared state is made ready, and any threads blocked in a
        function waiting for the object's shared state to become ready are
        unblocked. A \texttt{future\_error} exception is thrown upon error,
        containing 
       \begin{itemize}
       \item \texttt{promise\_already\_satisfied} if the shared state has already been
            made ready;
        \item \texttt{no\_state} if the current object does not have any shared state.
       \end{itemize}
       Calling this member synchronizes with calling any member function of a
        \texttt{(shared\_)future} object that provides access to the
        \texttt{packaged\_task's} results.

\item \texttt{void reset()}:\ \\ Abandons any available shared state, initializing the current object
        to \texttt{packaged\_task(std::move(funct))}, where \texttt{funct} is the
        object's stored task. This member may throw the following exceptions:
       \begin{itemize}
       \item \texttt{bad\_alloc} if memory for the new shared state could not be
            allocated;
        \item  any exception thrown by the move constructor of the task stored in
                the shared state;   
        \item \texttt{future\_error} with a \texttt{no\_state} error condition if the current
            object contains no shared state.
       \end{itemize}

\item \texttt{void swap(packaged\_task \&other) noexcept}:\ \\ The shared states and stored tasks of the current object  and other
        are swapped. 

\item \texttt{bool valid() const noexcept}:\ \\ Returns \texttt{true} if the current object contains a shared state,
        otherwise \texttt{false} is returned;
    \end{itemize}

The following non-member (free) function operating on \texttt{packaged\_task}
objects is available:
    \begin{itemize}
    \item  \texttt{void swap}\texttt{(packaged\_task$<$ReturnType(Args...)$>$ \&lhs,}
                                                            \linebreak 
            \texttt{packaged\_task$<$ReturnType(Args...)$>$ \&rhs}\texttt{) noexcept}
       \begin{quote}Calls \texttt{lhs.swap(rhs)}\end{quote}
    \end{itemize}

\section{The class `std::promise'}\label{PROMISE}
\typeout{Original Yodl file: threading/promise}In addition to \texttt{std::packaged\_task} and \texttt{std::async} the class template
    \index{promise}\texttt{std::promise} can be used to obtain the results from a
separate thread.

Before using the class template \texttt{promise} the \index{future: header file}\texttt{$<$future$>$} header file
must be included.

A \texttt{promise} is used to obtain the results from another thread without
further synchronization requirements. Consider the following program:
        \begin{verbatim}
    void compute(int *ret)
    {
        *ret = 9;
    }
    
    int main()
    {
        int ret = 0;
        std::thread(compute, &ret).detach();
        cout << ret << '\n';
    }
\end{verbatim}
 Chances are that this program shows the value 0: the \texttt{cout} statement has
already been executed before the detached thread has had a chance to complete
its work. In this example that problem can easily be solved by using a
non-detached thread, and using the thread's \texttt{join} member, but when multiple
threads are used that requires named threads and as many \texttt{join}
calls. Instead, using a \texttt{promise} might be preferred:
        \begin{verbatim}
     1: void compute(promise<int> &ref)
     2: {
     3:     ref.set_value(9);
     4: }
     5: 
     6: int main()
     7: {
     8:     std::promise<int> prom;
     9:     std::thread(compute, ref(prom)).detach();
    10: 
    11:     cout << prom.get_future().get() << '\n';
    12: }
\end{verbatim}
    This example also uses a detached thread, but its results are kept for
future reference in a \texttt{promise} object, instead of directly being assigned
to a final destination variable. The \texttt{promise} object contains a \texttt{future}
object holding the computed value. The \texttt{future's get} member blocks until
the future has been made ready, at which point the result becomes
available. By then the detached thread may or may not yet have been
completed. If it already completed its work then \texttt{get} immediately returns,
otherwise there will be a slight delay.

Promises are useful when implementing a multi threaded version of some
algorithm without having to use additional synchronization statements. As an
example consider matrix multiplications.  Each element of the resulting
product matrix is computed as the inner product of two vectors: the inner
product of a row of the left-hand matrix operand and a column of the
right-hand matrix operand becomes element \texttt{{[}row{]}{[}column{]}} of the resulting
matrix. Since each element of the resulting matrix can independently be
computed from the other elements, a multi threaded implementation is well
possible. In the following example the function \texttt{innerProduct} (lines 4..11)
leaves its result in a \texttt{promise} object:
        \begin{verbatim}
     1: int m1[2][2] = {{1, 2}, {3, 4}};
     2: int m2[2][2] = {{3, 4}, {5, 6}};
     3: 
     4: void innerProduct(promise<int> &ref, int row, int col)
     5: {
     6:     int sum = 0;
     7:     for (int idx = 0; idx != 2; ++idx)
     8:         sum += m1[row][idx] * m2[idx][col];
     9: 
    10:     ref.set_value(sum);
    11: }
    12: 
    13: int main()
    14: {
    15:     promise<int> result[2][2];
    16: 
    17:     for (int row = 0; row != 2; ++row)
    18:     {
    19:         for (int col = 0; col != 2; ++col)
    20:             thread(innerProduct, ref(result[row][col]), row, col).detach();
    21:     }
    22: 
    23:     for (int row = 0; row != 2; ++row)
    24:     {
    25:         for (int col = 0; col != 2; ++col)
    26:             cout << setw(3) << result[row][col].get_future().get();
    27:         cout << '\n';
    28:     }
    29: }
\end{verbatim}
    Each inner product is computed by a separate (anonymous and detached)
thread (lines 17..21), which starts as soon as the run-time system allows it
to start. By the time the threads have finished the resulting inner products
can be retrieved from the promises' futures. Since futures' \texttt{get} members
block until their results are actually available, the resulting matrix can
simply be displayed by calling those members in sequence (lines 23..28).

So, a \texttt{promise} allows us to use a thread to compute a value (or
exception, see below), which value may then be collected by another thread at
some future point in time. The promise remains available, and as a consequence
further synchronization of the threads and the program starting the threads is
not necessary. When the promise object contains an exception, rather than a
value, its future's \texttt{get} member rethrows the stored exception.

Here is the class \texttt{promise's} interface. Note that the class \texttt{promise} is
a class template: its template type parameter \texttt{ReturnType} specifies the
template type parameter of the \texttt{std::future} that can be retrieved from it.

Constructors and destructor:
    \begin{itemize}
    \item \texttt{promise()}:\ \\ The default constructor constructs a \texttt{promise} object containing a
        shared state. The shared state may be returned by the member
        \texttt{get\_future} (see below), but that future has not yet been made
        ready;

\item \texttt{promise(promise \&\&tmp) noexcept}:\ \\ The move constructor constructs a \texttt{promise} object, transferring
        the ownership of \texttt{tmp's} shared state to the newly constructed
        object. After the object has been constructed, \texttt{tmp} no longer
        contains a shared state;

\item \texttt{\textasciitilde{}promise()}:\ \\ The object's shared state (if any) is abandoned;
    \end{itemize}

Member functions:
    \begin{itemize}
    \item \texttt{std::future$<$ReturnType$>$ get\_future()}:\ \\ A \texttt{std::future} object sharing the current object's shared state is
        returned. A \texttt{future\_error} exception is thrown upon error,
        containing 
       \begin{itemize}
       \item \texttt{future\_already\_retrieved} if \texttt{get\_future} was already called on a
            \texttt{packaged\_task} object containing the same shared state as the
            current object;
        \item \texttt{no\_state} if the current object has no shared state.
       \end{itemize}
       Note: Any \texttt{futures} that share the object's shared state may
        access the result returned by the object's task;

\item \texttt{promise \&operator=(promise \&\&rhs) noexcept}:\ \\ The move assignment operator first releases the current object's
        shared state (if available), after which the current object and
        \texttt{tmp} are swapped;

\item \texttt{void promise$<$void$>$::set\_value()}:\ \\ See below, at the last \texttt{set\_value} member's description;

\item \texttt{void set\_value(ReturnType \&\&value)}:\ \\ See below, at the last \texttt{set\_value} member's description;

\item \texttt{void set\_value(ReturnType const \&value)}:\ \\ See the next member function's description;

\item \texttt{void set\_value(ReturnType \&value)}:\ \\ The argument (\texttt{value}) is atomically stored in the shared state,
        which is then also made ready. A \texttt{future\_error} exception is thrown
        upon error, containing
       \begin{itemize}
       \item \texttt{promise\_already\_satisfied} if the shared state has already been
            made ready;
        \item \texttt{no\_state} if the current object does not have any shared state.
       \end{itemize}
       Alternatively, any exception thrown by \texttt{value}'s move or copy
        constructor may be thrown;
     

\item \texttt{void set\_exception(std::exception\_ptr obj)}:\ \\ \texttt{Exception\_ptr obj} (cf. section \ref{EXCPTR}) is atomically stored
        in the shared state, making that state ready. A \texttt{future\_error}
        exception is thrown upon error, containing
       \begin{itemize}
       \item \texttt{promise\_already\_satisfied} if the shared state has already been
            made ready;
        \item \texttt{no\_state} if the current object does not have any shared state;
       \end{itemize}

\item \texttt{void set\_exception\_at\_thread\_exit(exception\_ptr ptr)}:\ \\ The exception pointer \texttt{ptr} is stored in the shared state without
        immediately making that state ready. The state becomes ready when the
        current thread exits, once all objects of thread storage duration
        which are associated with the ending thread have been destroyed.  A
        \texttt{future\_error} exception is thrown upon error, containing
       \begin{itemize}
       \item \texttt{promise\_already\_satisfied} if the shared state has already been
            made ready;
        \item \texttt{no\_state} if the current object does not have any shared state;
       \end{itemize}

\item \texttt{void set\_value\_at\_thread\_exit()}:\ \\ See below, at the last \texttt{set\_value\_at\_thread\_exit} member's
        description;

\item \texttt{void set\_value\_at\_thread\_exit(ReturnType \&\&value)}:\ \\ See below, at the last \texttt{set\_value\_at\_thread\_exit} member's
        description;

\item \texttt{void set\_value\_at\_thread\_exit(ReturnType const \&value)}:\ \\ See the next \texttt{set\_value\_at\_thread\_exit} member's
        description;

\item \texttt{void set\_value\_at\_thread\_exit(ReturnType \&value)}:\ \\ Stores \texttt{value} in the shared state without immediately making that
        state ready.  The state becomes ready when the current thread exits,
        once all objects of thread storage duration which are associated with
        the ending thread have been destroyed.  A \texttt{future\_error} exception
        is thrown upon error, containing
       \begin{itemize}
       \item \texttt{promise\_already\_satisfied} if the shared state has already been
            made ready;
        \item \texttt{no\_state} if the current object does not have any shared state;
       \end{itemize}

\item \texttt{void swap(promise\& other) noexcept}:\ \\ The shared states (if any) of the current object and \texttt{other} are
        exchanged.
    \end{itemize}

The following non-member (free) function operating on \texttt{promise} objects is
available:
    \begin{itemize}
    \item \texttt{void swap(promise$<$ReturnType$>$ \&lhs, promise$<$ReturnType$>$ \&rhs)
        noexcept}:\ \\ Calls \texttt{lhs.swap(rhs)}
    \end{itemize}

\section{An example: multi-threaded compilations}\label{MULTICOMP}
\typeout{Original Yodl file: threading/compilations}In this section another program is developed. This section's  example program
illustrates the use of \texttt{packaged\_tasks}. 

Like the multi-threaded quicksort example a worker pool is used. However, in
this example the workers in fact do not know what their task is. In the
current example the tasks happens to be identical, but different tasks might
as well have been used, without having to update the workers.

The program uses a \texttt{class Task} containing a command-specification
(\texttt{d\_command}), and a task specification (\texttt{d\_task}) (cf. Figure \ref{compile}), the
sources of the program are found in the 
\texttt{yo/threading/examples/multicompile} directory of the \textbf{C++} Annotations.

\begin{figure}[tbp]
\centerline{\epsffile{threading/compile.eps}}
\caption{\label{compile}Data structure used for the multi-threading compilation}
\end{figure}

In this program \texttt{main} starts by firing up its workforce in a series of
threads. Following this, the compilation jobs are prepared and pushed on a
\texttt{task-queue} by \texttt{jobs}, where they're retrieved from by the workers. Once
the compilations have been completed (i.e., after the worker threads have
joined the main thread), the results of the compilation jobs are handled by
\texttt{results}:
        \begin{verbatim}
    int main()
    {
        workforce();                    // start the worker threads
        jobs();                         // prepare the jobs: push all tasks on the
                                        // taskQ
    
        for (thread &thr: g_thread)     // wait for the workers to end
            thr.join();
    
        results();                      // show the results
    
    }
\end{verbatim}
The \texttt{jobs} function receives the names of the files to compile from the
\texttt{nextCommand} function, which ignores empty lines and returns non-empty
lines. Eventually \texttt{nextCommand} returns an empty line once all lines of the
standard input stream have been read:
        \begin{verbatim}
    string nextCommand()
    {
        string ret;
        while (true)
        {
            if (not getline(cin, ret))    // no more lines
                break;
    
            if (not ret.empty())          // ready once there's line content.
                break;
        }
        return ret;
    }
\end{verbatim}
With non-empty lines \texttt{jobs} waits for an available worker using (line 12)
the \texttt{g\_dispatcher} semaphore. Initialized to the size of the work force, it
is reduced by an active worker, and incremented by workers who have completed
their tasks. If a compilation fails, then \texttt{g\_done} is set to \texttt{true} and no
additional compilations are performed (lines 14, 15). While \texttt{jobs} receives
the names of the files to compile, workers may detect compilation errors. If
so, the workers set variable \texttt{g\_done} to \texttt{true}. Once the \texttt{job}
function's \texttt{while} loop ends the workers are notified once again (line 24),
who will then, because there's no task to perform anymore, end their threads
        \begin{verbatim}
     1: void jobs()
     2: {
     3:     while (true)
     4:     {
     5:         string line = nextCommand();
     6:         if (line.empty())                   // no command? jobs() done.
     7:         {
     8:             g_done = true;
     9:             break;
    10:         }
    11: 
    12:         g_dispatcher.wait();                // wait for an available worker
    13: 
    14:         if (g_done.load())                  // if a worker found an error
    15:             break;                          // then quit anyway
    16: 
    17:         newTask(line);                      // push a new task (and its
    18:                                             // results)
    19: 
    20:         g_worker.notify_all();              // inform the workers: job is
    21:                                             // available
    22:     }
    23: 
    24:     g_worker.notify_all();                  // end the workers at an empty Q
    25: }
\end{verbatim}
The function \texttt{newTask} prepares the program for the next task. First a
\texttt{Task} object is constructed. \texttt{Task} contains the name of the file to
compile, and a \texttt{packaged\_task}. It encapsulates all activities that are
associated with a \texttt{packaged\_task}. Here is its (in-class) definition:
        \begin{verbatim}
     1: using PackagedTask = packaged_task<Result (string const &fname)>;
     2: 
     3: class Task
     4: {
     5:     string d_command;
     6:     PackagedTask d_task;
     7: 
     8:     public:
     9:         Task()  = default;
    10: 
    11:         Task(string const &command, PackagedTask &&tmp)
    12:         :
    13:             d_command(command),
    14:             d_task(move(tmp))
    15:         {}
    16: 
    17:         void operator()()
    18:         {
    19:             d_task(d_command);
    20:         }
    21: 
    22:         shared_future<Result> result()
    23:         {
    24:             return d_task.get_future().share();
    25:         }
    26: };
\end{verbatim}
Note (lines 22-25) that \texttt{result} returns a \emph{shared\_future}. Since the
dispatcher runs in a different thread than the one processing the results, the
\texttt{futures} created by the dispatcher must be shared with the \texttt{futures}
required by the function processing the results. Hence the \texttt{shared\_futures}
returned by \texttt{Task::result}. 

Once a \texttt{Task} object has been constructed its \texttt{shared\_future} object is
pushed on the result queue. Although the actual results aren't available by
this time, the \texttt{result} function is eventually called to process the results
that were pushed on the result-queue. Additionally, the \texttt{Task} itself is
pushed on a \emph{task queue}, and it will be retrieved by a worker:
        \begin{verbatim}
    class Task
    {
        string d_command;
        PackagedTask d_task;

        public:
            Task()  = default;

            Task(string const &command, PackagedTask &&tmp);
            void operator()();
            shared_future<Result> result();
    };
\end{verbatim}
\begin{verbatim}
    void pushResultQ(shared_future<Result> const &sharedResult)
    {
        lock_guard<mutex> lk(g_resultQMutex);
        g_resultQ.push(sharedResult);
    }
\end{verbatim}
The workers have a simple task: wait for the next task, then retrieve it from
the task queue, and complete that task. Whatever happens inside the tasks
themselves is of no concern to the worker. Also, when notified (normally by
the \texttt{jobs} function) that there's a task waiting it'll execute that
task. However, at the end, once all tasks have been pushed on the task queue,
\texttt{jobs} once again notifies the workers. In that case the task queue is
empty, and the worker function ends. But just before that it notifies its
fellow workers, which in turn end, thus ending all worker threads, allowing
them to join the \texttt{main}-thread:
        \begin{verbatim}
    void worker()
    {
        Task task;
        while (true)
        {
            g_worker.wait();                    // wait for an available task
    
            if (g_taskQ.empty())                // no task? then done
                break;
    
            g_taskQ.popFront(task);
            g_dispatcher.notify_all();          // notify the dispatcher that
                                                // another task can be pushed
            task();
        }
        g_worker.notify_all();                  // no more tasks: notify the other
    }                                           // workers.
\end{verbatim}
This completes the description of how tasks are handled. 

The task itself are now described. In the current program \textbf{C++} source files
are compiled. The compilation command is passed to the constructor of a
\texttt{CmdFork} object, which starts the compiler as a child process. The result
of the compilation is retrieved via its \texttt{childExit} member (returning the
compiler's exit code) and \texttt{childOutput} member (returning any textual output
produced by the compiler). If compilation fails, the exit value won't be
zero. In this case no further compilation tasks will be issued as \texttt{g\_done}
is set to \texttt{true} (lines 11 and 12; the implementation of the \texttt{class
CmdFork} is available from the \textbf{C++} Annotations'
\texttt{yo/threading/examples/cmdfork} directory). Here is the function
\texttt{compile}:
        \begin{verbatim}
     1: Result compile(string const &line)
     2: {
     3:     string command("/usr/bin/g++ -Wall -c " + line);
     4: 
     5:     CmdFork cmdFork(command);
     6:     cmdFork.fork();
     7: 
     8:     Result ret {cmdFork.childExit() == 0,
     9:                 line + "\n" + cmdFork.childOutput()};
    10: 
    11:     if (not ret.ok)
    12:         g_done = true;
    13: 
    14:     return ret;
    15: }
\end{verbatim}
The \texttt{results} function continues for as long as \texttt{newResults} indicates
that results are available. By design the program will show all available
successfully completed compilations, and (if several workers encountered
compilation errors) only the compiler's output of the first 
compilation error is displayed. All \emph{available} successfully completed
compilations meaning that, in case of a compilation error, the source files
that were successfully compiled by the currently active work force are listed,
but remaining source files are not processed anymore:
        \begin{verbatim}
    void results()
    {
        Result result;
    
        string errorDisplay;
    
        while (newResult(result))
        {
            if (result.ok)
                cerr << result.display;
            else if (errorDisplay.empty())
                errorDisplay = result.display;  // remember the output of
        }                                       // the first compilation error
        if (not errorDisplay.empty())           // which is displayed at the end
            cerr << errorDisplay;
    }
\end{verbatim}
The function \texttt{newResult} controls \texttt{results' while}-loop. It returns
\texttt{true} when as long as the result queue isn't empty, in which case the
queue's front element is stored at the external \texttt{Result} object, and the
queue's front element is removed from the queue:
        \begin{verbatim}
    bool newResult(Result &result)
    {
        if (g_resultQ.empty())
            return false;
    
        result = g_resultQ.front().get();
        g_resultQ.pop();
    
        return true;
    }
\end{verbatim}
\section{Transactional Memory}\label{TRANSMEM}
\typeout{Original Yodl file: threading/transactionalmemory}

Transactional memory is used to simplify shared data access in multithreaded
programs. The benefits of transactional memory is best illustrated by a
small program. Consider a situation where threads need to write information to
a file. A plain example of such a program would be:
        \begin{verbatim}
    void fun(int value)
    {
        for (size_t rept = 0; rept != 10; ++rept)
        {
            this_thread::sleep_for(chrono::seconds(1));
            cout << "fun " << value << '\n';
        }
    }
    
    int main()
    {
        thread thr{ fun, 1 };
        fun(2);
        thr.join();
    }
\end{verbatim}
When this program is run the \texttt{fun 1} and \texttt{fun 2} messages are
intermixed. To prevent this we traditionally define a \texttt{mutex}, lock it,
write the message, and release the lock:
        \begin{verbatim}
    void fun(int value)
    {
        static mutex guard;

        for (size_t rept = 0; rept != 10; ++rept)
        {
            this_thread::sleep_for(chrono::seconds(1));
            guard.lock();
            cout << "fun " << value << '\n';
            guard.unlock();
        }
    };
\end{verbatim}
Transactional memory handles the locking for us. Transactional memory is used
when statements are embedded in a \index{synchronized}\texttt{synchronized} block. The function
\texttt{fun}, using transactional memory, looks like this:
        \begin{verbatim}
    void fun(int value)
    {
        for (size_t rept = 0; rept != 10; ++rept)
        {
            this_thread::sleep_for(chrono::seconds(1));
            synchronized
            {
                cout << "fun " << value << '\n';
            }
        }
    };
\end{verbatim}
\index{transactional memory: -fgnu-tm}
    To compile source files using transactional memory the \texttt{g++} compiler
option \index{-fgnu-tm}\texttt{-fgnu-tm} must be specified.

The code inside a synchronized block is executed as a single, as if the
block was protected by a mutex. Different from using mutexes transactional
memory is implemented in software instead of using hardware-facilities.

Considering how easy it is to use transactional memory compared to using
the \texttt{mutex}-based locking mechanism using transactional memory appears
too good to be true. And in a sense it is. When encountering a synchronized
block the thread unconditionally executes the block's statements. At the same
time it keeps a detailed log of all its actions. Once the statements have been
completed the thread checks whether another thread didn't start executing the
block just before it. If so, it reverses its actions, using the synchronized
block's log. The implication of this should be clear: there's at least the
overhead of maintaining the log, and \emph{if} another thread started executing 
the synchronized block before the current thread then there's the additional
overhead of reverting its actions and to try again. 

The advantages of transactional memory should also be clear: the
programmers no longer is responsible for correctly controlling access to
shared memory; risks of encountering deadlocks have disappeared as has all
adminstrative overhead of defining mutexes, locking and unlocking. Especially
for inherently slow operations like writing to files transactional memory can
greatly simplify parts of your code. Consider a \texttt{std::stack}. Its
top-element can be inspected but its \texttt{pop} member does not return the
topmost element. To retrieve the top element and then maybe remove it
traditionally requires a mutex lock surrounding determining the stack's size,
and if empty, release the lock and wait. If not empty then retrieve its
topmost element, followed by removing it from the stack. Using a transactional
memory we get something as simple as:
            \begin{verbatim}
    bool retrieve(stack<Item> &itemStack, Item &item)
    {
        synchronized
        {
            if (itemStack.empty())
                return false;
            item = std::move(itemStack.top());
            itemStack.pop();
            return true;
        }
    }
\end{verbatim}
Variants of \texttt{synchronized} are:
    \begin{itemize}
    \item \index{atomic\_noexcept}\texttt{atomic\_noexcept}: the statements inside its compound statement may not
        throw exceptions. If they do, \texttt{std::abort} is called. If the earlier
        \texttt{fun} function specifies \texttt{atomic\_noexcept} instead of
        \texttt{synchronized} the compiler generates and error about the use of the
        insertion operator, from which an exception may be thrown.
    \item \index{atomic\_cancel}\texttt{atomic\_cancel}: not yet supported by \texttt{g++}. If an
        exception other than (\texttt{std::}) \texttt{bad\_alloc, bad\_array\_new\_length,
        bad\_cast, bad\_typeid, bad\_exception, exception, tx\_exception$<$Type$>$} is
        thrown \texttt{std::abort} is called. If an acceptable exception is thrown,
        then the statements executed so far are undone.
    \item \index{atomic\_commit}\texttt{atomic\_commit}: if an exception is thrown from its compound statement
        all thus far executed statements are kept (i.e., not undone).
    \end{itemize}

\section{Synchronizing output to streams}\label{OSYNC}
\typeout{Original Yodl file: threading/osyncstream}Consider the situation where different threads of a multi-threaded program
must write to the same file. The information written by each thread should
show up as a single block in that file. There are several ways to solve this
problem: each thread could write to a global file that's associated with just
one thread, and by the time the threads have stopped all these files are
copied to the destination file. Alternatively, the destination file could be
passed to the threads, while each thread defines its own local file, writing
its information to that file. Then, by the time the thread is about to end it
locks access to the destination file, and copies its local file to the
destination file. 

Recently the class \texttt{std::osyncstream} was added to the language, allowing
multi threaded programs allowing threads to write information block-wise to a
common stream without having to define separate streams receiving the
thread-specific information, eventually copying those streams to the
destination stream. Before using \texttt{osyncstream} objects the \index{syncstream: header file}\texttt{$<$syncstream$>$}
header file must be included.

The \texttt{osyncstream} class publicly inherits from \texttt{std::ostream},
initializing the \texttt{ostream} base class with a \texttt{std::syncbuf} stream buffer
(described in the next section), which performs the actual synchronization.

Information written to \texttt{osyncstream} objects can explicitly be copied to a
destination \texttt{ostream}, or is automatically copied to the destination
\texttt{ostream} by the \texttt{osyncstream's} destructor. Each thread may construct its
own \texttt{osyncstream} object, handling the block-wise copying of the
information it receives to the destination stream.

\textbf{Constructors}

\begin{itemize}
    \item \texttt{osyncstream\{ostream \&out\}} constructs an \texttt{osyncstream} object
        eventually writing the information it receives to \texttt{out}. Below,
        \texttt{out} is called the \emph{destination stream};
    \item \texttt{osyncstream\{osyncstream \&\&tmp\}} the move constructor is available;
    \end{itemize}

The default- and copy-constructors are not available.

\textbf{Member functions}

In addition to the members inherited from \texttt{std::ostream} (like the
\texttt{rdbuf} member returing a pointer to the object's \texttt{syncbuf} (described in
the next section)) the class \texttt{osyncstream} offers these members:
    \begin{itemize}
    \item \index{get\_wrapped}\texttt{get\_wrapped}, returning a pointer to the destination stream's stream
        buffer;
    \item \index{emit}\texttt{emit}, copies the received information as a block to the destination
        stream.
    \end{itemize}

The following program illustrates how \texttt{osyncstream} objects can be used.
    \begin{verbatim}
 1: #include <iostream>
 2: #include <syncstream>
 3: #include <string>
 4: #include <thread>
 5: 
 6: using namespace std;
 7: 
 8: void fun(char const *label, size_t count)
 9: {
10:     osyncstream out(cout);
11: 
12:     for (size_t idx = 0; idx != count; ++idx)
13:     {
14:         this_thread::sleep_for(1s);
15:         out << label << ": " << idx << " running...\n";
16:     }
17:     out << label << " ends\n";
18: }
19: 
20: int main(int argc, char **argv)
21: {
22:     cout << "the 1st arg specifies the #iterators "
23:             "using 3 iterations by default\n";
24: 
25:     size_t count = argc > 1 ? stoul(argv[1]) : 3;
26: 
27:     thread thr1{ fun, "first", count };
28:     thread thr2{ fun, "second", count };
29: 
30:     thr1.join();
31:     thr2.join();
32: }
\end{verbatim}
\begin{itemize}
    \item  The function \texttt{fun} (line 8) is called by \texttt{main} from two threads
        (lines 27, 28);
    \item  It defines an \texttt{osyncstream out} and, using short one-second pauses,
        writes some lines of text to \texttt{out} (lines 14, 15);
    \item  Just before leaving \texttt{fun} the local \texttt{out} content is written
        as a block to \texttt{cout} (line 18). Writing \texttt{out's} content to
        \texttt{cout} can also explicitly be requested by calling \texttt{out.emit()}.
    \end{itemize}

\subsection{The `std::syncbuf' streambuf}
    \typeout{Original Yodl file: threading/syncbuf}The \texttt{osyncstream} stream in fact is only a wrapper of \texttt{ostream}, using a
\texttt{syncbuf} as its stream buffer. The \texttt{std::syncbuf} handles the actual
synchronization. In order to use the \texttt{syncbuf} stream buffer the
\index{syncstream: header file}\texttt{$<$syncstream$>$} header file must be included.

A \texttt{syncbuf} stream buffer collects the information it receives from an
\texttt{ostream} in an internal buffer, and its destructor and \texttt{emit} member 
flush its buffer as a block to its destination stream.

\textbf{Constructors}

\begin{itemize}
    \item \texttt{syncbuf()}, the default constructor, constructs a \texttt{syncbuf} object
        with its \texttt{emit-on-sync} policy (see below) set to \texttt{false};

\item \texttt{explicit syncbuf(streambuf $*$destbuf)} constructs a \texttt{std::syncbuf}
        with its emit-on-sync policy set to \texttt{false}, using \texttt{destbuf} as
        the destination stream's \texttt{streambuf};

\item \texttt{syncbuf(syncbuf \&\&rhs)}, the move constructor, moves the content of
        \texttt{rhs} to the constructed \texttt{syncbuf}.
    \end{itemize}

\textbf{Member functions}

In addition to the members inherited from \texttt{std::streambuf} the class
\texttt{syncbuf} offers these members: 
    \begin{itemize}
    \item \index{get\_wrapped}\texttt{get\_wrapped}, returning a pointer to the destination stream's stream
        buffer;
    \item \index{emit}\texttt{emit}, copies the received information as a block to the destination
        stream;
    \item \index{set\_emit\_on\_sync}\texttt{void set\_emit\_on\_sync(bool how)} changes the
        current emit-on-sync policy. By default \texttt{how == false} flushing its
        internal buffer to the destination's stream buffer. When \texttt{how ==
        true} the internal buffer is always immediately flushed;
    \end{itemize}

\subsection{Multi-threaded compilations using `osyncstream'}
    \typeout{Original Yodl file: threading/osynccompile}Section \ref{MULTICOMP} describes the construction of a multi-threaded program
performing compilations. In that program separate threads were used for the 
\emph{workers}, who push their results on a results-queue. At the end of the
program the function \texttt{results} processes the queued results by showing the
names of the successfully compiled source files, and (if a compilation failed)
the name and error messages of the first source whose compilation failed.

The results-queue was used to store the results in a retrievable data
structure, using a mutex to ensure that the workers cannot simultaneously
push results on the results-queue.

Using \texttt{osyncstream} objects the results-queue and its mutexed protection
scheme is no longer required (the sources of the modified program are
available in the \textbf{C++} Annotations' directory
\texttt{yo/threading/examples/osyncmulticompile}). 

Instead of using a results-queue the program uses a single destination stream
\texttt{fstream g\_out\{ "/tmp/out", ios::trunc \textbar{} ios::in \textbar{} ios::out \}}, and its
\texttt{compile} function defines a local a \texttt{osyncstream} object, ensuring that
its output is sent as a block to \texttt{g\_out}:
        \begin{verbatim}
     1: void compile(string const &line)
     2: {
     3:     if (g_done.load())
     4:         return;
     5: 
     6:     string command("/usr/bin/g++ -Wall -c " + line);
     7: 
     8:     CmdFork cmdFork(command);
     9:     cmdFork.fork();
    10: 
    11:     int exitValue = cmdFork.childExit();
    12: 
    13:     osyncstream out(g_out);
    14:     out << exitValue << ' ' << line << '\n';
    15: 
    16:     if (exitValue != 0)
    17:     {
    18:         out << cmdFork.childOutput() << '\n' << g_marker << '\n';
    19:         g_done = true;
    20:     }
    21:     // out.emit();          // handled by out's destructor
    22: }
\end{verbatim}
\begin{itemize}
    \item  at line 13 the \texttt{osyncstream out} object is defined, and the results
        of the compilation are written to \texttt{out} at lines 14 and 18;
    \item  at line 14 the result of the compilation followed by the name of the
        source file is inserted into \texttt{out};
    \item  if a compilation fails then, at line 18, the compiler's error
        messages are inserted into \texttt{out} terminated by a marker,
        used by \texttt{results} (see below), to recognize the end of the error
        messages.
    \end{itemize}

Since the results of the compilation are no longer transferred to another
thread, there's no need for defining a \texttt{shared\_future$<$Result$>$}. In fact,
since \texttt{compile} handles the results of a compilation itself, it defines
return type \texttt{void} and the \texttt{packaged\_task} itself doesn't return anything
either. Therefore the \texttt{class Task} doesn't need a \texttt{result()} member
anymore. Instead, its function-call operator, having completed its task, calls
the task's \texttt{get\_future} so exceptions that might have been generated by
the \texttt{packaged\_tasks} are properly retrieved. Here's the simplified \texttt{class
Task}:
        \begin{verbatim}
    using PackagedTask = packaged_task<void (string const &fname)>;
    
    class Task
    {
        string d_command;
        PackagedTask d_task;
    
        public:
            Task()  = default;
    
            Task(string const &command, PackagedTask &&tmp)
            :
                d_command(command),
                d_task(move(tmp))
            {}
    
            void operator()()
            {
                d_task(d_command);
                d_task.get_future();    // handles potential exceptions
            }
    };
\end{verbatim}
At the end of \texttt{main} the function \texttt{results} is called:
        \begin{verbatim}
     1: void results()
     2: {
     3:     g_out.seekg(0);
     4: 
     5:     int value;
     6:     string line;
     7:     string errorDisplay;
     8: 
     9:     while (g_out >> value >> line)      // process g_out's content
    10:     {
    11:         g_out.ignore(100, '\n');
    12: 
    13:         if (value == 0)                 // no error: show the source file
    14:         {
    15:             cerr << line << '\n';
    16:             continue;
    17:         }
    18:                                         // at compilation errors:
    19:         if (not errorDisplay.empty())   // after the 1st error: skip
    20:         {
    21:             do
    22:             {
    23:                 getline(g_out, line);
    24:             }
    25:             while (line != g_marker);
    26: 
    27:             continue;
    28:         }
    29:                                         // first compilation error:
    30:         errorDisplay = line + '\n';     // keep the the name of the source
    31:         while (true)                    // and its error messages
    32:         {
    33:             getline(g_out, line);
    34: 
    35:             if (line == g_marker)
    36:                 break;
    37: 
    38:             errorDisplay += line + '\n';
    39:         }
    40:     }
    41: 
    42:     cerr << errorDisplay;               // eventually insert the error-info
    43: }                                       // (if any)
\end{verbatim}
\begin{itemize}
    \item  Each compilation starts with a compilation result and a source
        name. These are extracted in the \texttt{while} condition at line 9.
    \item  If the compilation was successful (line 13) the source's name is
        displayed.
    \item  If not, only the info of the first failed compilation is displayed
        (\emph{all} failed compilation messages could of course also be
        displayed, but this program only shows the messages of the first
        encountered failing compilation). If a compilation has already been
        encountered then the next error messages are ignored (lines 19 thru
        28).
    \item  The info of the first encountered compilation error is collected in
        \texttt{errorDisplay} (lines 30 thru 39).
    \item  Once \texttt{g\_out} has completely been read \texttt{errorDisplay} is displayed
        (line 42), which is either empty or contains the error messages of the
        first encountered compilation failure.
    \end{itemize}


\cleardoublepage\chapter{Function and Variable Templates}\label{TEMPLATES}
\typeout{Original Yodl file: functiontemplates}
\typeout{Original Yodl file: functiontemplates/intro}\textbf{C++} supports syntactic constructs allowing programmers to define and use
completely general (or abstract) functions or classes, based on generic types
and/or (possibly inferred) constant values. In the chapters on abstract
containers (chapter \ref{CONTAINERS}) and the \texttt{STL} (chapter \ref{STL}) we've
already used these constructs, commonly known as the
    \index{template mechanism}\emph{template mechanism}.

The template mechanism allows us to specify classes and algorithms, fairly
independently of the actual types for which the templates are eventually going
to be used. Whenever the template is used, the compiler generates code that is
tailored to the particular data type(s) used with the template. This code is
generated at \index{compile-time}compile-time from the template's definition. The piece of
generated code is called an \index{instantiation}\emph{instantiation} of the template.

In this chapter the syntactic peculiarities of templates are covered.  The
notions of \emph{template type parameter}, \emph{template non-type parameter}, and
\index{function template}\emph{function template} are introduced and several examples of templates are
provided (both in this chapter and in chapter \ref{CONCRETE}).  Template
\emph{classes} are covered in chapter \ref{TEMPCLASS}. For good reasons variadic
functions 
    \index{function: variadic}\index{variadic function} 
 are deprecated in \textbf{C++}. However, \emph{variadic templates} tell us a
completely different story, and variadic templates are perfectly
acceptable. Both function- and class-templates can be defined as variadic
templates. Both forms are covered in section \ref{VARIADIC}.

Templates already offered by the language include the abstract containers
(cf. chapter \ref{CONTAINERS}); the \texttt{string} (cf. chapter \ref{String});
streams (cf. chapter \ref{IOStreams}); and the generic algorithms (cf. chapter
\ref{GENERIC}). So, templates play a central role in present-day \textbf{C++}, and
should not be considered an esoteric feature of the language.

Templates should be approached somewhat similarly as generic algorithms:
they're a \emph{way of life}; a \textbf{C++} software engineer should actively look
for opportunities to use them.  Initially, templates may appear to be rather
complex and you might be tempted to turn your back on them. However, over time
their strengths and benefits are more and more appreciated. Eventually you'll
be able to recognize opportunities for using templates. That's the time where
your efforts should no longer focus on constructing ordinary functions
 \index{ordinary function} and classes \index{ordinary class} (i.e., functions or
classes that are not templates), but on constructing templates.

This chapter starts by introducing \emph{function templates}. The emphasis is on
the required syntax. This chapter lays the foundation upon which the other
chapters about templates are built.

\section{Defining function templates}\label{TEMPFUNDEF}
\typeout{Original Yodl file: functiontemplates/definitions}A \index{function template}function template's definition is very similar to the definition of
a normal function. A function template has a function head, a function body, a
return type, possibly overloaded definitions, etc.. However, different from
ordinary functions, function templates always use one or more
 \index{formal type}\emph{formal types}: types for which almost any existing
(class or primitive) type could be used. Let's have a look at a simple
example. The following function \texttt{add} expects two \texttt{Type} arguments and
returns their sum:
        \begin{verbatim}
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
Note how closely the above function's definition follows its description.
It receives two arguments, and returns its sum. Now consider what would happen
if we defined this function for, e.g., \texttt{int} values. We would write:
        \begin{verbatim}
    int add(int const &lhs, int const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
So far, so good. However, were we to add two doubles, we would overload
this function:
        \begin{verbatim}
    double add(double const &lhs, double const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
There is no end to the number of overloaded versions we might be forced to
construct: an overloaded version for \texttt{string}, for \texttt{size\_t}, for .... In
general, we would need an overloaded version for every type supporting
\texttt{operator+} and a copy constructor. All these overloaded versions of
basically the same function are required because of the strongly typed nature
of \textbf{C++}. Because of this, a truly generic function cannot be constructed
without resorting to the \index{template mechanism}template mechanism.

Fortunately, we've already seen an important part of a template
function. Our initial function \texttt{add} actually is an implementation of such a
function although it isn't a full template definition yet. If we gave the
first \texttt{add} function to the compiler, it would produce an error message
like:
        \begin{verbatim}
    error: `Type' was not declared in this scope
    error: parse error before `const'
\end{verbatim}
And rightly so, as we failed to define \texttt{Type}. The error is prevented
when we change \texttt{add} into a full template definition. To do this, we look
at the function's implementation and decide that \texttt{Type} is actually a
\emph{formal} typename. Comparing it to the alternate implementations, it is
clear that we could have changed \texttt{Type} into \texttt{int} to get the first
implementation, and into \texttt{double} to get the second.

The full template definition allows for this formal nature of the
\texttt{Type} typename. Using the keyword \texttt{template}, we prefix one line to
our initial definition, obtaining the following function template
definition:
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
    In this definition we distinguish:
    \begin{itemize}
    \item  The keyword \index{template}\texttt{template}, starting a template definition or
declaration.
    \item  The angle bracket enclosed list following \texttt{template}. This is a
list containing one or more comma-separated elements. This angle bracket
enclosed list is called the
 \index{template parameter list}\emph{template parameter list}. Template parameter lists using multiple
elements could look like this:
        \begin{verbatim}
    typename Type1, typename Type2
\end{verbatim}
\item  Inside the template parameter list we find the \index{formal type}\emph{formal type} name
\texttt{Type}. It is a formal type name, comparable to a formal parameter name in a
function's definition. Up to now we've only encountered formal variable names
with functions. The \emph{types} of the parameters were always known by the time
the function was defined. Templates escalate the notion of formal names one
step further up the ladder. Templates allow type names to be formalized,
rather than just the variable names themselves. The fact that \texttt{Type} is a
formal type name is indicated by the keyword \texttt{typename}, prefixed to
\texttt{Type} in the template parameter list. A formal type name like \texttt{Type} is
also called a \index{template type parameter}\emph{template type parameter}. Template non-type parameters also
exist, and are shortly introduced.

Other texts on \textbf{C++} sometimes use the keyword \index{class}\texttt{class} where we use
\index{class vs. typename} \texttt{typename}. So, in other texts template definitions
might start with a line like:
        \begin{verbatim}
    template <class Type>
\end{verbatim}
In the \textbf{C++} Annotations the use of \texttt{typename} over \texttt{class} is preferred,
reasoning that a template type parameter is, after all, a type name (some
authors prefer \texttt{class} over \texttt{typename}; in the end it's a matter of
taste).
    \item  The \texttt{template} keyword and the template parameter list is called
the \index{template header}template header.
    \item  The function head: it is like a normal function head, albeit that the
template's type parameters must be used in its parameter list. When the
function is eventually called using actual arguments having actual types,
these actual types are used by the compiler to infer which version (i.e.,
overload to fit the actual argument types) of the function template must be
used. At the point where the function is called the compiler creates the
function that is called, a process called \index{instantiation}\emph{instantiation}. The function
head may also use a formal type to specify its return value. This feature was
actually used in the \texttt{add} template definition.
    \item  The function parameters are specified as \texttt{Type const \&}
parameters. This has the usual meaning: the parameters are references to
\texttt{Type} objects or values that will not be modified by the function.
    \item  The function body is like a normal function body. In the body the
formal type names may be used to define or declare variables, which may then
be used as any other local variable. But some restrictions apply. Looking at
\texttt{add}'s body, it is clear that \texttt{operator+} is used, as well as a copy
constructor, as the function returns a value. This allows us to formulate the
following restrictions for the formal type \texttt{Type} as used by our \texttt{add}
function template:
        \begin{itemize}
        \item  \texttt{Type} should support \texttt{operator+}
        \item  \texttt{Type} should support a copy constructor
        \end{itemize}
    Consequently, while \texttt{Type} could be a \texttt{string}, it could never be
an \texttt{ostream}, as neither \texttt{operator+} nor the copy constructor are
available for streams.
    \end{itemize}
    Normal scope rules and identifier visibility rules apply to templates.
Within the template definition's scope formal type names overrule identically
named identifiers of broader scopes.

\subsection{Considerations regarding template parameters}
    \typeout{Original Yodl file: functiontemplates/considerations}We've managed to design our first function template:
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
    Look again at \texttt{add}'s parameters.  By specifying \texttt{Type const \&}
rather than \texttt{Type} superfluous copying is prevented, at the same time
allowing values of primitive types to be passed as arguments to the
function. So, when \texttt{add(3, 4)} is called, \texttt{int\{4\}} is assigned to
\texttt{Type const \&rhs}. In general, function parameters should be defined as
\texttt{Type const \&} to prevent unnecessary copying. The compiler is smart enough
to handle `references to references' in this case, which is something the
language normally does not support. For example, consider the following
\texttt{main} function (here and in the following simple examples it is assumed
that the template and the required headers and namespace declarations have
been provided):
        \begin{verbatim}
    int main()
    {
        size_t const &var = size_t{ 4 };
        cout << add(var, var) << '\n';
    }
\end{verbatim}
Here \texttt{var} is a reference to a constant \texttt{size\_t}. It is passed as
argument to \texttt{add}, thereby initializing \texttt{lhs} and \texttt{rhs} as \texttt{Type
const \&} to \texttt{size\_t const \&} values. The compiler interprets \texttt{Type} as
\texttt{size\_t}. Alternatively, the parameters might have been specified using
\texttt{Type \&}, rather than \texttt{Type const \&}. The disadvantage of this (non-const)
specification being that temporary values cannot be passed to the function
anymore. The following therefore fails to compile:
        \begin{verbatim}
    int main()
    {
        cout << add(string{ "a" }, string{ "b" }) << '\n';
    }
\end{verbatim}
Here, a \texttt{string const \&} cannot be used to initialize a \texttt{string \&}.
Had \texttt{add} defined \texttt{Type \&\&} parameters then the above program would have
compiled just fine. In addition the following example correctly compiles as
the compiler decides that \texttt{Type} apparently is a \texttt{string const}:
        \begin{verbatim}
    int main()
    {
        string const &s = string{ "a" };
        cout << add(s, s) << '\n';
    }
\end{verbatim}
What can we deduce from these examples?
    \begin{itemize}
    \item  In general, function parameters should be specified as \texttt{Type const
\&} parameters to prevent unnecessary copying.
    \item  The template mechanism is fairly flexible.  Formal types are
interpreted as plain types, const types, pointer types, etc., depending on the
actually provided types. The \index{rule of thumb}rule of thumb is that the formal type is used
as a generic mask for the actual type, with the formal type name covering
whatever part of the actual type must be covered. Some examples, assuming the
parameter is defined as \texttt{Type const \&}:

\begin{center}
        
        \begin{tabular}{ll}

        \hline

        

            \textbf{Provided argument:} &  \textbf{Actually used Type:}
         \\

        \hline

        

            \texttt{size\_t const} &  \texttt{size\_t}
         \\

        

            \texttt{size\_t} &  \texttt{size\_t}
         \\

        

            \texttt{size\_t $*$} &  \texttt{size\_t $*$}
         \\

        

            \texttt{size\_t const $*$} &  \texttt{size\_t const $*$}
         \\

        \hline

        
\end{tabular}
            \end{center}
    \end{itemize}

As a second example of a function template, consider the following
function template:
        \begin{verbatim}
    template <typename Type, size_t Size>
    Type sum(Type const (&array)[Size])
    {
        Type tp{};  // note: the default constructor must exist.

        for (size_t idx = 0; idx < Size; idx++)
            tp += array[idx];

        return tp;
    }
\end{verbatim}
This template definition introduces the following new concepts and
features:
    \begin{itemize}
    \item  The \index{template parameter list}\emph{template parameter list}. This template parameter list has
two elements. The first element is a well-known template type parameter, but
the second element has a very specific type: a \texttt{size\_t}. Template parameters
of specific (i.e., non-formal) types used in template parameter lists are
called
 \index{template non-type parameter}\emph{template non-type parameters}.
    A template non-type parameter defines the type of a
 \index{constant expression}constant expression, which must be known by the time the template is
instantiated and which is specified in terms of existing types, such as a
\texttt{size\_t}.
        \item  Looking at the function's head, we see one parameter:
        \begin{verbatim}
Type const (&array)[Size]
\end{verbatim}
This parameter defines \texttt{array} as a reference to an array having
\texttt{Size} elements of type \texttt{Type} that may not be modified.
    \item  In the parameter definition, both \texttt{Type} and \texttt{Size} are
used. \texttt{Type} is of course the template's type parameter \texttt{Type}, but
\texttt{Size} is also a template parameter. It is a \texttt{size\_t}, whose value must be
inferable by the compiler when it compiles an actual call of the \texttt{sum}
function template. Consequently, \texttt{Size} must be a \texttt{const} value. Such a
constant expression is called a \emph{template non-type parameter}, and its type
is named in the template's parameter list.
    \item  When the function template is called, the compiler must be able to
infer not only \texttt{Type}'s concrete value, but also \texttt{Size}'s value. Since the
function \texttt{sum} only has one parameter, the compiler is only able to infer
\texttt{Size}'s value from the function's actual argument. It can do so if the
provided argument is an array (of known and fixed size) rather than a pointer
to \texttt{Type} elements. So, in the following \texttt{main} function the first
statement will compile correctly but the second statement will not:
    \begin{verbatim}
int main()
{
    int values[5];
    int *ip = values;

    cout << sum(values) << '\n';    // compiles OK
    cout << sum(ip) << '\n';        // won't compile
}
\end{verbatim}
\item  Inside the function's body the definition \texttt{Type tp\{\}} is used
to define and initialize \texttt{tp} to a default value. Note here that no fixed
value (like 0) is used. Also, be careful not to use \texttt{Type tp()}, as this is
a \emph{declaration} of a function \texttt{tp}, expecting no arguments, and returning
a \texttt{Type}. Generally, when it is required to explicitly initialize a value
the empty curly braces should be used. The advantage of explicitly calling the
type's constructor is primarily encountered when \texttt{Type} is a basic
type. E.g., if \texttt{Type} is an \texttt{int} then \texttt{Type tp\{\}} initializes \texttt{tp} to
zero, whereas \texttt{Type tp} results in \texttt{tp} having an undefined value.
 \index{template type: initialization}
    But all types, even the primitive types, support default constructors
(some classes may choose not to implement a default constructor, or to make it
inaccessible; but most do offer default constructors). The default constructor
    \index{constructor: primitive type} of primitive types initializes their
variables to 0 (or \texttt{false}). Furthermore, the statement \texttt{Type tp = Type()}
is a true initialization: \texttt{tp} is initialized by \texttt{Type}'s default
constructor, rather than using \texttt{Type}'s copy constructor to assign
\texttt{Type}'s copy to \texttt{tp}.

It's interesting to note (although not directly related to the
current topic) that the syntactic construction \texttt{Type tp(Type())} \emph{cannot}
be used, even though it also looks like a proper initialization. Usually an
initializing argument can be provided to an object's definition, like
\texttt{string s("hello")}. Why, then, is \texttt{Type tp = Type()} accepted, whereas
\texttt{Type tp(Type())} isn't?  When \texttt{Type tp(Type())} is used it won't result
in an error message. So we don't immediately detect that it's \emph{not} a
\texttt{Type} object's default initialization. Instead, the compiler starts
generating error messages once \texttt{tp} is used. This is caused by the fact that
in \textbf{C++} (and in \textbf{C} alike) the compiler does its best to recognize a
function or
 \index{C++: function prevalence rule} function pointer whenever possible: the
\index{function prevalence rule}\emph{function prevalence rule}.  According to this rule \texttt{Type()} is (because
of the pair of parentheses) interpreted as a \emph{pointer to a function}
expecting no arguments; returning a \texttt{Type}. The compiler will do so unless
it clearly isn't possible to do so. In the initialization \texttt{Type tp = Type()}
it \emph{can't} see a pointer to a function as a \texttt{Type} object cannot be given
the value of a function pointer (remember: \texttt{Type()} is interpreted as
\texttt{Type ($*$)()} whenever possible). But in \texttt{Type tp(Type())} it \emph{can} use
the pointer interpretation: \texttt{tp} is now \emph{declared} as a \emph{function}
expecting a pointer to a function returning a \texttt{Type}, with \texttt{tp} itself
also returning a \texttt{Type}. E.g., \texttt{tp} could have been defined as:
    \begin{verbatim}
Type tp(Type (*funPtr)())
{
    return (*funPtr)();
}
\end{verbatim}
\item  Comparable to the first function template, \texttt{sum} also assumes the
existence of certain public members in \texttt{Type}'s class. This time
\texttt{operator+=} and \texttt{Type}'s copy constructor.
    \end{itemize}

Like class definitions, template definitions should not contain \texttt{using}
        \index{templates vs. using}\index{using vs. templates}
    directives or declarations: the template might be used in a situation
where such a directive overrides the programmer's intentions: ambiguities or
other conflicts may result from the template's author and the programmer using
different \texttt{using} directives (E.g, a \texttt{cout} variable defined in the
\texttt{std} namespace and in the programmer's own namespace). Instead, within
template definitions only \index{fully qualified name}\index{name: fully qualified}
fully qualified names, including all required namespace specifications should
be used.

\subsection{Auto and decltype}\label{AUTODECL}
    \typeout{Original Yodl file: functiontemplates/autodecl}    In section \ref{AUTO} the \texttt{auto} keyword was introduced. The keyword
\texttt{decltype}, related to \texttt{auto}, shows somewhat different behavior.  This
section concentrates on \texttt{decltype}. Different from \texttt{auto}, which requires
no further specifications, \texttt{decltype} is always followed by an
expression between parentheses (e.g., \texttt{decltype(variable)}).

As an initial illustration, assume we have a function defining a parameter
\texttt{std::string const \&text}. Inside the function we may encounter the
following two definitions:
        \begin{verbatim}
    auto scratch1{text};
    decltype(text) scratch2 = text;
\end{verbatim}
With \texttt{auto} the compiler deduces a plain type, so \texttt{scratch1} is a
\texttt{string}, and copy construction is used to initialize it from
`\texttt{text}'. 

Now consider \texttt{decltype}: \texttt{decltype} determines \texttt{text's} type:
\texttt{string const \&}, which is thereupon used as \texttt{scratch2's} type: \texttt{string
const \&scratch2}, referring to whatever string \texttt{text} refers to. This is
\texttt{decltype's} standard behavior: when provided with a variable's name,
it is replaced by that variable's type.

Alternatively, an expression can be specified when using \texttt{decltype}. Of
course, a variable is an expression by itself, but in the context of
\texttt{decltype} we define an `expression' as any expression that is more complex
than just a plain variable specification. But it may be as simple as
\texttt{(variable)}: the name of a variable between parentheses.

When an expression is used, the compiler determines whether a reference could
be appended to the expression's type. If so, \texttt{decltype(expression)} is
replaced by the type of such an lvalue reference (so you get
\texttt{expression-type \&}). If not, \texttt{decltype(expression)} is replaced by the
expression's plain type.

Here are some examples:
    \begin{verbatim}
    int *ptr;
    decltype(ptr) ref = ptr;
        // decltype's argument is a plain variable, and so
        // ptr's type is used: int *ref = ptr.
        // decltype(ptr) is replaced by int *.
        // (resulting in two warnings about not-initialized/used variables).

    int *ptr;
    decltype( (ptr) ) ref = ptr;
        // decltype's argument is an expression, and so
        // int *&ref = ptr is used.
        // decltype( (ptr) )  is replaced by int *&.

    int value;
    decltype(value + value) var = value + value;
        // decltype's argument is an expression, and so the compiler tries
        // to replace decltype(...) by int & (int &var = value + value)
        // since value + value is a temporary, var's type cannot be int &
        // and so decltype(...) is replaced by int 
        // (i.e., value + value's type) 
    
    string lines[20];
    decltype(lines[0]) ref = lines[6];
        // decltype's argument is an expression, so
        // string &ref = lines[6] is used.
        // decltype(...) is replaced by string &

    string &&strRef = string{};
    decltype(strRef) ref = std::move(strRef);
        // decltype's argument is a plain variable so the variable's
        // type is used: string &&ref = std::move(strRef).
        // decltype(...) is replaced by string &&

    string &&strRef2 = string{}
    decltype((strRef2)) ref2 = strRef2;
        // decltype's argument is an expression, so
        // string && &ref = strRef is used. This automatically becomes
        // string &ref = strRef which is OK
        // decltype is replaced by string &.
\end{verbatim}
In addition to this, \index{decltype(auto)}\texttt{decltype(auto)} specifications can be used, in
which case \texttt{decltype's} rules are applied to \texttt{auto}. So, \texttt{auto} is used
to determine the type of the initializing expression. Then, if the
initializing expression is a mere variable, then the expression's type is
used. Otherwise, if a reference can be added to the expression's type then
\texttt{decltype(auto)} is replaced by a reference to the expression's type. Here
are some examples:
    \begin{verbatim}
    int *ptr;
    decltype(auto) ptr2 = ptr;
        // auto produces ptr's type: int *, ptr is a plain variable, so
        // decltype(auto) is replaced by int *

    int value;
    decltype(auto) ret = value + value;
        // auto produces int, value + value is an expression, so int & is
        // attempted. However, value + value cannot be assigned to a 
        // reference so the expression's type is used:
        // decltype(auto) is replaced by int
    
    string lines[20];
    decltype(auto) line = lines[0];
        // auto produces string, lines[0] is an expression, so string & is
        // attempted. string &line = lines[0] is OK, so
        // decltype(auto) is replaced by string &

    decltype(auto) ref = string{} 
        // auto produces string, string{} is an expression, so string & is
        // attempted. However, string &ref = string{} is not a valid
        // initialization, so string itself is used:
        // decltype(auto) is replaced by string
\end{verbatim}
In practice, the \texttt{decltype(auto)} form is most often encountered with
function templates to define return types. Have a look at the following
struct definition (not using function templates, but illustrating the workings
of \texttt{decltype(auto)}):
        \begin{verbatim}
    struct Data
    {
        vector<string> d_vs;
        string *d_val = new string[10];
    
        Data()
        :
            d_vs(1)
        {}
    
        auto autoFun() const
        {
            return d_val[0];
        }

        decltype(auto) declArr() const       
        {
            return d_val[0];
        }

        decltype(auto) declVect() const
        {
            return d_vs[0];
        }
    };
\end{verbatim}
\begin{itemize}
\item  The member \texttt{autoFun} returns \texttt{auto}. Since \texttt{d\_val{[}0{]}} is passed to
    \texttt{auto}, \texttt{auto} is deducing as \texttt{string}, and the function's return
    type is \texttt{string};

\item  The member \texttt{declArr} returns \texttt{decltype(auto)}. Since \texttt{d\_val{[}0{]}}
    is an expression, representing a \texttt{string}, \texttt{decltype(auto)} is deduced
    as \texttt{string \&}, which becomes the function's return type.

\item  The member \texttt{declVect} returns \texttt{decltype(auto)}. Since \texttt{d\_vs{[}0{]}}
    is an expression, representing \texttt{string}, \texttt{decltype(auto)} is deduced
    as \texttt{string \&}. However, since \texttt{declVect} is also
    a const member, this reference should  be a \texttt{string const \&}. This is
    recognized by \texttt{decltype(auto)}, and so the function's return type
    becomes \texttt{string const \&}.
\end{itemize}

If you're wondering why there's no \texttt{const} in \texttt{declArr's} return type
while there is one in \texttt{declVect's} return type then have a look at \texttt{d\_vs}
and \texttt{d\_val}: both are constant in the context of their functions, but
\texttt{d\_val}, so a \texttt{const $*$}, points to non-const \texttt{string} objects. So,
\texttt{declArr} does \emph{not} have to return a \texttt{string const \&}, whereas
\texttt{declVect} \emph{should} return a \texttt{string const \&}.

\subsubsection{declval}
        \typeout{Original Yodl file: functiontemplates/declval}The keyword \texttt{decltype} is a tool for determining the type of an
expression. To use it an expression to which \texttt{decltype} is applied must be
available.  But what if a function template defines a \texttt{typename Class}
template parameter and the function template should use the return type of the
function \texttt{Class::fun()}? Since two classes may define members \texttt{fun} having
different return types, the return type to use is not immediately available.

These kinds of problems are solved by using the function template
    \index{declval}\texttt{std::declval}, defined in the \index{utility: header file}\texttt{$<$utility$>$} header
file. This function template defines one template type parameter, and returns
an rvalue reference to an object of the template type parameter's class,
without actually creating a temporary object. But since an rvalue reference is
available, its \texttt{fun} function can be called, and the return type of \emph{that}
function can then be produced by \texttt{decltype}. There are no specific
requirements for the constructors of the class type that's passed to
\texttt{declval}. Specifically: it doesn't have to have a default or public
constructor (but access rights \emph{are} used). Consider this 
function template:
        \begin{verbatim}
    template <typename Type>
    decltype(std::declval<Type>().fun()) value()
    {
        return 12.5;
    }
\end{verbatim}
The function \texttt{value's} return type is defined as the as yet unknown 
\texttt{Type::fun's} return type. 

By defining two structs, both having \texttt{fun} member functions \texttt{value's}
actual return type can now be returned. This is used in \texttt{main} where
respectively an \texttt{int} and a \texttt{double} is returned, resulting in the output
\texttt{12 12.5}:
        \begin{verbatim}
    struct Integral
    {
        int fun() const;            // implementation not required
    };
    
    struct Real
    {
        double fun() const;         // same.
    };
    
    int main()
    {
        std::cout << value<Integral>() << ' ' << value<Real>() << '\n';
    }
\end{verbatim}
\subsection{Late-specified return type}
    \typeout{Original Yodl file: functiontemplates/alternate}Traditional  \textbf{C++} requires function templates to specify their return type
or to specify the return type as a template type parameter. Consider the
following function:
        \begin{verbatim}
    int add(int lhs, int rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
The above function may be converted to a function template:
        \begin{verbatim}
    template <typename Lhs, typename Rhs>
    Lhs add(Lhs lhs, Rhs rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
Unfortunately, when the function template is called as
        \begin{verbatim}
    add(3, 3.4)
\end{verbatim}
the intended return type is probably a \texttt{double} rather than an
\texttt{int}. This can be solved by adding an additional template type parameter
specifying the return type but then  that type must explicitly be specified:
        \begin{verbatim}
    add<double>(3, 3.4);
\end{verbatim}
Using \index{decltype}\texttt{decltype} (cf. section \ref{AUTO}) to define the return type won't
work as \texttt{lhs} and \texttt{rhs} aren't known to the compiler by the time
\texttt{decltype} is used. Thus the next attempt to get rid of the additional
template type parameter fails to compile:
        \begin{verbatim}
    template <typename Lhs, typename Rhs>
    decltype(lhs + rhs) add(Lhs lhs, Rhs rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
The \texttt{decltype}-based definition of a function's return type may become
fairly complex. This complexity can be reduced by using the 
 \index{late-specified return type}\emph{late-specified return type} syntax that \emph{does} allow the use of
\texttt{decltype} to define a function's return type. It is primarily used with
function templates but it may also be used for ordinary (non-template)
functions:
        \begin{verbatim}
    template <typename Lhs, typename Rhs>
    auto add(Lhs lhs, Rhs rhs) -> decltype(lhs + rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
When this function is used in a statement like \texttt{cout $<$$<$ add(3, 3.4)} the
resulting value will be 6.4, which is most likely the intended result, rather
than 6. As an example how a late-specified return type may reduce the
complexity of a function's return type definition consider the following:
        \begin{verbatim}
    template <typename T, typename U>
    decltype((*(T*)0)+(*(U*)0)) add(T t, U u);
\end{verbatim}
Kind of hard to read? A term like \texttt{ ($*$(T$*$)0) } defines 0, using a \textbf{C}
    cast, as a pointer to type \texttt{T} and then dereferences the pointer,
    producing a value of type \texttt{T} (even though that value itself doesn't
    exist as a variable). Likewise for the second term that's used in the
    \texttt{decltype} expression. The resulting type is thereupon used as \texttt{add's}
    return type. 
    Using a late-specified return type we get the equivalent:
        \begin{verbatim}
    template <typename T, typename U>
    auto add(T t, U u) -> decltype(t+u);
\end{verbatim}
which most people consider easier to understand.

The expression specified with \texttt{decltype} does not necessarily use the
parameters \texttt{lhs} and \texttt{rhs} themselves. In the next function
definition \texttt{lhs.length} is used instead of \texttt{lhs} itself:
        \begin{verbatim}
    template <typename Class, typename Rhs>
    auto  add(Class lhs, Rhs rhs) -> decltype(lhs.length() + rhs)
    {
        return lhs.length() + rhs;
    }
\end{verbatim}
\emph{Any} variable visible at the time \texttt{decltype} is compiled can be used
in the \texttt{decltype} expression. It is also possible to
handle member selection through pointers to members. The following code aims
at specifying the address of a member function as \texttt{add}'s first argument and
then use its return value type to determine the function template's return
type. Here is an example:
        \begin{verbatim}
    std::string global{"hello world"};

    template <typename MEMBER, typename RHS>
    auto  add(MEMBER mem, RHS rhs) -> decltype((global.*mem)() + rhs)
    {
        return (global.*mem)() + rhs;
    }

    int main()
    {
        std::cout << add(&std::string::length, 3.4) << '\n'; // shows: 14.4
    }
\end{verbatim}
\section{Passing arguments by reference (reference wrappers)}\label{REFWRAP}
\typeout{Original Yodl file: functiontemplates/referencewrappers}Before using the reference wrappers discussed in this section the
\index{functional: header file}\texttt{$<$functional$>$} header file must be included.

Situations exist where the compiler is unable to infer that a reference rather
than a value is passed to a function template. In the following example the
function template  \texttt{outer} receives \texttt{int x} as its argument and the
compiler dutifully infers that \texttt{Type} is \texttt{int}:
        \begin{verbatim}
    template <typename Type>
    void outer(Type t)
    {
        t.x();
    }
    void useInt()
    {
        int arg;
        outer(arg);
    }
\end{verbatim}
    Compilation will of course fail (as \texttt{int} values don't have \texttt{x}
members) and the compiler nicely reports the inferred type, e.g.:
        \begin{verbatim}
    In function 'void outer(Type) [with Type = int]': ...
\end{verbatim}
Another type of error results from using \texttt{call} in the next example. Here,
\texttt{call} is a function template expecting a function-type argument. The
function that's passed to \texttt{call} is \texttt{sqrtArg}, defining a reference to a
\texttt{double}: the variable that's passed to \texttt{sqrtArg} is modified by
\texttt{sqrtArg}. 
        \begin{verbatim}
    void sqrtArg(double &arg)
    {
        arg = sqrt(arg);
    }
    template<typename Fun, typename Arg>
    void call(Fun fun, Arg arg)
    {
        fun(arg);
        cout << "In call: arg = " << arg << '\n';
    }
\end{verbatim}
    The first time \texttt{call} is used, \texttt{call(sqrtArg, value)} will not modify
\texttt{value}: the compiler infers \texttt{Arg} to be a \texttt{double} value, and hence
passes \texttt{value} by value to \texttt{call}, thus preventing \texttt{sqrtArg} to modify
\texttt{main's} variable.

To change \texttt{main's} variable \texttt{value} the compiler must be informed that
\texttt{value} must be passed by reference. Note that we do not want to 
define \texttt{call}'s template parameter as a reference parameter, 
as passing arguments by value might be appropriate in other situations.

In these situations the \index{ref(arg)}\texttt{ref(arg)} and \index{cref(arg)}\texttt{cref(arg)}
 \index{reference wrapper}\emph{reference wrappers} should be used. They accept an
argument and return their argument as a (const) reference-typed argument. To
actually change \texttt{value} it can be passed to \texttt{call} using \texttt{ref(value)} as
shown in the following \texttt{main} function:
        \begin{verbatim}
    int main()
    {
        double value = 3;
        call(sqrtArg, value);
        cout << "Passed value, returns: " << value << '\n';

        call(sqrtArg, ref(value));
        cout << "Passed ref(value), returns: " << value << '\n';
    }
    /*
        Displays:
            In call: arg = 1.73205
            Passed value, returns: 3
            In call: arg = 1.73205
            Passed ref(value), returns: 1.73205
    */
\end{verbatim}
\section{Using local and unnamed types as template arguments}
\typeout{Original Yodl file: functiontemplates/local}Usually, types have names. But an \index{anonymous type}\emph{anonymous type} may also be defined:
        \begin{verbatim}
    enum
    {
        V1,
        V2,
        V3
    };
\end{verbatim}
Here, the \texttt{enum} defines an \index{unnamed type} \emph{unnamed} or
        \index{type: anonymous, local}
    \index{anonymous type}\emph{anonymous type}.

When defining a function template, the compiler normally
deduces the types of its template type parameters from its arguments:
        \begin{verbatim}
    template <typename T>
    void fun(T &&t);

    fun(3);     // T is int
    fun('c');   // T is char
\end{verbatim}
The following, however, can also be used:
        \begin{verbatim}
    fun(V1);    // T is a value of the above enum type
\end{verbatim}
Within \texttt{fun} a \texttt{T} variable may be defined, even if it's an anonymous
type:
        \begin{verbatim}
    template <typename T>
    void fun(T &&t)
    {
        T var(t);
    }
\end{verbatim}
Values or objects of
        \index{local type}
    locally defined types may also be passed as arguments to function
templates. E.g.,
        \begin{verbatim}
    void definer()
    {
        struct Local
        {
            double  dVar;
            int     iVar;
        };
        Local local;            // using a local type

        fun(local);             // OK: T is 'Local'
    }
\end{verbatim}
\section{Template parameter deduction}\label{TEMPFUNARGS}
\typeout{Original Yodl file: functiontemplates/argumentdeduction}    In this section we concentrate on the process by which the compiler
deduces the actual types of the template type parameters. These types are
deduced when a function template is called using a process called
 \index{template parameter deduction}\emph{template parameter deduction}. As we've already seen, the compiler is
able to substitute a wide range of actual types for a single formal template
type parameter. Even so, not every thinkable conversion is possible. In
particular when a function has multiple parameters of the same template type
parameter, the compiler is very restrictive when determining what argument
types are actually accepted.

When the compiler deduces the actual types for template type parameters it
\emph{only} considers the types of the arguments that are actually
used. Neither local variables nor the function's return value is considered in
this process. This is understandable. When a function is called the compiler
is only certain about the types of the function template's arguments. At the
point of the call it definitely does not see the types of the function's local
variables. Also, the function's return value might not actually be used or may
be assigned to a variable of a subrange (or super-range) type of a deduced
template type parameter. So, in the following example, the compiler won't ever
be able to call \texttt{fun()}, as it won't be able to deduce the actual type for
the \texttt{Type} template type parameter.
        \begin{verbatim}
    template <typename Type>
    Type fun()              // can never be called as `fun()'
    {
        return Type{};
    }
\end{verbatim}
Although the compiler won't be able to handle a call to `\texttt{fun()}', it
\emph{is} possible to call \texttt{fun()} using an
 \index{type specification: explicit}\index{explicit type specification}explicit type specification. E.g.,
\texttt{fun$<$int$>$()} calls \texttt{fun}, instantiated for \texttt{int}. This is of course
\emph{not} the same as \emph{compiler} argument deduction.

In general, when a function has multiple parameters of identical template
type parameters, the actual types must be exactly the same. So, whereas
        \begin{verbatim}
    void binarg(double x, double y);
\end{verbatim}
may be called using an \texttt{int} and a \texttt{double}, with the \texttt{int} argument
silently being converted to a \texttt{double}, a similar function template cannot
be called using an \texttt{int} and \texttt{double} argument: the compiler won't by
itself promote \texttt{int} to \texttt{double} deciding that \texttt{Type} should be
\texttt{double}:
        \begin{verbatim}
    template <typename Type>
    void binarg(Type const &p1, Type const &p2)
    {}

    int main()
    {
        binarg(4, 4.5); // ?? won't compile: different actual types
    }
\end{verbatim}
What, then, are the transformations the compiler  applies when deducing
the actual types of template type parameters? It performs but three types
of
        \index{template: parameter type transformation}
    parameter type transformations and a fourth one to function template
non-type parameters. If it cannot deduce the actual types using these
transformations, the function template will not be considered. The
transformations performed by the compiler are:
    \begin{itemize}
    \item  \emph{lvalue transformations}, creating an \emph{rvalue} from an
\emph{lvalue};
    \item  \emph{qualification transformations}, inserting a \texttt{const} modifier to
a non-constant argument type;
    \item  \emph{transformation to a base class instantiated from a class template},
using a template base class when an argument of a template derived class type
was provided in the call.
    \item  Standard transformations for function template non-type
parameters. This isn't a template type parameter transformation, but it refers
to any remaining template non-type parameter of function templates. For these
function parameters the compiler performs any standard conversion it has
available (e.g., \texttt{int} to \texttt{size\_t}, \texttt{int} to \texttt{double}, etc.).
    \end{itemize}
    The purpose of the various template parameter type deduction
transformations is \emph{not} to match function arguments to function parameters,
but rather, having matched arguments to parameters, to determine the \emph{actual
types} of the various template type parameters.

\subsection{Lvalue transformations}
    \typeout{Original Yodl file: functiontemplates/lvalue}There are three types of \index{lvalue transformations}\emph{lvalue transformations}:
    \begin{itemize}
    \item  \textbf{lvalue-to-rvalue transformations.}
        \begin{quote}An \index{lvalue-to-rvalue transformation}lvalue-to-rvalue transformation is applied when an
\texttt{rvalue} is required, but an \texttt{lvalue} is provided.  This happens when a
variable is used as argument to a function specifying a \emph{value
parameter}. For example,
    \begin{verbatim}
template<typename Type>
Type negate(Type value)
{
    return -value;
}
int main()
{
    int x = 5;
    x = negate(x);  // lvalue (x) to rvalue (copies x)
}
\end{verbatim}
\end{quote}
    \item  \textbf{array-to-pointer transformations.}
        \begin{quote}An \index{array-to-pointer transformation}array-to-pointer transformation is applied when the name
of an array is assigned to a pointer variable. This is frequently used with
functions defining pointer parameters.  Such functions frequently receive
arrays as their arguments. The array's address is then assigned to the
pointer-parameter and its type is used to deduce the corresponding template
parameter's type. For example:
    \begin{verbatim}
template<typename Type>
Type sum(Type *tp, size_t n)
{
    return accumulate(tp, tp + n, Type());
}
int main()
{
    int x[10];
    sum(x, 10);
}
\end{verbatim}
In this example, the location of the array \texttt{x} is passed to \texttt{sum},
expecting a pointer to some type. Using the array-to-pointer transformation,
\texttt{x}'s address is considered a pointer value which is assigned to \texttt{tp},
deducing that \texttt{Type} is \texttt{int} in the process.
    \end{quote}
    \item  \textbf{function-to-pointer transformations.}
        \begin{quote}This transformation is most frequently used with function
templates defining a parameter which is a pointer to a function.  When calling
such a function the name of a function may be specified as its argument. The
address of the function is then assigned to the pointer-parameter, deducing
the template type parameter in the process. This is called a
    \index{function-to-pointer transformation}function-to-pointer transformation. For example:
        \begin{verbatim}
#include <cmath>

template<typename Type>
void call(Type (*fp)(Type), Type const &value)
{
    (*fp)(value);
}
int main()
{
    call(sqrt, 2.0);
}
\end{verbatim}
    In this example, the address of the \texttt{sqrt} function is passed to
\texttt{call}, expecting a pointer to a function returning a \texttt{Type} and expecting
a \texttt{Type} for its argument. Using the function-to-pointer transformation,
\texttt{sqrt}'s address is assigned to \texttt{fp}, deducing that \texttt{Type} is \texttt{double}
in the process (note that \texttt{sqrt} is the \emph{address} of a function, not a
variable that is a pointer to a function, hence the lvalue
transformation).

The argument \texttt{2.0} could not have been specified as \texttt{2} as there is no
\texttt{int sqrt(int)} prototype. Furthermore, the function's first parameter
specifies \texttt{Type ($*$fp)(Type)}, rather than \texttt{Type ($*$fp)(Type const \&)} as
might have been expected from our previous discussion about how to specify the
types of function template's parameters, preferring references over values.
However, \texttt{fp}'s argument \texttt{Type} is not a function template parameter, but
a parameter of the function \texttt{fp} points to. Since \texttt{sqrt} has prototype
\texttt{double sqrt(double)}, rather than \texttt{double sqrt(double const \&)},
\texttt{call}'s parameter \texttt{fp} \emph{must} be specified as \texttt{Type
($*$fp)(Type)}. It's that strict.
    \end{quote}
    \end{itemize}

\subsection{Qualification transformations}
    \typeout{Original Yodl file: functiontemplates/qualifications}A \index{qualification transformation}\emph{qualification transformation} adds \index{const}\texttt{const} or \index{volatile}\texttt{volatile}
qualifications to \emph{pointers}. This transformation is applied when the
function template's type parameter explicitly specifies \texttt{const} (or
\texttt{volatile}) but the function's argument isn't a \texttt{const} or \texttt{volatile}
entity. In that case \texttt{const} or \texttt{volatile} is provided by the compiler.
Subsequently the compiler deduces the template's type parameter. For example:
        \begin{verbatim}
    template<typename Type>
    Type negate(Type const &value)
    {
        return -value;
    }
    int main()
    {
        int x = 5;
        x = negate(x);
    }
\end{verbatim}
Here we see the function template's \texttt{Type const \&value} parameter: a
reference to a \texttt{const Type}. However, the argument isn't a \texttt{const int},
but an \texttt{int} that can be modified. Applying a qualification transformation,
the compiler adds \texttt{const} to \texttt{x}'s type, and so it matches \texttt{int const
x}.  This is then matched against \texttt{Type const \&value} allowing the compiler
to deduce that \texttt{Type} must be \texttt{int}.

\subsection{Transformation to a base class}
    \typeout{Original Yodl file: functiontemplates/baseclass}Although the \emph{construction} of class templates is the topic of chapter
\ref{TEMPCLASS}, we've already extensively \emph{used} class templates before. For
example, abstract containers (cf. chapter \ref{CONTAINERS}) are defined as
class templates.  Class templates can, like
 \index{ordinary class}\index{class: ordinary}
    ordinary classes, participate in the construction of class hierarchies.

In section \ref{DERIVEDTEMPCLASS} it is shown how a \index{class template}class template can
be derived from another class template.

As class template derivation remains to be covered, the following
discussion is necessarily somewhat premature. The reader may of course skip
briefly to section \ref{DERIVEDTEMPCLASS} returning back to this section
thereafter.

In this section it should be assumed, for the sake of argument, that a
class template \texttt{Vector} has somehow been derived from a \texttt{std::vector}.
Furthermore, assume that the following function template has been
constructed to sort a vector using some function object \texttt{obj}:
        \begin{verbatim}
    template <typename Type, typename Object>
    void sortVector(std::vector<Type> vect, Object const &obj)
    {
        sort(vect.begin(), vect.end(), obj);
    }
\end{verbatim}
To sort \texttt{std::vector$<$string$>$} objects case-insensitively, a \texttt{class
Caseless} could be constructed as follows:
        \begin{verbatim}
    class CaseLess
    {
        public:
            bool operator()(std::string const &before,
                            std::string const &after) const
            {
                return strcasecmp(before.c_str(), after.c_str()) < 0;
            }
    };
\end{verbatim}
Now various vectors may be sorted using \texttt{sortVector()}:
        \begin{verbatim}
    int main()
    {
        std::vector<string> vs;
        std::vector<int> vi;

        sortVector(vs, CaseLess());
        sortVector(vi, less<int>());
    }
\end{verbatim}
Applying the transformation
        \index{transformation to a base class}
        \index{class template: transformation to a base class}
    \emph{transformation to a base class instantiated from a class template}, the
function template \texttt{sortVector} may now also be used to sort \texttt{Vector}
objects. For example:
        \begin{verbatim}
    int main()
    {
        Vector<string> vs;      // `Vector' instead of `std::vector'
        Vector<int> vi;

        sortVector(vs, CaseLess());
        sortVector(vi, less<int>());
    }
\end{verbatim}
In this example, \texttt{Vector}s were passed as argument to
\texttt{sortVector}. Applying the transformation to a base class instantiated from
a class template, the compiler considers \texttt{Vector} to be a \texttt{std::vector}
enabling it to deduce the template's type parameter. A \texttt{std::string} for the
\texttt{Vector vs}, an \texttt{int} for \texttt{Vector vi}.

\subsection{The template parameter deduction algorithm}\label{PARDEDUCT}
    \typeout{Original Yodl file: functiontemplates/algorithm}    The compiler uses the following algorithm to deduce the actual types of
        \index{template type deduction} its template type parameters:
    \begin{itemize}
    \item  In turn, the function template's parameters are identified using the
arguments of the called function.
    \item  For each template parameter used in the function template's parameter
list, the template type parameter is associated with the corresponding
argument's type (e.g., \texttt{Type} is \texttt{int} if the argument is \texttt{int x}, and
the function's parameter is \texttt{Type \&value}).
    \item  While matching the argument types to the template type parameters,
the three allowed transformations (see section \ref{TEMPFUNARGS}) for template
type parameters are applied where necessary.
    \item  If identical template type parameters
        \index{template parameters: identical types}
    are used with multiple function parameters, the deduced template types
must exactly match. So, the next function template cannot be called with an
\texttt{int} and a \texttt{double} argument:
    \begin{verbatim}
template <typename Type>
Type add(Type const &lhs, Type const &rhs)
{
    return lhs + rhs;
}
\end{verbatim}
When calling this function template, two identical types must be used
(albeit that the three standard transformations are of course allowed). If the
template deduction mechanism does not come up with identical actual types for
identical template types, then the function template is not going to be
instantiated.
    \end{itemize}

\subsection{Template type contractions}\label{CONTRACTIONS}
    \typeout{Original Yodl file: functiontemplates/contractions}With function templates the combination of the types of template arguments and
template parameters shows some interesting contractions. What happens, for
example if a template type parameter is specified as an rvalue reference but
an lvalue reference argument type is provided?

In such cases the compiler performs type contractions. Doubling identical
reference types results in a simple contraction: the type is deduced to be a
single reference type. Example: if the template parameter type is specified as
a \texttt{Type \&\&} and the actual parameter is an \texttt{int \&\&} then \texttt{Type} is
deduced to be an \texttt{int}, rather than an \texttt{int \&\&}.

This is fairly intuitive. But what happens if the actual type is \texttt{int \&}?
There is no such thing as an \texttt{int \& \&\&param} and so the compiler contracts
the double reference by removing the rvalue reference, keeping the lvalue
reference. Here the following rules are applied:

\begin{quote}
    1. A function template parameter defined as an lvalue reference to
    a template's type parameter (e.g., \texttt{Type \&}) receiving an lvalue
    reference argument results in a single lvalue reference.

2. A function template parameter defined as an rvalue reference to a
    template's type parameter (e.g., \texttt{Type \&\&}) receiving any kind of
    reference argument uses the reference type of the argument.  \end{quote}
Examples:
    \begin{itemize}
    \item  When providing an \texttt{Actual \&} argument then \texttt{Type \&} becomes an
    \texttt{Actual \&} and \texttt{Type} is inferred as \texttt{Actual};

\item  When providing an \texttt{Actual \&} then \texttt{Type \&\&} becomes an
    \texttt{Actual \&} and \texttt{Type} is inferred as \texttt{Actual};

\item  When providing an \texttt{Actual \&\&} then \texttt{Type \&} also becomes
    \texttt{Actual \&}  and \texttt{Type} is inferred as \texttt{Actual};

\item  When providing an \texttt{Actual \&\&} then \texttt{Type \&\&}  becomes \texttt{Actual
    \&\&} and \texttt{Type} is inferred as \texttt{Actual};
    \end{itemize}

Let's look at a concrete example where contraction occurs. Consider the
following function template where a function parameter is defined as an rvalue
references to some template type parameter:
        \begin{verbatim}
    template <typename Type>
    void function(Type &&param)
    {
        callee(static_cast<Type &&>(param));
    }
\end{verbatim}
In this situation, when \texttt{function} is called with an (lvalue) argument of
type \texttt{TP \&} the template type parameter \texttt{Type} is deduced to be \texttt{Tp
\&}. Therefore, \texttt{Type \&\&param} is instantiated as \texttt{Tp \&param}, \texttt{Type}
becomes \texttt{Tp} and the rvalue reference is replaced by an lvalue reference.

Likewise, when \texttt{callee} is called using the \texttt{static\_cast} the same
contraction occurs, so \texttt{Type \&\&param} operates on \texttt{Tp \&param}. Therefore
(using contraction) the static cast \emph{also} uses type \texttt{Tp \&param}. If
\texttt{param} happened to be of type \texttt{Tp \&\&} then the static cast uses type
\texttt{Tp \&\&param}.

This characteristic allows us to pass a function argument to a nested function
\emph{without} changing its type: lvalues remain lvalues, rvalues remain
rvalues. This characteristic is therefore also known as
 \index{perfect forwarding}\emph{perfect forwarding} which is discussed in greater detail in section
\ref{PERFECT}. Perfect forwarding prevents the template author from having to
define multiple overloaded versions of a function template.

\section{Declaring function templates}\label{TEMPFUNDECL}
\typeout{Original Yodl file: functiontemplates/declarations}    Up to now, we've only defined function templates. There are various
 \index{function templates: multiply included} consequences of including function
template definitions in multiple source files, none of them serious, but worth
knowing.
    \begin{itemize}
    \item  Like class interfaces, template definitions are usually included in
header files. Every time a header file containing a template definition is
read by the compiler it must process the full definition. It must do so even
if it does not actually use the template. This somewhat  slows-down the
compilation. For example, compiling a template header file like \texttt{algorithm}
on my old laptop takes about four times the amount of time it takes to compile
a plain header file like \texttt{cmath}. The header file \texttt{iostream} is even
harder to process, requiring almost 15 times the amount of time it takes to
process \texttt{cmath}. Clearly, processing templates is serious business for the
compiler. On the other hand this drawback shouldn't be taken too seriously.
Compilers are continuously improving their template processing capacity and
computers keep getting faster and faster. What was a nuisance a few years ago
is hardly noticeable today.
    \item  Every time a function template is instantiated, its code appears in
the resulting object module. However, if multiple instantiations of a template
using the same actual types for its template parameters exist in multiple
object files the \index{one definition rule}\emph{one definition rule} is lifted.  The linker weeds out
superfluous instantiations (i.e., identical definitions of instantiated
templates). In the final program only one instantiation for a particular set
of actual template type parameters remain available (see section
\ref{TEMPFUNINST} for an illustration). Therefore, the linker has an
additional task to perform (\emph{viz.} weeding out multiple instantiations),
which somewhat slows down the linking process.
    \item  Sometimes the definitions themselves are \emph{not} required, but
references or pointers to the templates \emph{are}. Requiring the compiler to
process the full template definitions in those cases needlessly slows down the
compilation process.
    \item  In the context of \index{template meta programming}\emph{template meta programming} (see chapter
\ref{ADVANCEDTEMPL}) it is sometimes not even required to provide a template
implementation. Instead, only \emph{specializations} (cf. section
\ref{SPECIALIZING}) are created which are based upon the mere \emph{declaration}.
    \end{itemize}
    So in some contexts template \emph{definitions} may not be required.  Instead
the software engineer may opt to \emph{declare} a template rather than to
include the template's definition time and again in various source files.

When templates are declared, the compiler does not have to process the
template's definitions again and again; and no instantiations are created
on the basis of template declarations alone. Any actually required
instantiation must then be available elsewhere (of course, this holds true for
declarations in general). Unlike the situation we encounter with ordinary
functions, which are usually stored in libraries, it is currently not possible
to store templates in libraries (although the compiler may construct
\index{precompiled header}\emph{precompiled header} \emph{files}). Consequently, using template declarations
puts a burden on the shoulders of the software engineer, who has to make sure
that the required instantiations exist. Below a simple way to accomplish that
is introduced.

To create a function template declaration simply replace the function's
body by a semicolon. Note that this is exactly identical to the way ordinary
function declarations are constructed. So, the previously defined function
template \texttt{add} can simply be declared as
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &rhs);
\end{verbatim}
We've already encountered \index{template declaration}template declarations. The header file
\texttt{iosfwd} may be included in sources not requiring instantiations of elements
from the class \index{ios}\texttt{ios} and its derived classes. For example, to compile the
\emph{declaration}
        \begin{verbatim}
    std::string getCsvLine(std::istream &in, char const *delim);
\end{verbatim}
it is not necessary to include the \texttt{string} and \texttt{istream} header
files. Rather, a single
        \begin{verbatim}
    #include <iosfwd>
\end{verbatim}
is sufficient. Processing \texttt{iosfwd} requires only a fraction of the time
it takes to process the \texttt{string} and \texttt{istream} header files.

\subsection{Instantiation declarations}\label{TEMPFUNEXDEC}
    \typeout{Original Yodl file: functiontemplates/instantdecl}    If declaring function templates speeds up the compilation and the linking
phases of a program, how can we make sure that the required instantiations of
the function templates are available when the program is eventually linked
together?

For this a variant of a template declaration is available, a so-called
 \index{instantiation declaration}\index{explicit instantiation declaration}\emph{explicit instantiation declaration}.
    An explicit instantiation declaration consists of the following elements:
    \begin{itemize}
    \item  It starts with the keyword \texttt{template}, omitting the template
parameter list.
    \item  Next the function template's return type and name are specified.
    \item  The function template's name is followed by a \emph{type specification
list}. A type specification list is an angle brackets enclosed list of type
names.  Each type specifies the actual type of the corresponding template type
parameter in the template's parameter list.
    \item  Finally the function template's parameter list is specified,
terminated by a semicolon.
    \end{itemize}
    Although this is a declaration, it is understood by the compiler as a
request to instantiate that particular variant of the function template.

Using explicit instantiation declarations all instantiations of template
functions required by a program can be collected in one file. This file, which
should be a normal \emph{source} file, should include the template definition
header file and should subsequently specify the required explicit
instantiation declarations. Since it's a source file, it is not included
by other sources. So namespace \texttt{using} directives and declarations may
safely be used once the required headers have been included.  Here is an
example showing the required instantiations for our earlier \texttt{add} function
template, instantiated for \texttt{double}, \texttt{int}, and \texttt{std::string} types:
        \begin{verbatim}
    #include "add.h"
    #include <string>
    using namespace std;

    template int add<int>(int const &lhs, int const &rhs);
    template double add<double>(double const &lhs, double const &rhs);
    template string add<string>(string const &lhs, string const &rhs);
\end{verbatim}
If we're sloppy and forget to mention an instantiation required by our
program then the repair is easily made by adding the missing instantiation
declaration to the above list. After recompiling the file and relinking the
program we're done.

\section{Instantiating function templates}\label{TEMPFUNINST}
\typeout{Original Yodl file: functiontemplates/instantiations}    Different from an ordinary function that results in code once the compiler
reads its definition a template is not instantiated when its definition is
read. A template is merely a \emph{recipe} telling the compiler how to create
particular code once it's time to do so. It's indeed very much like a recipe
in a cooking book. You reading how to bake a cake doesn't mean you have
actually baked that cake by the time you've read the recipe.

So, when is a function template actually instantiated? There are two
situations where the compiler decides to instantiate templates:
    \begin{itemize}
    \item  They are instantiated when they are used (e.g., the function
\texttt{add} is called with a pair of \texttt{size\_t} values);
    \item  When addresses of function templates are taken they are instantiated.
Example:
        \begin{verbatim}
char (*addptr)(char const &, char const &) = add;
\end{verbatim}
\end{itemize}
    The location of statements causing the compiler to instantiate a template
is called the template's
        \index{template: point of instantiation}
    \index{point of instantiation}\emph{point of instantiation}. The point of instantiation has serious
implications for the function template's code. These implications are
discussed in section \ref{NAMERESFUN}.

The compiler is not always able to deduce the template's type parameters
unambiguously. When the compiler reports an ambiguity it must be solved by the
software engineer. Consider the following code:
        \begin{verbatim}
    #include <iostream>
    #include "add.h"

    size_t fun(int (*f)(int *p, size_t n));
    double fun(double (*f)(double *p, size_t n));

    int main()
    {
        std::cout << fun(add);
    }
\end{verbatim}
    When this little program is compiled, the compiler reports an ambiguity it
cannot resolve. It has two candidate functions as for each overloaded version
of \texttt{fun} an \texttt{add} function can be instantiated:
        \begin{verbatim}
    error: call of overloaded 'fun(<unknown type>)' is ambiguous
    note: candidates are: int fun(size_t (*)(int*, size_t))
    note:                 double fun(double (*)(double*, size_t))
\end{verbatim}
Such situations should of course be avoided. Function templates can only
be instantiated if there's no ambiguity. Ambiguities arise when multiple
functions emerge from the compiler's function selection mechanism (see section
\ref{FUNCTIONSELECTION}). It is up to us to resolve the ambiguities. They
\emph{could} be resolved using a blunt \index{static\_cast}\texttt{static\_cast} (by which we select among
alternatives, all of them possible and available):
        \begin{verbatim}
    #include <iostream>
    #include "add.h"

    int fun(int (*f)(int const &lhs, int const &rhs));
    double fun(double (*f)(double const &lhs, double const &rhs));

    int main()
    {
        std::cout << fun(
                        static_cast<int (*)(int const &, int const &)>(add)
                    );
    }
\end{verbatim}
    But it's good practice to avoid type casts wherever possible. How to do
this is explained in the next section (\ref{TEMPFUNEXPLICIT}).

\subsection{Instantiations: no `code bloat'}
    \typeout{Original Yodl file: functiontemplates/nocodebloat}    As mentioned in section \ref{TEMPFUNDECL}, the linker removes
 \index{linker: removing identical template instantiations} identical
instantiations of a template from the final program, leaving only one
instantiation for each unique set of actual template type parameters. To
illustrate the linker's behavior we do as follows:
    \begin{itemize}
    \item  First we construct several source files:
            \begin{itemize}
            \item \texttt{source1.cc} defines a function \texttt{fun}, instantiating
\texttt{add} for \texttt{int}-type arguments, including \texttt{add}'s template
definition. It displays \texttt{add}'s address using \texttt{union PointerUnion}:
        \begin{verbatim}
    union PointerUnion
    {
        int (*fp)(int const &, int const &);
        void *vp;
    };
\end{verbatim}
Here is a program using \texttt{PointerUnion}:
        \begin{verbatim}
    #include <iostream>
    #include "add.h"
    #include "pointerunion.h"

    void fun()
    {
        PointerUnion pu = { add };

        std::cout << pu.vp << '\n';
    }
\end{verbatim}
            \item \texttt{source2.cc} defines the same function, but merely declares the
proper \texttt{add} template using a template declaration (\emph{not} an instantiation
declaration). Here is \texttt{source2.cc}:
        \begin{verbatim}
    #include <iostream>
    #include "pointerunion.h"

    template<typename Type>
    Type add(Type const &, Type const &);

    void fun()
    {
        PointerUnion pu = { add };

        std::cout << pu.vp << '\n';
    }
\end{verbatim}
            \item \texttt{main.cc} again includes \texttt{add}'s template definition,
declares the function \texttt{fun} and defines \texttt{main}, defining \texttt{add}
for \texttt{int}-type arguments as well and displaying \texttt{add}'s function
address. It also calls the function \texttt{fun}. Here is \texttt{main.cc}:
        \begin{verbatim}
    #include <iostream>
    #include "add.h"
    #include "pointerunion.h"

    void fun();

    int main()
    {
        PointerUnion pu = { add };

        fun();
        std::cout << pu.vp << '\n';
    }
\end{verbatim}
            \end{itemize}
    \item  All sources are compiled to object modules. Note the different sizes
of \texttt{source1.o} (1912 bytes using \texttt{g++} version 4.3.4 (sizes of object
modules reported in this section may differ for different compilers and/or
run-time libraries)) and \texttt{source2.o} (1740 bytes). Since \texttt{source1.o}
contains the instantiation of \texttt{add}, it is somewhat larger than
\texttt{source2.o}, containing only the template's declaration. Now we're ready to
start our little experiment.
    \item  Linking \texttt{main.o} and \texttt{source1.o}, we obviously link together two
object modules, each containing its own instantiation of the same template
function. The resulting program produces the following output:
        \begin{verbatim}
    0x80486d8
    0x80486d8
\end{verbatim}
Furthermore, the size of the resulting program is 6352 bytes.
    \item  Linking \texttt{main.o} and \texttt{source2.o}, we now link together an object
module containing the instantiation of the \texttt{add} template, and another
object module containing the mere declaration of the same template
function. So, the resulting program cannot but contain a single instantiation
of the required function template. This program has exactly the same size, and
produces exactly the same output as the first program.
    \end{itemize}
    From our little experiment we conclude that the linker indeed removes
identical template instantiations from a final program. Furthermore we
conclude that using mere template declarations does not result in template
instantiations.

\section{Using explicit template types}\label{TEMPFUNEXPLICIT}
\typeout{Original Yodl file: functiontemplates/explicit}    In the previous section we saw that the compiler may encounter ambiguities
when attempting to instantiate a template. In an example overloaded versions
of a function (\texttt{fun}) existed, expecting different types of arguments. The
ambiguity resulted from the fact that both arguments could have been provided
by an instantiation of a function template. The intuitive way to solve such an
ambiguity is to use a \texttt{static\_cast}. But casts should be avoided wherever
possible.

With function templates static casts may indeed be avoided using
 \index{explicit template type arguments}\emph{explicit template type arguments}. Explicit template type arguments can
be used to inform the compiler about the actual types it should use when
instantiating a template. To use explicit type arguments the function's name
is followed by an \emph{actual template type argument list} which may again be
followed by the function's argument list. The actual types mentioned in the
actual template argument list are used by the compiler to `deduce' what types
to use when instantiating the template. Here is the example from the previous
section, now using explicit template type arguments:
        \begin{verbatim}
    #include <iostream>
    #include "add.h"

    int fun(int (*f)(int const &lhs, int const &rhs));
    double fun(double (*f)(double const &lhs, double const &rhs));

    int main()
    {
        std::cout << fun(add<int>) << '\n';
    }
\end{verbatim}
Explicit template type arguments  can be used in situations where the
compiler has no way to detect which types should actually be used. E.g., in
section \ref{TEMPFUNARGS} the function template \texttt{Type fun()} was defined. To
instantiate this function for the \texttt{double} type, we can call
\texttt{fun$<$double$>$()}.

\section{Overloading function templates}
\typeout{Original Yodl file: functiontemplates/overloading}Let's once again look at our \texttt{add} template. That template was designed to
return the sum of two entities. If we would want to compute the sum of three
entities, we could write:
        \begin{verbatim}
    int main()
    {
        add(add(2, 3), 4);
    }
\end{verbatim}
This is an acceptable solution for the occasional situation. However, if
we would have to add three entities regularly, an \emph{overloaded} version of
the \texttt{add} function expecting three arguments might be a useful function to
have. There's a simple solution to this problem: function templates may be
        \index{overloading: function template}
        \index{function template: overloading}
overloaded.

To define an overloaded function template, merely put multiple definitions
of the template in its header file. For the \texttt{add} function this would boil
down to:
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
    template <typename Type>
    Type add(Type const &lhs, Type const &mid, Type const &rhs)
    {
        return lhs + mid + rhs;
    }
\end{verbatim}
The overloaded function does not have to be defined in terms of simple
values. Like all overloaded functions, a unique set of function parameters is
enough to define an overloaded function template. For example, here's an
overloaded version that can be used to compute the sum of the elements of a
vector:
        \begin{verbatim}
    template <typename Type>
    Type add(std::vector<Type> const &vect)
    {
        return accumulate(vect.begin(), vect.end(), Type());
    }
\end{verbatim}
When overloading function templates we do not have to restrict ourselves
to the function's parameter list. The template's type parameter list itself
may also be
        \index{template: overloading type parameter list}
    overloaded. The last definition of the \texttt{add} template allows us to
specify a \texttt{vector} as its first argument, but no \texttt{deque} or
\texttt{map}. Overloaded versions for those types of containers could of course be
constructed, but how far should we go? A better approach seems to be to look
for common characteristics of these containers. If found we may be able to
define an overloaded function template based on these common
characteristics. One common characteristic of the mentioned containers is that
they all support \texttt{begin} and \texttt{end} members, returning iterators. Using
this, we could define a template type parameter representing containers that
must support these members. But mentioning a plain `container type' doesn't
tell us for what type of data it was instantiated. So we need a second
template type parameter representing the container's data type, thus
overloading the template's type parameter list. Here is the resulting
overloaded version of the \texttt{add} template:
        \begin{verbatim}
    template <typename Container, typename Type>
    Type add(Container const &cont, Type const &init)
    {
        return std::accumulate(cont.begin(), cont.end(), init);
    }
\end{verbatim}
One may wonder whether the \texttt{init} parameter could not be left out of the
parameter list as \texttt{init} often has a default initialization value. The
answer is `yes', but there are complications. It \emph{is} possible to define the
\texttt{add} function as follows:
        \begin{verbatim}
    template <typename Type, typename Container>
    Type add(Container const &cont)
    {
        return std::accumulate(cont.begin(), cont.end(), Type());
    }
\end{verbatim}
Note, however, that the template's type parameters were reordered, which
is necessary because the compiler won't be able to determine \texttt{Type} in a
call like:
        \begin{verbatim}
    int x = add(vectorOfInts);
\end{verbatim}
After reordering the template type parameters, putting \texttt{Type} first, an
explicit template type argument can be provided for the first template type
parameter:
        \begin{verbatim}
    int x = add<int>(vectorOfInts);
\end{verbatim}
In this example we provided a \texttt{vector$<$int$>$} argument. One might wonder
why we have to specify \texttt{int} explicitly to allow the compiler to determine
the template type parameter \texttt{Type}. In fact, we don't. A third kind of
template parameter exists, a \emph{template template parameter}, allowing the
compiler to determine \texttt{Type} directly from the actual container
argument. Template template parameters are discussed in section
\ref{TEMPTEMPPAR}.

\subsection{An example using overloaded function templates}
    \typeout{Original Yodl file: functiontemplates/example}    With all these overloaded versions in place, we may now start the compiler
to compile the following function:
        \begin{verbatim}
    using namespace std;

    int main()
    {
        vector<int> v;

        add(3, 4);          // 1 (see text)
        add(v);             // 2
        add(v, 0);          // 3
    }
\end{verbatim}
\begin{itemize}
    \item  In statement 1 the compiler recognizes two identical types, both
\texttt{int}. It therefore instantiates \texttt{add$<$int$>$}, our very first definition
of the \texttt{add} template.
    \item  In statement 2 a single argument is used. Consequently, the compiler
looks for an overloaded version of \texttt{add} requiring but one argument. It
finds the overloaded function template expecting a \texttt{std::vector}, deducing
that the template's type parameter must be \texttt{int}. It instantiates
        \begin{verbatim}
    add<int>(std::vector<int> const &)
\end{verbatim}
\item  In statement 3 the compiler again encounters an argument list having
  two arguments. However, this time the types of the arguments aren't equal,
so \texttt{add} template's first definition can't be used. But it \emph{can} use the
last definition, expecting entities having different types. As a
\texttt{std::vector} supports \texttt{begin} and \texttt{end}, the compiler is now able to
instantiate the function template
        \begin{verbatim}
add<std::vector<int>, int>(std::vector<int> const &, int const &)
\end{verbatim}
\end{itemize}
    Having defined the \texttt{add} function template for two equal and two
different template type parameters we've exhausted the possibilities for using
an \texttt{add} function template having two template type parameters.

\subsection{Ambiguities when overloading function templates}
    \typeout{Original Yodl file: functiontemplates/ambiguities}Although it \emph{is} possible to define another function template \texttt{add} this
introduces an ambiguity as the compiler won't be able to choose which of
the two overloaded versions defining two differently typed function parameters
should be used. For example when defining:
        \begin{verbatim}
    #include "add.h"

    template <typename T1, typename T2>
    T1 add(T1 const &lhs, T2 const &rhs)
    {
        return lhs + rhs;
    }
    int main()
    {
        add(3, 4.5);
    }
\end{verbatim}
the compiler reports an ambiguity like the following:
        \begin{verbatim}
        error: call of overloaded `add(int, double)' is ambiguous
        error: candidates are: Type add(const Container&, const Type&)
                                    [with Container = int, Type = double]
        error:                 T1 add(const T1&, const T2&)
                                    [with T1 = int, T2 = double]
\end{verbatim}
Now recall the overloaded function template accepting three arguments:
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &mvalue, Type const &rhs)
    {
        return lhs + mvalue + rhs;
    }
\end{verbatim}
It may be considered as a disadvantage that only equally typed arguments
are accepted by this function (three \texttt{int}s, three \texttt{double}s, etc.). To
remedy this we define yet another overloaded function template, this time
accepting arguments of any type.  This function template can only be used if
\texttt{operator+} is defined between the function's actually used types, but apart
from that there appears to be no problem. Here is the overloaded version
accepting arguments of any type:
        \begin{verbatim}
    template <typename Type1, typename Type2, typename Type3>
    Type1 add(Type1 const &lhs, Type2 const &mid, Type3 const &rhs)
    {
        return lhs + mid + rhs;
    }
\end{verbatim}
Now that we've defined the above two overloaded function templates
expecting three arguments let's call \texttt{add} as follows:
        \begin{verbatim}
    add(1, 2, 3);
\end{verbatim}
Should we expect an ambiguity here? After all, the compiler might select
the former function, deducing that \texttt{Type == int}, but it might also select
the latter function, deducing that \texttt{Type1 == int, Type2 == int} and \texttt{Type3
== int}. Remarkably, the compiler reports no ambiguity.

No ambiguity is reported because of the following. If overloaded template
functions are defined using \emph{less} and \emph{more} specialized template type
parameters (e.g., less specialized: all types different vs. more specialized:
        \index{function templates: specialized type parameters} all types equal)
then the compiler selects the more specialized function whenever possible.

As a \index{rule of thumb}rule of thumb: overloaded function templates must allow a unique
combination of template type arguments to be specified to prevent ambiguities
when selecting which overloaded function template to instantiate.  The
\emph{ordering} of template type parameters in the function template's type
parameter list is not important. E.g., trying to instantiate one of the
following function templates results in an ambiguity:
        \begin{verbatim}
    template <typename T1, typename T2>
    void binarg(T1 const &first, T2 const &second)
    {}
    template <typename T1, typename T2>
    void binarg(T2 const &first, T1 const &second)
    {}
\end{verbatim}
This should not come as a surprise. After all, template type parameters
are just formal names. Their names (\texttt{T1}, \texttt{T2} or \texttt{Whatever}) have no
concrete meanings.

\subsection{Declaring overloaded function templates}
    \typeout{Original Yodl file: functiontemplates/declaring}    Like any function, overloaded functions may be declared, either using
plain declarations or instantiation declarations. Explicit template argument
types may also be used. Example:
    \begin{itemize}
    \item  To declare a function template \texttt{add} accepting certain containers:
    \begin{verbatim}
template <typename Container, typename Type>
Type add(Container const &container, Type const &init);
\end{verbatim}
\item  to use an instantiation declaration (in which case the compiler must
already have seen the template's definition):
    \begin{verbatim}
template int add<std::vector<int>, int>
                (std::vector<int> const &vect, int const &init);
\end{verbatim}
\item  to use explicit template type arguments:
    \begin{verbatim}
std::vector<int> vi;
int sum = add<std::vector<int>, int>(vi, 0);
\end{verbatim}
\end{itemize}

\section{Specializing templates for deviating types}\label{SPECIALIZING}
\typeout{Original Yodl file: functiontemplates/specialization}    The initial \texttt{add} template, defining two identically typed parameters
works fine for all types supporting \texttt{operator+} and a copy
constructor. However, these assumptions are not always met. For example, with
\texttt{char $*$}s, using \texttt{operator+} or a `copy constructor' does not make
sense. The compiler tries to instantiate the function template, but
compilation fails as  \texttt{operator+} is not defined for pointers.

In such situations the compiler may be able to resolve the template type
parameters but it (or we ...) may then detect that the standard implementation
is pointless or produces errors.

To solve this problem a \index{template explicit specialization}\emph{template explicit specialization} may be
defined.  A template explicit specialization defines the function template for
which a generic definition already exists using specific actual template type
parameters. As we saw in the previous section the compiler always prefers
a more specialized function over a less specialized one. So the template
explicit specialization is selected whenever possible.

A template explicit specialization offers a specialization for its template
type parameter(s). The special type is consistently substituted for
the template type parameter in the function template's code. For
example if the explicitly specialized type is \texttt{char const $*$} then in the
template definition
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
\texttt{Type} must be replaced by \texttt{char const $*$}, resulting in a function
having prototype
        \begin{verbatim}
    char const *add(char const *const &lhs, char const *const &rhs);
\end{verbatim}
Now we try to use this function:
        \begin{verbatim}
    int main(int argc, char **argv)
    {
        add(argv[0], argv[1]);
    }
\end{verbatim}
However, the compiler ignores our specialization and tries to instantiate
the initial function template. This fails, leaving us wondering why it didn't
select the explicit specialization....

To see what happened here we replay, step by step, the compiler's actions:
    \begin{itemize}
    \item  \texttt{add} is called with \texttt{char $*$} arguments.
    \item  Both types are equal, so the compiler deduces that \texttt{Type} equals
\texttt{char $*$}.
    \item  Now it inspects the specialization. Can a \texttt{char $*$} template type
argument match a \texttt{char const $*$const \&} template parameter? Here
opportunities for the allowable transformations from section \ref{TEMPFUNARGS}
may arise. A qualification transformation seems to be the only viable one,
allowing the compiler to bind a const-parameter to a non-const argument.
    \item  So, in terms of \texttt{Type} the compiler can match an argument of some
\texttt{Type} or an argument of some \texttt{Type const} to a \texttt{Type const \&}.
    \item  \texttt{Type} itself is not modified, and so \texttt{Type} is a \texttt{char $*$}.
    \item  Next the compiler inspects the available explicit specializations. It
finds one, specializing for \texttt{char const $*$}.
    \item  Since a \texttt{char const $*$} is not a \texttt{char $*$} it rejects the explicit
specialization and uses the generic form, resulting in a compilation error.
    \end{itemize}
    If our \texttt{add} function template should also be able to handle \texttt{char $*$}
template type arguments another explicit specialization for \texttt{char $*$} may be
required, resulting in the prototype
        \begin{verbatim}
    char *add(char *const &lhs, char *const &rhs);
\end{verbatim}
Instead of defining another explicit specialization an \emph{overloaded}
function template could be designed expecting pointers. The following function
template definition expects two pointers to constant \texttt{Type} values and
returns a pointer to a non-constant \texttt{Type}:
        \begin{verbatim}
    template <typename Type>
    Type *add(Type const *t1, Type const *t2)
    {
        std::cout << "Pointers\n";
        return new Type;
    }
\end{verbatim}
What actual types may be bound to the above function parameters? In this
case only a \texttt{Type const $*$}, allowing \texttt{char const $*$}'s to be passed as
arguments. There's no opportunity for a qualification transformation here.
The qualification transformation allows the compiler to add a \texttt{const} to a
non-const argument if the parameter itself (and \emph{not}  \texttt{Type}) is
specified in terms of a \texttt{const} or \texttt{const \&}. Looking at, e.g., \texttt{t1} we
see that it's defined as a \texttt{Type const $*$}. There's nothing \texttt{const} here
that's referring to the parameter (in which case it would have been \texttt{Type
const $*$const t1} or \texttt{Type const $*$const \&t1}). Consequently a qualification
transformation cannot be applied here.

As the above overloaded function template only accepts \texttt{char const $*$}
arguments, it will not accept (without a reinterpret cast) \texttt{char $*$}
arguments. So \texttt{main}'s \texttt{argv} elements cannot be passed to our overloaded
function template.

\subsection{Avoiding too many specializations}
    \typeout{Original Yodl file: functiontemplates/avoiding}    So do we have to define yet another overloaded function template, this
time expecting \texttt{Type $*$} arguments? It is possible, but at some point it
should become clear that our approach doesn't scale. Like ordinary functions
and classes, function templates should have one conceptually clear
purpose. Trying to add overloaded function templates to overloaded function
templates quickly turns the template into a kludge. Don't use this approach. A
better approach is to construct the template so that it fits its original
purpose, to make allowances for the occasional specific case and to describe
its purpose clearly in its documentation.

In some situations constructing template explicit specializations may of
course be defensible. Two specializations for \texttt{const} and non-\texttt{const}
pointers to characters might be appropriate for our \texttt{add} function
template. \index{template: explicit specialization} Here's how they are
constructed:
    \begin{itemize}
    \item  Start with the keyword \texttt{template}.
    \item  Next, an empty set of angle brackets is written. This indicates to
the compiler that there must be an \emph{existing} template whose prototype
matches the one we're about to define. If we err and there is no such template
        \index{template: id-declaration mismatch}
then the compiler reports an error like:
        \begin{verbatim}
    error: template-id `add<char*>' for `char* add(char* const&, char*
           const&)' does not match any template declaration
\end{verbatim}
\item  Now the function's head is defined. It must match the prototype of
the initial function template or the form of a template explicit instantiation
declaration (see section \ref{TEMPFUNEXDEC}) if its specialized type cannot be
determined from the function's arguments. It must specify the correct
returntype, function name, maybe explicit template type arguments, as well as
the function's parameter list.
    \item  Finally the function's body is defined, providing the special
implementation that is required for the specialization.
    \end{itemize}

Here are two explicit specializations for the function template \texttt{add},
expecting \texttt{char $*$} and \texttt{char const $*$} arguments:
        \begin{verbatim}
    template <> char *add<char *>(char *const &p1,
                                        char *const &p2)
    {
        std::string str(p1);
        str += p2;
        return strcpy(new char[str.length() + 1], str.c_str());
    }

    template <> char const *add<char const *>(char const *const &p1,
                                        char const *const &p2)
    {
        static std::string str;
        str = p1;
        str += p2;
        return str.c_str();
    }
\end{verbatim}
Template explicit specializations are normally included in the file
containing the other function template's implementations.

\subsection{Declaring specializations}
    \typeout{Original Yodl file: functiontemplates/declaringspec}    Template explicit specializations can be declared in the usual way. I.e.,
by replacing its body with a semicolon.

When \emph{declaring} a template explicit specialization the pair of
 \index{angle brackets}angle brackets following the \texttt{template} keyword are essential. If
omitted, we would have constructed a
        \index{template instantiation declaration}template instantiation declaration.
    The compiler would silently process it, at the expense of a somewhat
longer compilation time.

When declaring a template explicit specialization (or when using an
instantiation declaration) the
        \index{template explicit type specification: omitting}
    explicit specification of the template type parameters can be omitted if
the compiler is able to deduce these types from the function's arguments.  As
this is the case with the \texttt{char (const) $*$} specializations, they could also
be declared as follows:
        \begin{verbatim}
    template <> char *add(char *const &p1, char *const &p2);
    template <> char const *add(char const *const &p1,
                                char const *const &p2);
\end{verbatim}
If in addition \texttt{template $<$$>$} would be omitted the function declaration would
no longer be a function template declaration but an ordinary function
declaration. This is not an error: function templates and ordinary
(non-template) functions may mutually overload each other. Ordinary functions
are not as restrictive as function templates with respect to allowed type
conversions. This could be a reason to overload a template with an ordinary
function every once in a while.

A function template explicit specialization is not just another overloaded
        \index{function template: specialization vs. overloading} version of
the function template. Whereas an overloaded version may define a completely
different set of template parameters, a specialization must use the same set
of template parameters as its non-specialized variant. The compiler uses the
specialization in situations where the actual template arguments match the
types defined by the specialization (following the rule that the most
specialized set of parameters matching a set of arguments will be
used). For different sets of parameters  overloaded versions of functions (or
function templates) must be used.

\subsection{Complications when using the insertion operator}
    \typeout{Original Yodl file: functiontemplates/insertion}    Now that we've covered explicit specializations and overloading let's
consider what happens when a class defines a \texttt{std::string} conversion
operator (cf. section \ref{ConversionOperators}).

A conversion operator is guaranteed to be used as an rvalue. This means that
objects of a class defining a \texttt{string} conversion operator can be assigned
to, e.g., \texttt{string} objects. But when trying to insert objects defining
\texttt{string} conversion operators into streams then the compiler complains that
we're attempting to insert an inappropriate type into an \texttt{ostream}.

On the other hand, when this class defines an \texttt{int} conversion operator
insertion is performed flawlessly.

The reason for this distinction is that \texttt{operator$<$$<$} is defined as a plain
(free) function when inserting a basic type (like \texttt{int}) but it is defined
as a function template when inserting a \texttt{string}. Hence, when trying to
insert an object of our class defining a \texttt{string} conversion operator the
compiler visits all overloaded versions of insertion operators inserting into
\texttt{ostream} objects.

Since no basic type conversion is available the basic type insertion operators
can't be used. Since the available conversions for template arguments do not
allow the compiler to look for conversion operators our class defining the
\texttt{string} conversion operator cannot be inserted into an \texttt{ostream}.

If it should be possible to insert objects of such a class into \texttt{ostream}
objects the class must define its own overloaded insertion operator (in
addition to the \texttt{string} conversion operator that was required to use the
class's objects as rvalue in \texttt{string} assignments).

\section{Static assertions}\label{STATICASSERT}
\typeout{Original Yodl file: functiontemplates/staticassertions}The \index{static\_assert}
        \begin{verbatim}
    static_assert(constant expression, error message)
\end{verbatim}
utility is available to allow assertions to be made from inside template
definitions. Here are two examples of its use:
        \begin{verbatim}
    static_assert(BUFSIZE1 == BUFSIZE2,
                                "BUFSIZE1 and BUFSIZE2 must be equal");

    template <typename Type1, typename Type2>
    void rawswap(Type1 &type1, Type2 &type2)
    {
        static_assert(sizeof(Type1) == sizeof(Type2),
                        "rawswap: Type1 and Type2 must have equal sizes");
        // ...
    }
\end{verbatim}
The first example shows how to avoid yet another preprocessor directive
        \index{preprocessor directive: error vs. static\_assert}
 (in this case the \index{\#error}\texttt{\#error} directive).

The second example shows how \texttt{static\_assert} can be used to ensure that
a template operates under the right condition(s).

The string defined in \texttt{static\_assert}'s second argument is displayed and
compilation stops if the condition specified in \texttt{static\_assert}'s first
argument is \texttt{false}.

Like the \texttt{\#error} preprocessor directive \texttt{static\_assert} is a
\index{compile-time}compile-time matter that doesn't have any effect on the \index{run-time}run-time
efficiency of the code in which it is used.

\section{Numeric limits}\label{NUMLIM}
\typeout{Original Yodl file: functiontemplates/limits}The header file \index{climits: header file}\texttt{$<$climits$>$} defines constants for various types, e.g.,
\index{INT\_MAX}\texttt{INT\_MAX} defines the maximum value that can be stored in an \texttt{int}.

The disadvantage of the limits defined in \texttt{climits} is that they are fixed
limits. Let's assume you write a function template that receives an argument
of a certain type. E.g,
        \begin{verbatim}
    template<typename Type>
    Type operation(Type &&type);
\end{verbatim}
Assume this function should return the largest negative value for \texttt{Type}
if \texttt{type} is a negative value and the largest positive value if \texttt{type} is
a positive value. However, 0 should be returned if the type is not an integral
value.

How to proceed?

Since the constants in \texttt{climits} can only be used if the type to use is
already known, the only approach seems to be to create function template
specializations for the various integral types, like:
        \begin{verbatim}
    template<>
    int operation<int>(int &&type)
    {
        return type < 0 ? INT_MIN : INT_MAX;
    }
\end{verbatim}
The facilities provided by \index{numeric\_limits}numeric\_limits provide an alternative. To use
these facilities the header file \index{limits: header file}\texttt{$<$limits$>$} header file must be included.

The class template \texttt{numeric\_limits} offers various members answering all
kinds of questions that could be asked of numeric types. Before introducing
these members, let's have a look at how we could implement the \texttt{operation}
function template as just one single function template:
        \begin{verbatim}
    template<typename Type>
    Type operation(Type &&type)
    {
        return
            not numeric_limits<Type>::is_integer ? 0 :
            type < 0 ? numeric_limits<Type>::min() :
                       numeric_limits<Type>::max();
    }
\end{verbatim}
Now \texttt{operation} can be used for all the language's primitive types.

Here is an overview of the facilities offered by \texttt{numeric\_limits}. Note
that the member functions defined by \texttt{numeric\_limits} return \texttt{constexpr}
values. A member `\texttt{member}' defined by \texttt{numeric\_limits} for type \texttt{Type}
can be used as follows:
        \begin{verbatim}
    numeric_limits<Type>::member    // data members
    numeric_limits<Type>::member()  // member functions
\end{verbatim}
\begin{itemize}
    \item \index{denorm\_min}\texttt{Type denorm\_min()}:\ \\ 
        if available for \texttt{Type}: its minimum positive denormalized value;
        otherwise it returns \texttt{numeric\_limits$<$Type$>$::min()}.

\item \index{digits}\texttt{int digits}:\ \\ 
        the number of non-sign bits used by \texttt{Type} values, or (floating
        point types) the number of digits in the mantissa are returned.

\item \index{digits10}\texttt{int digits10}:\ \\ 
        the number of digits that are required to represent a \texttt{Type} value
        without  changing it.

\item \index{epsilon}\texttt{constexpr Type epsilon()}:\ \\ 
        The difference for \texttt{Type} between the smallest value exceeding 1 and
        1 itself.

\item \index{has\_denorm}\texttt{float\_denorm\_style has\_denorm}:\ \\ 
        \index{float\_denorm\_style}
        \index{denorm\_style}
        denormalized floating point value representations use a variable
        number of exponent bits. The \texttt{has\_denorm} member returns information
        about denormalized values for type \texttt{Type}:
        \begin{itemize}
        \item \texttt{denorm\_absent}: \texttt{Type} does not allow denormalized values;
        \item \texttt{denorm\_indeterminate}: \texttt{Type} may or may not use denormalized
            values; the compiler cannot determine this at compile-time;
        \item \texttt{denorm\_present}: \texttt{Type} uses denormalized values;
        \end{itemize}

\item \index{has\_denorm\_loss}\texttt{bool has\_denorm\_loss}:\ \\ 
        \texttt{true} if a loss of accuracy was detected as a result of using
        denormalization (rather than being an inexact result).

\item \index{has\_infinity}\texttt{bool has\_infinity}:\ \\ 
        \texttt{true} if \texttt{Type} has a representation for positive infinity.

\item \index{has\_quiet\_NaN}\texttt{bool has\_quiet\_NaN}:\ \\ 
        \texttt{true} if \texttt{Type} has a representation for a non-signaling
        \index{NaN}`\index{Not-a-Number}Not-a-Number' value.

\item \index{has\_signaling\_NaN}\texttt{bool has\_signaling\_NaN}:\ \\ 
        \texttt{true} if \texttt{Type} has a representation for a signaling
        `Not-a-Number' value.

\item \index{infinity}\texttt{constexpr Type infinity()}:\ \\ 
        if available for \texttt{Type}: its positive infinity value.

\item \index{is\_bounded}\texttt{bool is\_bounded}:\ \\ 
        \texttt{true} if \texttt{Type} contains a finite set of values.

\item \index{is\_exact}\texttt{bool is\_exact}:\ \\ 
        \texttt{true} if \texttt{Type} uses an exact representation.

\item \index{is\_iec559}\texttt{bool is\_iec559}:\ \\ 
        \texttt{true} if \texttt{Type} uses the \index{IEC-559}IEC-559 (\index{IEEE-754}IEEE-754) standard. Such
        types always return \texttt{true} for \texttt{has\_infinity, has\_quiet\_NaN} and
        \texttt{has\_signaling\_NaN}, while \texttt{infinity(), quiet\_NaN()} and
        \texttt{signaling\_NaN()} return non-zero values.

\item \index{is\_integer}\texttt{bool is\_integer}:\ \\ 
        \texttt{true} if \texttt{Type} is an integral type.

\item \index{is\_modulo}\texttt{bool is\_modulo}:\ \\ 
        \texttt{true} if \texttt{Type} is a `modulo' type. Values of modulo types can
        always be added, but the addition may `wrap around' producing a
        smaller \texttt{Type} result than either of the addition's two operands.

\item \index{is\_signed}\texttt{bool is\_signed}:\ \\ 
        \texttt{true} if \texttt{Type} is signed.

\item \index{is\_specialized}\texttt{bool is\_specialized}:\ \\ 
        \texttt{true} for specializations of \texttt{Type}.

\item \index{lowest}\texttt{constexpr Type lowest()}:\ \\ 
        \texttt{Type}'s lowest finite value representable by \texttt{Type}: 
        no other finite value smaller than the value returned by \texttt{lowest}
        exists. This value equals the value returned by \texttt{min} except for
        floating-point types. 

\item \index{max}\texttt{constexpr Type max()}:\ \\ 
        \texttt{Type}'s maximum value.

\item \index{min}\texttt{constexpr Type min()}:\ \\ 
        \texttt{Type}'s minimum value. For denormalized floating point types the
        minimum positive normalized value.

\item \index{max\_exponent}\texttt{int max\_exponent}:\ \\ 
        maximum positive integral value for the exponent of a floating point
        type \texttt{Type} producing a valid \texttt{Type} value.

\item \index{max\_exponent10}\texttt{int max\_exponent10}:\ \\ 
        maximum integral value for the exponent that can be used for base 10,
        producing a valid \texttt{Type} value.

\item \index{min\_exponent}\texttt{int min\_exponent}:\ \\ 
        minimum negative integral value for the exponent of a floating point
        type \texttt{Type} producing a valid \texttt{Type} value.

\item \index{min\_exponent10}\texttt{int min\_exponent10}:\ \\ 
        minimum negative integral value for the exponent that can be used for
        base 10, producing a valid \texttt{Type} value.

\item \index{quiet\_NaN}\texttt{constexpr Type quiet\_NaN()}:\ \\ 
        if available for \texttt{Type}: its a non-signaling `Not-a-Number' value.

\item \index{radix}\texttt{int radix}:\ \\ 
        if \texttt{Type} is an integral type: base of the representation; if
        \texttt{Type} is a floating point type: the base of the exponent of the
        representation.

\item \index{round\_error}\texttt{constexpr Type round\_error()}:\ \\ 
        the maximum rounding error for \texttt{Type}.

\item \index{round\_style}\texttt{float\_round\_style round\_syle}:\ \\ 
        the rounding style used by \texttt{Type}. It has one of the following
        \texttt{enum} \index{float\_round\_style}\texttt{float\_round\_style}
                \index{round\_style} values:
        \begin{itemize}
        \item \texttt{round\_toward\_zero}: values are rounded towards zero;
        \item \texttt{round\_to\_nearest}: values are rounded to the nearest representable
            value;
        \item \texttt{round\_toward\_infinity}:values are rounded towards infinity;
        \item \texttt{round\_toward\_neg\_infinity}: if it rounds towards negative
            infinity; 
        \item \texttt{round\_indeterminate}: if the rounding style is indeterminable at
            compile-time.
        \end{itemize}

\item \index{signaling\_NaN}\texttt{constexpr Type signaling\_NaN()}:\ \\ 
        if available for \texttt{Type}: its a signaling `Not-a-Number' value.

\item \index{tinyness\_before}\texttt{bool tinyness\_before}:\ \\ 
        \texttt{true} if \texttt{Type} allows tinyness to be detected before rounding.

\item \index{traps}\texttt{bool traps}:\ \\ 
        \texttt{true} if \texttt{Type} implements trapping.

\end{itemize}

\section{Polymorphous wrappers for function objects}
\typeout{Original Yodl file: functiontemplates/polymorphouswrappers}In \textbf{C++} pointers to (member) functions have fairly strict rvalues. They can
only point to functions matching their types.  This becomes a problem when
defining templates where the type of a function pointer may depend on the
template's parameters.

To solve this problem 
        \index{polymorphous wrapper}
        \index{function pointer: polymorphic}
    \emph{polymorphous (function object) wrappers} can be used.  Polymorphous
wrappers refer to function pointers, member functions or function objects, as
long as their parameters match in type and number.

Before using polymorphic function wrappers the \index{functional: header file}\texttt{$<$functional$>$} header file
must be included.

Polymorphic function wrappers are made available through the
\texttt{std::function}\index{function (std::)}  class template. Its template argument
is the prototype of the function to create a wrapper for. Here is an example
of the definition of a polymorphic function wrapper that can be used to point
to a function expecting two \texttt{int} values and returning an \texttt{int}:
        \begin{verbatim}
    std::function<int (int, int)> ptr2fun;
\end{verbatim}
Here, the template's parameter is \texttt{int (int, int)}, indicating a
function expecting two \texttt{int} arguments, and returning and \texttt{int}. Other
prototypes return other, matching, function wrappers.

Such a function wrapper can now be used to point to any function the wrapper
was created for. E.g., `\texttt{plus$<$int$>$ add}' creates a functor defining an
\texttt{int operator()(int, int)} function call member. As this qualifies as a
function having prototype \texttt{int (int, int)}, our \texttt{ptr2fun} may point to
\texttt{add}:
        \begin{verbatim}
    ptr2fun = add;
\end{verbatim}
If \texttt{ptr2fun} does not yet point to a function (e.g., it is merely
defined) and an attempt is made to call a function through it a
        \index{bad\_function\_call}`\texttt{std::bad\_function\_call}'
    exception is thrown. Also, a polymorphic function wrapper that hasn't been
assigned to a function's address represents the value \texttt{false} in logical
expressions (as if it had been a pointer having value zero):
        \begin{verbatim}
    std::function<int(int)> ptr2int;

    if (not ptr2int)
        cout << "ptr2int is not yet pointing to a function\n";
\end{verbatim}
Polymorphous function wrappers can also be used to refer to functions,
functors or other polymorphous function wrappers having prototypes for which
standard conversions exist for either parameters or return values. E.g.,
        \begin{verbatim}
    bool predicate(long long value);

    void demo()
    {
        std::function<int(int)> ptr2int;

        ptr2int = predicate;    // OK, convertible param. and return type

        struct Local
        {
            short operator()(char ch);
        };

        Local object;

        std::function<short(char)> ptr2char(object);

        ptr2int = object;       // OK, object is a functor whose function
                                //  operator has a convertible param. and
                                // return type.
        ptr2int = ptr2char;     // OK, now using a polym. funct. wrapper
    }
\end{verbatim}
\section{Compiling template definitions and instantiations}\label{NAMERESFUN}
\typeout{Original Yodl file: functiontemplates/nameresolution}    Consider this definition of the \texttt{add} function template:
        \begin{verbatim}
    template <typename Container, typename Type>
    Type add(Container const &container, Type init)
    {
        return std::accumulate(container.begin(), container.end(), init);
    }
\end{verbatim}
Here \texttt{std::accumulate} is called using \texttt{container}'s \texttt{begin} and
\texttt{end} members.

The calls \texttt{container.begin()} and \texttt{container.end()} are said to
        \index{template: statements depending on type parameters}
    \emph{depend on template type parameters}. The compiler, not having seen
\texttt{container}'s interface, cannot check whether \texttt{container} actually
has members \texttt{begin} and \texttt{end} returning input iterators.

On the other hand, \texttt{std::accumulate} itself is independent of any
template type parameter. Its \emph{arguments} depend on template parameters, but
the function call itself isn't. Statements in a template's body that are
independent of template type parameters are said \emph{not to depend on template
type parameters}.

When the compiler encounters a template definition, it verifies the
syntactic correctness of all statements not depending on template
parameters. I.e., it must have seen all class definitions, all type
definitions, all function declarations etc. that are used in those statements.
If the compiler hasn't seen the required definitions and declarations then it
will reject the template's definition. Therefore, when submitting the above
template to the compiler the \texttt{numeric} header file must first have been
included as this header file declares \texttt{std::accumulate}.

With statements depending on template parameters the compiler cannot
perform those extensive syntactic checks. It has no way to verify the
existence of a member \texttt{begin} for the as yet unspecified type
\texttt{Container}. In these cases the compiler performs superficial checks,
assuming that the required members, operators and types eventually become
available.

The location in the program's source where the template is instantiated is
        \index{template: point of instantiation} \index{point of instantiation} called
its \emph{point of instantiation}. At the point of instantiation the compiler
deduces the actual types of the template's parameters. At that point it checks
the syntactic correctness of the template's statements that depend on template
type parameters. This implies that the compiler must have seen the required
declarations \emph{only at the point of instantiation}.  As a
        \index{rule of thumb}rule of thumb,
    you should make sure that all required declarations (usually: header
files) have been read by the compiler at every point of instantiation of the
template. For the template's definition itself a more relaxed requirement can
be formulated. When the definition is read only the declarations required for
statements \emph{not} depending on the template's type parameters must have been
provided.

On the other hand: at the point of instantiation the compiler must
\emph{also} have access to the template's definition. Therefore, template
definitions are commonly provided in header files: if a template must be
instantiated in some source file then the template definition, provided in a
header file (e.g., \texttt{template.h}) is included by the source file, so the
compiler can verify whether the template can be instantiated for the actually
used types (the same holds true for class templates, covered in the next
chapter). Here is a short example:
    \begin{itemize}
    \item  The function template \texttt{add} is defined in \texttt{add.h}:
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &fst, Type const &snd)
    {
        return fst + snd;
    }
\end{verbatim}
    \item  To use it \texttt{fun.h} includes \texttt{add.h}:
        \begin{verbatim}
    #include <iostream>
    #include "add.h"
    vouid fun(size_t lhs, size_t rhs)
    {
        std::cout << add(lhs, rhs) << '\n';
    }
\end{verbatim}
    \end{itemize}

Function template definitions can be defined as inline functions
by prefixing their definitions with the keyword \index{inline}\texttt{inline}. E.g,
        \begin{verbatim}
    template <typename Type>
    inline Type add(Type const &fst, Type const &snd)
    {
        return fst + snd;
    }
\end{verbatim}
    As always, inline should only be used for short, one-liner function
definitions. 

\section{The function selection mechanism}\label{FUNCTIONSELECTION}
\typeout{Original Yodl file: functiontemplates/selection}When the compiler encounters a function call, it must decide which function to
call when overloaded functions are available. Earlier we've encountered
principles like `the most specific function is selected'. This is a
fairly intuitive description of the compiler's \index{function selection}function selection mechanism.
In this section we'll have a closer look at this mechanism.

Assume we ask the compiler to compile the following \texttt{main} function:
        \begin{verbatim}
    int main()
    {
        process(3, 3);
    }
\end{verbatim}
Furthermore assume that the compiler has encountered the following
function declarations when it's about to compile \texttt{main}:
        \begin{verbatim}
    template <typename T>
    void process(T &t1, int i);                 // 1

    template <typename T1, typename T2>
    void process(T1 const &t1, T2 const &t2);   // 2

    template <typename T>
    void process(T const &t, double d);         // 3

    template <typename T>
    void process(T const &t, int i);            // 4

    template <>
    void process<int, int>(int i1, int i2);     // 5

    void process(int i1, int i2);               // 6

    void process(int i, double d);              // 7

    void process(double d, int i);              // 8

    void process(double d1, double d2);         // 9

    void process(std::string s, int i)          // 10

    int add(int, int);                          // 11
\end{verbatim}
The compiler, having read \texttt{main}'s statement, must now decide which
function must actually be called. It proceeds as follows:
    \begin{itemize}
    \item  First, a set of
 \index{function: candidate} \index{candidate functions}\emph{candidate functions} is constructed. This set
contains all functions that:
        \begin{itemize}
        \item  are visible at the point of the call;
        \item  have the same names as the called function.
        \end{itemize}
        As function 11 has a different name, it is removed from the set. The
compiler is left with a set of 10 candidate functions.

\item  Second, the set of
 \index{function: viable} \index{viable functions}\emph{viable functions} is constructed. Viable functions
are functions for which \index{type conversions}type conversions exist that can be applied so as to
match the types of the function's parameters to the types of the actual
arguments.

This implies that at least the number of arguments must match the number of
parameters of the viable functions. Function 10's first argument is a
\texttt{string}. As a \texttt{string} cannot be initialized by an \texttt{int} value no
appropriate conversion exists and function 10 is removed from the list of
candidate functions.  \texttt{double} parameters can be retained. Standard
conversions \emph{do} exists for \texttt{int}s to \texttt{double}s, so all functions having
ordinary \texttt{double} parameters can be retained. Therefore, the set of viable
functions consists of functions 1 through 9.
    \end{itemize}
    At this point the compiler tries to determine the types of the template
type parameters. This step is outlined in the following subsection.

\subsection{Determining the template type parameters}
    \typeout{Original Yodl file: functiontemplates/determining}Having determined the set of candidate functions and from that set the set of
viable functions the compiler must now determine the actual types of the
template type parameters.

It may use any of the three standard template parameter transformation
procedures (cf. section \ref{TEMPFUNARGS}) when trying to match actual types to
template type parameters. In this process it concludes that no type can be
determined for the \texttt{T} in function 1's \texttt{T \&t1} parameter as the argument
\texttt{3} is a constant \texttt{int} value. Thus function 1 is removed from the list of
viable functions. The compiler is now confronted with the following set of
potentially instantiated function templates and ordinary functions:
        \begin{verbatim}
    void process(T1 [= int] const &t1, T2 [= int] const &t2);   // 2
    void process(T [= int] const &t, double d);                 // 3
    void process(T [= int] const &t, int i);                    // 4
    void process<int, int>(int i1, int i2);                     // 5
    void process(int i1, int i2);                               // 6
    void process(int i, double d);                              // 7
    void process(double d, int i);                              // 8
    void process(double d1, double d2);                         // 9
\end{verbatim}
The compiler associates a \emph{direct match count} value to each of the
viable functions. The direct match count counts the number of arguments that
can be matched to function parameters without an (automatic) type
conversion. E.g., for function 2 this count equals 2, for function 7 it is 1
and for function 9 it is 0. The functions are now (decrementally) sorted by
their direct match count values:
        \begin{verbatim}
                                                             match
                                                             count
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  2 // 2
    void process(T [= int] const &t, int i);                   2 // 4
    void process<int, int>(int i1, int i2);                    2 // 5
    void process(int i1, int i2);                              2 // 6
    void process(T [= int] const &t, double d);                1 // 3
    void process(int i, double d);                             1 // 7
    void process(double d, int i);                             1 // 8
    void process(double d1, double d2);                        0 // 9
\end{verbatim}
If there is no draw for the top value the corresponding function is
selected and the function selection process is completed.

When multiple functions appear at the top the compiler verifies that no
ambiguity has been encountered. An ambiguity is encountered if the
\emph{sequences} of parameters for which type conversions were (not) required
differ. As an example consider functions 3 and 8. Using D for `direct match'
and C for `conversion' the arguments match function 3 as D,C and function 8 as
C,D. Assuming that 2, 4, 5 and 6 were not available, then the compiler would
have reported an ambiguity as the sequences of argument/parameter matching
procedures differ for functions 3 and 8. The same difference is encountered
comparing functions 7 and 8, but no such difference is encountered comparing
functions 3 and 7.

At this point there is a draw for the top value and the compiler
proceeds with the subset of associated functions (functions 2, 4, 5 and
6). With each of these functions an `ordinary parameter count' is associated
counting the number of non-template parameters of the functions. The functions
are decrementally sorted by this count, resulting in:
        \begin{verbatim}
                                                         ordin. param.
                                                             count
    void process(int i1, int i2);                              2 // 6
    void process(T [= int] const &t, int i);                   1 // 4
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  0 // 2
    void process<int, int>(int i1, int i2);                    0 // 5
\end{verbatim}
Now there is no draw for the top value. The corresponding function
(\texttt{process(int, int)}, function 6) is selected and the function selection
process is completed. Function 6 is used in \texttt{main}'s function call
statement.

Had function 6 not been defined, function 4 would have been used. Assuming
that neither function 4 nor function 6 had been defined, the selection
process would continue with functions 2 and 5:
        \begin{verbatim}
                                                         ordin. param.
                                                             count
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  0 // 2
    void process<int, int>(int i1, int i2);                    0 // 5
\end{verbatim}
In this situation a draw is encountered once again and the selection
process continues. A `type of function' value is associated with each of the
functions having the highest ordinary parameter count and these functions are
decrementally sorted by their type of function values. Value 2 is associated
to ordinary functions, value 1 to template explicit specializations and value
0 to plain function templates.

If there is no draw for the top value the corresponding function is
selected and the function selection process is completed. If there is a draw
the compiler reports an ambiguity and cannot determine which function to
call.  Assuming only functions 2 and 5 existed then this selection step
would have resulted in the following ordering:
        \begin{verbatim}
                                                           function
                                                             type
    void process<int, int>(int i1, int i2);                    1 // 5
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  0 // 2
\end{verbatim}
Function 5, the template explicit specialization, would have been
selected.
    \begin{figure}[tbp]
\centerline{\epsffile{functiontemplates/selection.eps}}
\caption{\label{selection}The function template selection mechanism}
\end{figure}
 Here is a summary of the function template selection mechanism (cf. figure
Figure \ref{selection}):
    \begin{itemize}
    \item  The set of candidate functions is constructed: identical names;
    \item  The set of viable functions is constructed: correct number of
        parameters and available type conversions;
    \item  Template type determination, dropping templates whose type parameters
        cannot be determined;
    \item  Decrementally sort the functions by their direct match count
        values. If there is no draw for the top value the associated function
        is selected, completing the selection process.
    \item  Inspect the functions associated with the top value for ambiguities
        in automatic type conversion sequences. If different sequences are
        encountered report an ambiguity and terminate the selection process.
    \item  Decrementally sort the functions associated with the top value by
        their ordinary parameter count values.  If there is no draw for the
        top value the associated function is selected, completing the
        selection process.
    \item  Decrementally sort the functions associated with the top value by
        their function type values using 2 for ordinary functions, 1 for
        template explicit specializations and 0 for plain function templates.
        If there is no draw for the top value the associated function is
        selected, completing the selection process.
    \item  Report an ambiguity and terminate the selection process.
    \end{itemize}

\section{SFINAE: Substitution Failure Is Not An Error}\label{SFINAE}
\typeout{Original Yodl file: functiontemplates/sfinae}Consider the following struct definition:
        \begin{verbatim}
    struct Int
    {
        using type = int;
    };
\end{verbatim}
Although at this point it may seem strange to embed a using declaration in a
struct, in chapter \ref{ADVANCEDTEMPL} we will encounter situations where this
is actually very useful.  It allows us to define a variable of a type that is
required by the template. E.g., (ignore the use of \texttt{typename} in the
following function parameter list, but see section \ref{DISTINGUISH} for
details):
        \begin{verbatim}
    template <typename Type>
    void func(typename Type::type value)
    {
    }
\end{verbatim}
When calling \texttt{func(10)} \texttt{Int} has to be specified explicitly since
there may be many structs that define \texttt{type}: the compiler needs some
assistance. The correct call is \texttt{func$<$Int$>$(10)}. Now that it's clear that
\texttt{Int} is meant, and the compiler correctly deduces that \texttt{value} is an
\texttt{int}.

But templates may be overloaded and our next definition is:
        \begin{verbatim}
    template <typename Type>
    void func(Type value)
    {}
\end{verbatim}
Now, to call this function we specify \texttt{func$<$int$>$(10)} and
again this flawlessly compiles.

But as we've seen in the previous section when the compiler determines
which template to instantiate it creates a list of viable functions and
selects the function to instantiate by matching the parameter types of viable
functions with the provided actual argument types. To do so it has to
\emph{determine} the types of the parameters and herein lies a problem.

When evaluating \texttt{Type = int} the compiler encounters the prototypes
\texttt{func(int::type)} (first template definition) and \texttt{func(int)} (second
template definition). But there is no \texttt{int::type}, and so in a way this
generates an error. The error results from matching the provided template type
argument with the types used in the various template definitions.

A type-problem caused by substituting a type in a template definition is,
however, \emph{not} considered an error, but merely an indication that that
particular type cannot be used in that particular template. The template is
therefore removed from the list of candidate functions.

This principle is known as \index{substitution failure}\emph{substitution failure} \emph{is not an error}
\index{SFINAE}(SFINAE) and it is often used by the compiler to select not only a
simple overloaded function (as shown here) but also to choose among available
template specializations (see also sections \ref{CLASSORNOT} and \ref{TYPECONV}).

\section{Conditional function definitions using `if constexpr'}\label{IFCONST}
\typeout{Original Yodl file: functiontemplates/ifconst}In addition to the common \texttt{if (cond)} selection statement the \texttt{if
constexpr (cond)} syntax is supported by the language. Although it can be used
in all situations where a standard \texttt{if} selection statement are used, its
specific use is encountered inside function templates: \index{if constexpr}\texttt{if constexpr} allows
the compiler to (conditionally) instantiate elements of a template function,
depending on the compile-time evaluation of the \texttt{if constexpr's (cond)}
clause.

Here is an example:
    \begin{verbatim}
     1: void positive();
     2: void negative();
     3: 
     4: template <int value>
     5: void fun()
     6: {
     7:     if constexpr (value > 0)
     8:         positive();
     9:     else if constexpr (value < 0)
    10:         negative();
    11: }
    12: 
    13: int main()
    14: {
    15:     fun<4>();
    16: }
\end{verbatim}
\begin{itemize}
    \item  At lines 7 and 9 \texttt{if constexpr} statements start. Since \texttt{value}
        is a template non-type parameter its value is compile-time available,
        and so are the values of the condition sections.
    \item  In line 15 \texttt{fun$<$4$>$()} is called: the condition in line 7 is
        therefore \texttt{true}, and the condition in line 9 is \texttt{false}.
    \item  The compiler therefore instantiates \texttt{fun$<$4$>$()} this way:
        \begin{verbatim}
    void fun<4>()
    {
        positive();
    }
\end{verbatim}
\end{itemize}
    Note that the \texttt{if constexpr} statements themselves do not result in
executable code: it is used by the compiler to \emph{select} which part (or
parts) it should instantiate. In this case only \texttt{positive}, which must be
available before the program's linking phase can properly complete.

\section{Summary of the template declaration syntax}
\typeout{Original Yodl file: functiontemplates/summary}In this section the basic syntactic constructions for declaring templates
are summarized. When \emph{defining} templates, the terminating
semicolon should be replaced by a function body.

Not every template declaration may be converted into a template definition. If
a definition may be provided it is explicitly mentioned.
    \begin{itemize}
    \item  A plain template declaration (a definition may be provided):
    \begin{verbatim}
template <typename Type1, typename Type2>
void function(Type1 const &t1, Type2 const &t2);
\end{verbatim}
\item  A template instantiation declaration (no definition may be provided):
    \begin{verbatim}
template
void function<int, double>(int const &t1, double const &t2);
\end{verbatim}
\item  A template using explicit types (no definition may be provided):
    \begin{verbatim}
void (*fp)(double, double) = function<double, double>;
void (*fp)(int, int) = function<int, int>;
\end{verbatim}
\item  A template explicit specialization (a definition may be provided):
    \begin{verbatim}
template <>
void function<char *, char *>(char *const &t1, char *const &t2);
\end{verbatim}
\item  A template declaration declaring friend function templates within
        \index{class template: friend function template} class templates (covered
in section \ref{TEMPFRIENDS}, no definition may be provided):
    \begin{verbatim}
friend void function<Type1, Type2>(parameters);
\end{verbatim}
\end{itemize}

\section{Variables as templates (template variables)}
\typeout{Original Yodl file: functiontemplates/variables.yo}In addition to function templates and class templates (cf. chapter
\ref{TEMPCLASS}) \textbf{C++} supports \emph{variable templates}. Variable templates
might come in handy when defining (function or class) templates defining
variables of types specified by template type parameters.

A variable template starts with a familiar \texttt{template} header, followed by
the definition of the variable itself. The template header specifies a type,
for which a default type may also be specified. E.g.,
        \begin{verbatim}
    template<typename T = long double>
    constexpr T pi = T(3.1415926535897932385);
\end{verbatim}
To use this variable a type must be specified, and as long as the initialized
value can be converted to the specified type the conversion is silently 
performed by the compiler:
        \begin{verbatim}
    cout << pi<> << ' ' << pi<int>;
\end{verbatim}
At the second insertion the \texttt{long double} initialization value is
converted to \texttt{int}, and 3 is displayed.

Specializations are also supported. E.g., to show the text `pi' a
specialization for a \texttt{char const $*$} type can be defined:
        \begin{verbatim}
    template<>
    constexpr char const *pi<char const *> = "pi";
\end{verbatim}
With this specialization we can do \texttt{cout $<$$<$ pi$<$char const $*$$>$} to show
\texttt{pi}.


\cleardoublepage\chapter{Class Templates}\label{TEMPCLASS}
\typeout{Original Yodl file: classtemplates}\typeout{Original Yodl file: classtemplates/intro}Templates can not only be constructed for functions but also for complete
classes. Consider constructing a \index{class template}class template when a class should be able
to handle different types of data. Class templates are frequently used in
\textbf{C++}: chapter \ref{CONTAINERS} discusses data structures like \texttt{vector,
stack} and \texttt{queue}, that are implemented as \emph{class templates}. With class
templates, the algorithms and the data on which the algorithms operate are
completely separated from each other. To use a particular data structure in
combination with a particular data type only the data type needs to be
specified when defining or declaring a class template object (as in
\texttt{stack$<$int$>$ iStack}).

In this chapter constructing and using class templates is discussed. In a
sense, class templates compete with object oriented programming (cf. chapter
\ref{POLYMORPHISM}), that uses a mechanism resembling that of
templates. Polymorphism allows the programmer to postpone the implementation
of algorithms by deriving classes from base classes in which algorithms are
only partially implemented. The actual definition and processing of the data
upon which the algorithms operate may be postponed until derived classes are
defined. Likewise, templates allow the programmer to postpone the
specification of the data upon which the algorithms operate. This is most
clearly seen with abstract containers, which completely specify the algorithms
and at the same time leave the data type on which the algorithms operate
completely unspecified. 

There exists an intriguing correspondence between the kind of polymorphism
we've encountered in chapter \ref{POLYMORPHISM} and certain uses of class
templates.  In their book \textbf{C++ Coding Standards} (Addison-Wesley, 2005)
        \index{Sutter, H.}\index{Alexandrescu, A.}
    Sutter and Alexandrescu refer to
        \index{static polymorphism}\emph{static polymorphism}\index{polymorphism: static} and
        \index{polymorphism: dynamic} \index{dynamic polymorphism}\emph{dynamic polymorphism}.
    \emph{Dynamic} polymorphism is what we use when overriding virtual members.
Using \emph{vtable}s the function that is actually called depends on the type of
object a (base) class pointer points at. \emph{Static} polymorphism is
encountered in the context of templates, and is discussed and compared to
dynamic polymorphism in section \ref{STATICPOLY}.

Generally, class templates are easier to use than polymorphism. It is
certainly easier to write \texttt{stack$<$int$>$ istack} to create a stack of \texttt{ints}
than to derive a new class \texttt{Istack: public stack} and to implement all
necessary member functions defining a similar stack of \texttt{ints} using object
oriented programming. On the other hand, for each different type for which an
object of a class template is defined another, possibly complete class must be
reinstantiated.  This is not required in the context of object oriented
programming where derived classes \emph{use}, rather than \emph{copy}, the functions
that are already available in their base classes (but see also section
\ref{DERIVEDTEMPCLASS}).

Previously we've already used class templates. Objects like \texttt{vector$<$int$>$ vi}
and \texttt{vector$<$string$>$ vs} are commonly used. The data types for which these
templates are defined and instantiated are an inherent part of such container
types. It is stressed that it is the \emph{combination} of a class template type
and its template parameter(s), rather than the mere class template's type
that defines or generates a
 \index{class template: generate types} type. So \texttt{vector$<$int$>$} is a type as is
\texttt{vector$<$string$>$}. Such types could very well be specified through
using-declarations: 
        \begin{verbatim}
    using IntVector =  std::vector<int>;
    using StringVector = std::vector<std::string>;

    IntVector vi;
    StringVector vs;
\end{verbatim}
Like function templates, class templates, both the class interface and the
implementations of the class member functions, must be available at their
points of instantiation. Therefore the interfaces and implementations of class
templates are commonly provided in a header file, which is then included by
source files using those classes (see also section \ref{NAMERESFUN}).

\subsection{Template Argument Deduction}\label{ARGDEDUCTION}
    \typeout{Original Yodl file: classtemplates/argdeduction}One important difference between function templates and class templates is
that the template arguments of function templates can normally be deduced by
the compiler, whereas template arguments of class templates may have to be 
specified by the user. That's not always required, but since the template
types of class templates are an inherent part of the class template's type it
must be completely clear to the compiler what the class template's types are.

So, in case we have a 
    \begin{verbatim}
    template <typename T>
    void fun(T const &param);
\end{verbatim}
we can do
    \begin{verbatim}
    vector<int> vi;
    fun(vi)
\end{verbatim}
and the compiler deduces \texttt{T == vector$<$int$>$}. 

On the other hand,  if we have
    \begin{verbatim}
    template <typename T>
    struct Fun
    {
        T d_data;
        Fun();
    };
\end{verbatim}
we can\textbf{not} do
    \begin{verbatim}
    Fun fun;
\end{verbatim}
since \texttt{Fun} is not a type, and the compiler cannot deduce what the intended
type is.

Sometimes the compiler \emph{can} deduce the intended types. Consider this:
    \begin{verbatim}
    vector vi{ 1, 2, 3, 4 };
\end{verbatim}
In this case the compiler deduces \texttt{int} from the provided values. The
compiler is smart enought to select the most general type, as in this example,
where \texttt{double} is deduced:
    \begin{verbatim}
    vector vi{ 1, 2.5 };
\end{verbatim}
The compiler is doing its utmost to deduce types when they're not
explicitly specified, and it will stay on the safe side. So the vector is a
\texttt{vector$<$int$>$} in the first example and a \texttt{vector$<$double$>$} in the second. 

Although it's nice that the compiler is willing and able to deduce types in
many situations it's at the same time a potential source of confusion. In the
first example only non-negative values are used, so why not define a
\texttt{vector$<$unsigned$>$} or a \texttt{vector$<$size\_t$>$}? In the second example the
compiler deduces \texttt{vector$<$double$>$}, but \texttt{vector$<$float$>$} could very well
also have been used. 

To avoid confusion, as a \index{rule of thumb}rule of thumb, it might be a good idea to specify
the types of class templates when defining class type objects. It requires
hardly any effort and it completely clarifies what you want and mean. So
prefer
    \begin{verbatim}
    vector<int>     vi{ 1, 2, 3 };
    vector<double>  vd{ 1, 2.5 };
\end{verbatim}
over the definitions implicitly using types.

\subsubsection{Simple Definitions}
        \typeout{Original Yodl file: classtemplates/simple}Here are some examples of how simple definitions where the compiler deduces
template arguments can (and cannot) be specified. 

Starting point:
    \begin{verbatim}
    template <class ...Types>           // any set of types
    class Deduce
    {
        public:
            Deduce(Types ...params);    // constructors
            void fun();                 // a member function
    };
\end{verbatim}
Some definitions:
        \begin{verbatim}
                                    // deduce:     full definition:
                                    // --------------------------------
    Deduce first{1};                // 1: int   -> Deduce<int> first{1} 
    Deduce second;                  // no Types -> Deduce<> second;  
    Deduce &&ref = Deduce<int>{ 1 };// int      -> Deduce<int> &&ref

    template <class Type>
    Deduce third{ static_cast<Type *>(0) };
\end{verbatim}
The template \texttt{third} is a recipe for constructing \texttt{Deduce}
objects from a type that's specified for \texttt{third}. The pointer's type simply 
is a pointer to the specified type (so, specifying \texttt{third$<$int$>$} implies an
\texttt{int $*$}). Now that the type of \texttt{third}'s argument is available (i.e., an
\texttt{int $*$}) the compiler deduces that \texttt{third\{0\}} is a \texttt{Deduce$<$int $*$$>$}.

This \texttt{Deduce$<$int $*$$>$} object could, e.g., be used to initialize a named
\texttt{Deduce$<$int $*$$>$} object:
        \begin{verbatim}
    auto x = third<int>;        // x's full definition: Deduce<int *> x{0}
\end{verbatim}
\texttt{Deduce's} member functions can be used by anonymous and named objects:
        \begin{verbatim}
    x.fun();                    // OK: fun called by named object
    third<int>.fun();           // OK: fun called by anonymous object
\end{verbatim}
Here are some examples that won't compile:
        \begin{verbatim}
    extern Deduce object;       // not an object definition
    Deduce *pointer = 0;        // any set of types could be intended
    Deduce function();          // same.
\end{verbatim}
When defining objects, either using function-type or curly brace definitions
template argument deduction is realized as follows:
    \begin{itemize}
    \item  First, a list of available constructors is formed. The list contains
all available ordinary constructors and constructor templates (i.e,
constructors defined as member templates);
    \item  For each element of that list a parallel imaginary function
is formed by the compiler (forming function templates for constructor
templates, and ordinary functions for ordinary constructors);
    \item  The return types of these imaginary functions are the class types of
the constructors, using the template parameters of the original class
template. For example, for the \texttt{Deduce::Deduce} constructor the imaginary
function 
        \begin{verbatim}
    template <class ...Types>
    Deduce<Types ...> imaginary(Types ...params);
\end{verbatim}
is formed.
    \item  Next, ordinary argument deduction and overload resolution is applied
to the set of imaginary functions. If this results in a best match for 
one of these imaginary functions then that function's class type (or
specialization) will be used. Otherwise the program is ill-formed.
    \end{itemize}

Let's apply this process to the class \texttt{Deduce}. The set of imaginary
functions matching \texttt{Deduce} looks like this:
        \begin{verbatim}
                                        // already encountered: matching
    template <class ...Types>           // Deduce(Types ...params)
    Deduce<Types ...> imaginary(Types ...params);

                                        // the copy constructor: matching
    template <class ...Types>           // Deduce(Deduce<Types ...> const &)
    Deduce<Types ...> imaginary(Deduce<Types ...> const &other);
                                    
                                        // the move constructor, matching
    template <class ...Types>           // Deduce(Deduce<Types ...> &&)
    Deduce<Types ...> imaginary(Deduce<Types ...> &&tmp);
\end{verbatim}
For the construction \texttt{Deduce first\{1\}} the first imaginary function wins
the overload contest, resulting in the template argument deduction \texttt{int} for
\texttt{class ...Types}, and hence \texttt{Deduce$<$int$>$ first\{1\}} is defined.

Note that when a class template is nested under a class template, the nested
class template's name depends on the outer class type. The outer class then
provides the name qualifier for the inner class template. In such cases
template argument deduction is used for the nested class, but (as it is not
used for name qualifiers) is not used for the outer class. Here is an example:
adding a nested class template to \texttt{Outer}:

\begin{verbatim}
    template <class OuterType>
    class Outer
    {
        public:
            template <class InnerType>
            struct Inner
            {
                Inner(OuterType);
                Inner(OuterType, InnerType);
                template <typename ExtraType>
                Inner(ExtraType, InnerType);
            };
    };
    // defining:
    Outer<int>::Inner inner{2.0, 1};
\end{verbatim}
In this case, the compiler uses these imaginary functions:
    \begin{verbatim}
    template <typename InnerType>
    Outer<int>::Inner<InnerType>            // copy constructor
        imaginary(Outer<int>::Inner<InnerType> const &);

    template <typename InnerType>       
    Outer<int>::Inner<InnerType>            // move constructor
        imaginary(Outer<int>::Inner<InnerType> &&);

    template <typename InnerType>           // first declared constructor
    Outer<int>::Inner<InnerType> imaginary(int);

    template <typename InnerType>           // second declared constructor
    Outer<int>::Inner<InnerType> imaginary(int, InnerType);

    template <typename InnerType>           // third declared constructor
    template <typename ExtraType>       
    Outer<int>::Inner<InnerType> imaginary(ExtraType, InnerType);
\end{verbatim}
Template argument deduction for calling  \texttt{imaginary(2.0, 1)} results in
\texttt{double} for its first argument and \texttt{int} for its second. Overload
resolution then favors the last imaginary function, and so \texttt{ExtraType:
double} and \texttt{InnerType: int}. Consequently, 
    \begin{verbatim}
    Outer<int>::Inner inner{ 2.0, 1 };
\end{verbatim}
is defined as:
    \begin{verbatim}
    Outer<int>::Inner<int> Inner{ 2.0, 1 };
\end{verbatim}
\subsubsection{Explicit Conversions}
        \typeout{Original Yodl file: classtemplates/explicit}Have a look at the following class interface:
        \begin{verbatim}
    template <class T>
    struct Class
    {
        std::vector<T> d_data;

        struct Iterator
        {
            using type = T;
            bool operator!=(Iterator const &rhs);
            Iterator operator++(int);
            type const &operator*() const;
            // ... 
        };
    
        Class();

        Class(T t);

        Class(Iterator begin, Iterator end);
    
        template <class Tp>
        Class(Tp first, Tp second)
        {}

        Iterator begin();
        Iterator end();
    };
\end{verbatim}
The implementation of the \texttt{Class} constructor expecting two
\texttt{Class::Iterator} arguments would probably be somewhat similar to the
following: 
        \begin{verbatim}
    template <class T>
    Class<T>::Class(Iterator begin, Iterator end)
    {
        while (begin != end)
            d_data.push_back(*begin++);
    }
\end{verbatim}
where \texttt{d\_data} is some container storing \texttt{T} values. A
\texttt{Class} object can now constructed from a pair of \texttt{Class::Iterators}:
        \begin{verbatim}
    Class<int> source;      
    ...
    Class<int> dest{source.begin(), source.end()};
\end{verbatim}
Here, the simple template argument deduction procedure fails to deduce the
\texttt{int} template argument. This fails:
        \begin{verbatim}
    Class dest{source.begin(), source.end()};
\end{verbatim}
When attempting to instantiate a \texttt{Class} object by passing it
\texttt{Class::Iterators} the compiler cannot directly deduce from the provided
arguments that a \texttt{Class$<$Class::Iterator::type$>$} is to be used: \texttt{type}
isn't directly available. Compare this to \texttt{Class's} third constructor,
where
    \begin{verbatim}
    Class intObject{12};
\end{verbatim}
allows the compiler to create an imaginary function 
        \begin{verbatim}
    template <class Type>
    Class <Type> imaginary(Type param)
\end{verbatim}
in which case \texttt{Type} clearly is an \texttt{int}, and so a \texttt{Class$<$int$>$}
object is constructed.

When we try to do this for \texttt{Class(Iterator, Iterator)} we get
        \begin{verbatim}
    template <class Iterator>
    Class<???> imaginary(Iterator, Iterator);
\end{verbatim}
and here \texttt{Class's} template argument isn't directly related to
\texttt{Iterator}: the compiler cannot deduce its type and consequently compilation
fails. 

A similar argument applies to the fourth constructor, which receives two \texttt{Tp}
arguments, which are both independent from \texttt{Class's} template type. 

In cases like these simple type template argument deduction procedure
fails. Still, not everything is lost: \index{explicit conversions}\emph{explicit conversions}, defined as
\emph{explicitly specified} \index{deduction rules}\emph{deduction rules} which are added (below) to the
class's interface can be used.

An explicitly specified deduction rule connects a class template constructor
signature to a class template type. It specifies the template arguments for
the class template object that is constructed using the constructor whose
signature is specified. The generic syntactical form of an explicitly
specified deduction rule looks like this:
        \begin{verbatim}
    class template constructor signature -> resulting class type ;
\end{verbatim}
Let's apply this to \texttt{Class(Iterator begin, Iterator end)}. Its signature is
        \begin{verbatim}
    template <class Iterator>
    Class(Iterator begin, Iterator end)
\end{verbatim}
Requiring that \texttt{Iterator} defines a typename \texttt{type}, we can now formulate
a resulting class type:
        \begin{verbatim}
    Class<typename Iterator::type>
\end{verbatim}
Now we can combine both in an explicitly specified deduction rule (which is
added as a separate line below \texttt{Class's} interface):
        \begin{verbatim}
    template <class Iterator>
    Class(Iterator begin, Iterator end) -> Class<typename Iterator::type>;
\end{verbatim}
After adding this deduction rule to \texttt{Class's} interface the following
constructor calls successfully compile:
        \begin{verbatim}
    Class src{12};      // already OK

    Class dest1{src.begin(), src.end()};
                        // begin() and end() return Class<int>::Iterator
                        // objects. Typename Class<int>::Iterator::type
                        // is defined as int, so Class<int> dest1 is
                        // defined.

    struct Double       // used at the next construction
    {
        using type = double;
        // ... members ...
    };

    Class dest2{Double{}, Double{}};
                        // Here the struct Double defines 
                        // typename double type, so
                        // Class<double> dest2 is defined.
\end{verbatim}
\emph{Within} classes the compiler uses (as before) the class itself when merely
referring to the class name: when referring to \texttt{Class} in the class
\texttt{Class}, the compiler considers \texttt{Class} to be \texttt{Class$<$T$>$}. So the headers
of the declaration and definition of \texttt{Class's} copy constructor look like
this:
        \begin{verbatim}
    Class(Class const &other);      // declaration

    template <class T>              // definition
    Class<T>::Class(Class const &other)
    { 
        // ... 
    }
\end{verbatim}
Sometimes the default type is not what you want, in which case the required
type must explicitly be specified. Consider what happens if add a
member \texttt{dup} to \texttt{Class}:
    \begin{verbatim}
    template <typename T>
    template <typename Tp>
    auto Class<T>::dup(Tp first, Tp second)
    {
        return Class{ first, second };  // probably not what you want
    }                                   // (see the following text)
\end{verbatim}
Here, because we're inside \texttt{Class} the compiler deduces that
\texttt{Class$<$T$>$} must be returned. But in the previous section we decided that,
when initializing \texttt{Class} from iterators, \texttt{Class$<$typename Tp::type$>$}
should be constructed and returned. To accomplish that, the required type is
explicitly specified:
    \begin{verbatim}
    template <typename T>
    template <typename Tp>
    auto Class<T>::dup(Tp first, Tp second)
    {                               // OK: explicitly specified Class tyoe.
        return Class<typename Tp::type>{ first, second };
    }
\end{verbatim}
As shown in this example, simple (implicit) or explicit deduction rules do not
\emph{have} to be used: they \emph{can} be used in many standard situations where
explicitly specifying the class's template arguments appears to be
superfluous. Template argument deduction was added to the language to simplify
object construction when using class templates. But in the end you don't
\emph{have} to use these deduction rules: it's always still possible to
explicitly specify template arguments.

\section{Defining class templates}\label{TEMPCLASSDEF}
\typeout{Original Yodl file: classtemplates/definitions}Having covered the construction of function templates, we're now ready for the
next step: constructing class templates. Many useful class templates already
exist. Rather than illustrating the construction of a class template by
looking at an already existing class template the construction of another
potentially useful new class template will be undertaken.

The new class implements a \index{circular queue}\emph{circular queue}.  A circular queue has a fixed
number of \texttt{max\_size} elements. New elements are inserted at its back and
only its head and tail elements can be accessed. Only the head element can be
removed from a circular queue. Once \texttt{n} elements have been appended the next
element is inserted again at the queue's (physical) first position. The
circular queue allows insertions until it holds \texttt{max\_size} elements. As long
as a circular queue contains at least one element elements may be removed from
it. Trying to remove an element from an empty circular queue or to add another
element to a full circular queue results in exceptions being thrown. In
addition to other constructors a circular queue must offer a constructor
initializing its objects for \texttt{max\_size} elements. This constructor must make
available the memory for the \texttt{max\_size} elements but must not call those
elements default constructors (hinting at the use of the placement \texttt{new}
operator). A circular queue should offer value semantics as well as a move
constructor.

Please note that in the above description the actual data type that is used
for the circular queue is nowhere mentioned. This is a clear indication that
our class could very well be defined as a
 \index{template: class}\index{class template}\emph{class template}. Alternatively, the class could be
defined for some concrete data type which is then abstracted when converting
the class to a class template.

The actual construction of a class template is provided in the next section,
where the class template \texttt{CirQue} (circular queue) is developed.

\subsection{Constructing the circular queue: CirQue}
    \typeout{Original Yodl file: classtemplates/cirque}The construction of a class template is illustrated in this section. Here,
we'll develop the class template \texttt{CirQue} (circular queue). This class
template has one template type parameter, \texttt{Data}, representing the data type
that is stored in the circular queue. The outline of the interface of this
class template looks like this:
    \index{template parameter list}
        \begin{verbatim}
    template<typename Data>
    class CirQue
    {
        // member declarations
    };
\end{verbatim}
A class template's definition starts like a function template's
definition:
    \begin{itemize}
    \item  The keyword \index{template}\texttt{template}, starting a template definition or
declaration.
    \item  The angle bracket enclosed list following \texttt{template}: a
list containing one or more comma-separated elements is called the
 \index{template parameter list}\emph{template parameter list}. Template parameter lists may have multiple
elements, like this:
        \begin{verbatim}
    typename Type1, typename Type2, typename Type3
\end{verbatim}
When a class template defines multiple template type parameters they are
matched in sequence with the list of template type arguments provided when
defining objects of such a class template. Example:
        \begin{verbatim}
template <typename Type1, typename Type2, typename Type3>
class MultiTypes
{
    ...
};

MultiTypes<int, double, std::string> multiType;
    // Type1 is int, Type2 is double, Type3 is std::string
\end{verbatim}
\item  Inside the template parameter list we find the \index{formal type}\emph{formal type} name
(\texttt{Data} for \texttt{CirQue}). It is a formal (type) name, like the formal types
used in function template parameter lists.
    \item  Following the template header the class interface is defined. It may
use the formal type names defined in the template header as type names.
    \end{itemize}
    Once the \texttt{CirQue} class template has been defined it can be used to
create all kinds of circular queues. As one of its constructors expects a
\texttt{size\_t} argument defining the maximum number of elements that can be stored
in the circular queue, circular queues could be defined like this:
        \begin{verbatim}
    CirQue<int> cqi(10);            // max 10 ints
    CirQue<std::string> cqstr(30);  // max 30 strings
\end{verbatim}
As noted in the introductory section of this chapter the combination of
name of the class template and the data type for which it is instantiated
defines a data type. Also note the similarity between defining a
\texttt{std::vector} (of some data type) and a \texttt{CirQue} (of some data type).

Like \texttt{std::map} containers class templates may be defined with multiple
template type parameters.

Back to \texttt{CirQue}. A \texttt{CirQue} must be capable of storing \texttt{max\_size}
\texttt{Data} elements. These elements are eventually stored in memory pointed at
by a pointer \texttt{Data $*$d\_data}, initially pointing to raw memory. New elements
are added at the backside of the \texttt{CirQue}. A pointer \texttt{Data $*$d\_back} is
used to point to the location where the next element is going to be
stored. Likewise, \texttt{Data $*$d\_front} points to the location of the \texttt{CirQue}'s
first element. Two \texttt{size\_t} data members are used to monitor the filling
state of the \texttt{CirQue}: \texttt{d\_size} represents the number of elements
currently stored in the \texttt{CirQue}, \texttt{d\_maxSize} represents the maximum
number of elements that the \texttt{CirQue} can contain. Thus, the \texttt{CirQue}'s
data members are:
    \begin{verbatim}
    size_t d_size;
    size_t d_maxSize;
    Data *d_data;
    Data *d_front;
    Data *d_back;
\end{verbatim}
\subsection{Non-type parameters}
    \typeout{Original Yodl file: classtemplates/nontype}Function template parameters are either template type parameters or template
non-type parameters (actually, a third type of template parameter exists, the
\emph{template template parameter}, which is discussed in chapter
\ref{ADVANCEDTEMPL} (section \ref{TEMPTEMPPAR})).

Class templates \index{class template: non-type parameter} may also define
non-type parameters. Like the function template non-type parameters they must
be (integral) constants whose values must be known at object instantiation
time.

Different from function template non-type parameters the values of class
template non-type parameters are \emph{not} deduced by the compiler using
arguments passed to class template members.

Assume we extend our design of the class template \texttt{CirQue} so that it
defines a second (non-type) parameter \texttt{size\_t Size}. Our intent is to use
this \texttt{Size} parameter in the constructor defining an array parameter of
\texttt{Size} elements of type \texttt{Data}.

The  \texttt{CirQue} class template now becomes (only showing the relevant
constructor):
        \begin{verbatim}
    template <typename Data, size_t Size>
    class CirQue
    {
        // ... data members
        public:
            CirQue(Data const (&arr)[Size]);
            ...
    };

    template <typename Data, size_t Size>
    CirQue<Data, Size>::CirQue(Data const (&arr)[Size])
    :
        d_maxSize(Size),
        d_size(0),
        d_data(operator new(Size * sizeof(Data))),
        d_front(d_data),
        d_back(d_data),
    {
        std::copy(arr, arr + Size, back_inserter(*this));
    }
\end{verbatim}
Unfortunately, this setup doesn't satisfy our needs as  the values of
template non-type parameters are not deduced by the compiler. When the
compiler is asked to compile the following \texttt{main} function it reports a
mismatch between the required and actual number of template parameters:
        \begin{verbatim}
    int main()
    {
        int arr[30];

        CirQue<int> ap{ arr };
    }
    /*
        Error reported by the compiler:

        In function `int main()':
            error: wrong number of template arguments (1, should be 2)
            error: provided for `template<class Data, size_t Size>
                   class CirQue'
    */
\end{verbatim}
Defining \texttt{Size} as a non-type parameter having a default value doesn't
work either. The compiler always uses the default unless its value is
explicitly specified. Reasoning that \texttt{Size} can be 0 unless we need another
value, we might be tempted to specify \texttt{size\_t Size = 0} in the template's
parameter type list.  Doing so we create  a mismatch between the default
value 0 and the actual size of the array \texttt{arr} as defined in the above
\texttt{main} function. The compiler, using the default value, reports:
        \begin{verbatim}
    In instantiation of `CirQue<int, 0>':
    ...
    error: creating array with size zero (`0')
\end{verbatim}
So, although class templates may use non-type parameters they must always
be specified like type parameters when an object of that class is
defined. Default values can be specified for those non-type parameters causing
the compiler to use the default when the non-type parameter is left
unspecified.

\index{template parameter: default value} Default template parameter values
(either type or non-type template parameters) may \emph{not} be specified when
defining template member functions. In general: function template definitions
(and thus: class template member functions) may not be given default template
(non) type arguments. If default template arguments are to be used for class
template members, they \emph{have} to be specified by the class interface.

Similar to non-type parameters of function templates default argument
values for non-type class template parameters may only be specified as
constants:
    \begin{itemize}
    \item  Global \index{global variable} variables have constant addresses, which
can be used as arguments for non-type parameters.
    \item  Local \index{local variables} and \index{dynamically allocated variables}dynamically allocated variables have
addresses that are \emph{not} known by the compiler when the source file is
compiled. These addresses can therefore \emph{not} be used as arguments for
non-type parameters.
    \item  Lvalue \index{lvalue transformations} transformations are allowed: if a
pointer is defined as a non-type parameter, an array name may be specified.
    \item  \index{conversions} Qualification \index{qualification conversions}
conversions are allowed: a pointer to a non-const object may be used with a
non-type parameter defined as a \texttt{const} pointer.
    \item  Promotions \index{promotions} are allowed: a constant of a `narrower'
data type may be used when specifying a default argument for a non-type
parameter of a `wider' type (e.g., a \texttt{short} can be used when an \texttt{int} is
called for, a \texttt{long} when a \texttt{double} is called for).
    \item  Integral \index{integral conversions} conversions are allowed: if a
\texttt{size\_t} parameter is specified, an \texttt{int} may be used as well.
    \item  Variables cannot be used to specify template non-type parameters as
their values are not constant expressions. Variables defined using the
\texttt{const} modifier, however, may be used as their values never change.
    \end{itemize}

Although our attempts to define a constructor of the class \texttt{CirQue}
accepting an array as its argument has failed so far, we're not yet out of
options. In the next section a method is described that \emph{does} allow us
to reach our goal.

\subsection{Member templates}\label{MEMTEMP}
    \typeout{Original Yodl file: classtemplates/membertemplates}Our previous attempt to define a template non-type parameter that is
initialized by the compiler to the number of elements of an array failed
because the template's parameters are not implicitly deduced when a
constructor is called. Instead, they must explicitly be specified when an
object of the class template is defined. As the template arguments are
specified just before the template's constructor is called the compiler
doesn't have to deduce anything and it can simply use the explicitly specified
template arguments.

In contrast, when \emph{function} templates are used, the actual template
parameters are deduced from the arguments used when calling the function. This
opens up an alley leading to the solution of our problem. If the constructor
itself is turned into a function template (having its own template header),
then the compiler \emph{will} be able to deduce the non-type parameter's value
and there is no need anymore to specify it explicitly using a class template
non-type parameter.

Members (functions or nested classes) of class templates that are themselves
templates are called
        \index{member template}
        \index{class template: member template}
 \emph{member templates}.

Member templates are defined as any other template, including its own template
header.

When converting our earlier \texttt{CirQue(Data const (\&array){[}Size{]})} constructor
into a member template the class template's \texttt{Data} type parameter can still
be used, but we must provide the member template with a non-type parameter of
its own. Its declaration in the (partially shown) class interface looks like
this:
        \begin{verbatim}
    template <typename Data>
    class CirQue
    {
        public:
            template <size_t Size>
            explicit CirQue(Data const (&arr)[Size]);
    };
\end{verbatim}
Its implementation becomes:
    \begin{verbatim}
    template <typename Data>
    template <size_t Size>
    CirQue<Data>::CirQue(Data const (&arr)[Size])
    :
        d_size(0),
        d_maxSize(Size),
        d_data(static_cast<Data *>(operator new(sizeof(arr)))),
        d_front(d_data),
        d_back(d_data)
    {
        std::copy(arr, arr + Size, std::back_inserter(*this));
    }
\end{verbatim}
    The implementation uses the STL's \texttt{copy} algorithm and a
\texttt{back\_inserter} adapter to insert the array's elements into the
\texttt{CirQue}. To use the \texttt{back\_inserter} \texttt{CirQue} must provide two (public)
using-declarations (cf. section \ref{INSERTER}):
    \begin{verbatim}
    using value_type = Data;
    using const_reference = value_type const &;
\end{verbatim}
Member templates have the following characteristics:
    \begin{itemize}
    \item  Two \texttt{template}
            \index{template header: for member templates}
     headers must be used: the class template's \texttt{template}
header is specified first followed by the member template's template header;
    \item  Normal access rules apply: the member template can be
used by programs to construct an \texttt{CirQue} object of a given data
type. As usual for class templates, the data type must be specified when the
object is constructed. To construct a \texttt{CirQue} object from the array
\texttt{int array{[}30{]}} we define:
        \begin{verbatim}
CirQue<int> object(array);
\end{verbatim}
\item  Any member can be defined as a member template, not just a
constructor;
    \item  When a template member is implemented below its class interface, the
template class header must precede the function template header of the member
template;
    \item  The implementation of the member template must specify its proper
scope.  The member template is defined as a member of the class \texttt{CirQue},
instantiated for the formal template parameter type \texttt{Data};
    \item  The template parameter names in the declaration and
implementation must be identical;
    \item  The member template should be defined inside its proper namespace
environment. The organization of files defining class templates within a
namespace should therefore be:
        \begin{verbatim}
namespace SomeName
{
    template <typename Type, ...>   // class template definition
    class ClassName
    {
        ...
    };

    template <typename Type, ...>   // non-inline member definition(s)
    ClassName<Type, ...>::member(...)
    {
        ...
    }
}                                   // namespace closes
\end{verbatim}
\end{itemize}

A potentially occurring problem remains. Assume that in addition to the
above member template a \texttt{CirQue$<$Data$>$::CirQue(Data const $*$data)} has been
defined. Some (here not further elaborated) protocol could be defined allowing
the constructor to determine the number of elements that should be stored in
the \texttt{CirQue} object. When we now define
        \begin{verbatim}
    CirQue<int> object{ array };
\end{verbatim}
it is this latter constructor, rather than the member template, that the
compiler will use.

The compiler selects this latter constructor as it is a more specialized
version of a constructor of the class \texttt{CirQue} than the member template
(cf. section \ref{FUNCTIONSELECTION}). Problems like these can be solved by
defining the constructor \texttt{CirQue(Data const $*$data)} into a member template
as well or by defining a constructor using two parameters, the second
parameter defining the number of elements to copy.

When using the former constructor (i.e., the member template) it must define a
template type parameter \texttt{Data2}. Here `\texttt{Data}' cannot be used as template
parameters of a member template may not shadow
    \index{class template: shadowing parameters} template parameters of its
class. Using \texttt{Data2} instead of \texttt{Data} takes care of this subtlety. The
following declaration of the constructor \texttt{CirQue(Data2 const $*$)} could
appear in \texttt{CirQue}'s header file:
        \begin{verbatim}
    template <typename Data>
    class CirQue
    {
        template <typename Data2>
        explicit CirQue(Data2 const *data);
    }
\end{verbatim}
Here is how the two constructors are selected in code defining two
\texttt{CirQue} objects:
        \begin{verbatim}
    int main()
    {
        int array[30];
        int *iPtr = array;

        CirQue<int> ac{ array };    // calls CirQue(Data const (&arr)[Size])
        CirQue<int> acPtr{ iPtr };  // calls CirQue(Data2 const *)
    }
\end{verbatim}
\subsection{CirQue's constructors and member functions}
    \typeout{Original Yodl file: classtemplates/cirquemembers}    It's time to return to \texttt{Cirque}'s design and construction again.

The class \texttt{CirQue} offers various member functions.  Normal design
principles should be adhered to when constructing class template
members. Class template type parameters should preferably be defined as
\texttt{Type const \&}, rather than \texttt{Type}, to prevent unnecessary copying of
large data structures. Template class constructors should use member
initializers rather than member assignment within the body of the
constructors. Member function definitions should preferably not be provided
in-class but below the class interface. Since class template member functions
are function templates their  definitions should be provided in the header
file offering the class interface. They \emph{may} be given the \texttt{inline}
attribute.

\texttt{CirQue} declares several constructors and (public) members (their
definitions are provided as well; all definitions are provided below the class
interface).

Here are the constructors and the destructor:

\begin{itemize}
    \item \texttt{explicit CirQue(size\_t maxSize = 0)}:\ \\ Constructor initializing a
        \texttt{CirQue} capable of storing \texttt{max\_size Data} elements. As the
constructor's parameter is given a default argument value this constructor can
also be used as a default constructor, allowing us to define, e.g., vectors of
\texttt{CirQue}s.  The constructor initializes the \texttt{Cirque} object's \texttt{d\_data}
member to a block of raw memory and \texttt{d\_front} and \texttt{d\_back} are initialized
to \texttt{d\_data}. As class template member functions are themselves function
templates their implementations outside of the class template's interface must
start with the class template's template header. Here is the implementation of
the \texttt{CirQue(size\_t)} constructor:
        \begin{verbatim}
    template<typename Data>
    CirQue<Data>::CirQue(size_t maxSize)
    :
        d_size(0),
        d_maxSize(maxSize),
        d_data(
            maxSize == 0 ?
                0
            :
                static_cast<Data *>(
                            operator new(maxSize * sizeof(Data)))
        ),
        d_front(d_data),
        d_back(d_data)
    {}
\end{verbatim}
\item \texttt{CirQue(CirQue$<$Data$>$ const \&other)}:\ \\ The copy constructor has no
special features. It uses a private support member \texttt{inc} to increment
\texttt{d\_back} (see below) and placement new to copy the other's \texttt{Data} elements
to the current object. The implementation of the copy constructor is
straightforward:
        \begin{verbatim}
    template<typename Data>
    CirQue<Data>::CirQue(CirQue<Data> const &other)
    :
        d_size(other.d_size),
        d_maxSize(other.d_maxSize),
        d_data(
            d_maxSize == 0 ?
                0
            :
                static_cast<Data *>(
                    operator new(d_maxSize * sizeof(Data)))
        ),
        d_front(d_data + (other.d_front - other.d_data))
    {
        Data const *src = other.d_front;
        d_back = d_front;
        for (size_t count = 0; count != d_size; ++count)
        {
            new(d_back) Data(*src);
            d_back = inc(d_back);
            if (++src == other.d_data + d_maxSize)
                src = other.d_data;
        }
    }
\end{verbatim}
\item \texttt{CirQue(CirQue$<$Data$>$ \&\&tmp)}:\ \\ The move constructor merely
initializes the current object's \texttt{d\_data} pointer to 0 and swaps (see the
member \texttt{swap}, below) the temporary object with the current
object. \texttt{CirQue}'s destructor inspects \texttt{d\_data} and immediately
returns when it's zero. Implementation:
        \begin{verbatim}
    template<typename Data>
    CirQue<Data>::CirQue(CirQue<Data> &&tmp)
    :
        d_data(0)
    {
        swap(tmp);
    }
\end{verbatim}
\item \texttt{CirQue(Data const (\&arr){[}Size{]})}:\ \\ This constructor is declared
as a member template, providing the \texttt{Size} non-type parameter. It allocates
room for \texttt{Size} data elements and copies \texttt{arr}'s content to the newly
allocated memory.Implementation:
        \begin{verbatim}
    template <typename Data>
    template <size_t Size>
    CirQue<Data>::CirQue(Data const (&arr)[Size])
    :
        d_size(0),
        d_maxSize(Size),
        d_data(static_cast<Data *>(operator new(sizeof(arr)))),
        d_front(d_data),
        d_back(d_data)
    {
        std::copy(arr, arr + Size, std::back_inserter(*this));
    }
\end{verbatim}
\item \texttt{CirQue(Data const $*$data, size\_t size)}:\ \\ This constructor acts
very much like the previous one, but is provided with a pointer to the first
\texttt{Data} element and with a \texttt{size\_t} providing the number of elements to
copy. In our current design the member template variant of this constructor is
left out of the design. As the implementation of this constructor is very
similar to that of the previous constructor, it is left as an exercise to the
reader.

\item \texttt{\textasciitilde{}CirQue()}:\ \\ The destructor inspects the \texttt{d\_data} member. If it is
zero then nothing has been allocated and the destructor immediately
returns. This may occur in two situations: the circular queue contains no
elements or the information was grabbed from a temporary object by some move
operation, setting the temporary's \texttt{d\_data} member to zero. Otherwise
\texttt{d\_size} elements are destroyed by explicitly calling their destructors
followed by returning the element's raw memory to the common
pool. Implementation:
        \begin{verbatim}
    template<typename Data>
    CirQue<Data>::~CirQue()
    {
        if (d_data == 0)
            return;
        for (; d_size--; )
        {
            d_front->~Data();
            d_front = inc(d_front);
        }
        operator delete(d_data);
    }
\end{verbatim}
\end{itemize}

Here are \texttt{Cirque}'s members:
    \begin{itemize}
    \item \texttt{CirQue \&operator=(CirQue$<$Data$>$ const \&other)}:\ \\ The copy assignment
        operator has a  standard implementation:
        \begin{verbatim}
    template<typename Data>
    CirQue<Data> &CirQue<Data>::operator=(CirQue<Data> const &rhs)
    {
        CirQue<Data> tmp(rhs);
        swap(tmp);
        return *this;
    }
\end{verbatim}
\item \texttt{CirQue \&operator=(CirQue$<$Data$>$ \&\&tmp)}:\ \\ The move assignment
        operator also has a standard implementation. As its implementation
        merely calls \texttt{swap} it is defined as an inline function template:
        \begin{verbatim}
    template<typename Data>
    inline CirQue<Data> &CirQue<Data>::operator=(CirQue<Data> &&tmp)
    {
        swap(tmp);
        return *this;
    }
\end{verbatim}
\item \texttt{void pop\_front()}:\ \\ removes the element pointed at by \texttt{d\_front} from
        the \texttt{CirQue}.  Throws an exception if the \texttt{CirQue} is empty. The
        exception is thrown as a \texttt{CirQue$<$Data$>$::EMPTY} value, defined by the
        \texttt{enum CirQue$<$Data$>$::Exception} (see \texttt{push\_back}). The
        implementation is straightforward (explicitly calling the destructor
        of the element that is removed):
       \begin{verbatim}
    template<typename Data>
    void CirQue<Data>::pop_front()
    {
        if (d_size == 0)
            throw EMPTY;

        d_front->~Data();
        d_front = inc(d_front);
        --d_size;
    }
\end{verbatim}
\item \texttt{void push\_back(Data const \&object)}:\ \\ adds another element to the
        \texttt{CirQue}.  Throws a \texttt{CirQue$<$Data$>$::FULL} exception if the
        \texttt{CirQue} is full. The exceptions that can be thrown by a \texttt{CirQue}
        are defined in its \texttt{Exception} enum:
       \begin{verbatim}
    enum Exception
    {
        EMPTY,
        FULL
    };
\end{verbatim}
        A copy of \texttt{object} is installed in the \texttt{CirQue}'s raw memory using
        placement \texttt{new} and its \texttt{d\_size} is incremented.
       \begin{verbatim}
    template<typename Data>
    void CirQue<Data>::push_back(Data const &object)
    {
        if (d_size == d_maxSize)
            throw FULL;

        new (d_back) Data(object);
        d_back = inc(d_back);
        ++d_size;
    }
\end{verbatim}
\item \texttt{void swap(CirQue$<$Data$>$ \&other)}:\ \\ swaps the current \texttt{CirQue} object
        with another \texttt{CirQue$<$Data$>$} object;
       \begin{verbatim}
    template<typename Data>
    void CirQue<Data>::swap(CirQue<Data> &other)
    {
        static size_t const size = sizeof(CirQue<Data>);

        char tmp[size];
        memcpy(tmp, &other, size);
        memcpy(reinterpret_cast<char *>(&other), this, size);
        memcpy(reinterpret_cast<char *>(this), tmp, size);
    }
\end{verbatim}
\end{itemize}
    The remaining public members all consist of one-liners and were
implemented as inline function templates:
    \begin{itemize}
    \item \texttt{Data \&back()}:\ \\ returns a reference to the element pointed at by
        \texttt{d\_back} (undefined result if the \texttt{CirQue} is empty):
       \begin{verbatim}
    template<typename Data>
    inline Data &CirQue<Data>::back()
    {
        return d_back == d_data ? d_data[d_maxSize - 1] : d_back[-1];
    }
\end{verbatim}
\item \texttt{Data \&front()}:\ \\ returns reference to the element pointed at by
        \texttt{d\_front} (undefined result if the \texttt{CirQue} is empty);
       \begin{verbatim}
    template<typename Data>
    inline Data &CirQue<Data>::front()
    {
        return *d_front;
    }
\end{verbatim}
\item \texttt{bool empty() const}:\ \\ returns \texttt{true} if the \texttt{CirQue} is empty;
       \begin{verbatim}
    template<typename Data>
    inline bool CirQue<Data>::empty() const
    {
        return d_size == 0;
    }
\end{verbatim}
\item \texttt{bool full() const}:\ \\ returns \texttt{true} if the \texttt{CirQue} is full;
       \begin{verbatim}
    template<typename Data>
    inline bool CirQue<Data>::full() const
    {
        return d_size == d_maxSize;
    }
\end{verbatim}
\item \texttt{size\_t size() const}:\ \\ returns the number of elements currently stored
        in the  \texttt{CirQue};
       \begin{verbatim}
    template<typename Data>
    inline size_t CirQue<Data>::size() const
    {
        return d_size;
    }
\end{verbatim}
\item \texttt{size\_t maxSize() const}:\ \\ returns the maximum number of elements that
        can be stored in the \texttt{CirQue};
       \begin{verbatim}
    template<typename Data>
    inline size_t CirQue<Data>::maxSize() const
    {
        return d_maxSize;
    }
\end{verbatim}
\end{itemize}

Finally, the class has one private member, \texttt{inc}, returning a
cyclically incremented pointer into \texttt{CirQue}'s raw memory:
       \begin{verbatim}
    template<typename Data>
    Data *CirQue<Data>::inc(Data *ptr)
    {
        ++ptr;
        return ptr == d_data + d_maxSize ? d_data : ptr;
    }
\end{verbatim}
\subsection{Using CirQue objects}
    \typeout{Original Yodl file: classtemplates/cirqueuse}    When objects of a class template are instantiated, \emph{only} the
definitions of all the template's member functions that are actually used must
have been seen by the compiler.

That characteristic of templates could be refined to the point where each
definition is stored in a separate function template definition file. In that
case only the definitions of the function templates that are actually needed
would have to be included. However, it is hardly ever done that way. Instead,
the usual way to define class templates is to define the interface and to
define the remaining function templates immediately below the class template's
interface (defining some functions inline).

Now that the class \texttt{CirQue} has been defined, it can be used. To use the
class its object must be instantiated for a particular data type. In the
following example it is initialized for data type \texttt{std::string}:
        \begin{verbatim}
#include "cirque.h"
#include <iostream>
#include <string>
using namespace std;

int main()
{
    CirQue<string> ci(4);
    ci.push_back("1");
    ci.push_back("2");
    cout << ci.size() << ' ' << ci.front() << ' ' << ci.back() << '\n';

    ci.push_back("3");
    ci.pop_front();
    ci.push_back("4");
    ci.pop_front();
    ci.push_back("5");
    cout << ci.size() << ' ' << ci.front() << ' ' << ci.back() << '\n';

    CirQue<string> copy(ci);
    copy.pop_front();
    cout << copy.size() << ' ' << copy.front() << ' ' << copy.back() << '\n';

    int arr[] = {1, 3, 5, 7, 9};
    CirQue<int> ca(arr);
    cout << ca.size() << ' ' << ca.front() << ' ' << ca.back() << '\n';

//    int *ap = arr;
//    CirQue<int> cap(ap);
}
\end{verbatim}
    This program produces the following output:
        \begin{verbatim}
    2 1 2
    3 3 5
    2 4 5
    5 1 9
\end{verbatim}
\subsection{Default class template parameters}
    \typeout{Original Yodl file: classtemplates/default}Different from function templates, template parameters of template classes may
be given default argument
        \index{class template: default arguments} values.
    This holds true for both template type- and template non-type
parameters. If default template arguments were defined and if a class template
object is instantiated without specifying arguments for its template
parameters then the template parameter's defaults are used.

When defining defaults keep in mind that they should be suitable for the
majority of instantiations of the class. E.g., for the class template
\texttt{CirQue} the template's type parameter list could have been altered
by specifying \texttt{int} as its default type:
        \begin{verbatim}
    template <typename Data = int>
\end{verbatim}
Even though default arguments can be specified, the compiler must still be
informed that object definitions refer to templates. When instantiating class
template objects using default template arguments the type specifications may
be omitted but the angle brackets must be retained. Assuming a default
type for the \texttt{CirQue} class, an object of that class may be defined
as:
        \begin{verbatim}
    CirQue<> intCirQue(10);
\end{verbatim}
Default template arguments cannot be specified when defining template
members. So, the definition of, e.g., the \texttt{push\_back} member must always
begin with the same \texttt{template} specification:
        \begin{verbatim}
    template <typename Data>
\end{verbatim}
When a class template uses multiple template parameters, all may be given
default values. Like default function arguments, once a default value is used
all remaining template parameters must also use their default values. A
template type specification list may not start with a comma, nor may it
contain multiple consecutive commas.

\subsection{Declaring class templates}\label{DECLCLASSTEMP}
    \typeout{Original Yodl file: classtemplates/declaring}    Class templates may also be \emph{declared}. This may be useful in
situations where forward class declarations are required. To declare a
        \index{class template: declaration}
    class template, simply remove its interface (the part between the curly
braces):
        \begin{verbatim}
    template <typename Data>
    class CirQue;
\end{verbatim}
Default \index{class template: default argument} template arguments may also
be specified when declaring class templates. However, default template
arguments cannot be specified for both the declaration and the definition of a
class template. As a \index{rule of thumb}rule of thumb default template arguments should be
omitted from \emph{declarations}, as class template declarations are never used
when instantiating objects but are only occasionally used as forward
references. Note that this differs from default parameter value specifications
for member functions in ordinary classes. Such defaults are always specified
when declaring the member functions in the class interface.

\subsection{Preventing template instantiations}
    \typeout{Original Yodl file: classtemplates/externtemplate}In \textbf{C++} templates
    \index{template: when instantiated}
 are instantiated when the address of a function template or class template
object is taken or when a function template or class template is used. As
described in section \ref{DECLCLASSTEMP} it is possible to (forward) declare a
class template to allow the definition of a pointer or reference to
that template class or to allow it being used as a return type.

In other situations templates are instantiated when they are being used.  If
this happens many times (i.e., in many different source files) then this may
slow down the compilation process considerably. Fortunately, \textbf{C++} allows
programmers to \emph{prevent} templates
    \index{template: preventing instantiation}
 from being instantiated, using the 
\index{extern template}\texttt{extern template} syntax. Example:
        \begin{verbatim}
    extern template class std::vector<int>;
\end{verbatim}
Having declared the class template it can be used in its translation
unit. E.g., the following function  properly compiles:
        \begin{verbatim}
#include <vector>
#include <iostream>
using namespace std;

extern template class vector<int>;

void vectorUser()
{
    vector<int> vi;
    cout << vi.size() << '\n';
}
\end{verbatim}
    But be careful:
    \begin{itemize}
    \item  The declaration by itself does \emph{not} make the class definition
available. The \texttt{vector} header file \emph{still} needs to be included to make
the features of the class vector known to the compiler. But due to the
\texttt{extern template} declaration none of the used members will be instantiated
for the current compilation unit;
    \item  The compiler \emph{assumes} (as it always does) that what is declared
has been implemented elsewhere. In this case the compiler encounters an
\emph{implicit declaration}: the features of the vector class that are actually
used by the above program are not individually declared but they are declared
as a group, using the \index{extern template}\texttt{extern template} declaration. This not only holds
true for explicitly used members but hidden members (copy constructors, move
constructors, conversion operators, constructors called during promotions, to
name a few): all are assumed by the compiler to have been instantiated
elsewhere;
    \item  Although the above source file \emph{compiles}, the \emph{instantiations}
of the templates must be available before the linker can build the final
program. To accomplish this one or more source files may be constructed in
which all required instantiations are made available.

In a stand-alone program one might postpone defining the required members
and wait for the linker to complain about unresolved external
references. These may then be used to create a series of instantiation
declarations which are then linked to the program to satisfy the linker. Not
a very simple task, though, as the declarations must strictly match the way
the members are declared in the class interface. An easier approach is to
define an \index{instantiation source}\emph{instantiation source} \emph{file} in which all facilities that
are used by the program are actually instantiated in a function that is never
called by the program. By adding this \index{instantiation function}instantiation function to the source
file containing \texttt{main} we can be sure that all required members are
instantiated as well. Here is an example of how this can be done:
        \begin{verbatim}
#include <vector>
#include <iostream>

extern void vectorUser();

int main()
{
    vectorUser();
}

// this part is never called. It is added to make sure all required
// features of declared templates will also be instantiated.

namespace
{
    void instantiator()
    {
        std::vector<int> vi;
        vi.size();
    }
}
\end{verbatim}
\item  Last, but certainly not least: a fully matching
        \index{instantiation declaration}instantiation declaration of a class template (e.g., for
\texttt{std::vector$<$int$>$}) looks like this:
            \begin{verbatim}
template class std::vector<int>;
\end{verbatim}
Adding this to a source file, however, will instantiate the \emph{full
class}, i.e., all its members are now instantiated. This may not what you
want, as it might needlessly inflate your final executable.
    \item  On the other hand, if it is known that the required template members
have already been instantiated elsewhere, then an \index{extern template}\emph{extern template}
declaration can be used to prevent member instantiations in the current
compilation unit, which may speed up compilation. E.g.,
        \begin{verbatim}
        // the compiler assumes that required members of
        // vector<int> have already been instantiated elsewhere
extern template class std::vector<int>;

int main()
{
    std::vector<int> vi(5);     // constructor and operator[]
    ++vi[0];                    // are NOT instantiated
}
\end{verbatim}
\end{itemize}

\subsection{Template parameter initialization}
    \typeout{Original Yodl file: classtemplates/paraminit}Class templates commonly specify their parameter types, which types are then
used to define, e.g., the parameters of their members. But template parameter
types can also, somewhat comparable to the way template function parameter
types are determined, be derived from the actually used template arguments,
which is called \emph{template parameter initialization}. Template parameter
types which are derived from the actually used template argument values start
with \texttt{auto} as illustrated in the following example (the examples in this
section use in-class implementations for brevity and assume \texttt{\#include
$<$iostream$>$} and \texttt{using namespace std}):
    \begin{verbatim}
    template <auto val> struct Demo
    {
        Demo()
        {
            cout << val << '\n';
        }
    };
    
    int main()
    {
        Demo<12> d1;
        Demo<'a'> d2;
    }
\end{verbatim}
This program shows, respectively, \texttt{12} (an \texttt{int}) and \texttt{a} (a
\texttt{char}). Those types are determined from the actually used template
parameter arguments, and the argument name(s) can be used by the template
class's members.

Those members are available inside the class template as \texttt{constexpr}
data members. Since they are \texttt{constexpr} data members the compiler must be
able to construct those arguments compile-time. Consequently, when
specifying a template argument using a class object only the object's
\texttt{const} members can be used, and that object's class cannot declare
\texttt{mutable} data members, illustrated by the next example:
    \begin{verbatim}
    struct Accepted
    {
        int d_val = 10;
        void unchanged() const
        {
            cout << d_val << '\n';
        }
        void changed()              // OK: not used by Demo below
        {
            cout << ++d_val << '\n';
        }
    };
    
    struct Rejected
    {
        mutable int d_val = 10;     // 'Rejected' can't be used by
                                    // Demo because of 'mutable'
        void unchanged() const
        {
            cout << d_val << '\n';
        }
        void changed()              // OK: not used by Demo below
        {
            cout << ++d_val << '\n';
        }
    };
    
    template <auto val> struct Demo
    {
        Demo()
        {
            val.unchanged();
        }
    };
    
    int main()
    {
        Demo<Accepted{}> sa;
        // Demo<Rejected{}> sr;     // won't compile
    }
\end{verbatim}
Assuming the class's template parameter is defined as used above as \texttt{auto
val} then \texttt{val's} type can be obtained with a \texttt{using} declaration. E.g.,
    \begin{verbatim}
    template <auto val> struct Demo
    {
        using Type = decltype(val);
        ...
    }
\end{verbatim}
    and \texttt{Type} can be used to define such data members or to refer to such
types when specifying member function parameters. Such \texttt{Type} variables
are not by default immutable:
    \begin{verbatim}
    template <auto val> struct Demo
    {
        using Type = decltype(val);
        Type d_val = val;
        Demo()
        {
            cout << ++d_val << '\n';
        }
    }
\end{verbatim}
Initialized template parameters become (immutable) data members which can be
used in the class template's members. In the next example the class template's
\texttt{Adder} defines an initialized template parameter \texttt{auto add} whose value
is added to the elements of a \texttt{std::vector}. Also, all the initial elements
of the vector are summed, which value is then retrieved by the member
\texttt{total}:
    \begin{verbatim}
    #include <vector>
    #include <string>
    
    template <auto val> class Adder
    {
        using Type = decltype(val);
    
        Type d_sum = Type();            // initialize d_sum
    
        public:
            Adder()
            {
                cout << "adding " << val << "\n\n";
            }
                                        // append 'val' to vect's elements
            void append(std::vector<Type> &vect)
            {
                for (auto &elem: vect)
                {
                    d_sum += elem;
                    elem += val;
                }
            }
                                        // show vect's elements
            void show(std::vector<Type> const &vect) const
            {
                for (auto &elem: vect)
                    cout << elem << '\n';
                cout.put('\n');
            }
    
            Type const &total() const   // show vect elements' original sum
            {
                return d_sum;
            }
    };
    
    template <auto val>
    void process(vector<decltype(val)> &vect)
    {
        Adder<val> adder;
        adder.show(vect);
        adder.append(vect);
        adder.show(vect);
        cout << "original sum: " << adder.total() << "\n\n";
    }
    
    int main()
    {
        vector<int> vi{1, 2, 3, 4};
        process<3>(vi);                     // add 3 to the vi's elements
    
        vector<double> vd{1.1, 2.2, 3.3, 4.4};
        process<3.5>(vd);                   // add 3.5 to the vd's elements
    }
\end{verbatim}
\subsection{Generic lambda expressions}
    \typeout{Original Yodl file: classtemplates/lambda}Like template parameter initializations \emph{generic lambda expressions}
\index{lambda: generic} may use \texttt{auto} to define their parameters. When used, a
lambda expression is instantiated by looking at the actual types of
arguments. Since \texttt{auto} is generic, different parameters defined using
\texttt{auto} can be instantiated to different types. Here is an example (assuming
all required headers and namespace declaration were specified):
    \begin{verbatim}
     1: int main()
     2: {
     3:     auto lambda = [](auto lhs, auto rhs)
     4:                 {
     5:                     return lhs + rhs;
     6:                 };
     7: 
     8:     vector<int> values {1, 2, 3, 4, 5};
     9:     vector<string> text {"a", "b", "c", "d", "e"};
    10: 
    11:     cout <<
    12:         accumulate(values.begin(), values.end(), 0, lambda) << '\n' <<
    13:         accumulate(text.begin(), text.end(), string{}, lambda) << '\n';
    14: }
\end{verbatim}
    The generic lambda function is defined in lines 3 through 6, and is
assigned to the \texttt{lambda} identifier. Then, \texttt{lambda} is passed to
\texttt{accumulate} in lines 12 and 13. In line 12 it is instantiated to add
\texttt{int} values, in line 13 to add \texttt{std::string} values: the same \texttt{lambda}
is instantiated to two completely different functors, which are only locally
available in \texttt{main}.

Generic lambda expressions are in fact class templates. To illustrate: the
above example of a generic lambda expression could also have been implemented
using the following class template:
        \begin{verbatim}
    struct Lambda
    {
        template <typename LHS, typename RHS>
        auto operator()(LHS const &lhs, RHS const &rhs) const 
        {
            return lhs + rhs;
        }
    };
    auto lambda = Lambda{};
\end{verbatim}
This identity implies that using \texttt{auto} in the lambda expression's
parameter list obeys the rules of template argument deduction (cf. section
\ref{TEMPFUNARGS}), which are somewhat different from the way \texttt{auto} normally
operates.

Another extension is the way generic lambda expressions capture outer scope
variables.  Previously variables could only be captured by value or by
reference. As a consequence an outer scope variable of a type that only
supports move construction could not be passed by value to a lambda
function. This restriction was dropped, allowing variables to be initialized
from arbitrary expressions. This not only allows move-initialization of
variables in the lambda introducer, but with generic lambdas variables may
also be initialized if they do not have a correspondingly named variable in
the lambda expression's outer scope. In this case initializer expressions can
be used as follows:
        \begin{verbatim}
    auto fun = [value = 1] 
               {
                   return value;
               };
\end{verbatim}
This lambda function (of course) returns 1: the declared capture deduces
the type from the initializer expression as if \texttt{auto} had been used.

To use move-initialization \texttt{std::move} should be used. E.g., a
\emph{unique\_ptr} only supports move-assignment. Here it is used to return one of
its values via a lambda function:
        \begin{verbatim}
    std::unique_ptr<int> ptr(new int(10));
    auto fun = [value = std::move(ptr)] 
               {
                   return *value;
               };
\end{verbatim}
In generic lambda expressions the keyword \texttt{auto} indicates that the compiler
determines which types to use when the lambda function is instantiated. A
generic lambda expression therefore \emph{is} a class template, even though it
doesn't look like one. As an example, the following lambda expression defines
a generic class template, which can be used as shown:
        \begin{verbatim}
    char const *target = "hello";

    auto lambda =         
       [target](auto const &str)
       {
           return str == target;
       };
       
    vector<string> vs{stringVectorFactory()};

    find_if(vs.begin(), vs.end(), lambda);
\end{verbatim}
This works fine, but if you define \texttt{lambda} this way then you should be
prepared for complex error messages if the types of the derefenced iterators
and lambda's (silently assumed) \texttt{str} type don't match.

Here is a little program illustrating how generic lambda expressions can be
used in other generic lambda expressions: class templates could also have been
used. In lines 1 through 9 a generic lambda expression \texttt{accumulate} is
defined, defining a second paramater which is used as a function: its argument
therefore should be usable as a function. A functor definitely is, an the
second generic lambda expression \texttt{lambda}, defined in lines 11 through 14
provides it. In line 21 \texttt{accumulate} and \texttt{lambda} are instantiated so that
they operate on (a vector of) \texttt{ints}, in line 22 they are instantiated for
processing (a vector of) \texttt{strings}:
    \begin{verbatim}
     1: auto accumulate(auto const &container, auto function)
     2: {
     3:     auto accu = decltype(container[0]){};
     4: 
     5:     for (auto &value: container)
     6:         accu = function(accu, value);
     7: 
     8:     return accu;
     9: }
    10: 
    11: auto lambda = [](auto lhs, auto rhs)
    12:             {
    13:                 return lhs + rhs;
    14:             };
    15: 
    16: int main()
    17: {
    18:     vector<int> values  = {1, 2, 3, 4, 5};
    19:     vector<string> text = {"a", "b", "c", "d", "e"};
    20: 
    21:     cout << accumulate(values,  lambda) << '\n' <<
    22:             accumulate(text,    lambda) << '\n';
    23: }
\end{verbatim}
In some situations generic lambdas are a bit too generic, resulting in verbose
implementations which are not required by templates in general. Consider a
generic lambda that specifies an \texttt{auto \&it} parameter, but in addition it
should specify a parameter \texttt{value} of type \texttt{ValueType} that should be
defined by \texttt{it's} class. Such a parameter requires the use of a \texttt{decltype}
(and maybe also the use of \texttt{std::decay\_t}) to retrieve \texttt{it's} actual
type. Inside the lambda's body a \texttt{using} declaration can be specified to
make the type available, but that again requires a verbose specification using
\texttt{std::decay\_t} and \texttt{decltype}. Here is an example:
        \begin{verbatim}
    auto generic = 
        [](auto &it, 
           typename std::decay_t<decltype(it)>::ValueType value)
        {
            using Type = std::decay_t<decltype(it)>;
            typename Type::ValueType val2{ value };
            Type::staticMember();
        };
\end{verbatim}
To avoid this kind of verbosity generic lambda functions can also be defined
like ordinary templates, in which case the template header immediately follows
the lambda-introducer. Using this alternative form the definition of the
\texttt{generic} generic lambda simply and straightforwardly becomes:
        \begin{verbatim}
    auto generic = 
        []<typename Type>(Type &it, typename Type::ValueType value)
        {
            typename Type::ValueType val2{ value };
            Type::staticMember();
        };
\end{verbatim}
\section{Static data members}
\typeout{Original Yodl file: classtemplates/static}    When \index{static members}static members are defined in class templates, they
        \index{class template: static members}
    are defined for every new type for which the class template is
instantiated. As they are static
members, there will only be one member per type for which the class template
is instantiated. For example, in a class like:
        \begin{verbatim}
    template <typename Type>
    class TheClass
    {
        static int s_objectCounter;
    };
\end{verbatim}
There will be \emph{one} \texttt{TheClass$<$Type$>$::objectCounter} for each different
\texttt{Type} specification. The following object definitions result in the
instantiation of just one single static variable, shared among the two
objects:
        \begin{verbatim}
    TheClass<int> theClassOne;
    TheClass<int> theClassTwo;
\end{verbatim}
Mentioning static members in interfaces does not mean these members are
actually defined. They are only \emph{declared} and must be \emph{defined}
separately.  With static members of class templates this is no different. The
definitions of static members
        \index{class template: static members}
    are usually provided immediately following (i.e., below) the template
class interface. For example, the static member
\texttt{s\_objectCounter}'s definition, positioned just below its class interface,
looks like this:
        \begin{verbatim}
    template <typename Type>                    // definition, following
    int TheClass<Type>::s_objectCounter = 0;    // the interface
\end{verbatim}
Here \texttt{s\_objectCounter} is an \texttt{int} and is thus independent of the
template type parameter \texttt{Type}. Multiple instantiations of
\texttt{s\_objectCounter} for identical \texttt{Type}s cause no problem, as the linker
will remove all but one instantiation from the final executable (cf. section
\ref{TEMPFUNDECL}).

\index{pointer: to object}
    In list-like constructions, where a pointer to objects of the class
itself is required, the template type parameter \texttt{Type} must be used when
defining the static variable. Example:
        \begin{verbatim}
    template <typename Type>
    class TheClass
    {
        static TheClass *s_objectPtr;
    };

    template <typename Type>
    TheClass<Type> *TheClass<Type>::s_objectPtr = 0;
\end{verbatim}
    As usual, the definition can be read from the variable name back to the
beginning of the definition: \texttt{s\_objectPtr} of the class \texttt{TheClass$<$Type$>$}
is a pointer to an object of \texttt{TheClass$<$Type$>$}.

When a static variable of a template's type parameter's type is defined,
it should of course not be given the initial value 0. The default constructor
(e.g., \texttt{Type()}) is usually more appropriate. Example:
        \begin{verbatim}
    template <typename Type>                    // s_type's definition
    Type TheClass<Type>::s_type = Type();
\end{verbatim}
\subsection{Extended use of the keyword `typename'}\label{DISTINGUISH}
\typeout{Original Yodl file: classtemplates/typename}Until now the keyword \texttt{typename} has been used to indicate a template type
parameter. However, it is also used to
    \index{typename: disambiguating code}
 disambiguate code inside templates. Consider the following function template:
        \begin{verbatim}
    template <typename Type>
    Type function(Type t)
    {
        Type::Ambiguous *ptr;

        return t + *ptr;
    }
\end{verbatim}
When this code is processed by the compiler, it complains with an -at
first sight puzzling- error message like:
        \begin{verbatim}
    4: error: 'ptr' was not declared in this scope
\end{verbatim}
The error message is puzzling as it was the programmer's intention to
declare a pointer to a type \texttt{Ambiguous} defined within the class template
\texttt{Type}. But the compiler, confronted with \texttt{Type::Ambiguous} may interpret
the statement in various ways. Clearly it cannot inspect \texttt{Type} itself
trying to uncover \texttt{Type}'s true nature as \texttt{Type} is a template
type. Because of this \texttt{Type}'s actual definition isn't available yet.

The compiler is confronted with two possibilities: either
\texttt{Type::Ambiguous} is a \emph{static member} of the as yet mysterious template
\texttt{Type}, or it is a \emph{subtype} of \texttt{Type}. As the standard
specifies that the compiler must assume the former, the statement
        \begin{verbatim}
    Type::Ambiguous *ptr;
\end{verbatim}
is interpreted as a \emph{multiplication} of the static member
\texttt{Type::Ambiguous} and the (now undeclared) entity \texttt{ptr}. The reason for
the error message should now be clear: in this context \texttt{ptr} is unknown.

To disambiguate code in which an identifier refers to a
        \index{template: identifying subtypes}
        \index{class template: identifying subtypes}
        \index{typename: and template subtypes}
 subtype of a template type parameter the keyword \texttt{typename} must be
used. Accordingly, the above code is altered into:
        \begin{verbatim}
    template <typename Type>
    Type function(Type t)
    {
        typename Type::Ambiguous *ptr;

        return t + *ptr;
    }
\end{verbatim}
Classes fairly often define subtypes. When such subtypes appear inside
template definitions as subtypes of template type parameters the \texttt{typename}
keyword \emph{must} be used to identify them as subtypes. Example: a class
template \texttt{Handler} defines a \texttt{typename Container} as its template type
parameter. It also defines a data member storing the iterator returned by the
container's \texttt{begin} member. In addition \texttt{Handler} offers a constructor
accepting any container supporting a \texttt{begin} member.  \texttt{Handler}'s class
interface could then look like this:
        \begin{verbatim}
    template <typename Container>
    class Handler
    {
        Container::const_iterator d_it;

        public:
            Handler(Container const &container)
            :
                d_it(container.begin())
            {}
    };
\end{verbatim}
What did  we have in mind when designing this class?
    \begin{itemize}
    \item  The typename \texttt{Container} represents any container supporting
iterators.
    \item  The container presumably supports a member \texttt{begin}. The
initialization \texttt{d\_it(container.begin())} clearly depends on the
template's type parameter, so it's only checked for basic syntactic
correctness.
    \item  Likewise, the container presumably supports a \emph{subtype}
\texttt{const\_iterator}, defined in the class \texttt{Container}.
    \end{itemize}
    The final consideration is an indication that \texttt{typename} is required. If
this is omitted and a \texttt{Handler} is instantiated the compiler produces a
peculiar compilation error:
        \begin{verbatim}
    #include "handler.h"
    #include <vector>
    using namespace std;

    int main()
    {
        vector<int> vi;
        Handler<vector<int> > ph{ vi };
    }
    /*
        Reported error:

    handler.h:4: error: syntax error before `;' token
    */
\end{verbatim}
Clearly the line
        \begin{verbatim}
    Container::const_iterator d_it;
\end{verbatim}
in the class \texttt{Handler} causes a problem. It is interpreted by the
compiler as a \emph{static member} instead of a subtype. The problem is
solved  using \texttt{typename}:
        \begin{verbatim}
    template <typename Container>
    class Handler
    {
        typename Container::const_iterator d_it;
        ...
    };
\end{verbatim}
An interesting illustration that the compiler indeed assumes \texttt{X::a} to
be a member \texttt{a} of the class \texttt{X} is provided by the error message we get
when we try to compile \texttt{main} using the following implementation of
\texttt{Handler}'s constructor:
        \begin{verbatim}
    Handler(Container const &container)
    :
        d_it(container.begin())
    {
        size_t x = Container::ios_end;
    }
    /*
        Reported error:

        error: `ios_end' is not a member of type `std::vector<int,
                std::allocator<int> >'
    */
\end{verbatim}
Now consider what happens if the function template introduced at the
beginning of this section doesn't return a \texttt{Type} value, but a
\texttt{Type::Ambiguous} value. Again, a subtype of a template type is referred to,
and \texttt{typename} must be used:
        \begin{verbatim}
    template <typename Type>
    typename Type::Ambiguous function(Type t)
    {
        return t.ambiguous();
    }
\end{verbatim}
\texttt{Typename}s can be embedded in using declarations. As is often the case,
this
        \index{template: embedded in using declarations}
reduces the complexities of declarations and definitions appearing
elsewhere. In the next example the type \texttt{Iterator} is defined as a subtype
of the template type \texttt{Container}. \texttt{Iterator} may now be used without
requiring the use of the keyword \texttt{typename}:
        \begin{verbatim}
    template <typename Container>
    class Handler
    {
        using Iterator = Container::const_iterator;

        Iterator d_it;
        ...
    };
\end{verbatim}
\section{Specializing class templates for deviating types}
\typeout{Original Yodl file: classtemplates/specialization}The class \texttt{CirQue} can be used for many different types. Their common
characteristic is that they can simply be pointed at by the class's \texttt{d\_data}
member. But this is not always as simple as it looks. What if \texttt{Data} turns
out to be a \texttt{vector$<$int$>$}? For such data types the vanilla \texttt{CirQue}
implementation cannot be used and a specialization could be considered. When
considering a specialization one should also consider inheritance. Often a
class derived from the class template accepting the incompatible data
structure as its argument but otherwise equal to the original class template
can easily be designed. The developmental advantage of inheritance over
specialization is clear: the inherited class inherits the members of its base
class while the specialization inherits nothing. All members defined by the
original class template must be implemented again by the class template's
specialization.

The specialization considered here is a true specialization in that the
data members and representation used by the specialization greatly differ from
the original \texttt{CirQue} class template. Therefore all members defined by the
orginal class template must be modified to fit the specialization's data
organization.

Like function template specializations class template specializations
start with a template header that may or may not have an empty template
parameter list. If the template parameters are directly specialized by the
specialization it remains empty (e.g., \texttt{CirQue}'s template type parameter
\texttt{Data} is specialized for \texttt{char $*$} data). But the template parameter list
may show \texttt{typename Data} when specializing for a \texttt{vector$<$Data$>$}, i.e., a
vector storing any type of data. This leads to the following principle:
    \begin{quote}\index{template: specialization} A template specialization is recognized
by the template argument list following a function or class template's
\emph{name} and \emph{not} by an empty template parameter list. Class template
specializations may have non-empty template parameter lists. If so, a
\index{partial class template specialization}\emph{partial class template specialization} is defined.\end{quote}

A completely specialized class has the following characteristics:
    \begin{itemize}
    \item  The class template specialization must be provided after the generic
class template definition. As it is a specialization the compiler
must first have seen the original class template;
    \item  The completely specialized class template's template parameter list
is empty;
    \item  All of the class's template parameters are given explicit type names
or (for the non-type parameters) explicit values. These explicitations are
provided in a template parameter specification list (surrounded by angle
brackets) that is inserted immediately after the specialized template's class
\emph{name};
    \item  All members of the specialized class template use specialized types
and values where original template parameters are used in the original
template definition;
    \item  All original template's members (maybe with the exception of some
constructors) \emph{should} be redefined by the specialization. If a member is
left out of the specialization, it cannot be used for a specialized class
template object;
    \item  The specialization may define additional members (but maybe shouldn't
as it breaks the one-to-one correspondence between the original and
specialized class template);
    \item  Member functions of specialized class templates may be declared by
the specializing class and implemented below their class interface. If their
implementations follow the class interface they may \emph{not} begin with a
\texttt{template $<$$>$} header, but must immediately start with the member function's
header.
    \end{itemize}

\subsection{Example of a class specialization}
    \typeout{Original Yodl file: classtemplates/cirqueexample}Here is an example of a completely specialized \texttt{CirQue} class, specialized
for a \texttt{vector$<$int$>$}. All members of the specialized class are declared, but
only non-trivial implementations of its members are provided. The specialized
class uses a copy of the \texttt{vector} passed to the constructor and implements a
circular queue using its \texttt{vector} data member:

\begin{verbatim}
#ifndef INCLUDED_CIRQUEVECTOR_H_
#define INCLUDED_CIRQUEVECTOR_H_

#include <vector>
#include "cirque.h"

template<>
class CirQue<std::vector<int>>
{
    using IntVect =  std::vector<int>;

    IntVect d_data;
    size_t d_size;

    using iterator = IntVect::iterator;
    iterator d_front;
    iterator d_back;

    public:
        using value_type = int;
        using const_reference = value_type const &;

        enum Exception
        {
            EMPTY,
            FULL
        };

        CirQue();
        CirQue(IntVect const &iv);
        CirQue(CirQue<IntVect> const &other);

        CirQue &operator=(CirQue<IntVect> const &other);

        int &back();
        int &front();
        bool empty() const;
        bool full() const;
        size_t maxSize() const;
        size_t size() const;
        void pop_front();
        void push_back(int const &object);
        void swap(CirQue<IntVect> &other);

    private:
        iterator inc(iterator const &iter);
};

CirQue<std::vector<int>>::CirQue()
:
    d_size(0)
{}
CirQue<std::vector<int>>::CirQue(IntVect const &iv)
:
    d_data(iv),
    d_size(iv.size()),
    d_front(d_data.begin()),
    d_back(d_data.begin())
{}
CirQue<std::vector<int>>::CirQue(CirQue<IntVect> const &other)
:
    d_data(other.d_data),
    d_size(other.d_size),
    d_front(d_data.begin() + (other.d_front - other.d_data.begin())),
    d_back(d_data.begin() + (other.d_back - other.d_data.begin()))
{}
CirQue<std::vector<int>> &CirQue<std::vector<int>>::operator=(
                                        CirQue<IntVect> const &rhs)
{
    CirQue<IntVect> tmp(rhs);
    swap(tmp);
}
void CirQue<std::vector<int>>::swap(CirQue<IntVect> &other)
{
    char tmp[sizeof(CirQue<IntVect>)];
    memcpy(tmp, &other, sizeof(CirQue<IntVect>));
    memcpy(reinterpret_cast<char *>(&other), this, sizeof(CirQue<IntVect>));
    memcpy(reinterpret_cast<char *>(this), tmp, sizeof(CirQue<IntVect>));
}
void CirQue<std::vector<int>>::pop_front()
{
    if (d_size == 0)
        throw EMPTY;

    d_front = inc(d_front);
    --d_size;
}
void CirQue<std::vector<int>>::push_back(int const &object)
{
    if (d_size == d_data.size())
        throw FULL;

    *d_back = object;
    d_back = inc(d_back);
    ++d_size;
}
inline int &CirQue<std::vector<int>>::back()
{
    return d_back == d_data.begin() ? d_data.back() : d_back[-1];
}
inline int &CirQue<std::vector<int>>::front()
{
    return *d_front;
}
CirQue<std::vector<int>>::iterator CirQue<std::vector<int>>::inc(
    CirQue<std::vector<int>>::iterator const &iter)
{
    iterator tmp(iter + 1);
    tmp =  tmp == d_data.end() ? d_data.begin() : tmp;
    return tmp;
}

#endif
\end{verbatim}
The next example shows how to use the specialized \texttt{CirQue} class:
    \begin{verbatim}
static int iv[] = {1, 2, 3, 4, 5};

int main()
{
    vector<int> vi(iv, iv + 5);
    CirQue<vector<int>> ci(vi);

    cout << ci.size() << ' ' << ci.front() << ' ' << ci.back() << '\n';
    ci.pop_front();
    ci.pop_front();

    CirQue<vector<int>> cp;

    cp = ci;
    cout << cp.size() << ' ' << cp.front() << ' ' << cp.back() << '\n';
    cp.push_back(6);
    cout << cp.size() << ' ' << cp.front() << ' ' << cp.back() << '\n';
}

/*
    Displays:
        5 1 5
        3 3 5
        4 3 6
*/
\end{verbatim}
\section{Partial specializations}\label{PARTIAL}
\typeout{Original Yodl file: classtemplates/partial}In the previous section class template specializations were introduced.  In
this section we'll introduce a variant of this specialization, both in
number and type of template parameters that are specialized.  \emph{Partial
specializations} may be defined for class templates having
        \index{partial specialization}
        \index{class template: partial specialization}
    multiple template parameters. 

Function templates cannot be partially specialized: there is no need for
        \index{function template: partial specialization}
    that, as a `partially specialized function template' merely is a function
template that is tailored to particular types of some of its parameters. Since
function templates can be overloaded, `partially specializing' a function
template simply means that overloads have to be defined for those specialized
parameter types.

With partial specializations a subset (any subset) of template type parameters
are given specific values. It is also possible to use a class template partial
specialization when the intent is to specialize the class template, but to
parameterize the data type that is processed by the specialization.

To start our discussion with an example of the latter use of a partial class
template specialization consider the class \texttt{CirQue$<$vector$<$int$>$$>$}
developed in the previous section. When designing \texttt{CirQue$<$vector$<$int$>$$>$}
you may have asked yourself how many specializations you'd have to
implement. One for \texttt{vector$<$int$>$}, one for \texttt{vector$<$string$>$}, one for
\texttt{vector$<$double$>$}?  As long as the data types handled by the \texttt{vector} used
by the class \texttt{CirQue$<$vector$<$...$>$$>$} behaves like an \texttt{int} (i.e., is a
value-type of class) the answer is: zero. Instead of defining full
specializations for each new data type the data type itself can be
parameterized, resulting in a partial specialization:
        \begin{verbatim}
    template <typename Data>
    class CirQue<std::vector<Data>>
    {
        ...
    };
\end{verbatim}
The above class is a specialization as a template argument list is
appended to the \texttt{CirQue} class name. But as the class template itself has a
non-empty template parameter list it is in fact recognized as a partial
specialization. There is one characteristic that distinguishes the
implementation (subsequent to the class template's interface) of a class
template member function of a partial specialization from the implementation
of a member function of a full specialization. Implementations of partially
specialized class template member functions receive a template header. No
template headers are used when implementing fully specialized class template
members.

Implementing the partial specialization for \texttt{CirQue} is not difficult and is
left as an exercise for the reader (hints: simply change \texttt{int} into \texttt{Data}
in the \texttt{CirQue$<$vector$<$int$>$$>$} specialization of the previous section).
Remember to prefix the type \texttt{iterator} by \texttt{typename} (as in \texttt{using
iterator = DataVect::iterator}) (as discussed in section \ref{DISTINGUISH}).

In the next subsections we'll concentrate on specializing class template
non-type template parameters. These partial specializations are now
illustrated using some simple concepts defined in matrix algebra, a branch of
linear algebra.

\subsection{Intermezzo: some simple matrix algebraic concepts}
    \typeout{Original Yodl file: classtemplates/matrixalgebra}In this section some simple matrix algebraic terms are introduced. These terms
are used in the next sections to illustrate and discuss partial
specializations of class templates.  Readers proficient in matrix algebra may
skip this section without loss of continuity.

A matrix is commonly thought of as a table of some rows and columns,
filled with numbers. Immediately we recognize an opening for using templates:
the numbers might be plain \texttt{double} values, but they could also be complex
numbers, for which our complex container (cf. section \ref{COMPLEX}) might
prove useful. Our class template is therefore provided with a \texttt{DataType}
template type parameter. It is  specified when a
matrix is constructed. Some simple matrices using \texttt{double} values, are:
        \begin{verbatim}
    1   0   0           An identity matrix,
    0   1   0           (a 3 x 3 matrix).
    0   0   1

    1.2  0    0    0    A rectangular matrix,
    0.5  3.5  18  23    (a 2 x 4 matrix).

    1   2   4   8       A matrix of one row
                        (a 1 x 4 matrix), also known as a
                        `row vector' of 4 elements.
                        (column vectors are analogously defined)
\end{verbatim}
Various operations are defined on matrices. They may, for example be
added, subtracted or multiplied. Here we will not focus on these
operations. Rather, we concentrate on some simple operations: computing
marginals and sums.

Marginals are the sums of row elements or the sums of column elements of a
matrix. These two kinds of marginals are also known as, respectively,
\emph{row marginals} and
\emph{column marginals}.

\begin{itemize}
    \item  \emph{Row marginals} are obtained by adding, for each row,
all the row's elements and putting these (\texttt{Rows}) sums in corresponding
elements of a (column) vector of \texttt{Rows} elements.
    \item  Column marginals are
obtained by adding, for each column, all the column's elements and putting
these (\texttt{Columns}) sums in corresponding elements of a (row) vector of
\texttt{Columns} elements.
    \item  The sum of all elements of a matrix can of course be computed as the
sum of the elements of one of its marginals.
    \end{itemize}
    The following example shows a matrix, its marginals, and the sum of its
values:
        \begin{verbatim}
    -------------------------------------
                                row
                matrix          marginals
                ---------
                1   2   3        6
                4   5   6       15
                ---------
    column      5   7   9       21  (sum)
    marginals
    -------------------------------------
\end{verbatim}
\subsection{The Matrix class template}
    \typeout{Original Yodl file: classtemplates/matrix}We'll start out by introducing a class template defining a matrix. Having
defined this class template we'll continue with defining several
specializations.

Since matrices consist of well defined numbers of rows and columns (the
\emph{dimensions} of the matrix), that normally do not change when matrices are
used, we might consider specifying their values as template non-type
parameters. The \texttt{DataType = double} will be used in the majority of
cases. Therefore, \texttt{double} can be selected as the template's default type
argument. Since it's a sensible default, the \texttt{DataType} template type
parameter is used last in the template type parameter list.

Our template class \texttt{Matrix} begins its life as:
        \begin{verbatim}
    template <size_t Rows, size_t Columns, typename DataType = double>
    class Matrix
    ...
\end{verbatim}
What do we want our class template to offer?
    \begin{itemize}
    \item  It needs a place to store its matrix elements. This can be defined as
an array of `\texttt{Rows}' rows each containing `\texttt{Columns}' elements of type
\texttt{DataType}. It can be an array, rather than a pointer, since the matrix'
dimensions are known \emph{a priori}. Since a vector of \texttt{Columns} elements (a
\emph{row} of the matrix), as well as a vector of \texttt{Row} elements (a \emph{column}
of the matrix) is often used, the class could specify using-declarations to
represent them. The class interface's initial section thus contains:
        \begin{verbatim}
        using MatrixRow = Matrix<1, Columns, DataType>;
        using MatrixColumn = Matrix<Rows, 1, DataType>;

        MatrixRow d_matrix[Rows];
\end{verbatim}
    \item  It should offer constructors: a default constructor and (e.g.,) a
constructor initializing the matrix from a stream. A copy or move constructor
is not required as the class does not use pointers. Likewise, no overloaded
assignment operator or destructor is required. Implementations:
        \begin{verbatim}
    template <size_t Rows, size_t Columns, typename DataType>
    Matrix<Rows, Columns, DataType>::Matrix()
    {
        std::fill(d_matrix, d_matrix + Rows, MatrixRow());
    }
    template <size_t Rows, size_t Columns, typename DataType>
    Matrix<Rows, Columns, DataType>::Matrix(std::istream &str)
    {
        for (size_t row = 0; row < Rows; row++)
            for (size_t col = 0; col < Columns; col++)
                str >> d_matrix[row][col];
    }
\end{verbatim}
    \item  The class's \texttt{operator{[}{]}} member (and its \texttt{const} variant) only
handles the first index, returning a reference to a complete
\texttt{MatrixRow}. How elements in a \texttt{MatrixRow} can be retrieved is shortly
covered. To keep the example simple, no array bound check has been
implemented:
        \begin{verbatim}
    template <size_t Rows, size_t Columns, typename DataType>
    Matrix<1, Columns, DataType>
    &Matrix<Rows, Columns, DataType>::operator[](size_t idx)
    {
        return d_matrix[idx];
    }
\end{verbatim}
    \item  Now we get to the interesting parts: computing marginals and the sum
of all elements in a \texttt{Matrix}. We'll define the type \texttt{MatrixColumn} as the
type containing the row marginals of a matrix, and the type \texttt{MatrixRow} as
the type containing the column marginals of a matrix.

There is also the sum of all the elements of a matrix. This sum of all the
elements of a matrix is a number that itself can be thought of as a \texttt{1 x 1}
matrix.

Marginals can be considered as special forms of matrices. To represent these
marginals we can construct \emph{partial specializations} defining the class
templates \texttt{MatrixRow} and \texttt{MatrixColumn} objects; and we construct a
partial specialization handling \texttt{1 x 1} matrices.  These partial
specializations are used to compute marginals and the sum of all the elements
of a matrix.

Before concentrating on these partial specializations themselves we'll use
them here to implement the members computing the marginals and the sum of all
elements of a matrix:
        \begin{verbatim}
    template <size_t Rows, size_t Columns, typename DataType>
    Matrix<1, Columns, DataType>
    Matrix<Rows, Columns, DataType>::columnMarginals() const
    {
        return MatrixRow(*this);
    }

    template <size_t Rows, size_t Columns, typename DataType>
    Matrix<Rows, 1, DataType>
    Matrix<Rows, Columns, DataType>::rowMarginals() const
    {
        return MatrixColumn(*this);
    }

    template <size_t Rows, size_t Columns, typename DataType>
    DataType Matrix<Rows, Columns, DataType>::sum()  const
    {
        return rowMarginals().sum();
    }
\end{verbatim}
    \end{itemize}

\subsection{The MatrixRow partial specialization}
    \typeout{Original Yodl file: classtemplates/matrixrow}    Class template \emph{partial specializations} can be defined for any (subset)
        \index{class template: partial specialization}
    of template parameters. They can be defined for template type parameters
and for template non-type parameters alike. Our first partial specialization
defines a row of a generic \texttt{Matrix}, mainly (but not only) used for the
construction of column marginals. Here is how such a partial specialization is
designed:
    \begin{itemize}
    \item  The partial specialization starts with a template header defining all
template parameters that are \emph{not} specialized in the partial
specialization. This template header cannot specify any defaults (like
\texttt{DataType = double}) since defaults were already specified by the generic
class template definition.  The specialization \emph{must} follow the definition
of the generic class template's definition, or the compiler complains that it
doesn't know what class is being specialized. Following the template header,
the class's interface starts. It's a class template (partial) specialization
so the class name must be followed by a template argument list specifying the
template arguments used by the partial specialization. The arguments specify
explicit types or values for some of the template's parameters. Remaining
types are simply copied from the class template partial specialization's
template parameter list. E.g., the \texttt{MatrixRow} specialization specifies 1
for the generic class template's \texttt{Rows} non-type parameter (as we're talking
here about a single row). Both \texttt{Columns} and \texttt{DataType} remain to be
specified. The \texttt{MatrixRow} partial specialization therefore starts as
follows:
        \begin{verbatim}
    template <size_t Columns, typename DataType>  // no default allowed
    class Matrix<1, Columns, DataType>
\end{verbatim}
    \item  A \texttt{MatrixRow} holds the data of a single row. So it needs a
data member storing \texttt{Columns} values of type \texttt{DataType}. Since \texttt{Columns}
is a constant value, the \texttt{d\_row} data member can be defined as an array:
        \begin{verbatim}
        DataType d_column[Columns];
\end{verbatim}
    \item  The class template partial specialization's constructors require some
attention. The default constructor is simple. It merely initializes the
\texttt{MatrixRow}'s data elements using \texttt{DataType}'s default constructor:
        \begin{verbatim}
    template <size_t Columns, typename DataType>
    Matrix<1, Columns, DataType>::Matrix()
    {
        std::fill(d_column, d_column + Columns, DataType());
    }
\end{verbatim}
    Another constructor is needed initializing a \texttt{MatrixRow} object
with the column marginals of a generic \texttt{Matrix} object. This requires us to
provide the constructor with a non-specialized \texttt{Matrix} parameter.

The \index{rule of thumb}rule of thumb here is to define a member template that allows us to
keep the general nature of the parameter. The generic \texttt{Matrix}
template requires three template parameters. Two of these were already
provided by the template specialization. The third parameter is mentioned in
the member template's template header. Since this parameter refers to the
number of rows of the generic matrix it is simply called \texttt{Rows}.

Here then is the implementation of the second constructor, initializing the
\texttt{MatrixRow}'s data with the column marginals of a generic \texttt{Matrix} object:
        \begin{verbatim}
    template <size_t Columns, typename DataType>
    template <size_t Rows>
    Matrix<1, Columns, DataType>::Matrix(
                            Matrix<Rows, Columns, DataType> const &matrix)
    {
        std::fill(d_column, d_column + Columns, DataType());

        for (size_t col = 0; col < Columns; col++)
            for (size_t row = 0; row < Rows; row++)
                d_column[col] += matrix[row][col];
    }
\end{verbatim}
    The constructor's parameter is a reference to a \texttt{Matrix} template using
the additional \texttt{Row} template parameter as well as the template parameters
of the partial specialization.
    \item  We don't really require additional members to satisfy our current
needs. To access the data elements of the \texttt{MatrixRow} an overloaded
\texttt{operator{[}{]}()} is of course useful. Again, the \texttt{const} variant can be
implemented like the non-\texttt{const} variant. Here is its implementation:
        \begin{verbatim}
    template <size_t Columns, typename DataType>
    DataType &Matrix<1, Columns, DataType>::operator[](size_t idx)
    {
        return d_column[idx];
    }
\end{verbatim}
    \end{itemize}
    Now that we have defined the generic \texttt{Matrix} class and the
partial specialization defining a single row the compiler selects the
row's specialization whenever a \texttt{Matrix} is defined using \texttt{Row = 1}. For
example:
        \begin{verbatim}
    Matrix<4, 6> matrix;        // generic Matrix template is used
    Matrix<1, 6> row;           // partial specialization is used
\end{verbatim}
\subsection{The MatrixColumn partial specialization}
    \typeout{Original Yodl file: classtemplates/matrixcol}    The partial specialization for a \texttt{MatrixColumn} is constructed
similarly. Let's present its highlights (the full \texttt{Matrix} class template
definition as well as all its specializations are provided in the
\texttt{cplusplus.yo.zip} archive (that can be obtained from the \textbf{C++} Annotations' 
\texttt{Gitlab}\footnote{https://fbb-git.gitlab.io/cppannotations/} website) in the
file \texttt{yo/classtemplates/examples/matrix.h}):
    \begin{itemize}
    \item  The class template partial specialization once again starts with a
template header. Now the class interface specifies a fixed value for the
second template parameter of the generic class template. This illustrates that
we can construct partial specializations for every single template parameter;
not just for the first or the last:
        \begin{verbatim}
    template <size_t Rows, typename DataType>
    class Matrix<Rows, 1, DataType>
\end{verbatim}
    \item  Its constructors are implemented completely analogously to the way
the \texttt{MatrixRow} constructors were implemented. Their implementations are
left as an exercise to the reader (and they can be found in \texttt{matrix.h}).
    \item  An additional member \texttt{sum} is defined to compute the sum of the
elements of a \texttt{MatrixColumn} vector. It's simply implemented
using the \texttt{accumulate} generic algorithm:
        \begin{verbatim}
    template <size_t Rows, typename DataType>
    DataType Matrix<Rows, 1, DataType>::sum()
    {
        return std::accumulate(d_row, d_row + Rows, DataType());
    }
\end{verbatim}
    \end{itemize}

\subsection{The 1x1 matrix: avoid ambiguity}
    \typeout{Original Yodl file: classtemplates/onebyone}    The reader might wonder what happens if we define the following matrix:
        \begin{verbatim}
    Matrix<1, 1> cell;
\end{verbatim}
Is this a \texttt{MatrixRow} or a \texttt{MatrixColumn} specialization? The answer
is: neither.

It's ambiguous, precisely because \emph{both} the columns \emph{and} the rows could
be used with a (different) template partial specialization. If such a
\texttt{Matrix} is actually required, yet another specialized template must be
designed.

Since this template specialization can be useful to obtain the sum of the
elements of a \texttt{Matrix}, it's covered here as well.
    \begin{itemize}
    \item  This class template partial specialization also needs a template
header, this time only specifying \texttt{DataType}. The class definition specifies
two fixed values: 1 for the number of rows and 1 for the number of columns:
        \begin{verbatim}
    template <typename DataType>
    class Matrix<1, 1, DataType>
\end{verbatim}
    \item  The specialization defines the usual batch of constructors.
Constructors expecting a more generic \texttt{Matrix} type are again implemented as
member templates. For example:
        \begin{verbatim}
    template <typename DataType>
    template <size_t Rows, size_t Columns>
    Matrix<1, 1, DataType>::Matrix(
                            Matrix<Rows, Columns, DataType> const &matrix)
    :
        d_cell(matrix.rowMarginals().sum())
    {}

    template <typename DataType>
    template <size_t Rows>
    Matrix<1, 1, DataType>::Matrix(Matrix<Rows, 1, DataType> const &matrix)
    :
        d_cell(matrix.sum())
    {}
\end{verbatim}
    \item  Since \texttt{Matrix$<$1, 1$>$} is basically a wrapper around a \texttt{DataType}
value, we need members to access that latter value. A type conversion
operator might be useful, but we also defined a \texttt{get} member to obtain
the value if the conversion operator isn't used by the compiler (which
happens when the compiler is given a choice, see section
\ref{ConversionOperators}). Here are the accessors (leaving out their \texttt{const}
variants):
        \begin{verbatim}
    template <typename DataType>
    Matrix<1, 1, DataType>::operator DataType &()
    {
        return d_cell;
    }

    template <typename DataType>
    DataType &Matrix<1, 1, DataType>::get()
    {
        return d_cell;
    }
\end{verbatim}
    \end{itemize}

Finally, the \texttt{main} function shown below illustrates how the \texttt{Matrix}
class template and its partial specializations can be used:
    \begin{verbatim}
    #include <iostream>
    #include "matrix.h"
    using namespace std;

    int main(int argc, char **argv)
    {
        Matrix<3, 2> matrix(cin);

        Matrix<1, 2> colMargins(matrix);
        cout << "Column marginals:\n";
        cout << colMargins[0] << " " << colMargins[1] << '\n';

        Matrix<3, 1> rowMargins(matrix);
        cout << "Row marginals:\n";
        for (size_t idx = 0; idx < 3; idx++)
            cout << rowMargins[idx] << '\n';

        cout << "Sum total: " << Matrix<1, 1>(matrix) << '\n';
    }
    /*
        Generated output from input: 1 2 3 4 5 6

        Column marginals:
        9 12
        Row marginals:
        3
        7
        11
        Sum total: 21
    */
\end{verbatim}
\section{Variadic templates}\label{VARIADIC}
\typeout{Original Yodl file: classtemplates/variadic}Up to this point we've encountered templates defining a fixed number of
template parameters. However, templates may also defined as
    \index{template: variadic}\index{variadic templates}\emph{variadic templates}, allowing any number of
arguments to be passed to their instantiations.

Variadic templates are defined for function templates and for class
templates. Variadic templates allow us to specify an arbitrary number of
template arguments of any type.

Variadic templates were added to the language to prevent us from having to
define many overloaded templates and to be able to create \emph{type safe}
variadic functions.

Although \textbf{C} (and \textbf{C++}) support \index{variadic functions}variadic functions, their use has
always been deprecated in \textbf{C++} as those functions are notoriously
type-\emph{un}safe. Variadic function templates can be used to process objects
that until now couldn't be processed properly by \textbf{C}-style variadic
functions.

Template headers of variadic templates use the phrase
 \index{typename ...Params}\texttt{typename ...Params} (\texttt{Params} being a formal
name). A variadic class template \texttt{Variadic} could be declared as follows:
        \begin{verbatim}
    template<typename ...Params> class Variadic;
\end{verbatim}
Assuming the class template's definition is available then this template
can be instantiated using any number of template arguments. Example:
        \begin{verbatim}
    class Variadic<
            int,
            std::vector<int>,
            std::map<std::string, std::vector<int>>
    > v1;
\end{verbatim}
The template argument list of a variadic template can also be
empty. Example:
        \begin{verbatim}
    class Variadic<> empty;
\end{verbatim}
If this is considered undesirable using an empty template argument list
can be prevented by providing one or more fixed parameters. Example:
        \begin{verbatim}
    template<typename First, typename ...Rest>
    class tuple;
\end{verbatim}
\textbf{C}'s function \index{printf}\texttt{printf} is a well-known example of a type-unsafe
function. It is turned into a type-safe function when it is implemented as a
variadic function template. Not only does this turn the function into a
type-safe function but it is also automatically extended to accept any type
that can be defined by \textbf{C++}. Here is a possible declaration of a variadic
function template \texttt{printcpp}:
        \begin{verbatim}
    template<typename ...Params>
    void printcpp(std::string const &strFormat, Params ...parameters);
\end{verbatim}
The \index{ellipsis}ellipsis (\index{...}...) used in the declaration serves two purposes:
    \begin{itemize}
    \item  In the template header it is written to the \emph{left} of a template
        parameter name where it declares a \index{parameter pack}\emph{parameter pack}. A parameter
        pack allows us to specify any number of template arguments when
        instantiating the template. Parameter packs can be used to
        bind type and non-type template arguments to template parameters.
    \item  In a template implementation it appears to the \emph{right} of the
        template pack's parameter name. In that case it represents a series of
        template arguments that are subsequently matched with a function
        parameter that in turn is provided to the right of the ellipsis. Here
        the ellipsis is known as the \index{unpack operator}\emph{unpack operator} as it `unpacks' a
        series of arguments in a function's argument list thereby implicitly
        defining its parameters.
    \end{itemize}
    \textbf{C++} offers no syntax to access the individual template arguments
directly. However, the arguments can be visited recursively. An example is
provided in the next section. The \emph{number}
 \index{variadic template: number of arguments} of arguments is determined using a
new invocation of the \index{sizeof}\texttt{sizeof} operator:
        \begin{verbatim}
    template<typename ...Params>
    struct StructName
    {
        enum: size_t { s_size = sizeof ...(Params) };
    };

    // StructName<int, char>::s_size          -- initialized to 2
\end{verbatim}
\subsection{Defining and using variadic templates}\label{DEFVARTEMP}
    \typeout{Original Yodl file: classtemplates/defining}The arguments associated with a variadic template parameter are not directly
available to the implementation of a function or class template. We have to
resort to other means to obtain them.

By defining a partial specialization of a variadic template, explicitly
defining an additional template type parameter, we can associate the first
template argument of a parameter pack with this additional (first) type
parameter. The setup of such a variadic function template (e.g., \texttt{printcpp},
see the previous section) is as follows:
    \begin{itemize}
    \item  The \texttt{printcpp} function receives at least a format
string. Following the format string any number of additional arguments may be
specified.
    \item  If there are no arguments trailing the format string then there is no
need to use a function template. An overloaded (non-template) function
is defined to handle this situation.
    \item  A variadic function template handles all remaining situations. In
this case there is always at least one  argument trailing the format
string. That argument's type is matched with the variadic template function's
first (ordinary) template type parameter \texttt{First}. The types of any remaining
arguments are bound to the template function's second template parameter,
which is a parameter pack.
    \item  The variadic function template processes the argument trailing the
format string. Then it recursively calls itself passing the format string and
the parameter pack to the recursive call
    \item  If the recursive call merely receives the format string the
overloaded (non-template) function is called (cf. section
\ref{FUNCTIONSELECTION}) ending the recursion. Otherwise the parameter pack's
first argument is matched with the recursive call's \texttt{First} parameter. As
this reduces the size of the recursive call's parameter pack the recursion
eventually stops.
    \end{itemize}

The overloaded non-template function prints the remainder of the format
string, \emph{en passant} checking for any left-over format specifications:
        \begin{verbatim}
    void printcpp(string const &format)
    {
        size_t left = 0;
        size_t right = 0;

        while (true)
        {
            if ((right = format.find('%', right)) == string::npos)
                break;
            if (format.find("%%", right) != right)
                throw std::runtime_error(
                            "printcpp: missing arguments");
            ++right;
            cout << format.substr(left, right - left);
            left = ++right;
        }
        cout << format.substr(left);
    }
\end{verbatim}
Here is the variadic function template's implementation:
        \begin{verbatim}
    template<typename First, typename ...Params>
    void printcpp(std::string const &format, First value, Params ...params)
    {
        size_t left = 0;
        size_t right = 0;
        while (true)
        {
            if ((right = format.find('%', right)) == string::npos)      // 1
                throw std::runtime_error("printcpp: too many arguments");

            if (format.find("%%", right) != right)                      // 2
                break;

            ++right;
            cout << format.substr(left, right - left);
            left = ++right;
        }
        cout << format.substr(left, right - left) << value;
        printcpp(format.substr(right + 1), params...);
   }
\end{verbatim}
\begin{itemize}
    \item  At 1 the format string is searched for a parameter specification
\texttt{\%}. If none is found then the function is called with too many arguments
and it throws an exception;
    \item  At 2 it verifies that it has not encountered \texttt{\%\%}. If only a single
\texttt{\%} has been seen the \texttt{while}-loop ends, the format string is inserted
into \texttt{cout} up to the \texttt{\%} followed by \texttt{value}, and the recursive call
receives the remaing part of the format string as well as the remaining
parameter pack;
    \item  If \texttt{\%\%} was seen the format string is inserted up to the second
\texttt{\%}, which is ignored, and processing of the format string continues beyond
the \texttt{\%\%}.
    \end{itemize}
    Make sure that the overloaded function is at least declared before the
compiler processes the function template's definition or it won't
call the overloaded function \texttt{printcpp} when compiling the function
template.

Different from \textbf{C}'s \texttt{printf} function \texttt{printcpp} only recognizes
\texttt{\%} and \texttt{\%\%} as format specifiers. The above implementation does not
recognize, e.g., field widths. Type specifiers like \texttt{\%c} and \texttt{\%x} are of
course not needed as \texttt{ostream}'s insertion operator is aware of the types of
the arguments that are inserted into the \texttt{ostream}.  Extending the format
specifiers so that field widths etc. are recognized by this \texttt{printcpp}
implementation is left as an exercise to the reader. Here is an example
showing how \texttt{printcpp} can be called:
        \begin{verbatim}
    printcpp("Hello % with %%main%% called with % args"
                                            " and a string showing %\n",
        "world", argc, "A String"s);
\end{verbatim}
\subsection{Perfect forwarding}\label{PERFECT}
    \typeout{Original Yodl file: classtemplates/perfect}Consider \texttt{string}'s member \texttt{insert}. \texttt{String::insert} has several
overloaded implementations. It can be used to insert text (completely or
partially) provided by a \texttt{string} or by a \texttt{char const $*$} argument; to
insert single characters a specified number of times; iterators can be used to
specify the range of characters to be inserted; etc., etc.. All in all,
\texttt{string} offers as many as five overloaded \texttt{insert} members.

Assume the existence of a class \texttt{Inserter} that is used to insert
information into all kinds of objects. Such a class could have a \texttt{string}
data member into which information can be inserted. \texttt{Inserter}'s interface
only partially has to copy \texttt{string}'s interface to realize this: only
\texttt{string::insert}'s interfaces must be duplicated. The members duplicating
interfaces often contain one statement (calling the appropriate member
function of the object's data member) and are for this reason often
implemented in-line. Such \emph{wrapper functions} merely \index{forward}\emph{forward} their
parameters to the matching member functions of the object's data member.

Another example is found in \emph{factory functions} that also frequently forward
their parameters to the constructors of objects that they return.

\textbf{C++} simplifies and generalizes forwarding of parameters by
offering \index{perfect forwarding}\emph{perfect forwarding}, implemented through rvalue references and
variadic templates. With perfect forwarding the arguments passed to functions
are `perfectly forwarded' to nested functions. Forwarding is called
\emph{perfect} as the arguments are forwarded in a type-safe way. To use perfect
forwarding nested functions must define parameter lists matching the
forwarding parameters both in types and number.

Perfect forwarding is easily implemented:
    \begin{itemize}
    \item  The forwarding function is defined as a template\ \\ 
        (usually a \emph{variadic} template, but single argument forwarding is
        also possible. To define and forward a single argument omit the
        ellipsis from the following code);
    \item  The forwarding function's parameter list is an
        \index{parameter pack: rvalue reference}
        \emph{rvalue reference parameter pack} (e.g., \texttt{Params \&\&...params});
    \item \index{forward}\texttt{std::forward} is used to forward the forwarding function's
        arguments to the nested function, keeping track of their types and
        number. Before \texttt{forward} can be used the \index{utility: header file}\texttt{$<$utility$>$} header file
        must be included.
    \item  The nested function is called using this stanza to specify its
        arguments: \ \\ 
        \texttt{std::forward$<$Params$>$(params)...}.
    \end{itemize}

In the next example perfect forwarding is used to implement \emph{one} member
\texttt{Inserter::insert} that can be used to call any of the five overloaded
\texttt{string::insert} members. The \texttt{insert} function that's actually called now
simply depends on the types and number of arguments that are passed to
\texttt{Inserter::insert}:
        \begin{verbatim}
    class Inserter
    {
        std::string d_str;  // somehow initialized
        public:
                            // constructors not implemented,
                            // but see below
            Inserter();
            Inserter(std::string const &str);
            Inserter(Inserter const &other);
            Inserter(Inserter &&other);

            template<typename ...Params>
            void insert(Params &&...params)
            {
                d_str.insert(std::forward<Params>(params)...);
            }
    };
\end{verbatim}
A factory function returning an \texttt{Inserter} can also easily be implemented
using perfect forwarding. Rather than defining four overloaded factory
functions a single one now suffices. By providing the factory function with an
additional template type parameter specifying the class of the object to
construct the factory function is turned into a completely general factory
function:
        \begin{verbatim}
    template <typename Class, typename ...Params>
    Class factory(Params &&...params)
    {
        return Class(std::forward<Params>(params)...);
    }
\end{verbatim}
Here are some examples showing its use:
        \begin{verbatim}
    Inserter inserter(factory<Inserter>("hello"));
    string delimiter(factory<string>(10, '='));
    Inserter copy(factory<Inserter>(inserter));
\end{verbatim}
The function \texttt{std::forward} is provided by the  standard library. It
performs no magic, but merely returns \texttt{params} as a nameless object. That
way it acts like \texttt{std::move} that also removes the name from an object,
returning it as a nameless object. The unpack operator has nothing to do with
the use of \texttt{forward} but merely tells the compiler to apply \texttt{forward} to
each of the arguments in turn. Thus it behaves similarly to \textbf{C}'s ellipsis
operator used by variadic functions.

Perfect forwarding was introduced in section \ref{CONTRACTIONS}: a template
function defining a \texttt{Type \&\&param}, with \texttt{Type} being a template type
parameter converts \texttt{Type \&\&} to \texttt{Tp \&} if the function is called with
an argument of type \texttt{Tp \&}. Otherwise it binds \texttt{Type} to \texttt{Tp},
with \texttt{param} being defined as  \texttt{Tp \&\&param}. As a result an \emph{lvalue}
argument binds to an lvalue-type (\texttt{Tp \&}), while an \emph{rvalue} argument
binds to an rvalue-type (\texttt{Tp \&\&}).

The function \texttt{std::forward} merely passes the argument (and its type) on to
the called function or object. Here is its simplified implementation:
        \begin{verbatim}
    typedef <type T>
    T &&forward(T &&a)
    {
        return a;
    }
\end{verbatim}
Since \texttt{T \&\&} turns into an lvalue reference when \texttt{forward} is called
with an lvalue (or lvalue reference) and remains an rvalue reference if
\texttt{forward} is called with an rvalue reference, and since \texttt{forward} (like
\texttt{std::move}) anonymizes the variable passed as argument to \texttt{forward}, the
argument value is forwarded while passing its type from the function's
parameter to the called function's argument.

This is called \emph{perfect forwarding} as the nested function can only be
called if the types of the arguments that were used when calling the `outer'
function (e.g., \texttt{factory}) exactly match the types of the parameters of the
nested function (e.g., \texttt{Class}'s constructor). Perfect forwarding therefore
is a tool to realize type safety.

A cosmetic improvement to \texttt{forward} requires users of \texttt{forward} to
specify the type to use rather than to have the compiler deduce the type as a
result of the function template parameter type deduction's process. This is
realized by a small support struct template:
        \begin{verbatim}
    template <typename T>
    struct identity
    {
        using type = T;
    };
\end{verbatim}
This struct merely defines \texttt{identity::type} as \texttt{T}, but as it is a
struct it must be specified explicitly. It cannot be determined from the
function's argument itself. The subtle modification to the above
implementation of \texttt{forward} thus becomes (cf. section \ref{DISTINGUISH} for
an explanation of the use of \texttt{typename}):
        \begin{verbatim}
    typedef <type T>
    T &&forward(typename identity<T>::type &&arg)
    {
        return arg;
    }
\end{verbatim}
Now \texttt{forward} must explicitly state \texttt{arg}'s type, as in:
        \begin{verbatim}
    std::forward<Params>(params)
\end{verbatim}
Using the \texttt{std::forward} function and the rvalue reference specification
is not restricted to the context of parameter packs. Because of the special
way rvalue references to template type parameters are treated (cf. section
\ref{CONTRACTIONS}) they can profitably be used to forward individual function
    \index{forward: parameters}
 parameters as well. Here is an example showing how an argument to a function
can be forwarded from a template to a function that is itself passed to the
template as a pointer to an (unspecified) function:
        \begin{verbatim}
    template<typename Fun, typename ArgType>
    void caller(Fun fun, ArgType &&arg)
    {
        fun(std::forward<ArgType>(arg));
    }
\end{verbatim}
A function \texttt{display(ostream \&out)} and \texttt{increment(int \&x)} may now
both be called through \texttt{caller}. Example:
        \begin{verbatim}
    caller(display, cout);
    int x = 0;
    caller(increment, x);
\end{verbatim}
\subsection{The unpack operator}\label{UNPACK}
    \typeout{Original Yodl file: classtemplates/unpack}    The \index{unpack operator}\emph{unpack operator} is used to obtain template arguments in many
situations. No mechanism other than recursion (as shown in section
\ref{DEFVARTEMP}) is available to obtain the individual types and values of a
variadic template.

The unpack operator can also be used to define template classes that are
derived from any number of base classes.
  \index{perfect forwarding: inheritance} Here is how it's done:
        \begin{verbatim}
    template <typename ...BaseClasses>
    class Combi: public BaseClasses...          // derive from base classes
    {
        public:
                                                // specify base class objects
                                                // to its constructor using
                                                // perfect forwarding
            Combi(BaseClasses &&...baseClasses)
            :
                BaseClasses(baseClasses)...     // use base class initializers
            {}                                  // for each of the base
    };                                          // classes
\end{verbatim}
This allows us to define classes that combine the features of any number
of other classes. If the class \texttt{Combi} is derived of classes \texttt{A, B,} and
\texttt{C} then \texttt{Combi} is-an \texttt{A, B,} and \texttt{C}. It should of course be given a
virtual destructor. A \texttt{Combi} object can be passed to functions expecting
pointers or references to any of its base class type objects. Here is an
example defining \texttt{Combi} as a class derived from a vector of complex
numbers, a string and a pair of ints and doubles (using uniform intializers in
a sequence matching the sequence of the types specified for the used \texttt{Combi}
type):
        \begin{verbatim}
    using MultiTypes = Combi<
        vector<complex<double>>, string, pair<int, double> >;

    MultiTypes mt = { {3.5, 4}, "mt", {1950, 1.72} };
\end{verbatim}
The same construction can also be used to define template data members
supporting variadic type lists such as \texttt{tuples} (cf. section
\ref{TUPLES}). Such a class could be designed along these lines:
        \begin{verbatim}
    template <typename ...Types>
    struct Multi
    {
        std::tuple<Types...> d_tup;        // define tuple for Types types

        Multi(Types ...types)
        :                                   // initialize d_tup from Multi's
            d_tup(std::forward<Types>(types)...)   //             arguments
        {}
    };
\end{verbatim}
The ellipses that are used when forwarding parameter packs are
essential. The compiler considers their omission an error. In the following
\texttt{struct} definition it was the intent of the programmer to pass a parameter
pack on to a nested object construction but ellipses were omitted while
specifying the template parameters, resulting in a
    \index{parameter pack: not expanded}
 \emph{parameter packs not expanded with `...'} error message:
        \begin{verbatim}
    template <int size, typename ...List>
    struct Call
    {
        Call(List &&...list)
        {
            Call<size - 1, List &&> call(std::forward<List>(list)...);
        }
    };
\end{verbatim}
Instead of the above definition of the \texttt{call} object the programmer
should have used:
        \begin{verbatim}
    Call<size - 1, List &&...> call(std::forward<List>(list)...);
\end{verbatim}
\subsection{Non-type variadic templates}
    \typeout{Original Yodl file: classtemplates/variadicnontype}Variadic templates not necessarily define template types. Non-types can also
be used with
    \index{variadic non-type parameters}
        variadic templates. The following function template accepts any series
of \texttt{int} values, forwarding these values to a class template. The class
template defines an \texttt{enum} value \texttt{result} which is returned by the
function, unless no int values were specified, in which case 0 is returned.
        \begin{verbatim}
    template <int ...Ints>
    int forwarder()
    {
        return computer<Ints ...>::result;  // forwarding the Ints
    }

    template <>     // specialization if no ints are provided
    int forwarder<>()
    {
        return 0;
    }

    // use as:
    cout << forwarder<1, 2, 3>() << ' ' << forwarder<>() << '\n';
\end{verbatim}
The \texttt{sizeof} operator can be used for variadic non-type parameters as
well: \texttt{sizeof...(Ints)} would return 3 when used in the first function
template for \texttt{forwarder$<$1, 2, 3$>$()}.

Variadic non-type parameters are used to define variadic literal
operators, introduced in section \ref{UDL}.

\subsection{Folding expressions}\label{FOLDEXP}
    \typeout{Original Yodl file: classtemplates/fold}Functions accepting variable numbers of arguments (of possibly varying types)
are commonly handled using variadic templates.  Implementations usually
process the first argument, passing the remaining arguments to an overloaded
function, which is defined by the compiler for these remaining argument
types. One of the overloaded versions, accepting zero or one argument, ends
the compiler's recursive implementations.

Sometimes the arguments must be combined using binary operators (like \texttt{arg1
+ arg2 + ...}). In those cases a \index{folding expression}\emph{folding expression} can be used instead
of combining the arguments using a traditional variadic template.

All binary operators (including the assignment, compound assignment and comma
operators) can be used in folding expressions. 

\begin{itemize}
    \item  A \emph{unary left fold} is a fold expression that looks like this:
        \begin{verbatim}
    (... op expr)
\end{verbatim}
where \emph{op} is the binary operator that is used in the fold expression,
and \emph{expr} is an expression formulated in terms of the function parameter
representing the variadic arguments. Here is an example:
        \begin{verbatim}
    template <typename ReturnType, typename ...Params>
    ReturnType sum(Params ...params)
    {
        return (... + params);
    }
\end{verbatim}
If a more elaborate expression than just the designator of the variadic
arguments is used then the expression must be clearly demarcated, e.g., by 
surrounding it with parentheses:
        \begin{verbatim}
    return (... + (2 * params));
\end{verbatim}
In a unary fold expression all the function's arguments matching the types
of the parameter pack are combined using specified operator. E.g.,
        \begin{verbatim}
    sum<int>(1, 2, 3);
\end{verbatim}
returns 6.
    \end{itemize}
    There are no special restrictions that apply to function templates using
fold expressions. Directly returning the result of the fold expression is OK,
but the result could also be used in another expression (maybe inserting its
value into an \texttt{ostream}), or when initializing a variable or object. Also,
the types of the arguments do not have to be identical: the only requirement
is that the fully expanded expression (in the example: \texttt{1 + 2 + 3} is a
valid expression).

\begin{itemize}
    \item  A \emph{unary right fold} is a fold expression that results in the same
expression as its unary left fold alternative, but swaps the ellipses and the
\texttt{params} identifier:
        \begin{verbatim}
    (expr op ...)
\end{verbatim}
\end{itemize}

Together, unary left folds and unary right folds are called \emph{unary folds}.

\begin{itemize}
    \item  A \emph{binary fold} is a fold expression of the following form:
        \begin{verbatim}
    (expr1 op ... op expr2)
\end{verbatim}
Here, either \texttt{expr1} is the identifier representing the variable
arguments or \texttt{expr2} must be that identifier. The other one can be any other
valid expression (as with unary folds, both expressions must be clearly
demarcated). In addition, both operators must be identical.
    \end{itemize}

If a binary operator has been overloaded, it will be used where applicable. A
well-known example is of course \texttt{operator$<$$<$} as defined for \texttt{std::ostream}
objects. A binary fold defined for \texttt{operator$<$$<$} will not only do shifts, but
can also be used to insert a series of arguments into \texttt{cout}:
        \begin{verbatim}
    template <class ...Pack>
    ostream &out2(ostream &out, Pack &&...args)
    {
        return (out << ... << args);
    };
\end{verbatim}
Here is another interesting example: a fold expression for the comma operator:
        \begin{verbatim}
    template <class ...Pack>
    void call(Pack &&...args)
    {
        ... , args();
    };
\end{verbatim}
This unary fold calls each of its arguments in sequence. Arguments could
be function addresses, function object or lambda functions. Note the use of
the rvalue reference when defining the variadic parameter list which prevents
copying of function objects that might be passed to \texttt{call}. Assuming that
\texttt{struct Functor} defines a functor, and that \texttt{void function()} has been
defined, then \texttt{call} could be called this way:
        \begin{verbatim}
    Functor functor;
    call(functor, function, functor, 
        []()
        {
            // ...    
        }
    );
\end{verbatim}
Finally: don't forget the 
        \index{fold expression: parentheses}
    parentheses surrounding fold expressions: they are required!

\section{Tuples}\label{TUPLES}
\typeout{Original Yodl file: classtemplates/tuples}\textbf{C++} offers a \index{generalized pair}\emph{generalized pair} container: the \index{tuple}\emph{tuple}, covered in
this section.  Before tuples can be used the header file \index{tuple: header file}\texttt{$<$tuple$>$} must be
included.

Whereas \texttt{std::pair} containers have limited functionality and only support
two members, tuples have slightly more functionality and may contain an
unlimited number of different data types. In that respect a tuple can be
considered the `template's answer to \textbf{C}'s struct'.

A tuple's generic declaration (and definition) uses the variadic template
notation:
        \begin{verbatim}
    template <class ...Types>
    class tuple;
\end{verbatim}
Here is an example of its use:
        \begin{verbatim}
    using tuple_idsc = std::tuple<int, double &, std::string, char const *>;

    double pi = 3.14;
    tuple_idsc idsc(59, pi, "hello", "fixed");

    // access a field:
    std::get<2>(idsc) = "hello world";
\end{verbatim}
The \index{get}\texttt{std::get$<$idx$>$(tupleObject)} function template returns a
reference to the \texttt{idx}$^{th}$ (zero based) field of the tuple
\texttt{tupleObject}. The index is specified as the function template's non-type
template argument.

Type-based tuple addressing (\index{tuples: type based addressing}) can be
used for tuple types used once in a tuple definition (if the same type is used
repeatedly referring to that type introduces an ambiguity). The next example
shows how to refer to the elements in the above example by type:
        \begin{verbatim}
    get<int>(idsc)              // 59
    get<double &>(idsc)         // 3.14
    get<string>(idsc)           // "hello"s
    get<char const *>(idsc)     // "fixed"
\end{verbatim}
Tuples may be constructed without specifying initial values. Primitive
types are initialized to zeroes; class type fields are initialized by their
default constructors. Be aware that in some situations the construction of a
tuple may succeed but its use may fail. Consider:
        \begin{verbatim}
    tuple<int &> empty;
    cout << get<0>(empty);
\end{verbatim}
Here the tuple \texttt{empty} cannot be used as its \texttt{int \&} field is an
undefined reference. However, \texttt{empty}'s construction succeeds.

Tuples may be assigned to each other if their type lists are identical; if
supported by their constituent types copy constructors are available as
well. Copy construction and assignment is also available if a right-hand type
can be converted to its matching left-hand type or if the left-hand type can
be constructed from the matching right-hand type. Tuples
(matching in number and (convertible) types) can be compared using relational
operators as long as their constituent types support comparisons. In this
respect tuples are like pairs.

Tuples offer the following static elements (using compile-time
initialization):
    \begin{itemize}
    \item \index{tuple\_size}\texttt{std::tuple\_size$<$Tuple$>$::value} returns the number of
types defined for the tuple type \texttt{Tuple}. Example:
        \begin{verbatim}
cout << tuple_size<tuple_idsc>::value << '\n';  // displays: 4
\end{verbatim}
\item \index{tuple\_element}\texttt{std::tuple\_element$<$idx, Tuple$>$::type}
        returns the type of element \texttt{idx} of \texttt{Tuple}. Example:
        \begin{verbatim}
tuple_element<2, tuple_idsc>::type text;  // defines std::string text
\end{verbatim}
\end{itemize}

The unpack operator can also be used to forward the arguments of a
constructor to a tuple data member. Consider a class \texttt{Wrapper} that is
defined as a variadic template:
        \begin{verbatim}
    template <typename ...Params>
    class Wrapper
    {
        ...
        public:
            Wrapper(Params &&...params);
    };
\end{verbatim}
This class may be given a tuple data member which should be initialized by
the types and values that are used when initializing an object of the class
 \index{perfect forwarding: to data members} \texttt{Wrapper} using perfect
forwarding. Comparable to the way a class may inherit from its template types
(cf. section \ref{UNPACK}) it may forward its types and constructor arguments
to its tuple data member:
        \begin{verbatim}
    template <typename ...Params>
    class Wrapper
    {
        std::tuple<Params...> d_tuple;     // same types as used for
                                            // Wrapper itself
        public:
            Wrapper(Params &&...params)
            :                               // initialize d_tuple with
                                            // Wrapper's arguments
                d_tuple(std::forward<Params>(params)...)
            {}
    };
\end{verbatim}
\subsection{Tuples and structured bindings}
    \typeout{Original Yodl file: classtemplates/bindings}Structured bindings were introduced in section \ref{STRUCTBIND}. That
section concentrated on associating structured binding declarations with
data members of structs, returned as POD values. 

Structured bindings, however, can also be used in a much more generic way, by
associating them with tuples. By doing so structured bindings don't have to be
associated with data members, but they may hold values returned by class
members.

The association between structured binding declarations and tuples is very
strong. In fact it is so strong that the standard explicitly allows users to
define tuple specializations, even though tuple specializations live in the
standard namespace, which otherwise is off-limits to programmers (except, of
course, when using its features).

In order to allow structured bindings to be associated with class members
the following steps must be performed:

\begin{itemize}
    \item  The class must be provided with overloaded \texttt{get} member templates,
        using \texttt{int} (or another integral type) specializations, where each
        specialization returns a class element (e.g., a member function).

The availability of \texttt{if constexpr} clauses makes it easy to combine
        all these specializations into a single member template.

Alternatively, a function template defined outside of the class can be
        defined, which allows associating structured bindings with class
        members even if you're not the class's author. In this case the
        function defines a \texttt{ClassType {[}cv{]} \&object} parameter.

\item  A specialization of \texttt{std::tuple\_size$<$Type$>$} is provided, defining
        \texttt{static size\_t const value} as the number of index values that can
        be specified with the \texttt{get$<$idx$>$} function. Although defining
        entities in the standard namespace is normally
       \index{std namespace: additions OK} \emph{off limits} to ordinary programs, in
        this special case such specializations are allowed by the \textbf{C++}
        standard.

\item  A specialization of \texttt{std::tuple\_element$<$idx, Type$>$} is provided,
        defining \texttt{type} as the type matching the return type of
        \texttt{get$<$idx$>$}. 
    \end{itemize}

The flexibility that is achieved by being able to use structured bindings this
way is enormous. As long as a class offers members returning values those
members can be associated with structured binding variables. The member
functions don't even have to return values that are immediately available
(e.g, as data members accessors) but their return values could also be
computed on the spot, by simply referring to the corresponding structured
binding variable.

To illustrate the abovementioned steps for associating structured bindings
with class members we use these classes:
    \begin{verbatim}
    class Euclid
    {
        size_t d_x;
        size_t d_y;
    
        public:
            Euclid(size_t x = 0, size_t y = 0);
            double distance() const;        // sqrt(d_x * d_x + d_y * d_y)
    };
    class Data
    {
        std::string d_text{ "hello from Data" };
        Euclid d_euclid;
    
        public:
            void setXY(size_t x, size_t y);
    
            Euclid factory() const;
            double distance() const;
            std::string const &text() const;
    };
\end{verbatim}
The first step towards allowing structured bindings for \texttt{Data} consists of
defining a (member) termplate \texttt{get}.  If \texttt{Data} is our own class we can
add a member template \texttt{get}. Alternatively, if we're only interested in
accessing \texttt{Data's} public members we could derive a class \texttt{DataGet} from
\texttt{Data}, and provide that class with the \texttt{get} member template. Yet another
possibility is to define a free \texttt{get} function template. The \texttt{get}
function must return whatever we're interested in. To make the appropriate
selection we use an integral type (\texttt{int, size\_t, ...}) selector value, and
the function template thus only has a non-type template parameter. Rather than
defining several specializations using the \texttt{if constexpr} clause is advised,
as it greatly simplifies the function's definition. 

Our \texttt{get} function defines selector 0 for \texttt{factory}, selector 1 for
\texttt{distance} and selector 2 for \texttt{text}. The \texttt{distance} member simply
returns \texttt{d\_euclid.distance()}, and \texttt{Euclid::distance} is run-time
evaluated using its \texttt{d\_x} and \texttt{d\_y} values. Thus, \texttt{distance} is an
example of a function that will be run-time evaluated when we're referring,
later on, to the third structured bindings variable.

Here's the definition of the member template \texttt{get}:
    \begin{verbatim}
    template <size_t Nr>
    auto get() const
    {
        if constexpr (Nr == 0)
            return factory();
    
        if constexpr (Nr == 1)
            return distance();
    
        if constexpr (Nr == 2)
            return text();
    
        static_assert(Nr >= 0 and Nr < 3);
    }
\end{verbatim}
This function is still suboptimal. Consider its specialization for value 2: it
returns \texttt{Data::text()}. As \texttt{auto} merely inspects the returned data type,
\texttt{get$<$2$>$()} returns a \texttt{std::string}, rather than (text's) return type,
which is a \texttt{std::string const \&}. To use the return types that are actually
returned by \texttt{Data's} member functions, \texttt{get's} return type should be
defined as \texttt{decltype(auto)} rather than just \texttt{auto}:
        \begin{verbatim}
    template <size_t Nr>
    decltype(auto) get() const
    ...
\end{verbatim}
When defining \texttt{get} as a free function template it must be provided with a
parameter \texttt{Data const \&data} (or \texttt{Data \&data} if members are used that may
modify \texttt{data's} data members), returning the parameter's member
functions. E.g.,
        \begin{verbatim}
        // get as a free function template:
    template <size_t Nr>
    decltype(auto) get(Data const &data)
    {
        if constexpr (Nr == 0)
            return data.factory();
    
        if constexpr (Nr == 1)
            return data.distance();
    
        ... // (etc)
    }
\end{verbatim}
Now that step 1 has been completed, we turn our attention to the
\texttt{std::tuple} specializations. These specializations 
    \index{std namespace: additions OK} are defined inside the \texttt{std} namespace
(using \texttt{namespace std \{ ... \}} or \texttt{std::tuple...}).

The specialization of \texttt{std::tuple\_size} for \texttt{Data} defines 
\texttt{static size\_t const value} as the number of index values
that can be specified with the \texttt{get$<$idx$>$} function:
    \begin{verbatim}
    template<>
    struct std::tuple_size<Data>
    {
        static size_t const value = 3;
    };
\end{verbatim}
The specialization of \texttt{std::tuple\_element} for \texttt{Data} returns the types
matching the various return types of the \texttt{get} member template. Its
implementation also provides a nice example where \texttt{declval} is used: the
return type of the \texttt{get$<$Nr$>$} specialization must be determined. But to
obtain that return type a \texttt{Data} object is required, which isn't available
by just mentioning \texttt{Data} in \texttt{tupe\_element's} specialization. However,
\texttt{declval$<$Data$>$()} defines an rvalue reference, which \emph{can} be passed to
\texttt{get$<$Nr$>$}. But the function's return \emph{value} isn't required, so the object
doesn't have to be constructed. Only its return type is needed. Hence, by
surrounding the \texttt{get$<$Nr$>$} call by \texttt{decltype} no object is constructed, and
merely its return type is used:
    \begin{verbatim}
    template<size_t Nr>
    struct std::tuple_element<Nr, Data>
    {
        using type = decltype( declval<Data>().get<Nr>() );
        // if get<Nr> is a free function use:
        //           decltype( get<Nr>( declval<Data>() ) );
    
    };
\end{verbatim}
As \texttt{tuple\_size} and \texttt{tuple\_element} are directly associated with the class
\texttt{Data} their definitions should be provided in \texttt{Data's} header file, below
\texttt{Data's} class interface.

Here's how this could be used in a \texttt{main} function, showing single object
access and access using a range-based for-loop:
    \begin{verbatim}
    int main()
    {
        Data data;
        auto &[ ef, dist, txt ] = data;
        // or maybe:
        // auto &&[ ef, dist, txt ] = Data{};
    
        cout << dist << ' ' << txt << '\n';
    
        Data array[5];
        for (auto &[ ef, dist, txt]: array)
            cout << "for: " << dist << ' ' << txt << '\n';
    }
\end{verbatim}
\section{Computing the return type of function objects}
\typeout{Original Yodl file: classtemplates/returntype}As amply illustrated in chapter \ref{GENERIC} function objects play an
important role with generic algorithms. Like generic algorithms themselves,
function objects can be generically defined as members of class templates. If
the function call operators (\texttt{operator()}) of such classes define parameters
then the types of those parameters may also be abstracted by defining the
function call operators themselves as member templates.  Example:
        \begin{verbatim}
    template <typename Class>
    class Filter
    {
        Class obj;
        public:
            template <typename Param>
            Param operator()(Param const &param) const
            {
                return obj(param);
            }
    };
\end{verbatim}
The template class \texttt{Filter} is a wrapper around \texttt{Class}, filtering
\texttt{Class}'s function call operator through its own function call operator. In
the above example the return value of \texttt{Class}'s function call operator is
simply passed on, but any other manipulation is of course also possible.

A type that is specified as \texttt{Filter}'s template type argument may of
course have multiple function call operators:
        \begin{verbatim}
    struct Math
    {
        int operator()(int x);
        double operator()(double x);
    };
\end{verbatim}
\texttt{Math} objects can now be filtered using \texttt{Filter$<$Math$>$ fm} using
\texttt{Math}'s first or second function call operator, depending on the actual
argument type. With \texttt{fm(5)} the \texttt{int}-version is used, with \texttt{fm(12.5)}
the \texttt{double}-version is used.

However, this scheme doesn't work if the function call operators have
different return and argument types. Because of this the following class
\texttt{Convert} cannot be used with \texttt{Filter}:
        \begin{verbatim}
    struct Convert
    {
        double operator()(int x);           // int-to-double
        std::string operator()(double x);   // double-to-string
    };
\end{verbatim}
This problem can be tackled successfully by the class template
 \index{return type: via invoke\_result}
 \texttt{std::invoke\_result$<$Functor, Types...$>$}. Before using
\texttt{std::invoke\_result} the header file \index{functional: header file}\texttt{$<$functional$>$} must be included.

The \texttt{result\_of} class template offers a using declaration (\texttt{type}),
representing the type that is returned by \texttt{Functor$<$TypeList$>$}. It can be
used as follows to improve the implementation of \texttt{Filter}:
        \begin{verbatim}
    template <typename Class>
    class Filter
    {
        Class obj;
        public:
            template <typename Arg>
            std::invoke_result<Class, Arg>::type 
                operator()(Arg const &arg) const
                {
                    return obj(arg);
                }
    };
\end{verbatim}
Using this definition, \texttt{Filter$<$Convert$>$ fc} can be constructed. Now
\texttt{fc(5)} returns a \texttt{double}, while \texttt{fc(4.5)} returns a
\texttt{std::string}.

The class \texttt{Convert} must define the relationships between its function call
operators and their return types. Predefined function objects (like those in
the standard template library) already do so, but self-defined function
objects must do this explicitly.

If a function object class defines only one function call operator it can
specify its return type through a using-declaration. If the above class
\texttt{Convert} would only define the first of its two function call operators
then the using declaration (in the class's \texttt{public} section) should be:
        \begin{verbatim}
    using type = double;
\end{verbatim}
If multiple function call operators are defined, each with its own signature
and return type, then the association between signature and return type is set
up as follows (all in the class's \texttt{public} section):
    \begin{itemize}
    \item  define a generic \texttt{struct result} like this:
        \begin{verbatim}
template <typename Signature>
struct result;
\end{verbatim}
\item  For each function call signature define a \emph{specialization} of
\texttt{struct result}. \texttt{Convert}'s first function call operator gives rise to:
        \begin{verbatim}
template <typename Class>
struct result<Class(int)>
{
    using type = double;
};
\end{verbatim}
and \texttt{Convert}'s second function call operator to:
        \begin{verbatim}
template <typename Class>
struct result<Class(double)>
{
    using type = std::string;
};
\end{verbatim}
\item  In cases where function call operators have multiple arguments the
specifications should again provide for the correct signatures. A function
call operator called with an \texttt{int} and a \texttt{double}, returning a \texttt{size\_t}
gets:
        \begin{verbatim}
template <typename Class>
struct result<Class(int, double)>
{
    using type = size_t;
};
\end{verbatim}
\end{itemize}

\section{Instantiating class templates}
\typeout{Original Yodl file: classtemplates/instantiations}Class templates \index{class template: instantiation} are instantiated when an
object of a class template is defined. When a class template object is
defined or declared its template parameters must explicitly be specified.

Template parameters are \emph{also} specified when default template parameter
values are specified albeit that in that case the compiler provides the
defaults (cf. section \ref{PARTIAL} where \texttt{double} is used as the default
type to use for the template's \texttt{DataType} parameter).  The actual values or
types of template parameters are
    \index{class template: deducing parameters}
 \emph{never} deduced from arguments as is done with function template
parameters. So to define a \texttt{Matrix} of complex-valued elements, the
following syntax is used:
        \begin{verbatim}
    Matrix<3, 5, std::complex> complexMatrix;
\end{verbatim}
Since the class template \texttt{Matrix} uses a default data type
a matrix of \texttt{double}-valued elements can be defined like this:
        \begin{verbatim}
    Matrix<3, 5> doubleMatrix;
\end{verbatim}
A class template object may be \emph{declared} using the keyword \index{extern}\texttt{extern}.
        \index{class template: declaration}
    For example, to \emph{declare} the matrix \texttt{complexMatrix} use:
        \begin{verbatim}
    extern Matrix<3, 5, std::complex> complexMatrix;
\end{verbatim}
\index{reference: to class template}
        \index{pointer: to class template}
        \index{class template: reference to}
        \index{class template: pointer to}
    A class template declaration suffices to compile return values or
parameters that are of class template types. Example: the following source
file may be compiled, although the compiler hasn't seen the definition of the
\texttt{Matrix} class template.  Generic classes and (partial) specializations may
all be declared. A function expecting or returning a class template object,
reference, or parameter automatically becomes a function template itself. This
is necessary to allow the compiler to tailor the function to the types of
various actual arguments that may be passed to the function:
        \begin{verbatim}
    #include <cstddef>

    template <size_t Rows, size_t Columns, typename DataType = double>
    class Matrix;

    template <size_t Columns, typename DataType>
    class Matrix<1, Columns, DataType>;

    Matrix<1, 12> *function(Matrix<2, 18, size_t> &mat);
\end{verbatim}
When class templates are \emph{used} the compiler must first have seen their
implementations. So, template member functions must be known to the compiler
when the template is instantiated.  This does not mean that \emph{all} members of
a template class are instantiated or must have been seen when a class template
object is defined.
        \index{class template: member instantiation}
    The compiler only instantiates those members that are actually used. This
is illustrated by the following simple class \texttt{Demo} that has two
constructors and two members. When we use one constructor and call one member
in \texttt{main} note the sizes of the resulting object file and executable
program. Next the class definition is modified in that the unused constructor
and member are commented out. Again we compile and link the program. Now
observe that these latter sizes are identical to the former sizes.  There are
other ways to illustrate that only used members are instantiated. The \index{nm}\texttt{nm}
program could be used. It shows the symbolic content of object files.  Using
\texttt{nm} we'll reach the same conclusion: \emph{only template member functions that
are actually used are instantiated}.  Here is the class template \texttt{Demo} that
was used for our little experiment. In \texttt{main} only the first constructor
and the first member function are called and thus only these members were
instantiated:
        \begin{verbatim}
    #include <iostream>

    template <typename Type>
    class Demo
    {
        Type d_data;
        public:
            Demo();
            Demo(Type const &value);
            void member1();
            void member2(Type const &value);
    };
    template <typename Type>
    Demo<Type>::Demo()
    :
        d_data(Type())
    {}
    template <typename Type>
    void Demo<Type>::member1()
    {
        d_data += d_data;
    }

    // the following members should be commented out before
    // compiling for the 2nd time:

    template <typename Type>
    Demo<Type>::Demo(Type const &value)
    :
        d_data(value)
    {}
    template <typename Type>
    void Demo<Type>::member2(Type const &value)
    {
        d_data += value;
    }

    int main()
    {
        Demo<int> demo;
        demo.member1();
    }
\end{verbatim}
\section{Processing class templates and instantiations}
\typeout{Original Yodl file: classtemplates/nameresolution}In section \ref{NAMERESFUN} the distinction between code depending on template
parameters and code not depending on template parameters was introduced.
The same distinction also holds true when class templates are defined and
used.

Code not depending on template parameters is verified by the compiler when
the template is defined. If a member function in a class template uses a
\index{qsort}\texttt{qsort} function, then \texttt{qsort} does not depend on a template
parameter. Consequently, \texttt{qsort} must be known to the compiler when it
encounters \texttt{qsort}'s function call. In practice this implies that the
\index{cstdlib: header file}\texttt{$<$cstdlib$>$} header file must have been read by the compiler before it
is able to compile the class template definition.

On the other hand, if a template defines a \texttt{$<$typename Ret$>$} template
type parameter to parameterize the return type of some template member
function as in:
        \begin{verbatim}
    Ret member();
\end{verbatim}
then the compiler may encounter \texttt{member} or the class to which
\texttt{member} belongs in the following locations:
    \begin{itemize}
    \item  the location where a class template object is defined. This is called
the
        \index{point of instantiation}\emph{point of instantiation} of the class template object.
    The compiler must have read the class template's implementation and has
performed a basic check for syntactic correctness of member functions like
\texttt{member}. It won't accept a definition or declaration like \texttt{Ret \&\&
$*$member}, because \textbf{C++} does not support functions returning pointers to
rvalue references. Furthermore, it checks whether the actual type name
that is used for instantiating the object is valid. This type name must be
known to the compiler at the object's point of instantiation.
    \item  the location where the template member function is used. This is
called the template member function's point of instantiation. Here
the \texttt{Ret} parameter must have been specified (or deduced) and at this point
\texttt{member}'s
statements that depend on the \texttt{Ret} template parameter are checked for
syntactic correctness. For example, if \texttt{member} contains a statement
like
        \begin{verbatim}
    Ret tmp(Ret(), 15);
\end{verbatim}
then this is in principle a syntactically valid statement. However, when
\texttt{Ret = int} the statement fails to compile as \texttt{int} does not have a
constructor expecting two \texttt{int} arguments. Note that this is \emph{not} a
problem when the compiler instantiates an object of \texttt{member}'s class.  At
the point of instantiation of the object its member function `\texttt{member}' is
not instantiated and so the invalid \texttt{int} construction remains undetected.
    \end{itemize}

\section{Declaring friends}\label{TEMPFRIENDS}
\typeout{Original Yodl file: classtemplates/friends}    Friend \index{friend} functions are normally constructed as \emph{support} (free)
functions of a class that cannot be implemented and declared as class
members. The insertion operator for output streams is a well-known
example. Friend classes are most often seen in the context of nested classes.
Here the inner class declares the outer class as its friend (or the other way
around). Again we see a support mechanism: the inner class is constructed to
support the outer class.

Like ordinary classes, class templates may declare other functions and
classes as their friends. Conversely, ordinary classes may declare template
classes as their friends. Here too, the friend is constructed as a special
function or class augmenting or supporting the functionality of the declaring
class. Although the \texttt{friend} keyword can be used by any type of class
        \index{class template: using friend}
        \index{friend: in class templates}
    (ordinary or template) when using class templates the following cases
should be distinguished:
    \begin{itemize}
    \item  A class template may declare an ordinary function or class as its
friend. This is a common friend declaration, such as the insertion operator
for \texttt{ostream} objects.
    \item  A class template may declare another function template or class
template as its friend. In this case, the friend's template parameters may
have to be specified.

If the actual values of the friend's template parameters \emph{must} be equal
to the template parameters of the class declaring the friend, the friend is
said to be a \index{bound friend}\emph{bound friend}\index{friend: bound} class or function template. In
this case the template parameters of the template specifying the \texttt{friend}
declaration determine (\emph{bind}) the values of the template parameters of the
friend class or function. Bound friends result in a one-to-one correspondence
between the template's parameters and the friend's template parameters.
    \item  In the most general case a class template may declare another
function template or class template to be its friend, irrespective of the
friend's actual template arguments.

In this case an \index{unbound friend}\emph{unbound friend} class or function template is
declared. The template parameters of the friend class or function template
remain to be specified and are not related in some predefined way to the
template parameters of the class declaring the friend. If a class template has
data members of various types, specified by its template parameters and
another class should be allowed direct access to these data members we want to
specify any of the current template arguments when specifying such a
friend. Rather than specifying multiple bound friends, a single generic
(unbound) friend may be declared, specifying the friend's actual template
parameters only when this is required.
    \item  The above cases, in which a template is declared as a friend, may
also be encountered when ordinary classes are used:
        \begin{itemize}
        \item  The ordinary class declaring ordinary friends has already been
covered (chapter \ref{Friends}).
        \item  The equivalent of bound friends occurs if an ordinary class
specifies specific actual template parameters when declaring its friend.
        \item  The equivalent of unbound friends occurs if an ordinary class
declares a generic template as its friend.
        \end{itemize}
    \end{itemize}

\subsection{Non-templates used as friends in templates}
    \typeout{Original Yodl file: classtemplates/normalfriends}    A class template may declare an ordinary function, ordinary member
function or ordinary class as its friend.  Such a \index{friend}friend may access the
class template's \index{private members}private members.

Concrete classes and ordinary functions can be declared as friends, but
before a single member function of a class can be declared as a friend, the
compiler must have seen the \index{class interface}class interface declaring that member. Let's
consider the various possibilities:
    \begin{itemize}
    \item  A class template may declare an ordinary function to be its
friend. It is not completely clear \emph{why} we would like to declare an
ordinary function as a friend. Usually we pass an object of the class
declaring the friend to such a function. With class templates this requires us
to provide the (friend) function with a template parameter without specifying
its types. As the language does not support constructions like
        \begin{verbatim}
void function(std::vector<Type> &vector)
\end{verbatim}
unless \texttt{function} itself is a template, it is not immediately clear how
and why such a friend should be constructed. One reason could be to allow the
function access to the class's private static members. In addition such
friends could instantiate objects of classes that declare them as their
friends. This would allow the friend functions direct access to such object's
private members. For example:
        \begin{verbatim}
    template <typename Type>
    class Storage
    {
        friend void basic();
        static size_t s_time;
        std::vector<Type> d_data;
        public:
            Storage();
    };
    template <typename Type>
    size_t Storage<Type>::s_time = 0;
    template <typename Type>
    Storage<Type>::Storage()
    {}

    void basic()
    {
        Storage<int>::s_time = time(0);
        Storage<double> storage;
        std::sort(storage.d_data.begin(), storage.d_data.end());
    }
\end{verbatim}
    \item  Declaring an ordinary class to be a class template's friend probably
finds more applications. Here the ordinary (friend) class may instantiate any
kind of object of the class template. The friend class may then access all
private members of the instantiated class template:
        \begin{verbatim}
    template <typename Type>
    class Composer
    {
        friend class Friend;
        std::vector<Type> d_data;
        public:
            Composer();
    };

    class Friend
    {
        Composer<int> d_ints;
        public:
            Friend(std::istream &input);
    };

    inline::Friend::Friend(std::istream &input)
    {
        std::copy(std::istream_iterator<int>(input),
                  std::istream_iterator<int>(),
                  back_inserter(d_ints.d_data));
    }
\end{verbatim}
    \item  Alternatively, just a single member function of an ordinary class may
be declared as a friend. This requires that the compiler has read the friend
class's interface before declaring the friend. Omitting the required
destructor and overloaded assignment operators, the following shows an example
of a class whose member \texttt{sorter} is declared as a friend of the class
\texttt{Composer}:
        \begin{verbatim}
    template <typename Type>
    class Composer;

    class Friend
    {
        Composer<int> *d_ints;
        public:
            Friend(std::istream &input);
            void sorter();
    };

    template <typename Type>
    class Composer
    {
        friend void Friend::sorter();
        std::vector<Type> d_data;
        public:
            Composer(std::istream &input)
            {
                std::copy(std::istream_iterator<int>(input),
                          std::istream_iterator<int>(),
                          back_inserter(d_data));
            }
    };

    inline Friend::Friend(std::istream &input)
    :
        d_ints(new Composer<int>{ input })
    {}

    inline void Friend::sorter()
    {
        std::sort(d_ints->d_data.begin(), d_ints->d_data.end());
    }
\end{verbatim}
    In this example \texttt{Friend::d\_ints} is a pointer member. It
cannot be a \texttt{Composer$<$int$>$} object as the \texttt{Composer} class interface
hasn't yet been seen by the compiler when it reads \texttt{Friend}'s class
interface. Disregarding this and defining a data member \texttt{Composer$<$int$>$
d\_ints} results in the compiler generating the error
        \index{field `...' has incomplete type}
        \begin{verbatim}
error: field `d_ints' has incomplete type
\end{verbatim}
`Incomplete type', as the compiler at this points knows of the existence
of the class \texttt{Composer}, but as it hasn't seen \texttt{Composer}'s interface it
doesn't know what size the \texttt{d\_ints} data member has.
    \end{itemize}

\subsection{Templates instantiated for specific types as friends}
    \typeout{Original Yodl file: classtemplates/boundfriends}    With \index{bound friend}\emph{bound friend}\index{friend: bound} class or function templates there
is a one-to-one mapping between the template arguments of the friend templates
and the template arguments of the class templates declaring them as
friends. In this case, the friends themselves are templates too. Here are the
various possibilities:
    \begin{itemize}
    \item  A function template is a friend of a class template. In this case we
don't experience the problems we encountered with ordinary functions declared
as friends of class templates. Since the friend function template itself is a
template it may be provided with the required template arguments allowing it
to become the declaring class's friend. The various declarations are organized
like this:
    \begin{itemize}
    \item  The class template declaring the bound template friend function is
defined;
    \item  The (friend) function template is defined, now having access to all
the class template's (private) members.
        \end{itemize}
    The bound template friend declaration specifies the required template
arguments immediately following the template's function name. Without the
template argument list affixed to the function name it would remain an
ordinary friend function. Here is an example showing a bound friend to create
a subset of the entries of a dictionary. For real life examples, a dedicated
function object returning \texttt{!key1.find(key2)} is probably more useful.  For
the current example, \texttt{operator==} is acceptable:
        \begin{verbatim}
    template <typename Key, typename Value>
    class Dictionary
    {
        friend Dictionary<Key, Value>
            subset<Key, Value>(Key const &key,
                               Dictionary<Key, Value> const &dict);

        std::map<Key, Value> d_dict;
        public:
            Dictionary();
    };

    template <typename Key, typename Value>
    Dictionary<Key, Value>
               subset(Key const &key, Dictionary<Key, Value> const &dict)
    {
        Dictionary<Key, Value> ret;

        std::remove_copy_if(dict.d_dict.begin(), dict.d_dict.end(),
                            std::inserter(ret.d_dict, ret.d_dict.begin()),
                            std::bind2nd(std::equal_to<Key>(), key));
        return ret;
    }
\end{verbatim}
\item  By declaring a full class template as a class template's friend, all
members of the friend class may access all private members of the class
declaring the friend. As the friend class only needs to be declared, the
organization of the declaration is much easier than when function templates
are declared as friends. In the following example a class \texttt{Iterator} is
declared as a friend of a class \texttt{Dictionary}. Thus, the \texttt{Iterator} is able
to access \texttt{Dictionary}'s private data. There are some interesting points to
note here:
        \begin{itemize}
        \item  To declare a class template as a friend, that class only needs to
be declared as a class template before it is declared as a friend:
            \begin{verbatim}
    template <typename Key, typename Value>
    class Iterator;

    template <typename Key, typename Value>
    class Dictionary
    {
        friend class Iterator<Key, Value>;
\end{verbatim}
        \item  However, members of the friend class may already be used, even
though the compiler hasn't seen  the friend class's interface yet:
            \begin{verbatim}
    template <typename Key, typename Value>
    template <typename Key2, typename Value2>
    Iterator<Key2, Value2> Dictionary<Key, Value>::begin()
    {
        return Iterator<Key, Value>(*this);
    }
    template <typename Key, typename Value>
    template <typename Key2, typename Value2>
    Iterator<Key2, Value2> Dictionary<Key, Value>::subset(Key const &key)
    {
        return Iterator<Key, Value>(*this).subset(key);
    }
\end{verbatim}
        \item  Of course, the friend class's interface must eventually be seen
by the compiler. Since it's a support class for \texttt{Dictionary} it can safely
define a \texttt{std::map} data member that is initialized by the friend class's
constructor. The constructor may then access the \texttt{Dictionary}'s private data
member \texttt{d\_dict}:
            \begin{verbatim}
    template <typename Key, typename Value>
    class Iterator
    {
        std::map<Key, Value> &d_dict;

        public:
            Iterator(Dictionary<Key, Value> &dict)
            :
                d_dict(dict.d_dict)
            {}
\end{verbatim}
        \item  The \texttt{Iterator} member \texttt{begin} may return a \texttt{map}
iterator. Since the compiler does not know what the instantiation of the map
looks like, a \texttt{map$<$Key, Value$>$::iterator} is a template subtype. So it
cannot be used as-is, but it must be prefixed by
\texttt{typename} (see the function \texttt{begin}'s return type in the next example):
            \begin{verbatim}
    template <typename Key, typename Value>
    typename std::map<Key, Value>::iterator Iterator<Key, Value>::begin()
    {
        return d_dict.begin();
    }
\end{verbatim}
        \end{itemize}

\item  In the previous example we might decide that only a \texttt{Dictionary}
should be able to construct an \texttt{Iterator} (maybe because we conceptually
consider \texttt{Iterator} to be a sub-type of \texttt{Dictionary}). This is easily
accomplished by defining \texttt{Iterator}'s constructor in its private section,
and by declaring \texttt{Dictionary} to be a friend of \texttt{Iterator}. Consequently,
only a \texttt{Dictionary} can create an \texttt{Iterator}. By declaring the constructor
of a \emph{specific} \texttt{Dictionary} type as a friend of \texttt{Iterator}'s we declare
a \emph{bound} friend. This ensures that only that particular type of
\texttt{Dictionary} can create \texttt{Iterator}s using template parameters identical to
its own. Here is how it's done:
        \begin{verbatim}
    template <typename Key, typename Value>
    class Iterator
    {
        friend Dictionary<Key, Value>::Dictionary();
        std::map<Key, Value> &d_dict;
        Iterator(Dictionary<Key, Value> &dict);
        public:
\end{verbatim}
    In this example, \texttt{Dictionary}'s constructor is \texttt{Iterator}'s
friend. The friend is a template member. Other members can be declared as
a class's friend as well. In those cases their prototypes must be used, also
specifying the types of their return values. Assuming that
        \begin{verbatim}
std::vector<Value> sortValues()
\end{verbatim}
is a member of \texttt{Dictionary} then the matching bound friend declaration
is:
        \begin{verbatim}
friend std::vector<Value> Dictionary<Key, Value>::sortValues();
\end{verbatim}
\item  A class template may define free members, which should have access to
the data of instantiations of the class template, but only for matching
types. An example is a class template for which the free member \texttt{operator==}
must be available. If this is required for a template \texttt{ClassTemplate},
requiring a \texttt{typename Type} template type argument, then
a free member 
        \begin{verbatim}
    template<typename Type>
    bool operator==(ClassTemplate<Type> const &lhs, 
                    ClassTemplate<Type> const &rhs);
\end{verbatim}
must have been declared prior to \texttt{ClassTemplate}'s interface
itself. Within the class interface \texttt{operator==} may then be declared as a
friend, specifying \texttt{operator==} as a specialized function template (note the
\texttt{$<$$>$} following the function name) like this:
        \begin{verbatim}
    template <typename Type>
    class ClassTemplate
    {
        friend  bool operator==<>(ClassTemplate<Type> const &lhs, 
                                ClassTemplate<Type> const &rhs);
        ...
    };
\end{verbatim}
Now that the class has been declared, \texttt{operator==}'s implementation may
follow. 
    \end{itemize}

Finally, the following example can be used as a prototype for
situations where bound friends are useful:
        \begin{verbatim}
    template <typename T>   // a function template
    void fun(T *t)
    {
        t->not_public();
    };
    template<typename X>    // a free member function template
    bool operator==(A<X> const &lhs, A<X> const &rhs);
    template <typename X>   // a class template
    class A
    {                       // fun() is used as friend bound to A,
                            // instantiated for X, whatever X may be
        friend void fun<A<X>>(A<X> *);
                            // operator== is a friend for A<X> only
        friend  bool operator==<>(A<X> const &lhs, A<X> const &rhs);

        int d_data = 10;

        public:
            A();

        private:
            void not_public();
    };
    template <typename X>
    A<X>::A()
    {
        fun(this);
    }
    template <typename X>
    void A<X>::not_public()
    {}
    template<typename X>    // may access lhs/rhs's private data
    bool operator==(A<X> const &lhs, A<X> const &rhs)
    {
        return lhs.d_data == rhs.d_data;
    }

    int main()
    {
        A<int> a;

        fun(&a);            // fun instantiated for A<int>.
    }
\end{verbatim}
\subsubsection{Free operators as friends of nested classes}\label{FREEBOUND}
        \typeout{Original Yodl file: classtemplates/freeoperators}When nesting a class under a class template it may be desirable to provide
that nested class with free operators, which are bound to the surrounding
class. This situation is encountered when defining a nested iterator for which
a free \texttt{operator==(iterator const \&lhs, iterator const \&rhs)} operator is
preferred over a member \texttt{operator==(iterator const \&rhs) const}, as the
member does not allow promotions of the lhs operand.

It is possible to define the free \texttt{operator==} as friend in the nested
class, which then automatically becomes a bound friend. E.g.,
        \begin{verbatim}
    #include <string>

    template <typename Type>
    struct String
    {
        struct iterator
        {
            std::string::iterator d_iter;

            friend bool operator==(iterator const &lhs, iterator const &rhs)
            {
                return lhs.d_iter == rhs.d_iter;
            }
        };

        iterator begin()
        {
            return iterator{};
        }
    };

    int main()
    {
        String<int> str;
        return  str.begin() == str.begin();
    }
\end{verbatim}
    However, this requires an in-class implementation, which should be avoided
as it combines interfaces and implementations which reduces clarity.

But when moving the implementation out of the interface we run into the
problem that \texttt{operator==} is a function template, which must be declared as
such in the class interface. The compiler suggests to \emph{make sure the
function template has already been declared and add '$<$$>$' after the function
name}. But declaring
        \begin{verbatim}
    template <typename Type>
    bool operator==(Type const &lhs, Type const &rhs);
\end{verbatim}
before the \texttt{struct String} class template, and then implementing
\texttt{operator==} as 
        \begin{verbatim}
    template <typename Type>
    inline bool operator==(String<Type>::iterator const &lhs,
                           String<Type>::iterator const &rhs)
    {
        return lhs.d_iter == rhs.d_iter;
    }
\end{verbatim}
    the compiler still complains, reporting \emph{declaration of 'operator==' as
non-function}.

So how to solve this issue? There are two known ways to solve this
problem. One was suggested by Radu Cosma (teaching assistant of our \textbf{C++}
course in the 2021-2022 academic year), the other solution is provided in 
section \ref{BOUNDCONCEPT}.

Radu proposed using an application of \emph{SFINAE}: by defining a free operator
provided with a type uniquely defined by the nested class, which is then
provided with a default value in the free function's implementation, the
compiler automatically selects the appropriate overloaded function. This works
for multiple classes declaring nested classes and for classes defining
multiple nested classes alike. Here is an example of two classes each
declaring a nested class \texttt{iterator}:
        \begin{verbatim}
    template <typename Type>
    struct String
    {
        struct iterator
        {
            using StringType_iterator = int;
            friend bool operator==<>(iterator const &lhs, iterator const &rhs);
    
            std::string::iterator d_iter;
        };
        iterator begin()
        {
            return iterator{};
        }
    };
    
    template <typename Type>
    struct Container
    {
        struct iterator
        {
            using ContainerType_iterator = int;
            friend bool operator==<>(iterator const &lhs, iterator const &rhs);
    
            int *d_ptr;
        };
        iterator begin()
        {
            return iterator{};
        }
    };
\end{verbatim}
    Note that the nested classes declare the free functions as function
template specializations.

Then, for each nested class an implementation of the free operator is
provided. These implementations are function templates 
provided with a template type \texttt{Type} and a second type which is the uniquely
named \texttt{int} type of the nested class for which the free operator is
implemented:
        \begin{verbatim}
    template <typename Type, Type::StringType_iterator = 0>
    inline bool operator==(Type const &lhs, Type const &rhs)
    {
        return lhs.d_iter == rhs.d_iter;
    }
    
    template <typename Type, Type::ContainerType_iterator = 0>
    inline bool operator==(Type const &lhs, Type const &rhs)
    {
        return lhs.d_ptr == rhs.d_ptr;
    }
\end{verbatim}
    The \texttt{main} function illustrates the use of both free operators:
        \begin{verbatim}
    int main()
    {
        String<int> str;
        Container<int> cnt;
        return str.begin() == str.begin() and cnt.begin() == cnt.begin();
    }
\end{verbatim}
\subsection{Unbound templates as friends}
    \typeout{Original Yodl file: classtemplates/unboundfriends}    When a friend is declared as an
 \index{friend: unbound}\index{unbound friend}\emph{unbound} friend it merely declares an
existing template to be its friend (no matter how it is instantiated). This
may be useful in situations where the friend should be able to instantiate
objects of class templates declaring the friend, allowing the friend to access
the instantiated object's private members.  Functions, classes, and member
functions may all be declared as unbound friends.

Here are  the syntactic conventions  declaring unbound friends:
    \begin{itemize}
        \item  Declaring a function template as an unbound friend: any
instantiation of the function template may instantiate objects of the template
class and may access its private members. Assume the following
function template has been defined
        \begin{verbatim}
template <typename Iterator, typename Class, typename Data>
Class &ForEach(Iterator begin, Iterator end, Class &object,
                    void (Class::*member)(Data &));
\end{verbatim}
This function template can be declared as an unbound friend in the
following class template \texttt{Vector2}:
        \begin{verbatim}
template <typename Type>
class Vector2: public std::vector<std::vector<Type> >
{
    template <typename Iterator, typename Class, typename Data>
    friend Class &ForEach(Iterator begin, Iterator end, Class &object,
                void (Class::*member)(Data &));
    ...
};
\end{verbatim}
If the function template is defined inside some namespace this namespace
must be mentioned as well. Assuming that \texttt{ForEach} is defined in the
namespace \texttt{FBB} its friend declaration becomes:
        \begin{verbatim}
template <typename Iterator, typename Class, typename Data>
friend Class &FBB::ForEach(Iterator begin, Iterator end, Class &object,
                void (Class::*member)(Data &));
\end{verbatim}
The following example illustrates the use of an unbound friend. The class
\texttt{Vector2} stores vectors of elements of template type parameter
\texttt{Type}. Its \texttt{process} member allows \texttt{ForEach} to call its private
\texttt{rows} member. The \texttt{rows} member, in turn, uses another \texttt{ForEach} to
call its private \texttt{columns} member. Consequently, \texttt{Vector2} uses two
instantiations of \texttt{ForEach} which is a clear hint for using an unbound
friend. It is assumed that \texttt{Type} class objects can be inserted into
\texttt{ostream} objects (the definition of the \texttt{ForEach} function template can
be found in the \texttt{cplusplus.yo.zip} archive that can be retrieved from
\texttt{https://fbb-git.gitlab.io/cppannotations/}). Here is the program:
        \begin{verbatim}
    template <typename Type>
    class Vector2: public std::vector<std::vector<Type> >
    {
        using iterator = typename Vector2<Type>::iterator;

        template <typename Iterator, typename Class, typename Data>
        friend Class &ForEach(Iterator begin, Iterator end, Class &object,
                    void (Class::*member)(Data &));
        public:
            void process();

        private:
            void rows(std::vector<Type> &row);
            void columns(Type &str);
    };

    template <typename Type>
    void Vector2<Type>::process()
    {
        ForEach<iterator, Vector2<Type>, std::vector<Type> >
                (this->begin(), this->end(), *this, &Vector2<Type>::rows);
    }

    template <typename Type>
    void Vector2<Type>::rows(std::vector<Type> &row)
    {
        ForEach(row.begin(), row.end(), *this,
                                        &Vector2<Type>::columns);
        std::cout << '\n';
    }

    template <typename Type>
    void Vector2<Type>::columns(Type &str)
    {
        std::cout << str << " ";
    }

    using namespace std;

    int main()
    {
        Vector2<string> c;
        c.push_back(vector<string>(3, "Hello"));
        c.push_back(vector<string>(2, "World"));

        c.process();
    }
    /*
        Generated output:

        Hello Hello Hello
        World World
    */
\end{verbatim}
    \item  Analogously, a full class template may be declared as friend. This
allows all instantiations of the friend's member functions to instantiate
objects of the class template declaring the friend class. In this case, the
class declaring the friend should offer functionality that is useful to
different instantiations of its friend class (i.e., instantiations using
different template arguments). The syntactic convention is comparable to the
convention used when declaring an unbound friend function template:
        \begin{verbatim}
template <typename Type>
class PtrVector
{
    template <typename Iterator, typename Class>
    friend class Wrapper;      // unbound friend class
};
\end{verbatim}
All members of the class template \texttt{Wrapper} may now instantiate
\texttt{PtrVector}s using any actual type for its \texttt{Type} parameter. This allows
the \texttt{Wrapper} instantiation to access all of \texttt{PtrVector}'s private
members.
    \item  When only some members of a class template need access to private
members of another class template (e.g., the other class template has private
constructors and only some members of the first class template need to
instantiate objects of the second class template), then the latter class
template may declare only those members of the former class template requiring
access to its private members as its friends. Again, the friend class's
interface may be left unspecified. However, the compiler must be informed that
the friend member's class is indeed a class. A forward declaration of that
class must therefore be provided. In the next example \texttt{PtrVector}
declares \texttt{Wrapper::begin} as its friend. Note the forward declaration of
the class \texttt{Wrapper}:
        \begin{verbatim}
template <typename Iterator>
class Wrapper;

template <typename Type>
class PtrVector
{
    template <typename Iterator> friend
        PtrVector<Type> Wrapper<Iterator>::begin(Iterator const &t1);
    ...
};
\end{verbatim}
\end{itemize}

\subsection{Extended friend declarations}
    \typeout{Original Yodl file: classtemplates/extended}Through \index{extended friend}\emph{extended friend} \emph{declarations}, which are also available for
class templates, template type parameters can be declared as friends. A
template type argument, however, does not necessarily have to be a type for
which the keyword \texttt{friend} makes sense, like \texttt{int}. In those cases the
friend declaration is simply ignored.

Consider the following class template, declaring \texttt{Friend} as a friend:
        \begin{verbatim}
    template <typename Friend>
    class Class
    {
        friend Friend;
        void msg();             // private, displays some message
    };
\end{verbatim}
Now, an actual \texttt{Friend} class may access all of \texttt{Class}'s members
        \begin{verbatim}
    class Concrete
    {
        Class<Concrete> d_class;
        Class<std::string> d_string;

       public:
            void msg()
            {
                d_class.msg();    // OK: calls private Class<Concrete>::msg()
                //d_string.msg(); // fails to compile: msg() is private
            }
    };
\end{verbatim}
A declaration like \texttt{Class$<$int$>$ intClass} is also OK, but here the friend
declaration is simply ignored. After all, there are no `int members' to access
\texttt{Class$<$int$>$}'s private members.

\section{Class template derivation}\label{DERIVEDTEMPCLASS}
\typeout{Original Yodl file: classtemplates/derived}Class templates can be used for inheritance purposes as well. When a
class template is used in class derivation, the following situations should be
distinguished:
    \begin{itemize}
    \item  An existing class template is used as base class when deriving a
ordinary class. The derived class itself will partially be a class template,
but this is somewhat hidden from view when an object of the derived class is
defined.
    \item  An existing class template is used as the base class when deriving
another class template. Here the class template characteristics remain clearly
visible.
    \item  An ordinary class is used as the base class when deriving a template
class. This interesting hybrid allows us to construct class templates that
        \index{class template: partially compiled}
are \emph{partially compiled}.
    \end{itemize}
    These three variants of \index{class template: derivation} class template
derivation are elaborated in this and the upcoming sections.

Consider the following base class:
        \begin{verbatim}
    template<typename T>
    class Base
    {
        T const &t;

        public:
            Base(T const &t);
    };
\end{verbatim}
The above class is a class template that can be used as a base class for
the following derived class template \texttt{Derived}:
        \begin{verbatim}
    template<typename T>
    class Derived: public Base<T>
    {
        public:
            Derived(T const &t);
    };
    template<typename T>
    Derived<T>::Derived(T const &t)
    :
        Base(t)
    {}
\end{verbatim}
Other combinations are also possible. The base class may be instantiated
by specifying template arguments, turning the derived class into an ordinary
class (showing a class object's definition as well):
        \begin{verbatim}
    class Ordinary: public Base<int>
    {
        public:
            Ordinary(int x);
    };
    inline Ordinary::Ordinary(int x)
    :
        Base(x)
    {}

    Ordinary ordinary{ 5 };
\end{verbatim}
This approach allows us to
 \index{class template: adding functionality}
    add functionality to a class template, without the need for constructing a
derived class template.

Class template derivation pretty much follows the same rules as ordinary
class derivation, not involving class templates. Some subtleties that are
specific for class template derivation may easily cause confusion like the use
of \texttt{this} when members of a template base class are called from a derived
class. The reasons for using \texttt{this} are discussed in section \ref{SUBTLE}. In
the upcoming sections the focus will be on the class derivation proper.

\subsection{Deriving ordinary classes from class templates}
    \typeout{Original Yodl file: classtemplates/template2concrete}When an existing class template is used as a base class for deriving an
ordinary class, the class template parameters are specified when defining the
derived class's interface.  If in a certain context an existing class template
lacks a particular functionality, then it may be useful to derive an ordinary
class from a class template. For example, although the class \texttt{map} can
easily be used in combination with the \texttt{find\_if()} generic algorithm
(section \ref{FIND}), it requires the construction of a class and at least
two additional function objects of that class. If this is considered too much
overhead then extending a class template with tailor-made functionality
might be considered.

Example: a program executing commands entered at the keyboard might accept all
unique initial abbreviations of the commands it defines. E.g., the command
\texttt{list} might be entered as \texttt{l, li, lis} or \texttt{list}. By deriving a class
\texttt{Handler} from
        \begin{verbatim}
    map<string, void (Handler::*)(string const &cmd)>
\end{verbatim}
and by defining a member function \texttt{process(string const \&cmd)} to do the
actual command processing a program might simply execute the following
\texttt{main()} function:
        \begin{verbatim}
    int main()
    {
        string line;
        Handler cmd;

        while (getline(cin, line))
            cmd.process(line);
    }
\end{verbatim}
    The class \texttt{Handler} itself is derived from a \texttt{std::map}, in which
the map's values are pointers to \texttt{Handler}'s member functions, expecting the
command line entered by the user. Here are \texttt{Handler}'s characteristics:
    \begin{itemize}
    \item  The class is derived from a \texttt{std::map}, expecting the command
associated with each command-processing member as its keys. Since
\texttt{Handler} uses the map merely to define associations between
        \index{inheritance: private derivation} the commands and the processing
member functions and to make \texttt{map}'s types available, private derivation is
used:
        \begin{verbatim}
    class Handler: private std::map<std::string,
                            void (Handler::*)(std::string const &cmd)>
\end{verbatim}
    \item  The actual association can be defined using static private data
members: \texttt{s\_cmds} is an array of \texttt{Handler::value\_type} values, and
\texttt{s\_cmds\_end} is a constant pointer pointing beyond the array's last element:
        \begin{verbatim}
        static value_type s_cmds[];
        static value_type *const s_cmds_end;
\end{verbatim}
    \item  The constructor simply initializes the map from these two static data
members. It could be implemented inline:
        \begin{verbatim}
    inline Handler::Handler()
    :
        std::map<std::string,
                    void (Handler::*)(std::string const &cmd)>
        (s_cmds, s_cmds_end)
    {}
\end{verbatim}
    \item  The member \texttt{process} iterates along the map's elements. Once the
first word on the command line matches the initial characters of the command,
the corresponding command is executed. If no such command is found, an error
message is issued:
        \begin{verbatim}
    void Handler::process(std::string const &line)
    {
        istringstream istr(line);
        string cmd;
        istr >> cmd;
        for (iterator it = begin(); it != end(); it++)
        {
            if (it->first.find(cmd) == 0)
            {
                (this->*it->second)(line);
                return;
            }
        }
        cout << "Unknown command: " << line << '\n';
    }
\end{verbatim}
    \end{itemize}

\subsection{Deriving class templates from class templates}
    \typeout{Original Yodl file: classtemplates/template2template}    Although it's perfectly acceptable to derive an ordinary class from a
class template, the resulting class of course has limited generality compared
to its template base class. If generality is important, it's probably a better
idea to derive a class template from a class template. This allows us to
extend an existing class template with new functionality or to override the
functionality of the existing class template.

The class template \texttt{SortVector} presented below is derived from the
existing class template \texttt{std::vector}. It allows us to perform a
\index{hierarchic sort}\emph{hierarchic sort} of its elements using any ordering of any data members
its data elements may contain. To accomplish this there is but one
requirement. \texttt{SortVector}'s data type must offer dedicated member
functions comparing its members.

For example, if \texttt{SortVector}'s data type is an object of class
\texttt{MultiData}, then \texttt{MultiData} should implement member functions having the
following prototypes for each of its data members which can be compared:
        \begin{verbatim}
    bool (MultiData::*)(MultiData const &rhv)
\end{verbatim}
So, if \texttt{MultiData} has two data members, \texttt{int d\_value} and
\texttt{std::string d\_text} and both may be used by a hierarchic sort, then
\texttt{MultiData} should offer the following two members:
        \begin{verbatim}
    bool intCmp(MultiData const &rhv);  // returns d_value < rhv.d_value
    bool textCmp(MultiData const &rhv); // returns d_text  < rhv.d_text
\end{verbatim}
Furthermore, as a convenience it is assumed that \texttt{operator}$<<$ and
\texttt{operator}$>>$ have been defined for \texttt{MultiData} objects.

The class template \texttt{SortVector} is directly derived from the template
class \texttt{std::vector}. Our implementation inherits all members from that base
class. It also offers two simple constructors:
        \begin{verbatim}
    template <typename Type>
    class SortVector: public std::vector<Type>
    {
        public:
            SortVector()
            {}
            SortVector(Type const *begin, Type const *end)
            :
                std::vector<Type>(begin, end)
            {}
\end{verbatim}
Its member \texttt{hierarchicSort} is the true \emph{raison d'\^{e}tre} for the
class. It defines the hierarchic sort criteria. It expects
        \index{sort criteria: hierarchic sorting}
    a pointer to a series of pointers to member functions of the class
\texttt{Type} as well as a \texttt{size\_t} representing the size of the array.

The array's first element indicates \texttt{Type}'s most significant sort
criterion, the array's last element indicates the class's least significant
sort criterion. Since the \index{stable\_sort}\texttt{stable\_sort} generic algorithm was designed
explicitly to support hierarchic sorting, the member uses this generic
algorithm to sort \texttt{SortVector}'s elements. With hierarchic sorting, the
least significant criterion should be sorted first. \texttt{hierarchicSort}'s
implementation is therefore easy. It requires a support class \texttt{SortWith}
whose objects are initialized by the addresses of the member functions passed
to the \texttt{hierarchicSort()} member:
        \begin{verbatim}
    template <typename Type>
    void SortVector<Type>::hierarchicSort(
                bool (Type::**arr)(Type const &rhv) const,
                size_t n)
    {
        while (n--)
            stable_sort(this->begin(), this->end(), SortWith<Type>(arr[n]));
    }
\end{verbatim}
The class \texttt{SortWith} is a simple wrapper class around a pointer to
a predicate function. Since it depends on \texttt{SortVector}'s actual data
type the class \texttt{SortWith} must also be a class template:
        \begin{verbatim}
    template <typename Type>
    class SortWith
    {
       bool (Type::*d_ptr)(Type const &rhv) const;
\end{verbatim}
\texttt{SortWith}'s constructor receives a pointer to a predicate function and
initializes the class's \texttt{d\_ptr} data member:
        \begin{verbatim}
    template <typename Type>
    SortWith<Type>::SortWith(bool (Type::*ptr)(Type const &rhv) const)
    :
        d_ptr(ptr)
    {}
\end{verbatim}
Its binary predicate member (\texttt{operator()}) must return \texttt{true} if its
first argument should eventually be placed ahead of its second argument:
        \begin{verbatim}
    template <typename Type>
    bool SortWith<Type>::operator()(Type const &lhv, Type const &rhv) const
    {
        return (lhv.*d_ptr)(rhv);
    }
\end{verbatim}
The following examples, which can be embedded in a \texttt{main}
function, provides an illustration:
    \begin{itemize}
    \item  First, A \texttt{SortVector} object is created for \texttt{MultiData} objects.
It uses the \index{copy}\texttt{copy} generic algorithm to fill the \texttt{SortVector} object from
information appearing at the program's standard input stream. Having
initialized the object its elements are displayed to the standard output
stream:
        \begin{verbatim}
        SortVector<MultiData> sv;

        copy(istream_iterator<MultiData>(cin),
                istream_iterator<MultiData>(),
                back_inserter(sv));
\end{verbatim}
    \item  An array of pointers to members is initialized with the addresses of
two member functions. The text comparison is the most significant sort
criterion:
        \begin{verbatim}
        bool (MultiData::*arr[])(MultiData const &rhv) const =
        {
            &MultiData::textCmp,
            &MultiData::intCmp,
        };
\end{verbatim}
    \item  Next, the array's elements are sorted and displayed to the standard
output stream:
        \begin{verbatim}
        sv.hierarchicSort(arr, 2);
\end{verbatim}
    \item  Then the two elements of the array of pointers to \texttt{MultiData}'s
member functions are swapped, and the previous step is repeated:
        \begin{verbatim}
        swap(arr[0], arr[1]);
        sv.hierarchicSort(arr, 2);
\end{verbatim}
    \end{itemize}
    After compiling the program the following command can be given:
        \begin{verbatim}
    echo a 1 b 2 a 2 b 1 | a.out
\end{verbatim}
This results in the following output:
        \begin{verbatim}
    a 1 b 2 a 2 b 1
    ====
    a 1 a 2 b 1 b 2
    ====
    a 1 b 1 a 2 b 2
    ====
\end{verbatim}
\subsection{Deriving class templates from ordinary classes}\label{TFROMC}
    \typeout{Original Yodl file: classtemplates/concrete2template}    An ordinary class may be used as the base class for deriving a template
        \index{class template: derived from ordinary class} class. The advantage
of such an inheritance tree is that the base class's members may all be
compiled beforehand. When objects of the class template are now instantiated
only the actually used members of the derived class template must be
instantiated.

This approach may be used for all class templates having member functions
whose implementations do not depend on template parameters. These members may
be defined in a separate class which is then used as a base class of the
class template derived from it.

As an illustration of this approach we'll develop such a class template
below. We'll develop a class \texttt{Table} derived from an ordinary class
\texttt{TableType}. The class \texttt{Table} displays elements of some type in a
table having a configurable number of columns. The elements are either
displayed horizontally (the first \emph{k} elements occupy the first row) or
vertically (the first \emph{r} elements occupy a first column).

When displaying the table's elements they are inserted into a stream.  The
table is handled by a separate class (\texttt{TableType}), implementing the table's
presentation. Since the table's elements are inserted into a stream, the
conversion to text (or \texttt{string}) is implemented in \texttt{Table}, but the
handling of the strings themselves is left to \texttt{TableType}. We'll cover some
characteristics of \texttt{TableType} shortly, concentrating on \texttt{Table}'s
interface first:

\begin{itemize}
    \item  The class \texttt{Table} is a class template, requiring only one template
type parameter: \texttt{Iterator} referring to an iterator to some data type:
        \begin{verbatim}
template <typename Iterator>
class Table: public TableType
{
\end{verbatim}
    \item  \texttt{Table} doesn't need any data members. All data manipulations are
performed by \texttt{TableType}.
    \item  \texttt{Table} has two constructors. The constructor's first two
parameters are \texttt{Iterator}s used to iterate over the elements that must be
entered into the table. The constructors require us to specify the number of
columns we would like our table to have as well as a
\emph{FillDirection}. \texttt{FillDirection} is an \texttt{enum}, defined by \texttt{TableType},
having values \texttt{HORIZONTAL} and \texttt{VERTICAL}. To allow \texttt{Table}'s users to
exercise control over headers, footers, captions, horizontal and vertical
separators, one constructor has a \texttt{TableSupport} reference parameter. The
class \texttt{TableSupport} is developed at a later stage as a virtual class
allowing clients to exercise this control. Here are the class's constructors:
        \begin{verbatim}
        Table(Iterator const &begin, Iterator const &end,
                size_t nColumns, FillDirection direction);
        Table(Iterator const &begin, Iterator const &end,
                TableSupport &tableSupport,
                size_t nColumns, FillDirection direction);
\end{verbatim}
    \item  The constructors are \texttt{Table}'s only two public members. Both
constructors use a base class initializer to initialize their \texttt{TableType}
base class and then call the class's private member \texttt{fill} to insert data
into the \texttt{TableType} base class object. Here are the constructor's
implementations:
        \begin{verbatim}
template <typename Iterator>
Table<Iterator>::Table(Iterator const &begin, Iterator const &end,
                TableSupport &tableSupport,
                size_t nColumns, FillDirection direction)
:
    TableType(tableSupport, nColumns, direction)
{
    fill(begin, end);
}

template <typename Iterator>
Table<Iterator>::Table(Iterator const &begin, Iterator const &end,
                size_t nColumns, FillDirection direction)
:
    TableType(nColumns, direction)
{
    fill(begin, end);
}
\end{verbatim}
    \item  The class's \texttt{fill} member iterates over the range of elements
\texttt{[begin, end)}, as defined by the constructor's first two parameters.
As we will see shortly, \texttt{TableType} defines a protected data member
\texttt{std::vector$<$std::string$>$ d\_string}. One of the requirements of the data
type to which the iterators point is that this data type can be inserted into
streams. So, \texttt{fill} uses an \texttt{ostringstream} object to obtain the textual
representation of the data, which is then appended to \texttt{d\_string}:
        \begin{verbatim}
template <typename Iterator>
void Table<Iterator>::fill(Iterator it, Iterator const &end)
{
    while (it != end)
    {
        std::ostringstream str;
        str << *it++;
        d_string.push_back(str.str());
    }
    init();
}
\end{verbatim}
    \end{itemize}

This completes the implementation of the class \texttt{Table}. Note that this
class template only has three members, two of them being
constructors. Therefore, in most cases only two function templates must be
instantiated: a constructor and the class's \texttt{fill} member. For example, the
following defines a table having four columns, vertically filled by
\texttt{string}s extracted from the standard input stream:
        \begin{verbatim}
    Table<istream_iterator<string> >
        table(istream_iterator<string>(cin), istream_iterator<string>(),
              4, TableType::VERTICAL);
\end{verbatim}
The fill-direction is specified as
\texttt{TableType::VERTICAL}. It could also have been specified using \texttt{Table},
but since \texttt{Table} is a class template its specification would have been
slightly more complex: \texttt{Table$<$istream\_iterator$<$string$>$ $>$::VERTICAL}.

Now that the \texttt{Table} derived class has been designed, let's turn our
attention to the class \texttt{TableType}. Here are its essential characteristics:
    \begin{itemize}
    \item  It is an ordinary class, designed to operate as \texttt{Table}'s base
class.
    \item  It uses various private data members, among which \texttt{d\_colWidth}, a
vector storing the width of the widest element per column and \texttt{d\_indexFun},
pointing to the class's member function returning the element in
\texttt{table{[}row{]}{[}column{]}}, conditional to the table's fill
direction. \texttt{TableType} also uses a \texttt{TableSupport} pointer and a
reference. The constructor not requiring a \texttt{TableSupport} object uses the
\texttt{TableSupport $*$} to allocate a (default) \texttt{TableSupport} object and then
uses the \texttt{TableSupport \&} as the object's alias. The other constructor
initializes the pointer to 0 and uses the reference data member to refer to
the \texttt{TableSupport} object provided by its parameter. Alternatively, a static
\texttt{TableSupport} object could have been used to initialize the reference data
member in the former constructor. The remaining private data members are
probably self-explanatory:
        \begin{verbatim}
        TableSupport           *d_tableSupportPtr;
        TableSupport           &d_tableSupport;
        size_t                d_maxWidth;
        size_t                d_nRows;
        size_t                d_nColumns;
        WidthType               d_widthType;
        std::vector<size_t>   d_colWidth;
        size_t               (TableType::*d_widthFun)
                                        (size_t col) const;
        std::string const     &(TableType::*d_indexFun)
                                        (size_t row, size_t col) const;
\end{verbatim}
    \item  The actual \texttt{string} objects populating the table are stored in a
protected data member:
        \begin{verbatim}
        std::vector<std::string> d_string;
\end{verbatim}
    \item  The (protected) constructors perform basic tasks: they initialize the
object's data members. Here is the constructor expecting a reference to a
\texttt{TableSupport} object:
        \begin{verbatim}
#include "tabletype.ih"

TableType::TableType(TableSupport &tableSupport, size_t nColumns,
                        FillDirection direction)
:
    d_tableSupportPtr(0),
    d_tableSupport(tableSupport),
    d_maxWidth(0),
    d_nRows(0),
    d_nColumns(nColumns),
    d_widthType(COLUMNWIDTH),
    d_colWidth(nColumns),
    d_widthFun(&TableType::columnWidth),
    d_indexFun(direction == HORIZONTAL ?
                    &TableType::hIndex
                :
                    &TableType::vIndex)
{}
\end{verbatim}
    \item  Once \texttt{d\_string} has been filled, the table is initialized by
\texttt{Table::fill}. The \texttt{init} protected member resizes \texttt{d\_string} so
that its size is exactly \texttt{rows x columns}, and it determines the maximum
width of the elements per column. Its implementation is straightforward:
        \begin{verbatim}
#include "tabletype.ih"

void TableType::init()
{
    if (!d_string.size())                   // no elements
        return;                             // then do nothing

    d_nRows = (d_string.size() + d_nColumns - 1) / d_nColumns;
    d_string.resize(d_nRows * d_nColumns);  // enforce complete table

                                            // determine max width per column,
                                            // and max column width
    for (size_t col = 0; col < d_nColumns; col++)
    {
        size_t width = 0;
        for (size_t row = 0; row < d_nRows; row++)
        {
            size_t len = stringAt(row, col).length();
            if (width < len)
                width = len;
        }
        d_colWidth[col] = width;

        if (d_maxWidth < width)             // max. width so far.
            d_maxWidth = width;
    }
}
\end{verbatim}
    \item  The public member \texttt{insert} is used by the insertion operator
(\texttt{operator}$<<$) to insert a \texttt{Table} into a stream. First it informs the
\texttt{TableSupport} object about the table's dimensions. Next it displays the
table, allowing the \texttt{TableSupport} object to write headers, footers and
separators:
        \begin{verbatim}
#include "tabletype.ih"

ostream &TableType::insert(ostream &ostr) const
{
    if (!d_nRows)
        return ostr;

    d_tableSupport.setParam(ostr, d_nRows, d_colWidth,
                            d_widthType == EQUALWIDTH ? d_maxWidth : 0);

    for (size_t row = 0; row < d_nRows; row++)
    {
        d_tableSupport.hline(row);

        for (size_t col = 0; col < d_nColumns; col++)
        {
            size_t colwidth = width(col);

            d_tableSupport.vline(col);
            ostr << setw(colwidth) << stringAt(row, col);
        }

        d_tableSupport.vline();
    }
    d_tableSupport.hline();

    return ostr;
}
\end{verbatim}
    \item  The \texttt{cplusplus.yo.zip} archive contains \texttt{TableSupport}'s full
implementation. This implementation is found in the directory
\texttt{yo/classtemplates/examples/table}. Most of its remaining members are
private. Among those, these two members return table element
\texttt{{[}row{]}{[}column{]}} for, respectively, a horizontally filled table and a
vertically filled table:
      \begin{verbatim}
    inline std::string const &TableType::hIndex(size_t row, size_t col) const
    {
        return d_string[row * d_nColumns + col];
    }
    inline std::string const &TableType::vIndex(size_t row, size_t col) const
    {
        return d_string[col * d_nRows + row];
    }
\end{verbatim}
    \end{itemize}

The support class \texttt{TableSupport} is used to display headers, footers,
captions and separators. It has four virtual members to perform those tasks
(and, of course, a virtual constructor):
    \begin{itemize}
    \item \texttt{hline(size\_t rowIndex)}: called just before displaying
the elements in row
\texttt{rowIndex}.
    \item \texttt{hline()}: called immediately after displaying the final row.
    \item \texttt{vline(size\_t colIndex)}: called just before displaying the element in
column \texttt{colIndex}.
    \item \texttt{vline()}: called immediately after displaying all elements in a row.
    \end{itemize}
    The reader is referrred to the \texttt{cplusplus.yo.zip} archive for the full
implementation of the classes \texttt{Table}, \texttt{TableType} and \texttt{TableSupport}.
Here is a little program showing their use:
    \begin{verbatim}
    /*
                                  table.cc
    */

    #include <fstream>
    #include <iostream>
    #include <string>
    #include <iterator>
    #include <sstream>

    #include "tablesupport/tablesupport.h"
    #include "table/table.h"

    using namespace std;
    using namespace FBB;

    int main(int argc, char **argv)
    {
        size_t nCols = 5;
        if (argc > 1)
        {
            istringstream iss(argv[1]);
            iss >> nCols;
        }

        istream_iterator<string>   iter(cin);   // first iterator isn't const

        Table<istream_iterator<string> >
            table(iter, istream_iterator<string>(), nCols,
                  argc == 2 ? TableType::VERTICAL : TableType::HORIZONTAL);

        cout << table << '\n';
    }
    /*
        Example of generated output:
        After: echo a b c d e f g h i j | demo 3
            a e i
            b f j
            c g
            d h
        After: echo a b c d e f g h i j | demo 3 h
            a b c
            d e f
            g h i
            j
    */
\end{verbatim}
\section{Static Polymorphism}\label{STATICPOLY}
\typeout{Original Yodl file: classtemplates/staticpoly}Chapter \ref{POLYMORPHISM} introduced polymorphism. Polymorphism allows us to
use a base class's interface to call implementations which are defined in
derived classes. Traditionally this involves defining \emph{Vtables} for
polymorphic classes, containing pointers to functions that can be overridden
in derived classes.  Objects of polymorphic classes harbor hidden pointers,
pointing to their class's Vtables. This type of polymorphism is called
\index{dynamic polymorphism}\emph{dynamic polymorphism}, and it uses \index{late binding}\emph{late binding} as the function to
call is determined run-time, rather than compile-time.

In many cases, however, dynamic polymorphism isn't really required. Usually
the derived class objects that are passed to functions expecting base class
references are invariants: at fixed locations in programs fixed class types
are used to create objects. The polymorphic nature of these objects is used
inside the functions that receive these objects, expecting references to their
base classes. As an example consider reading information from a network
socket. A class \texttt{SocketBuffer} is derived from \texttt{std::streambuf}, and the
\texttt{std::stream} receiving a pointer to the \texttt{SocketBuffer} merely uses
\texttt{std::streambuf's} interface. However, the implementation, by using
polymorphism, in fact communicates with functions defined in \texttt{SocketBuffer}.

The disadvantages of this scheme are that, firstly, inside the functions
expecting references to polymorphic base classes execution is somewhat slowed
down precisely because of late-binding. Member functions aren't
directly called, but are called indirectly via the object's \emph{vpointer} and
their derived class's \emph{Vtable}. Secondly, programs using dynamic
polymorphism tend to become somewhat bloated compared to programs using static
binding. The \index{code bloat}code bloat is caused by the requirement to satisfy at
link-time all the references that are mentioned in all the object files
comprising the final program. This requirement forces the linker to link all
the functions whose addresses are stored in the \emph{Vtables} of all polymorphic
classes, even if these functions are never actually called.

Static polymorphism \index{static polymorphism} allows us to avoid these
disadvantages. It can be used instead of dynamic polymorphism in cases where
the abovementioned invariant holds. Static polymorphism, also called the
    \index{curiously recurring template pattern}\emph{curiously recurring template pattern} (\index{CRTP}\emph{CRTP}), is an example of 
    \index{template meta programming}\emph{template meta programming} (see also chapter \ref{ADVANCEDTEMPL} for
additional examples of template meta programming).

Whereas dynamic polymorphism is based on the concepts of \emph{vpointers,
Vtables}, and \emph{function overriding}, static polymorphism capitalizes on the
fact that function templates (c.q., member templates) are only compiled into
executable code when they are actually called. This allows us to write code in
which functions are called which are completely non-existent at the time we
write our code. This, however, shouldn't worry us too much. After all, we use
a comparable approach when calling a purely virtual function of an abstract
base class. The function is really called, but which function is eventually
called is determined later in time. With dynamic polymorphism it is determined
run-time, with static polymorphism it is determined compile-time.

There's no need to consider static and dynamic polymorphism as mutually
exclusive variants of polymorphism. Rather, both can be used together,
combining their strengths. 

This section contains several subsections.
    \begin{itemize}
    \item  First, the syntax used with static polymorphism is introduced and
        illustrated;
    \item  Next, it is shown how  classes that use dynamic polymorphism can be
        converted to classes that use static polymorphism;
    \item  Finally it is illustrated how static polymorphism can be used to
        reduce implementation effort. Static polymorphism allows us to
        implement only once what would have to be implemented repeatedly when
        only dynamic polymorphism is used.
    \end{itemize}

\subsection{An example of static polymorphism}
    \typeout{Original Yodl file: classtemplates/examplestaticpoly}With static polymorphism a class template takes the role of a base class in
dynamic polymorphism. This class template declares several members, which are
comparable to members of a polymorphic base class: they are either support
members or they call members that are overridden in derived classes.

In the context of dynamic polymorphism these overridable members are the base
class's virtual members. In the context of static polymorphism there are no
virtual members. Instead, the statically polymorphic base class (referred to
as the `base class' below) declares a \emph{template type parameter} (referred to
as the `derived class type' below). Next, the base class's interfacing members
call members of the derived class type.

Here is a simple example: a class template acting as a base class. Its public
interface consists of one member. But different from dynamic polymorphism
there's no reference in the class's interface to any member showing
polymorphic behavior (i.e, no `virtual' members are declared):
        \begin{verbatim}
    template <class Derived>
    struct Base
    {
        void interface();
    }
\end{verbatim}
Let's have a closer look at the member `\texttt{interface}'. This member is called
by functions receiving a reference or pointer to the base class, but it may
call members that must be available in the derived class type at the point
where \texttt{interface} is called. Before we can call members of the derived class
type an object of the derived class type must be available. This object is
obtained through inheritance. The derived class type is going to be derived
from the base class. Thus \texttt{Base's this} pointer is also \texttt{Derived's this}
pointer.

Forget about polymorphism for a second: when we have a \texttt{class Derived:
public Base} then (because of inheritance) a \texttt{static\_cast$<$Derived $*$$>$} can be
used to cast a \texttt{Base $*$} to a \texttt{Derived} object. A \texttt{dynamic\_cast} of
course doesn't apply, as we don't use dynamic polymorphism. But a
\texttt{static\_cast} is appropriate since our \texttt{Base $*$} \emph{does} in fact point to
a \texttt{Derived} class object.

So, to call a \texttt{Derived} class member from inside \texttt{interface} we
can use the following implementation (remember that \texttt{Base} is a base class
of \texttt{Derived}):
        \begin{verbatim}
    template<class Derived>
    void Base<Derived>::interface()
    {
        static_cast<Derived *>(this)->polymorphic();
    }
\end{verbatim}
It's remarkable that, when the compiler is given this implementation it
cannot determine whether \texttt{Derived} is \emph{really} derived from
\texttt{Base}. Neither can it determine whether the class \texttt{Derived} indeed offers
a member \texttt{polymorphic}. The compiler simply \emph{assumes} this to be true. If
so, then the provided implementation is syntactically correct. One of the
key characteristics of using templates is that the implementation's viability
is eventually determined at the function's point of instantiation (cf. section
\ref{TEMPFUNINST}). At that point the compiler will verify that, e.g., the
function \texttt{polymorphic} really is available.

Thus, in order to use the above scheme we must ensure that 
        \begin{itemize}
        \item  derived class type is actually derived from the base class and
        \item  that the derived class type defines a member
            `\texttt{polymorphic}'. 
        \end{itemize}
    The first requirement is satisfied by using the 
        \index{curiously recurring template pattern}\emph{curiously recurring template pattern}:
        \begin{verbatim}
    class First: public Base<First>
\end{verbatim}
In this curious pattern the class \texttt{First} is derived from \texttt{Base},
which itself is instantiated for \texttt{First}. This is acceptable, as the
compiler already has determined that the type \texttt{First} exists. At this point
that is all it needs.

The second requirement is simply satisfied by defining the member
\texttt{polymorphic}. In chapter \ref{POLYMORPHISM} we saw that virtual and
overriding members belong to the class's private interface. We can apply the
same philosophy here, by placing \texttt{polymorphic} in \texttt{First's} private
interface, allowing it to be accessed from the base class by declaring
        \begin{verbatim}
    friend void Base<First>::interface();
\end{verbatim}
\texttt{First's} complete class interface can now be designed, followed by
\texttt{polymorphic's} implementation:
        \begin{verbatim}
    class First: public Base<First>
    {
        friend void Base<First>::interface();

        private:
            void polymorphic();
    };
    void First::polymorphic()
    {
        std::cout << "polymorphic from First\n";
    }
\end{verbatim}
Note that the class \texttt{First} itself is not a class template: its members
can be separately compiled and stored in, e.g., a library. Also, as is the
case with dynamic polymorphism, the member \texttt{polymorphic} has full access to
all of \texttt{First}'s data members and member functions.

Multiple classes can now be designed like \texttt{First}, each offering their
own implementation of \texttt{polymorphic}. E.g., the member
\texttt{Second::polymorphic} of the class \texttt{Second}, designed like \texttt{First},
could be implemented like this:
        \begin{verbatim}
    void Second::polymorphic()
    {
        std::cout << "polymorphic from Second\n";
    }
\end{verbatim}
The polymorphic nature of \texttt{Base} becomes apparent once a function
template is defined in which \texttt{Base::interface} is called. Again, the
compiler simply assumes a member \texttt{interface} exists when it reads the
definition of the following function template:
        \begin{verbatim}
    template <class Class>
    void fun(Class &object)
    {
        object.interface();
    }
\end{verbatim}
Only where this function is actually called will the compiler verify the
viability of the generated code. In the following \texttt{main} function a
\texttt{First} object is passed to \texttt{fun}: \texttt{First} declares \texttt{interface}
through its base class, and \texttt{First::polymorphic} is called by
\texttt{interface}. The compiler will at this point (i.e., where \texttt{fun} is called)
check whether \texttt{first} indeed has a member \texttt{polymorphic}. Next a \texttt{Second}
object is passed to \texttt{fun}, and here again the compiler checks whether
\texttt{Second} has a member \texttt{Second::polymorphic}:
        \begin{verbatim}
    int main()
    {
        First first;
        fun(first);

        Second second;
        fun(second);
    }
\end{verbatim}
There are also downsides to 
        \index{static polymorphism: downsides} 
    using static polymorphism:
        \begin{itemize}
        \item  First, the sentence `a \texttt{Second} object is passed to \texttt{fun}'
formally isn't correct, since \texttt{fun} is a function template the functions
\texttt{fun} called as \texttt{fun(first)} and \texttt{fun(second)} are
\emph{different} functions, not just calls of one function with different
arguments. With static polymorphism every instantiation using its own template
parameters results in completely new code which is generated when the template
(e.g., \texttt{fun}) is instantiated. This is something to consider when creating
statically polymorphic base classes. If the base class defines data members
and member functions, and if these additional members are used by derived
class types, then each member has its own instantiation for each derived class
type. This also results in \index{code bloat}code bloat, albeit of a different kind than
observed with dynamic polymorphism. This kind of code bloat can often be
somewhat reduced by deriving the base class from its own (ordinary,
non-template) base class, encapsulating all elements of the statically
polymorphic base class that do not depend on its template type parameters.
        \item  Second, if different types of statically polymorphic objects are
dynamically created (using the \texttt{new} operator) then the types of the
returned pointers are all different. In addition, the types of the pointers to
their statically polymorphic base classes differ from each other. These
latter pointers are different because they are pointers to \texttt{Base$<$Derived$>$},
representing different types for different \texttt{Derived} types. Consequently,
and different from dynamic polymorphism, these pointers cannot be collected
in, e.g., a vector of shared pointers to base class pointers. There simply
isn't one base class pointer type. Thus, because of the different base class
types, there's no direct statically polymorphic equivalent to virtual
destructors.
        \item  Third, as illustrated in the next section, designing static
polymorphic classes using multiple levels of inheritance is not a trivial
task.
        \end{itemize}
    Summarizing, static polymorphism is best used in situations where a small
number of different derived class types are used, where a fixed number of
derived class objects are used, and where the statically polymorphic base
classes themselves are lean (possibly encapsulating some of their code in
ordinary base classes of their own).

\subsection{Converting dynamic polymorphic classes to static
            polymorphic classes}
    \typeout{Original Yodl file: classtemplates/converting}So you've decided that you want to convert some of your dynamically
polymorphic classes into statically polymorphic classes. Now what?

In chapter \ref{POLYMORPHISM} the base class \texttt{Vehicle} and some derived
classes were introduced. \texttt{Vehicle, Car} and \texttt{Truck}'s interfaces look like
this (regarding the members that are involved in their polymorphic behaviors):
        \begin{verbatim}
    class Vehicle
    {
        public:
            int mass() const;

        private:
            virtual int vmass() const;
    };

    class Car: public Vehicle
    {
        private:
            int vmass() const override;
    };
        
    class Truck: public Car
    {
        private:
            int vmass() const override;
    };
\end{verbatim}
When converting dynamically polymorphic classes to statically polymorphic
classes we must realize that polymorphic classes show two important
characteristics:
    \begin{itemize}
    \item  they define facilities (data members, member functions) that are
inherited by derived classes (e.g., \texttt{Vecicle::mass}) (i.e., the inheritable
interface), and
    \item  derived classes implement the redefinable interface in a way that
suits their purpose (e.g., \texttt{Truck::vmass}).
    \end{itemize}

With statically polymorphic classes these two characteristics should
completely be separated.  As we've seen in the previous section, a
statically polymorphic derived class derives from its base class by using its
own class type as argument to the base class's type parameter. This works fine
if there's only one level of inheritance (i.e., one base class, and one or
more classes that are directly derived from that base class).

With multiple levels of inheritance (e.g., \texttt{Truck -$>$ Car -$>$ Vehicle})
\texttt{Truck}'s inheritance specification becomes a problem. Here's an intial
attempt to use static polymorphism and multiple levels of inheritance:
        \begin{verbatim}
    template <class Derived>
    class Vehicle
    {
        public:
            void mass() 
            {
                static_cast<Derived *>(this)->vmass();
            }
    };
    
    class Car: public Vehicle<Car>
    {
        friend void Vehicle<Car>::mass();
        void vmass();
    };

    class Truck: public Car
    {
        void vmass();
    };
\end{verbatim}
\begin{itemize}
        \item  If \texttt{Truck} inherits from \texttt{Car}, then \texttt{Truck} implicitly
derives from \texttt{Vehicle$<$Car$>$}, as \texttt{Car} derives from
\texttt{Vehicle$<$Car$>$}. Consequently, when \texttt{Truck\{\}.mass()} is called it is not
\texttt{Truck::vmass} that's activated, but \emph{Car's} \texttt{vmass} function. But
\texttt{Truck} \emph{must} derive from \texttt{Car} in order to use \texttt{Car's} protected
features and to add \texttt{Car's} public features to its own public
interface. 
        \item  Multiple inheritance also doesn't solve the issue: when
inheriting \texttt{Truck} from \texttt{Vehicle$<$Truck$>$} \emph{and} from \texttt{Car} 
results in a class \texttt{Truck} that \emph{also} inherits from
\texttt{Vehicle$<$Car$>$} (through \texttt{Truck's Car} base class), and compilation fails
as the compiler encounters an ambiguity when instantiating \texttt{Vehicle::mass}:
should it call \texttt{Class::vmass} or should it call \texttt{Truck::vmass}?
    
    \end{itemize}
    To solve this problem (i.e., to ensure that \texttt{Truck\{\}.mass()} calls
\texttt{Truck::vmass}) the redefinable interface must be separated 
from the inheritable interface.

In derived classes the protected and public interfaces of (direct or indirect)
base classes are made available using standard inheritance. This is shown in
the left-hand side of figure \ref{STATPOLY}.  

\begin{figure}[tbp]
\centerline{\epsffile{classtemplates/converting.eps}}
\caption{\label{STATPOLY}Vehicle Static Polymorphic Class Design}
\end{figure}

The left-hand side classes are used as base classes for the next level of
inheritance (except for \texttt{TruckBase}, but \texttt{TruckBase} could be used as base
class for yet another level of class inheritance). This line of inheritance
declares the inheritable interface of the classes.

Each of the classes to the left is a base class of a single class to the
right: \texttt{VehicleBase} is a base class for \texttt{Vehicle}, \texttt{TruckBase} for
\texttt{Truck}. The classes to the left contain all members that are completely
independent of the elements that are involved in realizing the static
polymorphism. As that's a mere design principle to realize multiple levels of
static polymorphism the common data hiding principles are relaxed, and the
left-hand side classes declare their matching right-hand side derived class
templates as friend, to allow full access to all members of a left-hand side
class, including the private members, from the matching derived class template
to the right. E.g., \texttt{VehicleBase} declares \texttt{Vechicle} as its friend:
        \begin{verbatim}
    class VehicleBase
    {
        template <class Derived>
        friend class Vehicle;

        // all members originally in Vehicle, but not involved 
        // in realizing static polymorphism are declared here. E.g.,
        size_t d_massFactor = 1;
    };
\end{verbatim}
The top level class to the left (\texttt{VehicleBase}) lays the foundation of
static polymorphism, by defining that part of the interface that uses the
statically redefinable functions. E.g, using the curiously recurring template
pattern it defines a class member \texttt{mass} that calls the function \texttt{vmass}
of its derived class (in addition it can use all members of its non-class
template base class). E.g,:
        \begin{verbatim}
    template <class Derived>
    class Vehicle: public VehicleBase
    {
        public:
            int mass() const
            {
                return d_massFactor *
                        static_cast<Derived const *>(this)->vmass();
            }
    };
\end{verbatim}
Which function actually is called when \texttt{vmass} is called depends on the
implementation in the class \texttt{Derived}, which is handled by the remaining
classes, shown below \texttt{Vehicle}, which are all derived from \texttt{Vehicle} (as
well as from their own \texttt{...Base} class). These classes use the curiously
recurring template pattern. E.g.,
        \begin{verbatim}
    class Car: public CarBase, public Vehicle<Car>
\end{verbatim}
So, if \texttt{Car} now implements its own \texttt{vmass} function, which can use
any of its own (i.e., \texttt{CarBase's} members), then \emph{that} function is called
when calling a \texttt{Vehicle's mass} function. E.g.,
        \begin{verbatim}
    template <class Vehicle>
    void fun(Vehicle &vehicle)
    {
        cout << vehicle.mass() << '\n';
    }
    
    int main()
    {
        Car car;
        fun(car);       // Car's vmass is called
    
        Truck truck;
        fun(truck);     // Truck's vmass is called
    }
\end{verbatim}
Now that we've analyzed the design of statically polymorphic classes using
multiple levels of inheritance let's summarize the steps we took to
implement static polymorphism
    \begin{itemize}
    \item  First, starting at the base class,
the class \texttt{Vehicle}. \texttt{Vehicle's} non-redefinable interface is moved
to a class \texttt{VehicleBase}, and \texttt{Vehicle} itself is turned into a statically
polymorphic base class. In general all members of the original 
polymorphic base class that do not use or implement virtual members should be
moved to the \texttt{XBase} class. 

\item  \texttt{VehicleBase} declares \texttt{Vehicle} to be a \texttt{friend}, to allow
\texttt{Vehicle} full access to its former members, that are now in
\texttt{VehicleBase}.

\item  \texttt{Vehicle's} members refer to the redefinable interface. I.e., its
members call members of its \texttt{Derived} template type parameter.  In this
implementation \texttt{Vehicle} does not implement its own \texttt{vmass} member. We
cannot define \texttt{Vehicle$<$Vehicle$>$}, and with static polymorphism the base
class is essentially comparable to an abstract base class. If this is
inconvenient then a default class can be specified for \texttt{Vehicle's Derived}
class, implementing the redefinable interface of the original 
polymorphic base class (allowing for definitions like \texttt{Vehicle$<$$>$ vehicle}).

\item  Likewise the remaining classes have their members not involved in
static polymorphism moved to a base class. E.g., 
class \texttt{Car} moves these members to  \texttt{CarBase} and
\texttt{Truck} moves those members to  \texttt{TruckBase}.  

\item  A standard linear line of inheritance is used from \texttt{VehicleBase} to
\texttt{CarBase} and from there to \texttt{TruckBase}.

\item  Each of the remaining classes (here: \texttt{Car} and \texttt{Truck}) is a
class template that derives from its base classes, and also, using the
curiously recurrent template pattern, from \texttt{Vehicle}.

\item  Each of these remaining classes can now implement its own version of
the redefinable interface, as used by the members of \texttt{Vehicle}.
    \end{itemize}

This design pattern can be extended to any level of inheritance: for each
new level a base class is constructed, deriving from the most deeply nested
\texttt{XXXBase} class so far, and deriving from \texttt{Vehicle$<$XXX$>$}, implementing its
own ideas about the redefinable interface.

Functions that are used in combination with statically polymorphic classes
themselves must be function templates. E.g.,
        \begin{verbatim}
    template <class Vehicle>
    void fun(Vehicle &vehicle)
    {
        cout << vehicle.mass() << '\n';
    }
\end{verbatim}
Here, \texttt{Vehicle} is just a formal name. When an object is passed to
\texttt{fun} it must offer a member \texttt{mass}, or compilation will fail. If the
object is in fact a \texttt{Car} or \texttt{Truck}, then their \texttt{Vehicle$<$Type$>$} static
base class member \texttt{mass} is called, which in turn uses static polymorphism
to call the member \texttt{vmass} as implemented by the actually passed class
type. The following \texttt{main} function displays, respectively, 1000 and 15000:
        \begin{verbatim}
    int main()
    {
        Car car;
        fun(car);
    
        Truck truck;
        fun(truck);
    }
\end{verbatim}
Note that this program implements \texttt{fun} twice, rather than once in the
case of dynamic polymorphism. The same holds true for the \texttt{Vehicle} class
template: two implementations, one for the \texttt{Car} type, and one for the
\texttt{Truck} type. The statically polymorphic program will be slightly faster,
though.

(A compilable example using static polymorphism is found in the
\textbf{C++} Annotations's source distribution's file
\texttt{yo/classtemplates/examples/staticpolymorphism/polymorph.cc}.)

\subsection{Using static polymorphism to avoid reimplementations}
    \typeout{Original Yodl file: classtemplates/using}Static polymorphism may profitably be used to avoid reimplementing code in an
otherwise dynamic polymorphic environment.

Consider the situation where we have a class containing a container of
pointers to some polymorphic base class type (like the class \texttt{Vehicle} from
chapter \ref{POLYMORPHISM}). How to copy such a container to another container?
We're not hinting at using shared pointers here, but would like to make a full
copy. Clearly, we'll need to duplicate the objects the pointers point at, and
assign these new pointers to the copied object's container.

The prototype design patttern is commonly used to create copies of objects of
polymorphic classes, given pointers to their base classes. 

To apply the prototype design pattern we have to implement \texttt{newCopy} in all
derived classes. Not by itself a big deal, but static polymorphism can nicely
be used here to avoid having to  reimplement this function for each derived
class. 

We start off with an abstract base class \texttt{VehicleBase} declaring a pure
virtual member \texttt{newCopy}:
        \begin{verbatim}
    struct VehicleBase
    {
        virtual ~VehicleBase();
        VehicleBase *clone() const; // calls newCopy

        // declare any additional members defining the 
        // public user interface here

        private:
            VehicleBase *newCopy() const = 0;   
    };
\end{verbatim}
Next we define a static polymorphic class \texttt{CloningVehicle} which is derived
from \texttt{VehicleBase} (note that we thus combine dynamic and static
polymorphism). This class provides the generic implementation of
\texttt{newCopy}. This is possible because all derived classes can use this
implementation. Also, \texttt{CloningVehicle} will be re-implemented for each
concrete type of vehicle that is eventually used: a \texttt{Car}, a \texttt{Truck}, an
\texttt{AmphibiousVehicle}, etc, etc. \texttt{CloningVehicle} thus isn't shared (like
\texttt{VehicleBase}), but instantiated for each new type of vehicle. 

The core characteristic of a statically polymorphic class is that it can use
its class template type parameter via a \texttt{static\_cast} of its own type. A
member function like \texttt{newCopy} is implemented always the same way, viz.,
by using the derived class's copy constructor. Here is the class
\texttt{CloningVehicle}:
        \begin{verbatim}
    template <class Derived>
    class CloningVehicle: public VehicleBase
    {
        VehicleBase *newCopy() const
        {
            return new Derived(*static_cast<Derived const *>(this));
        }
    };
\end{verbatim}
And we're done. All types of vehicles should now be derived from
\texttt{CloningVehicle}, which automatically provides them with their own
implementation of \texttt{newCopy}. E.g., a class \texttt{Car} looks like this:
        \begin{verbatim}
    class Car: public CloningVehicle<Car>
    {
        // Car's interface, no need to either
        // declare or implement newCopy,
        // but a copy constructor is required.
    };
\end{verbatim}
Having defined a \texttt{std::vector$<$VehicleBase $*$$>$ original} we could create a
copy of \texttt{original} like this:
            \begin{verbatim}
    for(auto pointer: original)
        duplicate.push_back(pointer->clone());
\end{verbatim}
Irrespective of the actual type of vehicle to which the pointers point,
their \texttt{clone} members will return pointers to newly allocated copies of
objects of their own types.

\section{Class templates and nesting}
\typeout{Original Yodl file: classtemplates/nesting}When a class is nested within a class template, it automatically becomes a
class template itself.
        \index{class template: nested}
    The nested class may use the template parameters of the surrounding
class, as shown by the following skeleton program. Within a class
\texttt{PtrVector}, a class \texttt{iterator} is defined. The nested class receives its
information from its surrounding class, a \texttt{PtrVector$<$Type$>$} class. Since
this surrounding class should be the only class constructing its iterators,
\texttt{iterator}'s constructor is made \index{private}private and the surrounding class is
given access to the private members of \texttt{iterator} using a
 \index{bound friend}\emph{bound friend} declaration.
    Here is the initial section of \texttt{PtrVector}'s class interface:
        \begin{verbatim}
    template <typename Type>
    class PtrVector: public std::vector<Type *>
\end{verbatim}
    This shows that the \texttt{std::vector} base class stores pointers to \texttt{Type}
values, rather than the values themselves. Of course, a destructor is now
required as the (externally allocated) memory for the \texttt{Type} objects must
eventually be freed. Alternatively, the allocation might be part of
\texttt{PtrVector}'s tasks, when it stores new elements. Here it is assumed that
\texttt{PtrVector}'s clients do the required allocations and that the destructor is
implemented later on.

The nested class defines its constructor as a private member, and allows
\texttt{PtrVector$<$Type$>$} objects access to its private members. Therefore only
objects of the surrounding \texttt{PtrVector$<$Type$>$} class type are allowed to
construct their \texttt{iterator} objects. However, \texttt{PtrVector$<$Type$>$}'s clients
may construct \emph{copies} of the \texttt{PtrVector$<$Type$>$::iterator} objects they
use.

Here is the nested class \texttt{iterator}, using a (required) \texttt{friend}
declaration. Note the use of the \texttt{typename} keyword: since
\texttt{std::vector$<$Type $*$$>$::iterator} depends on a template parameter, it is not
yet an instantiated class. Therefore \texttt{iterator} becomes an implicit
typename.  The compiler issues a warning if \texttt{typename} has been
omitted. Here is the class interface:
        \begin{verbatim}
            class iterator
            {
                friend class PtrVector<Type>;
                typename std::vector<Type *>::iterator d_begin;

                iterator(PtrVector<Type> &vector);

                public:
                    Type &operator*();
            };
\end{verbatim}
    The implementation of the members shows that the base class's \texttt{begin}
member is called to initialize \texttt{d\_begin}.  \texttt{PtrVector$<$Type$>$::begin}'s
return type must again be preceded by \texttt{typename}:
        \begin{verbatim}
    template <typename Type>
    PtrVector<Type>::iterator::iterator(PtrVector<Type> &vector)
    :
        d_begin(vector.std::vector<Type *>::begin())
    {}

    template <typename Type>
    Type &PtrVector<Type>::iterator::operator*()
    {
        return **d_begin;
    }
\end{verbatim}
    The remainder of the class is simple. Omitting all other functions that
might be implemented, the function \texttt{begin} returns a newly constructed
\texttt{PtrVector$<$Type$>$::iterator} object. It may call the constructor since the
class \texttt{iterator} declared its surrounding class as its friend:
        \begin{verbatim}
    template <typename Type>
    typename PtrVector<Type>::iterator PtrVector<Type>::begin()
    {
        return iterator(*this);
    }
\end{verbatim}
    Here is a simple skeleton program, showing how the nested class
\texttt{iterator} might be used:
        \begin{verbatim}
    int main()
    {
        PtrVector<int> vi;

        vi.push_back(new int(1234));

        PtrVector<int>::iterator begin = vi.begin();

        std::cout << *begin << '\n';
    }
\end{verbatim}
Nested \index{enumeration: nested} enumerations and \index{typedefs: nested}
 \index{using: nested} nested typedefs and using declarations can also be defined
by class templates. The class \texttt{Table}, mentioned before (section
\ref{TFROMC}) inherited the enumeration \texttt{TableType::FillDirection}. Had
\texttt{Table} been implemented as a full class template, then this enumeration
would have been defined in \texttt{Table} itself as:
        \begin{verbatim}
    template <typename Iterator>
    class Table: public TableType
    {
        public:
            enum FillDirection
            {
                HORIZONTAL,
                VERTICAL
            };
        ...
    };
\end{verbatim}
In this case, the actual value of the template type parameter must be
specified when referring to a \texttt{FillDirection} value or to its type. For
example (assuming \texttt{iter} and \texttt{nCols} are defined as in section
\ref{TFROMC}):
        \begin{verbatim}
    Table<istream_iterator<string> >::FillDirection direction =
                argc == 2 ?
                    Table<istream_iterator<string> >::VERTICAL
                :
                    Table<istream_iterator<string> >::HORIZONTAL;

    Table<istream_iterator<string> >
        table(iter, istream_iterator<string>(), nCols, direction);
\end{verbatim}
\section{Constructing iterators}\label{ITERATORCONS}
\typeout{Original Yodl file: classtemplates/iteratorcons}    Section \ref{ITERATORS} iterators as used by generic algorithms were
introduced. We've seen that several types of iterators were distinguished:
InputIterators, ForwardIterators, OutputIterators, BidirectionalIterators,
RandomAccessIterators, and ContiguousIterators.

To ensure that an object of a class is interpreted as a particular type of
iterator, the class must be designed so that it satisfies the requirements of
that type of iterator. The interface of a class implementing an iterator uses
    \index{iterator\_tag} \emph{iterator\_tags}, which are available when including the
\index{iterator: header file}\texttt{$<$iterator$>$} header file.

Iterator classes should provide the following \texttt{using} declarations:
    \begin{itemize}
    \item \index{iterator\_category}\texttt{iterator\_category}, specifying the iterator's tag, as in
       \begin{verbatim}
   using iterator_category = std::random_access_iterator_tag;
\end{verbatim}
    \item \index{differenct\_type}\texttt{differenct\_type}, defining the type representing differences between
        pointers, commonly:
       \begin{verbatim}
   using difference_type = std::ptrdiff_t;
\end{verbatim}
    \item \index{value\_type}\texttt{value\_type}, defining the data type of a dereferenced iterator. E.g.,
       \begin{verbatim}
   using value_type = std::string;
\end{verbatim}
    \item \index{pointer}\texttt{pointer}, defining the iterator's pointer type which can also be
        defined as a \texttt{const} pointer. E.g.,
       \begin{verbatim}
   using pointer = value_type *; // or maybe:
    using pointer = value_type const *;
\end{verbatim}
    \item \index{reference}\texttt{reference}, defining the iterator's pointer type which can also be
        defined as a \texttt{const} pointer. E.g.,
       \begin{verbatim}
   using reference = value_type &; // or maybe:
    using reference = value_type const &;
\end{verbatim}
    \end{itemize}

These \emph{using declarations} are commonly encountered in the public
sections of iterators, which therefore might be defined as structs.
 \index{iterator: generic design}\index{iterator: 'using' declarations} Here's an
example of how an iterator's interface could be designed:
    \begin{verbatim}
    struct Iterator
    {
        using iterator_category = std::random_access_iterator_tag;
        using difference_type   = std::ptrdiff_t;
        using value_type        = std::string;
        using pointer           = value_type *;
        using reference         = value_type &;
 
        friend bool operator==(iterator const &lhs, iterator const &rhs);
        friend auto operator<=>(Iterator const &lhs, Iterator const &rhs);
        friend int operator-(Iterator const &lhs, Iterator const &rhs);
        friend Iterator operator+(Iterator const &lhs, int step);
        friend Iterator operator-(Iterator const &lhs, int step);
 
    private:
        // private data members
 
    public:
        // public members

    private:
        // private support members
    }
\end{verbatim}
    In section \ref{ITERATORS} the characteristics of iterators were
discussed. All iterators
        \index{iterator: common characteristics}
        \index{iterator: requirements}
    should support (using \texttt{Iterator} as the generic name of the designed
iterator class and \texttt{Type} to represent the (possibly \texttt{const}, in which
case the associated operator should be a \texttt{const} member as well) data type to
which \texttt{Iterator} objects refer):
    \begin{itemize}
    \item  a prefix increment operator (\texttt{Iterator \&operator++()});
    \item  a dereference operator (\texttt{Type \&operator$*$()});
    \item  a 'pointer to' operator (\texttt{Type $*$operator-$>$()});
    \item  comparison operators testing the (in)equality of two iterator objects
(preferably free operators, like \texttt{bool operator==(Iterator const \&lhs,
        Iterator const \&rhs)}, \texttt{bool operator!=((Iterator const \&lhs,
        Iterator const \&rhs))}). Instead of \texttt{operator!=} the `spaceship
        operator (\texttt{operator$<$=$>$}) can also be used, allowing ordering of the
        iterators.
    \end{itemize}

When
        \index{iterator: and generic algorithms}
    iterators are used in the context of generic algorithms they must meet
additional requirements. These are required because generic algorithms perform
checks on the types of the iterators they receive. Simple pointers are usually
accepted, but if an iterator-object is used the generic algorithm might
require the iterator to specify what type of iterator it represents.

The type of iterator that is implemented is indicated by the class's
\texttt{iterator\_category}. The six standard iterator categories are:
    \begin{itemize}
    \item \index{input\_iterator\_tag}\texttt{std::input\_iterator\_tag}. This tag is used when
the iterator class defines an \index{InputIterator}InputIterator.  Iterators of this type allow
reading operations, iterating from the first to the last element of the series
to which the iterator refers.

The InputIterator  dereference operator could be declared as follows:
        \begin{verbatim}
    value_type const &operator*() const;
\end{verbatim}
    or, in a concrete implementation the data type specified at \texttt{using
value\_type = ...} could be used instead to \texttt{value\_type}.  Except for the
standard operators there are no further requirements for InputIterators.

\item \index{output\_iterator\_tag}\texttt{std::output\_iterator\_tag}. This tag is used when
the iterator class defines an \index{OutputIterator}OutputIterator.  Iterators of this type allow
assignments to their dereferenced iterators. Therefore, the OutputIterator
dereference operator is usually declared as:
        \begin{verbatim}
    value_type &operator*();
\end{verbatim}
Except for the standard operators there are no further requirements for
OutputIterators.

\item \index{forward\_iterator\_tag}\texttt{std::forward\_iterator\_tag}. This tag is used
when the iterator class defines a \index{ForwardIterator}ForwardIterator.  Iterators of this type
allow reading \emph{and} assignment operations, iterating from the first to the
last element of the series to which the iterator refers. Therefore, the
ForwardIterator dereference operator should be declared as follows:
        \begin{verbatim}
    value_type &operator*();
\end{verbatim}
    and it could also declare an overloaded \texttt{operator$*$() const}:    
        \begin{verbatim}
    value_type const &operator*() const;
\end{verbatim}
Except for the standard operators there are no further requirements for
ForwardIterators.

\item \index{bidirectional\_iterator\_tag}\texttt{std::bidirectional\_iterator\_tag}. This
tag is used when the iterator class defines a
\index{BidirectionalIterator}BidirectionalIterator. Iterators of this type allow reading \emph{and}
assignment operations, iterating step by step, possibly in either direction,
over all elements of the series to which the iterator refers.

The Bidirectional dereference operator should allow assignment to the data
its dereference operator refers to and it should allow stepping
backward. BidirectionalIterator should therefore, in addition to the standard
operators required for iterators, offer the following operators:
        \begin{verbatim}
    value_type &operator*(); // any maybe its const-overload
    Iterator &operator--();
\end{verbatim}
\item \index{random\_access\_iterator\_tag}\texttt{std::random\_access\_iterator\_tag}. This tag is
used when the iterator class defines a \index{RandomAccessIterator}RandomAccessIterator.  These
iterators are like Bidirectional iterators, but in addition allow stepping to
the next iterator using \texttt{int} step sizes (the resulting iterator may point
to a location outside of the valid iterator range. Like other iterators,
RandomAccessIterators do not check the validity of the obtained iterator).

In addition to the members offered by the BidirectionalIterator, 
RandomAccessIterators provide the following operators:
    \begin{itemize}
    \item \texttt{Type operator-(Iterator const \&rhs) const}, returning the number of
data elements between the current and \texttt{rhs} iterator (returning a negative
value if \texttt{rhs} refers to a data element beyond the data element \texttt{this}
iterator refers to);
    \item \texttt{Iterator operator+(int step) const}, returning an iterator referring
to a data element \texttt{step} data elements beyond the data element \texttt{this}
iterator refers to;
    \item \texttt{Iterator operator-(int step) const}, returning an iterator referring
to a data element \texttt{step} data elements before the data element \texttt{this}
iterator refers to;
    \item \texttt{bool operator$<$(Iterator const \&rhs) const}, returning \texttt{true} if
the data element \texttt{this} iterator refers to is located before the data
element the \texttt{rhs} iterator refers to.
        \end{itemize}
\item \index{contiguous\_iterator\_tag}\texttt{std::contiguous\_iterator\_tag}. This tag is
used when the iterator class defines a \index{ContiguousIterator}ContiguousIterator.  These iterators
offer the same facilities as the RandomAccessIterators, but it is the
responsibility of the software engineer to ensure that the elements to which
the iterators refer are stored contiguously in memory.
    \end{itemize}

Each iterator tag assumes that a certain set of operators is
available. The \emph{RandomAccessIterators} ant \texttt{ContiguousIterators} are the
most complex, as other iterators only offer subsets of their facilities.

Note that iterators are always defined over a certain range
(\texttt{[begin, end)}). Increment and decrement operations may result in
undefined behavior of the iterator if the resulting iterator value would refer
to a location outside of this range.

Normally iterators of classes merely accesses the data elements of those
classes. Internally, an iterator might use an ordinary pointer but it is
hardly ever necessary for the iterator to allocate memory. Therefore,
iterators normally don't need to define copy constructors and assignment
operators. For the same reason iterators usually don't require destructors.

Most classes offering members returning iterators do so by having members
construct the required iterators that are thereupon returned as objects. As
the \emph{caller} of these member functions only has to \emph{use} or sometimes
\emph{copy} the returned iterator objects, there is usually no need to provide
publicly available constructors, except for the copy constructor (which is
available by default). Therefore additional constructors are usually defined as
\emph{private} or \emph{protected} members. To allow an outer class to create
iterator objects, the iterator class usually declares the outer class as its
\emph{friend}.

In the following sections a \emph{RandomAccessIterator}, and a \emph{reverse
RandomAccessIterator} is covered. The container class for which a random
access iterator must be developed may actually store its data elements in many
different ways (e.g., using containers or pointers to pointers).  Section
\ref{CONCRETEITER} contains an example of a self-made template iterator class.

The random access iterator developed in the next sections reaches data
elements that are only accessible through pointers. The iterator class is
designed as an inner class of a class derived from a vector of string
pointers.

\subsection{Implementing a `RandomAccessIterator'}\label{RANDOMIT}
    \typeout{Original Yodl file: classtemplates/randomiterator}In the chapter about containers (chapter \ref{CONTAINERS}) it was noted that
containers own the information they contain. If they contain objects, then
those objects are destroyed once the containers are destroyed. As pointers are
not objects their use in containers is discouraged (STL's \index{unique\_ptr}\texttt{unique\_ptr} and
\index{shared\_ptr}\texttt{shared\_ptr} type objects may be used, though).  Although discouraged, we
might be able to use pointer data types in specific contexts. In the following
class \texttt{StringPtr}, an ordinary class is derived from the \texttt{std::vector}
container that uses \texttt{std::string $*$} as its data type:
        \begin{verbatim}
    #ifndef INCLUDED_STRINGPTR_H_
    #define INCLUDED_STRINGPTR_H_

    #include <string>
    #include <vector>

    class StringPtr: public std::vector<std::string *>
    {
        public:
            StringPtr(StringPtr const &other);
            ~StringPtr();

            StringPtr &operator=(StringPtr const &other);
    };

    #endif
\end{verbatim}
    This class needs a destructor: as the object stores string pointers, a
destructor is required to destroy the strings once the \texttt{StringPtr} object
itself is destroyed.  Similarly, a copy constructor and an overloaded
assignment operator are required. Other members (in particular: constructors)
are not explicitly declared here as they are not relevant to this section's
topic.

Assume that we want to use the \texttt{sort} generic algorithm with
\texttt{StringPtr} objects. This algorithm (see section \ref{SORT}) requires two
\emph{RandomAccessIterators}. Although these iterators are available (via
\texttt{std::vector}'s \texttt{begin} and \texttt{end} members), they return iterators to
\texttt{std::string $*$}s. When comparing \texttt{string $*$} values the pointer values
instead of the content of the strings are compared, which is not what we want.

To remedy this, an internal type \texttt{StringPtr::iterator} is defined,
not returning iterators to pointers, but iterators to the \emph{objects} these
pointers point to. Once this \texttt{iterator} type is available, we can add the
following members to our \texttt{StringPtr} class interface, hiding the identically
named, but useless members of its base class:
        \begin{verbatim}
    StringPtr::iterator begin();    // returns iterator to the first element
    StringPtr::iterator end();      // returns iterator beyond the last
                                    // element
\end{verbatim}
Since these two members return the (proper) iterators, the elements in a
\texttt{StringPtr} object can easily be sorted:
        \begin{verbatim}
    int main()
    {
        StringPtr sp;               // assume sp is somehow filled

        sort(sp.begin(), sp.end()); // sp is now sorted
    }
\end{verbatim}
To make this work, a type \texttt{StringPtr::iterator} is defined. As suggested by
its type name, \texttt{iterator} is a nested type of \texttt{StringPtr}. To use a
\texttt{StringPtr::iterator} in combination with the \texttt{sort} generic algorithm it
must be a \index{RandomAccessIterator}\texttt{RandomAccessIterator}, whose \texttt{value\_type} is a
\texttt{std::string}. Therefore, the iterator specifies:
        \begin{verbatim}
    using iterator_category = std::random_access_iterator_tag;
    using difference_type   = std::ptrdiff_t;
    using value_type        = std::string;
    using pointer           = value_type *;
    using reference         = value_type &;
\end{verbatim}
Now we're ready to redesign \texttt{StringPtr}'s class interface. It offers
members returning (reverse) iterators, and a nested \texttt{iterator} class. Here
is its interface:
        \begin{verbatim}
struct StringPtr: public std::vector<std::string *>
{
    class iterator;
    using reverse_iterator = std::reverse_iterator<iterator>;

    iterator begin();
    iterator end();
    reverse_iterator rbegin();
    reverse_iterator rend();
};

struct StringPtr::iterator
{
//USING
    using iterator_category = std::random_access_iterator_tag;
    using difference_type   = std::ptrdiff_t;
    using value_type        = std::string;
    using pointer           = value_type *;
    using reference         = value_type &;
\end{verbatim}
Next we have a look at \texttt{StringPtr::iterator}'s characteristics:
    \begin{itemize}
    \item \texttt{iterator} defines \texttt{StringPtr} as its friend, so \texttt{iterator}'s
constructor can be private. Only the \texttt{StringPtr} class itself should be able
to construct iterators. Copy construction and iterator-assignment should be
possible, but that's possible by default and needs no specific declaration or
implementation. Furthermore, since an iterator is already provided by
\texttt{StringPtr}'s base class, we can use that iterator to access the information
stored in the \texttt{StringPtr} object.

\item  \texttt{StringPtr::begin} and \texttt{StringPtr::end} may simply return
\texttt{iterator} objects. They are implemented like this:
        \begin{verbatim}
inline StringPtr::iterator StringPtr::begin()
{
    return iterator(std::vector<std::string *>::begin());
}
inline StringPtr::iterator StringPtr::end()
{
    return iterator(std::vector<std::string *>::end());
}
\end{verbatim}
\item  All of \texttt{iterator}'s remaining members are public. It's very easy to
implement them, mainly manipulating and dereferencing the available iterator
\texttt{d\_current}. A \texttt{RandomAccessIterator} requires a series of operators. They
usually have very simple implementations, and can often very well be
implemented inline:
        \begin{itemize}
        \item \texttt{iterator \&operator++()}; the pre-increment operator:
            \begin{verbatim}
inline StringPtr::iterator &StringPtr::iterator::operator++()
{
    ++d_current;
    return *this;
}
\end{verbatim}
        \item  \texttt{iterator operator++(int)}; the post-increment operator:
            \begin{verbatim}
inline StringPtr::iterator StringPtr::iterator::operator++(int)
{
    return iterator(d_current++);
}
\end{verbatim}
        \item \texttt{iterator \&}\texttt{operator-{}-{}()}; the pre-decrement operator:
            \begin{verbatim}
inline StringPtr::iterator &StringPtr::iterator::operator--()
{
    --d_current;
    return *this;
}
\end{verbatim}
        \item  \texttt{iterator operator-{}-{}(int)}; the post-decrement operator:
            \begin{verbatim}
inline StringPtr::iterator StringPtr::iterator::operator--(int)
{
    return iterator(d_current--);
}
\end{verbatim}
        \item \texttt{iterator \&operator=(iterator const \&other)}; the overloaded
            assignment operator. Since \texttt{iterator} objects do not allocate
            any memory themselves, the default assignment operator can be
            used.
        \item \texttt{bool operator==(iterator const \&rhv) const}; testing the equality
            of two \texttt{iterator} objects:
                \begin{verbatim}
inline bool operator==(StringPtr::iterator const &lhs,
                       StringPtr::iterator const &rhs)
{
    return lhs.d_current == rhs.d_current;
}
\end{verbatim}
        \item \texttt{auto operator$<$=$>$(iterator const \&rhv) const}; testing the
            ordering of two \texttt{iterator} objects: 
                \begin{verbatim}
inline auto operator<=>(StringPtr::iterator const &lhs,
                        StringPtr::iterator const &rhs)
{
    return lhs.d_current <=> rhs.d_current;
}
\end{verbatim}
        \item \texttt{int operator-(iterator const \&rhv) const}; returning the number of
            elements between the element pointed to by the left-hand side
            iterator and the right-hand side iterator (i.e., the value to add
            to the left-hand side iterator to make it equal to the value of
            the right-hand side iterator):
                \begin{verbatim}
inline int operator-(StringPtr::iterator const &lhs,
                     StringPtr::iterator const &rhs)
{
    return lhs.d_current - rhs.d_current;
}
\end{verbatim}
        \item \texttt{Type \&operator$*$() const}; returning a reference to the object to
            which the current iterator points. With an \texttt{InputIterator} and
            with all \texttt{const\_iterators}, the return type of this overloaded
            operator should be \texttt{Type const \&}. This operator returns a
            reference to a string. This string is obtained by dereferencing
            the dereferenced \texttt{d\_current} value. As \texttt{d\_current} is an
            iterator to \texttt{string $*$} elements, two dereference operations are
            required to reach the string itself:
                \begin{verbatim}
inline std::string &StringPtr::iterator::operator*() const
{
    return **d_current;
}
\end{verbatim}
        \item \texttt{iterator operator+(int stepsize) const}; this operator
            advances the current iterator by \texttt{stepsize}:
                \begin{verbatim}
inline StringPtr::iterator operator+(StringPtr::iterator const &lhs,
                                                                int step)
{
    StringPtr::iterator ret{ lhs };
    ret.d_current += step;          // avoids ambiguity
    return ret;
}
\end{verbatim}
        \item \texttt{iterator operator-(int stepsize) const}; this operator
            decreases the current iterator by \texttt{stepsize}:
                \begin{verbatim}
inline StringPtr::iterator operator-(StringPtr::iterator const &lhs,
                                                                int step)
{
    StringPtr::iterator ret{ lhs };
    ret.d_current -= step;          // avoids ambiguity
    return ret;
}
\end{verbatim}
        \item \texttt{std::string $*$operator-$>$() const} is an additionally added
            operator. Here only one dereference operation is required,
            returning a pointer to the string, allowing us to access the
            members of a string via its pointer.
                \begin{verbatim}
inline std::string *StringPtr::iterator::operator->() const
{
    return *d_current;
}
\end{verbatim}
        \item  Two more additionally added operators are \texttt{operator+=} and
            \texttt{operator-=}. They are not formally required by
            \texttt{RandomAccessIterators}, but they come in handy anyway:
                \begin{verbatim}
inline StringPtr::iterator &StringPtr::iterator::operator+=(int step)
{
    d_current += step;
    return *this;
}
inline StringPtr::iterator &StringPtr::iterator::operator-=(int step)
{
    d_current -= step;
    return *this;
}
\end{verbatim}
        \end{itemize}
    \end{itemize}
    The interfaces required for other iterator types are simpler, requiring
only a subset of the interface required by a random access iterator. E.g.,
the forward iterator is never decremented and never incremented over arbitrary
step sizes. Consequently, in that case all decrement operators and
\texttt{operator+(int step)} can be omitted from the interface. Of course, the tag
to use would then be \texttt{std::forward\_iterator\_tag}. The tags (and the set of
required operators) vary accordingly for the other iterator types.

\subsection{Implementing a `reverse\_iterator'}\label{REVERSEIT}
    \typeout{Original Yodl file: classtemplates/reverseiterator}    Once we've implemented an iterator, the matching \index{reverse iterator}\emph{reverse iterator} can
be implemented in a jiffy. To implement a reverse\_iterator
\texttt{std::reverse\_iterator} \index{reverse\_iterator} is used, which nicely
implements the reverse iterator once we have defined an iterator. Its
constructor merely requires an object of the iterator type for which we want
to construct a reverse iterator.

To implement a reverse iterator for \texttt{StringPtr} we only need to define
the \texttt{reverse\_iterator} type in its interface. This requires us to specify
only one line of code, which must be inserted after the interface of the class
\texttt{iterator}:
        \begin{verbatim}
    using reverse_iterator = std::reverse_iterator<iterator>;
\end{verbatim}
Also, the well-known members \index{rbegin}\texttt{rbegin} and \index{rend}\texttt{rend} are added to
\texttt{StringPtr}'s interface. Again, they can easily be implemented inline:
        \begin{verbatim}
inline StringPtr::reverse_iterator StringPtr::rbegin()
{
    return reverse_iterator(end());
}
inline StringPtr::reverse_iterator StringPtr::rend()
{
    return reverse_iterator(begin());
}
\end{verbatim}
    Note the arguments the \texttt{reverse\_iterator} constructors receive: the
        \index{reverse\_iterator: initialized by iterator}
    \emph{begin point} of the reversed iterator is obtained by providing
\texttt{reverse\_iterator}'s constructor with the value returned by the member
\texttt{end}: the \emph{endpoint} of the normal iterator range; the \emph{endpoint} of
the reversed iterator is obtained by providing \texttt{reverse\_iterator}'s
constructor with the value returned by the member \texttt{begin}: the \emph{begin
point} of the normal iterator range.

The following program illustrates the use of \texttt{StringPtr}'s
\texttt{RandomAccessIterator}:
        \begin{verbatim}
    #include <iostream>
    #include <algorithm>
    #include "stringptr.h"
    using namespace std;

    int main(int argc, char **argv)
    {
        StringPtr sp;

        while (*argv)
            sp.push_back(new string{ *argv++ });

        sort(sp.begin(), sp.end());
        copy(sp.begin(), sp.end(), ostream_iterator<string>(cout, " "));

        cout << "\n======\n";

        sort(sp.rbegin(), sp.rend());
        copy(sp.begin(), sp.end(), ostream_iterator<string>(cout, " "));

        cout << '\n';
    }
    /*
            when called as:
        a.out bravo mike charlie zulu quebec

            generated output:
        a.out bravo charlie mike quebec zulu
        ======
        zulu quebec mike charlie bravo a.out
    */
\end{verbatim}
    Although it is thus possible to construct a reverse iterator from a normal
iterator, the opposite does not hold true: it is not possible to
initialize a normal iterator from a reverse iterator.

Assume we would like to process all lines stored in \texttt{vector$<$string$>$
lines} up to any trailing empty lines (or lines only containing blanks) it
might contain. How should we proceed? One approach is to start the processing
from the first line in the vector, continuing until the first of the trailing
empty lines. However, once we encounter an empty line it does of course not
have to be the first line of the set of trailing empty lines. In that case,
we'd better use the following algorithm:
    \begin{itemize}
    \item  First, use
        \begin{verbatim}
    rit = find_if(lines.rbegin(), lines.rend(), NonEmpty());
\end{verbatim}
to obtain a \texttt{reverse\_iterator rit} pointing to the last non-empty
        line.
    \item  Next, use
        \begin{verbatim}
    for_each(lines.begin(), --rit, Process());
\end{verbatim}
to process all lines up to the first empty line.
    \end{itemize}
    However, we can't mix iterators and reverse iterators when using generic
algorithms. So how can we initialize the second iterator using the available
\texttt{reverse\_iterator}? The solution is not very difficult, as an iterator may
be initialized from a pointer. Although the reverse iterator \texttt{rit} is not a
pointer, \texttt{\&$*$(rit - 1)} or \texttt{\&$*$+NOTRANS(-\{\}-\{\})rit} \emph{is}. So we use
        \begin{verbatim}
    for_each(lines.begin(), &*--rit, Process());
\end{verbatim}
    to process all the lines up to the first of the set of trailing empty
lines. In general, if \texttt{rit} is a \texttt{reverse\_iterator} pointing to some
element and we need an \texttt{iterator} to point to that element, we may use
\texttt{\&$*$rit} to initialize the iterator. Here, the dereference operator is
applied to reach the element the reverse iterator refers to. Then the address
operator is applied to obtain its address with which we can initialize the
iterator.

When defining a \texttt{const\_reverse\_iterator} (e.g., matching a
\texttt{const\_iterator} class), then the \texttt{const\_iterator's operator$*$} member
should be a member returning a non-modifiable value or object. Since a
\texttt{const\_reverse\_iterator} uses the iterator's \texttt{operator-{}-{}} member,
we're running against a small conceptual conflict. On the one hand, a
\texttt{std::input\_iterator\_tag} is inappropriate, since we must allow decrementing
the iterator. On the other hand, a \texttt{std::bidirectional\_iterator} is
inappropriate, since we don't allow modification of the data.

Iterator tags are primarily conceptual. If \texttt{const\_iterators} and
\texttt{const\_reverse\_iterators} only allow increment operations, then an
\texttt{input\_iterator\_tag} is the best match for the iterator's intended
use. Hence this tag is used below.

Furthermore, in line with the nature of a \texttt{input\_iterator\_tag} our
\texttt{const\_iterator} should not offer an \texttt{operator-{}-{}}. This, of course,
causes problems: a reverse iterator must be able to use the iterator's
\texttt{operator-{}-{}} member. This can easily be solved by stashing the iterator's
\texttt{operator-{}-{}} in the iterator's private section, and declaring
\texttt{std::reverse\_iterator$<$(const\_)iterator$>$} its friend (note that declaring a
\texttt{(const\_)reverse\_iterator} that is derived from \texttt{std::reverse\_iterator}
doesn't solve the issue: it is \texttt{std::reverse\_iterator} that calls the
iterator's \texttt{operator-{}-{}}, not a class that is derived from it).

To keep the const-ness of dereferencing \texttt{const\_iterator} iterators
\texttt{using} specification can added to the \texttt{const\_iterator} class. The
\texttt{using} specifications provided by \texttt{Data::iterator} are inherited by
\texttt{Data::const\_iterator}, but \texttt{Data::const\_iterator} may also specify:
        \begin{verbatim}
    using const_pointer   = value_type const *;
    using const_reference = value_type const &;
\end{verbatim}
    whereafter its \texttt{operator $*$()} can return a \texttt{const\_reference}.

The elements involved in defining an \texttt{iterator, const\_iterator,
reverse\_iterator} and \texttt{const\_reverse\_iterator} for a class \texttt{Data} is
illustrated in the following example, which only requires the definitions of
the \texttt{iterator} and \texttt{const\_iterator} classes, as these types can be passed
to the \texttt{reverse\_iterator} template to obtain the corresponding
reverse-iterators:
    \begin{verbatim}
    // compile only: members only declared, not implemented

#include <string>
#include <iterator>
#include <iostream>

struct Data
{
    class iterator;
    class const_iterator;

    using reverse_iterator = std::reverse_iterator<iterator>;
    using const_reverse_iterator = std::reverse_iterator<const_iterator>;

    private:
        std::string *d_data;
        size_t d_n;

    public:
        // ...
};

struct Data::iterator
{
    using iterator_category = std::bidirectional_iterator_tag;
    using difference_type   = std::ptrdiff_t;
    using value_type        = std::string;
    using pointer           = value_type *;
    using reference         = value_type &;

    friend class Data;

    private:
        pointer d_current;

    public:
        iterator() = default;

        iterator &operator++();
        iterator &operator--();
        std::string &operator*();

    private:
        iterator(std::string *data, size_t idx);

        friend class std::reverse_iterator<iterator>;
};

bool operator==(Data::iterator const &lhs, Data::iterator const &rhs);

struct Data::const_iterator: public Data::iterator
{
    using const_pointer   = value_type const *;
    using const_reference = value_type const &;

    friend class Data;
    friend class std::reverse_iterator<const_iterator>;

    const_iterator() = default;

    const_iterator &operator++();
    const_iterator &operator--();

    const_reference operator*() const;
    // or, in this case: std::string const &operator*() const;

    private:
        const_iterator(std::string const *data, size_t idx);
};

bool operator==(Data::const_iterator const &lhs,
                Data::const_iterator const &rhs);


void demo()
{
    Data::iterator iter;
    Data::reverse_iterator riter(iter);

    std::cout << *riter << '\n';

    Data::const_iterator citer;
    Data::const_reverse_iterator criter(citer);

    std::cout << *criter << '\n';
};
\end{verbatim}
\cleardoublepage\chapter{Advanced Template Use}\label{ADVANCEDTEMPL}
\typeout{Original Yodl file: advancedtemplates}
\typeout{Original Yodl file: advancedtemplates/intro}The main purpose of templates is to provide a generic definition of classes
and functions that may then be tailored to specific types.

But templates allow us to do more than that. If not for compiler
implementation limitations, templates could be used to program, at
compile-time, just about anything we use computers for. This remarkable feat,
offered by no other current-day computer language, stems from the fact that
templates allow us to do three things at compile-time:
    \begin{itemize}
    \item  Templates allow us to do integer arithmetic (and to save computed
values symbolically);
    \item  Templates allow us to make compile-time decisions;
    \item  Templates allow us to do things repeatedly.
    \end{itemize}

Of course, asking the compiler to compute, e.g., prime numbers, is one
thing. But it's a completely different thing to do so in an award winning
way. Don't expect speed records to be broken when the compiler performs
complex calculations for us. But that's all beside the point. In the end we
\emph{can} ask the compiler to compute virtually anything using \textbf{C++}'s
template language, including prime numbers....

In this chapter these remarkable features of templates are
discussed. Following a short overview of subtleties related to templates the
main characteristics of \index{template meta programming}template meta programming are introduced.

In addition to template type and template non-type parameters there is a third
kind of template parameter, the
    \index{template template parameter}\emph{template template parameter}. This kind of template parameter is
introduced shortly, laying the groundwork for the discussion of \emph{trait
classes} and \emph{policy classes}.

This chapter ends with the discussion of several additional and interesting
applications of templates: adapting compiler error messages, conversions to
class types and an elaborate example discussing compile-time list processing.

Much of the inspiration for this chapter came from two highly recommended
books: Andrei Alexandrescu's 2001 book
    \index{Alexandrescu, A.}\textbf{Modern C++ design} (Addison-Wesley) and Nicolai
Josutis and David \mbox{Vandevoorde's} 2003 book
    \index{Josutis, N.}\index{Vandevoorde, D.}\textbf{Templates} (Addison-Wesley).

\section{Subtleties}\label{SUBTLE}
    \typeout{Original Yodl file: advancedtemplates/subtle}In section \ref{DISTINGUISH} a special application of the keyword \index{typename}\texttt{typename}
was discussed. There we learned that it is not only used to define a name for
a (complex) type, but also to distinguish types defined by class templates
from members defined by class templates.  In this section another application
is introduced In section \ref{TYPERES} we cover the problem of how to refer to
base class templates from derived class templates.

In addition to the special applications of \texttt{typename} section
\ref{DOTTEMP} introduces some new syntax that is related to the extended use of
the keyword \texttt{typename}: \texttt{::template, .template} and \texttt{-$>$template} are
used to inform the compiler that a name used inside a template is itself a
class template.

\subsection{Type resolution for base class members}\label{TYPERES}
    \typeout{Original Yodl file: advancedtemplates/basenameresolution}Below we see two class templates. \texttt{Base} and \texttt{Derived}, \texttt{Base} being
\texttt{Derived}'s base class:
        \begin{verbatim}
    #include <iostream>

    template <typename T>
    class Base
    {
        public:
            void member();
    };
    template <typename T>
    void Base<T>::member()
    {
        std::cout << "This is Base<T>::member()\n";
    }
    template <typename T>
    class Derived: public Base<T>
    {
        public:
            Derived();
    };
    template <typename T>
    Derived<T>::Derived()
    {
        member();
    }
\end{verbatim}
    This example won't compile, and the compiler tells us something like:
        \index{no arguments depending on a template parameter}
        \begin{verbatim}
    error: there are no arguments to 'member' that depend on a template
           parameter, so a declaration of 'member' must be available
\end{verbatim}
This error causes some confusion as ordinary (non-template) base classes
readily make their public and protected members available to classes that are
derived from them. This is no different for class templates, but only if the
compiler can figure out what we mean. In the above example the compiler
\emph{can't} as it doesn't know for what type \texttt{T} the member function
\texttt{member} must be initialized when called from \texttt{Derived$<$T$>$::Derived}.

To appreciate why this is true, consider the situation where we have
defined a specialization:
        \begin{verbatim}
    template <>
    Base<int>::member()
    {
        std::cout << "This is the int-specialization\n";
    }
\end{verbatim}
Since the compiler, when \texttt{Derived$<$SomeType$>$::Derived} is called, does
not know whether a specialization of \texttt{member} is in effect, it can't
decide (when compiling \texttt{Derived$<$T$>$::Derived}) for what type to instantiate
\texttt{member}. It can't decide this when compiling \texttt{Derived$<$T$>$::Derived} as
\texttt{member}'s call in \texttt{Derived::Derived} doesn't require a template type
parameter.

In cases like these, where no template type parameter is available to
determine which type to use, the compiler must be told that it should postpone
its decision about the template type parameter to use (and therefore about the
particular (here: \texttt{member}) function to call)
    \index{template members: without template type parameters}
until instantiation time.

This may be implemented in two ways: either by using \texttt{this} or by
explicitly mentioning the base class, instantiated for the derived class's
template type(s). When \texttt{this} is used the compiler is informed that we're
referring to the type \texttt{T} for which the template was instantiated. Any
confusion about which member function to use (the derived class or base class
member) is resolved in favor of the derived class member. Alternatively, the
base or derived class can explicitly be mentioned (using \texttt{Base$<$T$>$} or
\texttt{Derived$<$T$>$}) as shown in the next example. Note that with the \texttt{int}
template type the \texttt{int} specialization is used.
        \begin{verbatim}
    #include <iostream>

    template <typename T>
    class Base
    {
        public:
            virtual void member();
    };
    template <typename T>
    void Base<T>::member()
    {
        std::cout << "This is Base<T>::member()\n";
    }
    template <>
    void Base<int>::member()
    {
        std::cout << "This is the int-specialization\n";
    }
    template <typename T>
    class Derived: public Base<T>
    {
        public:
            Derived();
            void member() override;
    };
    template <typename T>
    void Derived<T>::member()
    {
        std::cout << "This is Derived<T>::member()\n";
    }
    template <typename T>
    Derived<T>::Derived()
    {
        this->member();         // Using `this' implies using the
                                // type for which T was instantiated
        Derived<T>::member();   // Same: calls the Derived member
        Base<T>::member();      // Same: calls the Base member
        std::cout << "Derived<T>::Derived() completed\n";
    }

    int main()
    {
        Derived<double> d;
        Derived<int> i;
    }

    /*
        Generated output:
    This is Derived<T>::member()
    This is Derived<T>::member()
    This is Base<T>::member()
    Derived<T>::Derived() completed
    This is Derived<T>::member()
    This is Derived<T>::member()
    This is the int-specialization
    Derived<T>::Derived() completed
    */
\end{verbatim}
    The above example also illustrates the use of virtual member templates
(although virtual member templates aren't often used). In the example \texttt{Base}
declares a \texttt{virtual void member} and \texttt{Derived} defines its overriding
function \texttt{member}. In that case \texttt{this-$>$member()} in \texttt{Derived::Derived}
calls, due to \texttt{member}'s virtual nature, \texttt{Derived::member}. The statement
\texttt{Base$<$T$>$::member()}, however, always calls \texttt{Base}'s \texttt{member} function
and can be used to
    \index{polymorphism: bypassing} bypass dynamic polymorphism.

\subsection{::template, .template and -$>$template}\label{DOTTEMP}
    \typeout{Original Yodl file: advancedtemplates/dottemplate}In general, the compiler is able to determine the true nature of a name. As
discussed, this is not always the case and sometimes we have to advise the
compiler. The \texttt{typename} keyword is often used for that purpose.

While parsing a source the compiler receives a series of \emph{tokens},
representing meaningful units of text encountered in the program's source. A
token could represent, e.g., an identifier or a number. Other tokens represent
operators, like \texttt{=, +} or \texttt{$<$}. It is precisely the last token that may
cause problems as it may have very different meanings. The correct meaning
cannot always be determined from the context in which the compiler encounters
\texttt{$<$}. In some situations the compiler \emph{does} know that \texttt{$<$} does not
represent the \emph{less than} operator, as when a template parameter list
follows the keyword \texttt{template}, e.g.,
        \begin{verbatim}
    template <typename T, int N>
\end{verbatim}
Clearly, in this case \texttt{$<$} does not represent a `less than' operator.

The special meaning of \texttt{$<$} when it is preceded by \texttt{template} forms the
basis for the syntactic constructs discussed in this section.

Assume the following class has been defined:
        \begin{verbatim}
    template <typename Type>
    class Outer
    {
        public:
            template <typename InType>
            class Inner
            {
                public:
                    template <typename X>
                    void nested();
            };
    };
\end{verbatim}
The class template \texttt{Outer} defines a nested class template
\texttt{Inner}. \texttt{Inner} in turn defines a member template function.

Next a class template \texttt{Usage} is defined, offering a member function
\texttt{caller} expecting an object of the above \texttt{Inner} type.  An initial setup
for \texttt{Usage} looks like this:
        \begin{verbatim}
    template <typename T1, typename T2>
    class Usage
    {
        public:
            void caller(Outer<T1>::Inner<T2> &obj);
       ...
    };
\end{verbatim}
The compiler won't accept this as it interprets \texttt{Outer$<$T1$>$::Inner} as a
class type. But there is no class \texttt{Outer$<$T1$>$::Inner}. Here the compiler
generates an error like:
        \begin{verbatim}
    error: 'class Outer<T1>::Inner' is not a type
\end{verbatim}
There are two ways to inform the compiler that \texttt{Inner}
 \index{template: specified within template}
 \index{template: and the \textless{} token}
    itself is a template, using the template type parameter \texttt{$<$T2$>$}. One way
is to prefix \texttt{caller's} parameter specification with \texttt{typename}:
    \begin{verbatim}
    void caller(typename Outer<T1>::Inner<T2> &obj)
\end{verbatim}
    Although this works, specifying that \texttt{Outer$<$T1$>$::Inner$<$T2$>$} is a
typename might looks a bit strange. Therefore. alternatively, the 
\index{::template}\texttt{::template} construction can be used:
    \begin{verbatim}
    void caller(Outer<T1>::template Inner<T2> &obj)
\end{verbatim}
    \texttt{::template} tells the compiler that the next \texttt{$<$} must not be
interpreted as a `less than' token, but rather as a template type
argument.

Of course, \texttt{caller} itself is not just declared, it must also be
implemented. Assume that its implementation should call \texttt{Inner}'s member
\texttt{nested}, instantiated for yet another type \texttt{X}. The class template
\texttt{Usage} therefore receives a third template type parameter, called
\texttt{T3}. Assuming it has been defined by \texttt{Usage}, then to implement
\texttt{caller}, we write:
        \begin{verbatim}
    template <typename T1, typename T2, typename T3>
    void caller(typename Outer<T1>::template Inner<T2> &obj)
    {
        obj.nested<T3>();
    }
\end{verbatim}
    Here again we run into a problem. In the function's body the compiler 
again interprets \texttt{$<$} as `less than', seeing a logical expression having as
its right-hand side a primary expression instead of a function call specifying
a template type \texttt{T3}.

To tell the compiler that is should interpret \texttt{$<$T3$>$} as a type to
instantiate, the \texttt{template} keyword is used, as mentioned by the compiler:
    \begin{verbatim}
    expected `template' keyword before dependent template name
\end{verbatim}
    Although issued as a warning, this warning is then followed by error
messages caused by the compiler interpreting \texttt{$<$} as `less than'. To remove
the warning and the error messages we write \index{.template}\texttt{.template} informing
the compiler that what follows is not a `less than' operator, but a
type specification. The function's final implementation thus becomes:
        \begin{verbatim}
    template <typename T1, typename T2, typename T3>
    void caller(typename Outer<T1>::template Inner<T2> &obj)
    {
        obj.template nested<T3>();
    }
\end{verbatim}
Instead of defining value or reference parameters functions may also
define pointer parameters. Had \texttt{obj} been defined as a pointer parameter the
implementation would have had to use the \texttt{-$>$template} construction, rather
than the \texttt{.template} construction. E.g.,
        \begin{verbatim}
    template <typename T1, typename T2, typename T3>
    void caller(typename Outer<T1>::template Inner<T2> *ptr)
    {
        ptr->template nested<T3>();
    }
\end{verbatim}
As we've seen class templates can be derived from base class templates. The
base class template can declare a \index{static member template}static member template, which is
available to a class that is derived from this base class. Such a base class
might look like this:
        \begin{verbatim}
    template <typename Type>
    struct Base
    {
        template <typename Tp>
        static void fun();
    };
\end{verbatim}
Normally, when a base class defines a static member we can just call that
member by prefixing its name by its class name. E.g.,
        \begin{verbatim}
    int main()
    {
        Base<int>::fun<double>();
    }
\end{verbatim}
This also works fine if a class \texttt{Derived} is derived from \texttt{Base},
instantiated for a specific type:
        \begin{verbatim}
    struct Der: public Base<int>
    {
        static void call()
        {
            Base<int>::fun<int>();      // OK
            fun<int>();                 // also OK
        };
    };
\end{verbatim}
    But when the derived class itself is a class template this way to
call \texttt{fun} won't compile anymore, as it interprets \texttt{Base$<$Type$>$::fun} in
\texttt{Base$<$Type$>$::fun$<$int$>$} as a type, to be instantiated for \texttt{int}. This
interpretation can be overruled by indicating that \texttt{fun} itself is a
template. For this the \texttt{::template} prefix is used:
        \begin{verbatim}
    template <typename Type>
    struct Der: public Base<Type>
    {
        //template <typename Tp>    // 'call' may be a member template
        //static                    // 'call' may be a static member
        void call()
        {
            // fun<int>();                      // won't compile
            // Base<Type>::fun<int>();          // won't compile
            Base<Type>::template fun<int>();    // OK
            Base<Type>::template fun<Tp>();     // OK if call is a 
                                                //    member template
        };                                      // (activate typename Tp)
    };
\end{verbatim}
\section{Template Meta Programming}

\subsection{Values according to templates}
    \typeout{Original Yodl file: advancedtemplates/values}In \index{template programming}template programming values are preferably represented by \texttt{enum}
values. Enums are preferred over, e.g., \texttt{int const} values since enums never
require any linkage. They are pure symbolic values with no memory
representation whatsoever.

Consider the situation where a programmer must use a cast, say a
\index{reinterpret\_cast}\texttt{reinterpret\_cast}. A problem with a \texttt{reinterpret\_cast} is that it is the
ultimate way to turn off all compiler checks. All bets are off, and we can
write extreme but absolutely pointless \texttt{reinterpret\_cast} statements, like
        \begin{verbatim}
    int intVar = 12;
    ostream &ostr = reinterpret_cast<ostream &>(intVar);
\end{verbatim}
Wouldn't it be nice if the compiler would warn us against such oddities by
generating an error message?

If that's what we'd like the compiler to do, there must be some way to
distinguish madness from weirdness. Let's assume we agree on the following
distinction: reinterpret casts are never acceptable if the target type
represents a larger type than the expression (source) type, since that would
immediately result in exceeding the amount of memory that's actually available
to the target type. For this reason it's clearly silly to
\texttt{reinterpret\_cast$<$double $*$$>$(\&intVar)}, but \texttt{reinterpret\_cast$<$char
$*$$>$(\&intVar)} could be defensible.

The intent is now to create a new kind of cast, let's call it
\index{reinterpret\_to\_smaller\_cast}\texttt{reinterpret\_to\_smaller\_cast}. It should only be allowed to perform a
\texttt{reinterpret\_to\_smaller\_cast} if the target type occupies less memory than
the source type (note that this exactly the opposite reasoning as used by
Alexandrescu \index{Alexandrescu, A.}  (2001), section 2.1).

To start, we construct the following template:
        \begin{verbatim}
    template<typename Target, typename Source>
    Target &reinterpret_to_smaller_cast(Source &source)
    {
        // determine whether Target is smaller than source
        return reinterpret_cast<Target &>(source);
    }
\end{verbatim}
At the comment an enum-definition is inserted defining a symbol having a
suggestive name.  A compile-time error results if the required condition is
not met and the error message displays the name of the symbol. A division by
zero is clearly not allowed, and noting that a \texttt{false} value represents a
zero value, the condition could be:
        \begin{verbatim}
    1 / (sizeof(Target) <= sizeof(Source));
\end{verbatim}
The interesting part is that this condition doesn't result in any code at
all. The enum's value is a plain value that's computed by the compiler while
evaluating the expression:
        \begin{verbatim}
    template<typename Target, typename Source>
    Target &reinterpret_to_smaller_cast(Source &source)
    {
        enum
        {
            the_Target_size_exceeds_the_Source_size =
                1 / (sizeof(Target) <= sizeof(Source))
        };
        return reinterpret_cast<Target &>(source);
    }
\end{verbatim}
When \texttt{reinterpret\_to\_smaller\_cast} is used to cast from \texttt{int} to
\texttt{double} an error is produced by the compiler, like this:
        \begin{verbatim}
    error: enumerator value for 'the_Target_size_exceeds_the_Source_size'
        is not an integer constant
\end{verbatim}
whereas no error is reported if, e.g.,
\texttt{reinterpret\_to\_smaller\_cast$<$int$>$(doubleVar)} is requested with
\texttt{doubleVar} defined as a \texttt{double}.

In the above example an \texttt{enum} was used to compute (at compile-time) a
value that is illegal if an assumption is not met. The creative part is
finding an appropriate expression.

Enum values are well suited for these situations as they do not consume
any memory and their evaluation does not produce any executable code. They can
be used to accumulate values too: the resulting enum value then contains a
final value, computed by the compiler rather than by executable code as the
next sections illustrate. In general, programs shouldn't do run-time what they
can do
        \index{run-time vs. compile-time}
    at compile-time and performing complex calculations resulting in constant
values is a clear example of this principle.

\subsubsection{Converting integral types to types}\label{INTTYPE}
        \typeout{Original Yodl file: advancedtemplates/int2type}Another use of values buried inside templates is to `templatize' simple scalar
\texttt{int} values. This is useful in situations where a scalar value (often a
\texttt{bool} value) is available to select a specialization but a type is required
to base the selection on. This situation is shortly encountered (section
\ref{ALTERNATIVES}).

Templatizing
        \index{template: embedding integral values}
    integral values is based on the fact that a
        \index{class template: defining a type}
    class template together with its template arguments defines a type. E.g.,
\texttt{vector$<$int$>$} and \texttt{vector$<$double$>$} are different types.

Turning integral values into templates is easily done. Define a template (it
does not have to have any content at all) and store the integral value in an
\texttt{enum}:
        \begin{verbatim}
    template <int x>
    struct IntType
    {
        enum { value = x };
    };
\end{verbatim}
As \texttt{IntType} does not have any members the `\texttt{class IntType}' can be
defined as `\texttt{struct IntType}', saving us from having to type \texttt{public:}.

Defining the \texttt{enum} value `\texttt{value}' allows us to retrieve the value
used at the instantiation at no cost in storage. Enum values are neither
variables nor data members and thus have no address. They are mere values.

It's easy to use the \texttt{struct IntType}. An anonymous or named
object can be defined by specifying a value for its \texttt{int} non-type
parameter. Example:
        \begin{verbatim}
    int main()
    {
        IntType<1> it;
        cout << "IntType<1> objects have value: " << it.value << "\n" <<
                "IntType<2> objects are of a different type "
                        "and have values " << IntType<2>().value << '\n';
    }
\end{verbatim}
Actually, neither the named object nor the anonymous object is
    \index{class template: values without objects}
required. As the \texttt{enum} is defined as a plain value, associated with the
\texttt{struct IntType} we merely have to specify the specific \texttt{int} for which
the \texttt{struct IntType} is defined to retrieve its `\texttt{value}', like this:
        \begin{verbatim}
    int main()
    {
        cout << "IntType<100>, no object, defines `value': " <<
                IntType<100>::value << "\n";
    }
\end{verbatim}
\subsection{Selecting alternatives using templates}\label{ALTERNATIVES}
    \typeout{Original Yodl file: advancedtemplates/alternatives}An essential characteristic of programming languages is that they allow the
conditional execution of code. For this \textbf{C++} offers the \texttt{if} and
\texttt{switch} statements. If we want to be able to `program the compiler'
this feature must also be offered by templates.

Like templates storing values templates making choices do not require any code
to be executed at run-time. The selection is purely made by the compiler, at
compile-time. The essence of template meta programming is that we are \emph{not}
using or relying on any executable code.  The result of a template meta
program often is executable code, but that code is a function of decisions
merely made by the compiler.

Template (member) functions are only instantiated when they are actually
used. Consequently we can define specializations of functions that are
mutually exclusive. Thus it is possible to define a specialization that can be
compiled in situation one, but not in situation two and to define another
specialization that can be compiled in situation two, but not in situation
one. Using specializations code can be generated that is tailored to the
demands of a particular situation.

A feature like this cannot be implemented in run-time executable code. For
example, when designing a generic storage class the software engineer may
intend to store \emph{value class} type objects as well as objects of
\emph{polymorphic class} types in the final storage class. Thus the software
engineer may conclude that the storage class should contain pointers to
objects, rather than the objects themselves. The initial implementation
attempt could look like this:
        \begin{verbatim}
    template <typename Type>
    void Storage::add(Type const &obj)
    {
        d_data.push_back(
            d_ispolymorphic ?
                obj.clone()
            :
                new Type{obj}
        );
    }
\end{verbatim}
The intent is to use the \texttt{clone} member function of the class \texttt{Type}
if \texttt{Type} is a polymorphic class and the standard copy constructor if
\texttt{Type} is a value class.

Unfortunately, this scheme usually fails as value classes do not define
\texttt{clone} member functions and polymorphic base classes should \emph{delete}
their copy constructors (cf. section \ref{DEFAULTED}). It doesn't matter to the
compiler that \texttt{clone} is never called for value classes and that the copy
constructor is only available in value classes and not in polymorphic
classes. It merely has some code to compile, and can't do that because of
missing members. It's as simple as that.

\subsubsection{Defining overloading members}
        \typeout{Original Yodl file: advancedtemplates/overloaded}    Template meta programming comes to the rescue. Knowing that class template
member functions are only instantiated when used, our plan is to design
overloaded \texttt{add} member functions of which only one is going to be called
(and thus instantiated). Our selection will be based on an additional (in
addition to \texttt{Type} itself) template non-type parameter that indicates
whether we'll use \texttt{Storage} for polymorphic or non-polymorphic classes. Our
class \texttt{Storage} starts like this:
        \begin{verbatim}
    template <typename Type, bool isPolymorphic>
    class Storage
\end{verbatim}
Initially two \emph{overloaded} versions of our \texttt{add} member are defined:
one used with \texttt{Storage} objects storing polymorphic objects (using \texttt{true}
as its template non-type argument) and one storing value
class objects (using \texttt{false} as its template non-type argument).

Unfortunately we run into a small problem: functions cannot be overloaded
by their argument \emph{values} but only by their argument \emph{types}. But the
small problem may be solved. Realizing that types are defined by the
combination of template names and their template arguments we may convert the
values \texttt{true} and \texttt{false} into types using the knowledge from section
\ref{INTTYPE} about how to convert integral values to types.

We'll provide one (private) \texttt{add} member with an \texttt{IntType$<$true$>$} parameter
(implementing the polymorphic class) and another (private) \texttt{add} member with
an \texttt{IntType$<$false$>$} parameter (implementing the non-polymorphic class).

In addition to these two private members a third (public) member \texttt{add} is
defined calling the appropriate private \texttt{add} member by providing an
\texttt{IntType} argument, constructed from \texttt{Storage}'s template non-type
parameter.

Here are the implementations of the three \texttt{add} members:
        \begin{verbatim}
    // declared in Storage's private section:

    template <typename Type, bool isPolymorphic>
    void Storage<Type, isPolymorphic>::add(Type const &obj, IntType<true>)
    {
        d_data.push_back(obj.clone());
    }

    template <typename Type, bool isPolymorphic>
    void Storage<Type, isPolymorphic>::add(Type const &obj, IntType<false>)
    {
        d_data.push_back(new Type(obj));
    }

    // declared in Storage's public section:

    template <typename Type, bool isPolymorphic>
    void Storage<Type, isPolymorphic>::add(Type const &obj)
    {
        add(obj, IntType<isPolymorphic>());
    }
\end{verbatim}
The appropriate \texttt{add} member is instantiated and called because a
primitive value can be converted to a type. Each of the possible template
non-type values is thus used to define an overloaded class template member
function.

Since class template members are only instantiated when used only one of
the overloaded private \texttt{add} members is instantiated. Since the other one is
never called (and thus never instantiated) compilation errors are prevented.

\subsubsection{Class structure as a function of template parameters}\label{IFELSE}
        \typeout{Original Yodl file: advancedtemplates/classstructure}    Some software engineers have reservations when thinking about the
\texttt{Storage} class that uses pointers to store copies of value class
objects. Their argument is that value class objects can very well be stored by
value, rather than by pointer. They'd rather store value class objects by
value and polymorphic class objects by pointer.

Such distinctions  frequently occur in template meta programming and
the following \texttt{struct IfElse}
        \index{template: IfElse}
        \index{template: select type given bool}
    may be used to obtain one of two types, depending on a \texttt{bool} selector
value.

First define the \emph{generic form} of the template:
        \begin{verbatim}
    template<bool selector, typename FirstType, typename SecondType>
    struct IfElse
    {
        using type = FirstType;
    };
\end{verbatim}
Then define a partial specialization. The specialization represents
a specific selector value (e.g., \texttt{false}) and leaves the remaining types
open to further specification:
        \begin{verbatim}
    template<typename FirstType, typename SecondType>
    struct IfElse<false, FirstType, SecondType>
    {
        using type = SecondType;
    };
\end{verbatim}
The former (generic) definition associates \texttt{FirstType} with the
\texttt{IfElse::type} type definition, the latter definition (partially specialized
for the logical value \texttt{false}) associates \texttt{SecondType} with the
\texttt{IfElse::type} type definition.

The \texttt{IfElse} template allows us to define class templates whose data
organization is conditional to the template's parameters.
    \index{class template: conditional data organization}
 Using \texttt{IfElse} the \texttt{Storage} class may define
\emph{pointers} to store copies of polymorphic class type objects and \emph{values}
to store value class type objects:
        \begin{verbatim}
    template <typename Type, bool isPolymorphic>
    class Storage
    {
        using DataType = typename IfElse<isPolymorphic, Type *, Type>::type;

        std::vector<DataType> d_data;

        private:
            void add(Type const &obj, IntType<true>);
            void add(Type const &obj, IntType<false>);
        public:
            void add(Type const &obj);
    }

    template <typename Type, bool isPolymorphic>
    void Storage<Type, isPolymorphic>::add(Type const &obj, IntType<true>)
    {
        d_data.push_back(obj.clone());
    }

    template <typename Type, bool isPolymorphic>
    void Storage<Type, isPolymorphic>::add(Type const &obj, IntType<false>)
    {
        d_data.push_back(obj);
    }

    template <typename Type, bool isPolymorphic>
    void Storage<Type, isPolymorphic>::add(Type const &obj)
    {
        add(obj, IntType<isPolymorphic>());
    }
\end{verbatim}
The above example uses \texttt{IfElse}'s \texttt{type}, defined by \texttt{IfElse} as
either \texttt{FirstType} or \texttt{SecondType}. \texttt{IfElse}'s \texttt{type} defines the
actual data type to use for \texttt{Storage}'s \texttt{vector} data type.

The remarkable result in this example is that the \emph{data organization} of
the \texttt{Storage} class now depends on its template arguments. Since the
\texttt{isPolymorphic == true} situation uses different data types than the
\texttt{isPolymorphic == false} situation, the overloaded private \texttt{add} members
can utilize this difference immediately. E.g., \texttt{add(Type const \&obj,
IntType$<$false$>$)} uses direct copy construction to store a copy of \texttt{obj}
in \texttt{d\_vector}.

It is also possible to make a selection from multiple types as \texttt{IfElse}
structs can be nested. Realize that using \texttt{IfElse} never has any effect on
the size or execution time of the final executable program. The final program
simply contains the appropriate type, conditional to the type that's
eventually selected.

\subsubsection{An illustrative example}
        \typeout{Original Yodl file: advancedtemplates/example}    The next example, defining \texttt{MapType} as a map having plain types or
pointers for either its key or value types, illustrates this approach:
        \begin{verbatim}
    template <typename Key, typename Value, int selector>
    class Storage
    {
        using MapType =  
                typename IfElse<
                    selector == 1,              // if selector == 1:
                    map<Key, Value>,            // use map<Key, Value>

                    typename IfElse<
                        selector == 2,          // if selector == 2:
                        map<Key, Value *>,      // use map<Key, Value *>

                        typename IfElse<
                            selector == 3,      // if selector == 3:
                            map<Key *, Value>,  // use map<Key *, Value>
                                                // otherwise:
                            map<Key *, Value *> // use map<Key *, Value *>

                        >::type
                    >::type
                >::type;

        MapType d_map;

        public:
            void add(Key const &key, Value const &value);
        private:
            void add(Key const &key, Value const &value, IntType<1>);
           ...
    };
    template <typename Key, typename Value, int selector>
    inline void Storage<selector, Key, Value>::add(Key const &key,
                                                   Value const &value)
    {
        add(key, value, IntType<selector>());
    }
\end{verbatim}
The principle used in the above examples is: if class templates may use
data types that depend on template non-type parameters, an \texttt{IfElse} struct
can be used to select the appropriate data types. Knowledge about the various
data types may also be used to define overloaded member functions. The
implementations of these overloaded members may then be optimized to the
various data types. In programs only one of these alternate functions (the one
that is optimized to the actually used data types) will then be instantiated.

The private \texttt{add} functions define the same parameters as the public
\texttt{add} wrapper function, but add a specific \texttt{IntType} type, allowing the
compiler to select the appropriate overloaded version based on the template's
non-type selector parameter.

\subsection{Templates: Iterations by Recursion}
    \typeout{Original Yodl file: advancedtemplates/iterating}    As there are no variables in template meta programming, there is no
template equivalent to a \texttt{for} or \texttt{while} statement. However, iterations
can always be rewritten as recursions.  Recursions \emph{are} supported
by templates and so iterations can always be implemented as (tail) recursions.
        \index{template: iteration by recursion}

To implement iterations by (tail) recursion do as follows:
    \begin{itemize}
    \item  define a specialization implementing the end-condition;
    \item  define all other steps using recursion.
    \item  store intermediate values as \texttt{enum} values.
    \end{itemize}
    The compiler selects a more specialized template implementation over a
more generic one. By the time the compiler reaches the end-condition the
recursion stops since the specialization does not use recursion.

Most readers are probably familiar with the recursive implementation of
the mathematical `\emph{factorial}' operator, commonly represented by the
exclamation mark (\texttt{!}): \texttt{n} factorial (so: \texttt{n!}) returns the successive
products \texttt{n $*$ (n - 1) $*$ (n - 2) $*$ ... $*$ 1}, representing the number of ways
\texttt{n} objects can be permuted. Interestingly, the factorial operator is itself
usually defined by a \emph{recursive} definition:
        \begin{verbatim}
    n! = (n == 0) ?
            1
        :
            n * (n - 1)!
\end{verbatim}
To compute \texttt{n!} from a template, a template \texttt{Factorial} can be defined
using an \texttt{int n} template non-type parameter. A specialization is defined
for the case \texttt{n == 0}. The generic implementation uses recursion according
to the factorial definition. Furthermore, the \texttt{Factorial} template defines
an \texttt{enum} value `\texttt{value}' containing its factorial value. Here is the
generic definition:
        \begin{verbatim}
    template <int n>
    struct Factorial
    {
        enum { value = n * Factorial<n - 1>::value };
    };
\end{verbatim}
Note how the expression assigning a value to `\texttt{value}' uses constant
values that can be determined by the compiler. The value n is provided, and
\texttt{Factorial$<$n - 1$>$} is computed using \emph{template meta
programming}. \texttt{Factorial$<$n-1$>$} in turn results in value that can be
determined by the compiler (\emph{viz.}
\texttt{Factorial$<$n-1$>$::value}). \texttt{Factorial$<$n-1$>$::value} represents the \texttt{value}
defined by the \emph{type} \texttt{Factorial$<$n - 1$>$}. It is \emph{not} the value returned
by an \emph{object} of that type. There are no objects here but merely values
defined by types.

The recursion ends in  a specialization. The compiler selects the
specialization (provided for the terminating value 0) instead of  the generic
implementation whenever possible. Here is the specialization's implementation:
        \begin{verbatim}
    template <>
    struct Factorial<0>
    {
        enum { value = 1 };
    };
\end{verbatim}
The \texttt{Factorial} template can be used to determine, compile time, the
number of permutations of a fixed number of objects. E.g.,
        \begin{verbatim}
    int main()
    {
        cout << "The number of permutations of 5 objects = " <<
                Factorial<5>::value << "\n";
    }
\end{verbatim}
Once again, \texttt{Factorial$<$5$>$::value} is \emph{not} evaluated at run-time, but
at compile-time. The run-time equivalent of the above \texttt{cout} statement is,
therefore:
        \begin{verbatim}
    int main()
    {
        cout << "The number of permutations of 5 objects = " <<
                120 << "\n";
    }
\end{verbatim}
\section{User-defined literals}\label{UDL}
\typeout{Original Yodl file: advancedtemplates/userdefined}In addition to the literal operators discussed in section \ref{UDLITERALS} 
\textbf{C++} also offers a function template literal operator, matching the
prototype
        \begin{verbatim}
    template <char ...Chars>
    Type operator "" _identifier()
\end{verbatim}
This variadic non-type parameter function template defines no parameters,
but merely a variadic non-type parameter list.

Its argument must be an int constant, as is also expected by the literal
operator defining an \texttt{unsigned long long int} parameter. All the characters
of the int constant are passed as individual \texttt{char} non-type template
arguments to the literal operator.

For example, if \texttt{\_NM2km} is a literal operator function template, it can
be called as \texttt{80\_NM2km}. The function template is then actually called as
\texttt{\_NM2km$<$'8', '0'$>$()}. If this function template merely uses template meta
programming techniques and only processes integral data then its actions can
be performed completely at compile-time. To illustrate this, let's assume
\texttt{NM2km} only processes and returns unsigned values.

The function template \texttt{\_NM2km} can forward its argument to a class template,
defining an enum constant \texttt{value}, and that performs the required
computations. Here is the implementation of the variadic literal operator
function template \texttt{\_NM2km}:
            \begin{verbatim}
    template <char ... Chars>
    constexpr size_t operator "" _NM2km()
    {
        return static_cast<size_t>(             // forward Chars to NM2km
                NM2km<0, Chars ...>::value * 1.852);
    }
\end{verbatim}
The class template \texttt{NM2km} defines three non-type parameters: \texttt{acc}
accumulates the value, \texttt{c} is the first character of the variadic non-type
parameters, while \texttt{...Chars} represents the remaining non-type parameters,
contained in a non-type parameter pack. Since \texttt{c} is, at each recursive
call, the next character from the original non-type parameter pack, the value
so far multiplied by 10 plus the value of the next character is passed as the
next accumulated value to its recursive call, together with the remaining
elements of the parameter pack, represented by \texttt{Chars ...}:
            \begin{verbatim}
    template <size_t acc, char c, char  ...Chars>
    struct NM2km
    {
        enum
        {
            value = NM2km<10 * acc + c - '0', Chars ...>::value
        };
    };
\end{verbatim}
Eventually, the parameter pack is empty. For this case a partial
specialization of \texttt{NM2km} is available:
        \begin{verbatim}
    template <size_t acc, char c>   // empty parameter pack
    struct NM2km<acc, c>
    {
        enum
        {
            value = 10 * acc + c - '0'
        };
    };
\end{verbatim}
This works fine, but of course not in cases where binary, octal, or
hexadecimal values must also be interpreted. In that case we must first
determine whether the first character(s) indicate a special number
system. This can be determined by the class template \texttt{NM2kmBase}, that is
now called from the \texttt{\_NM2km} literal operator:
            \begin{verbatim}
    template <char ... Chars>
    constexpr size_t operator "" _NM2km()
    {
        return static_cast<size_t>(         // forward Chars to NM2kmBase
                NM2kmBase<Chars ...>::value * 1.852);
    }
\end{verbatim}
The \texttt{NM2kmBase} class template normally assumes the decimal number
system, passing base value 10 and initial sum 0 to \texttt{NM2km}. The \texttt{NM2km}
class template is provided with an additional (first) non-type parameter
representing the base value of the number system to use. Here is
\texttt{NM2kmBase}:
        \begin{verbatim}
    template <char ...Chars>
    struct NM2kmBase
    {
        enum
        {
            value = NM2km<10, 0, Chars ...>::value
        };
    };
\end{verbatim}
Partial specializations handle the different number systems, by inspecting
the first (one or two) characters:
        \begin{verbatim}
    template <char ...Chars>
    struct NM2kmBase<'0', Chars ...>        // "0..."
    {
        enum
        {                                   // octal value: base 8
            value = NM2km<8, 0, Chars ...>::value
        };
    };

    template <char ...Chars>
    struct NM2kmBase<'0', 'b', Chars ...>   // "0b..."
    {
        enum
        {                                   // binary value: base 2
            value = NM2km<2, 0, Chars ...>::value
        };
    };

    template <char  ...Chars>
    struct NM2kmBase<'0', 'x', Chars ...>   // "0x..."
    {
        enum
        {                                   // hex value: base 16
            value = NM2km<16, 0, Chars ...>::value
        };
    };
\end{verbatim}
\texttt{NM2km} is implemented as before, albeit that it can now handle
various number systems. The conversion from character to numeric value is left
to a small support function template, \texttt{cVal}:
        \begin{verbatim}
    template <char c>
    constexpr int cVal()
    {
        return '0' <= c <= '9' ? c - '0' : 10 + c - 'a';
    }

    template <size_t base, size_t acc, char c, char  ...Chars>
    struct NM2km
    {
        enum
        {
            value = NM2km<base, base * acc + cVal<c>(),
                                        Chars ...>::value
        };
    };

    template <size_t base, size_t acc, char c>
    struct NM2km<base, acc, c>
    {
        enum { value = base * acc + cVal<c>() };
    };
\end{verbatim}
\section{Template template parameters}\label{TEMPTEMPPAR}
\typeout{Original Yodl file: advancedtemplates/templateparam}Consider the following situation: a software engineer is asked to design a
storage class \texttt{Storage}. Data stored in \texttt{Storage} objects may either make
and store copies of the data or store the data as received. \texttt{Storage}
objects may also either use a vector or a linked list as its underlying
storage medium. How should the engineer tackle this request? Should four
different \texttt{Storage} classes be designed?

The engineer's first reaction could be to develop an all-in \texttt{Storage} class.
It could have two data members, a list and a vector, and its constructor could
be provided with maybe an enum value indicating whether the data itself or new
copies should be stored. The enum value can be used to initialize a series of
pointers to member functions performing the requested tasks (e.g., using a
vector to store the data or a list to store copies).

Complex, but doable. Then the engineer is asked to modify the class: in the
case of new copies a custom-made allocation scheme should be used rather than
the standard \texttt{new} operator.  He's also asked to allow the use of yet
another type of container, in addition to the vector and the list that were
already part of the design. Maybe a \texttt{deque} would be preferred or maybe even
a \texttt{stack}.

It's clear that the approach aiming at implementing all functionality and all
possible combinations in one class doesn't scale. The class \texttt{Storage} soon
becomes a monolithic giant which is hard to understand, maintain, test, and
deploy.

One of the reasons why the big, all-encompassing class is hard to deploy and
understand is that a well-designed class should
        \index{class: enforcing constraints}
    \emph{enforce constraints}: the design of the class should, by itself,
disallow certain operations, violations of which should be detected by the
compiler, rather than by a program that might terminate in a fatal error.

Think about the above request. If the class offers both an interface to access
the vector data storage \emph{and} an interface to access the list data storage,
then it's likely that the class offers an overloaded \index{operator[]}\texttt{operator{[}{]}} member
to access elements in the vector. This member, however, will be syntactically
present, but semantically invalid when the \emph{list} data storage is selected,
which doesn't support \texttt{operator{[}{]}}.

Sooner or later, \emph{users} of the monolithic all-encompassing class
\texttt{Storage} will fall into the trap of using \texttt{operator{[}{]}} even though
they've selected the list as the underlying data storage. The compiler won't
be able to detect the error, which only appears once the program is
running, confusing its users.

The question remains: how should the engineer proceed, when confronted with
the above questions? It's time to introduce \index{class: policy} \emph{policies}.

\subsection{Policy classes - I}
    \typeout{Original Yodl file: advancedtemplates/policies}A \index{policy}\emph{policy} defines (in some contexts: prescribes) a particular kind of
behavior. In \textbf{C++} a
    \index{class: policy}
 \emph{policy class} defines a certain part of the class interface. It may also
define inner types, member functions, and data members.

In the previous section the problem of creating a class that might use any of
a series of allocation schemes was introduced. These allocation schemes all
depend on the actual data type to use, and so the `template reflex' should
kick in.

Allocation schemes should probably be defined as template classes, applying
the appropriate allocation procedures to the data type at hand. When such
allocation schemes are used by the familiar STL containers (like
\texttt{std::vector, std::stack}, etc.), then such home-made allocation schemes
should probably be derived from \texttt{std::allocator}\index{allocator}, to provide
for the requirements made by these containers. The class template
\texttt{std::allocator} is declared by the \index{memory: header file}\texttt{$<$memory$>$} header file and the three
allocation schemes developed here were all derived from \texttt{std::allocator}.

Using in-class implementations for brevity the following allocation classes
could be defined:
    \begin{itemize}
    \item  No special allocation takes place, \texttt{Data} is used `as is':
    \begin{verbatim}
template <typename Data>
class PlainAlloc: public std::allocator<Data>
{
    template<typename IData>
    friend std::ostream &operator<<(std::ostream &out,
                                    PlainAlloc<IData> const &alloc);
    Data d_data;

    public:
        PlainAlloc()
        {}
        PlainAlloc(Data const &data)
        :
            d_data(data)
        {}
        PlainAlloc(PlainAlloc<Data> const &other)
        :
            d_data(other.d_data)
        {}
};
\end{verbatim}
\item  The second allocation scheme uses the standard \texttt{new} operator to
allocate a new copy of the data:
    \begin{verbatim}
template <typename Data>
class NewAlloc: public std::allocator<Data>
{
    template<typename IData>
    friend std::ostream &operator<<(std::ostream &out,
                                    NewAlloc<IData> const &alloc);
    Data *d_data;

    public:
        NewAlloc()
        :
            d_data(0)
        {}
        NewAlloc(Data const &data)
        :
            d_data(new Data(data))
        {}
        NewAlloc(NewAlloc<Data> const &other)
        :
            d_data(new Data(*other.d_data))
        {}
        ~NewAlloc()
        {
            delete d_data;
        }
};
\end{verbatim}
\item  The third allocation scheme uses the \index{placement new}placement new operator (see
        section \ref{PLACEMENT}), requesting memory from a
        common pool (the implementation of the member \texttt{request},
        obtaining the required amount of memory, is left as an exercise to the
        reader):
    \begin{verbatim}
template<typename Data>
class PlacementAlloc: public std::allocator<Data>
{
    template<typename IData>
    friend std::ostream &operator<<(std::ostream &out,
                                    PlacementAlloc<IData> const &alloc);
    Data *d_data;

    static char s_commonPool[];
    static char *s_free;

    public:
        PlacementAlloc()
        :
            d_data(0)
        {}
        PlacementAlloc(Data const &data)
        :
            d_data(new(request()) Data(data))
        {}
        PlacementAlloc(PlacementAlloc<Data> const &other)
        :
            d_data(new(request()) Data(*other.d_data))
        {}
        ~PlacementAlloc()
        {
            d_data->~Data();
        }
    private:
        static char *request();
};
\end{verbatim}
\end{itemize}
    The above three classes define \emph{policies} that may be selected by the
user of the class \texttt{Storage} introduced in the previous section. In addition
to these classes, additional allocation schemes could be implemented by the
user as well.

To apply the proper allocation scheme to the class \texttt{Storage},
\texttt{Storage} should be designed as a class template itself. The class also
needs a template type parameter allowing users to specify the data type.

The data type to be used by a particular allocation scheme could of course
be specified when specifying the allocation scheme to use. The class
\texttt{Storage} would then have two template type parameters, one for the data
type, one for the allocation scheme:
        \begin{verbatim}
    template <typename Data, typename Scheme>
    class Storage ...
\end{verbatim}
To use the class \texttt{Storage} we would then write, e.g.:
        \begin{verbatim}
    Storage<string, NewAlloc<string>> storage;
\end{verbatim}
Using \texttt{Storage} this way is fairly complex and potentially error-prone,
as it requires the user to specify the data type twice. Instead, the
allocation scheme should be specified using a new type of template parameter,
not requiring the user to specify the data type required by the allocation
scheme. This new kind of template parameter (in addition to the well-known
\emph{template type parameter} and \emph{template non-type parameter}) is called the
 \index{template template parameter}\emph{template template parameter}.

Starting with the C++14 standard the keyword \emph{class} 
        \index{template: class vs. typename} 
    in the syntactical form of template template parameters (\texttt{template
$<$parameter specifications$>$ class Name}) is no longer required. From that
standard onward, the keyword \texttt{typename} can also be used (e.g., \texttt{template
$<$parameter specifications$>$ typename Name}).

\subsection{Policy classes - II: template template parameters}
    \typeout{Original Yodl file: advancedtemplates/templateparam2}Template \index{template template parameter} template parameters allow us to
specify a \emph{class template} as a template parameter. By specifying a class
template, it is possible to add a certain kind of behavior (called a
\index{policy}\emph{policy}) to an existing class template.

To specify an allocation \emph{policy}, rather than an allocation \texttt{type}
for the class \texttt{Storage} we rephrase its class template header:
definition starts as follows:
        \begin{verbatim}
    template <typename Data, template <typename> class Policy>
    class Storage...
\end{verbatim}
The second template parameter is new. It is a \emph{template template
parameter}. It has the following elements:
    \begin{itemize}
    \item  The keyword \texttt{template}, starting the template template parameter;
    \item  The keyword \texttt{template} is followed (between angle brackets) by a
        list of template parameters that must be specified for the template
        template parameter. These parameters \emph{may} be given names, but names
        are usually omitted as those names cannot be used in subsequent
        template definitions. On the other hand, providing formal names may
        help the reader of the template to understand the kind of templates
        that must be specified with the template template parameter.
    \item  Template template parameters must match, in numbers and types (i.e.,
        template type parameters, template non-type parameters, template
        template parameters) the template parameters that must be specified
        for the policy. This can be tricky, as some templates use default
        parameters that are hardly ever changed (like the allocation schemes
        for containers). When specifying template template parameters those
        default types are used. If they should be specifiable then they must
        be added to the template template parameter's types. In the following
        example \texttt{fun} can only use the default allocator, \texttt{gun} \emph{must}
        specify the allocator when defining \texttt{vd}, and \texttt{hun} defines a
        default allocator type, offering the option to either specify the
        allocator type or use the default type:
            \begin{verbatim}
    #include <vector>
    using namespace std;

    template<typename Data, template <typename> class Vect>
    void fun()
    {
        // Vect<Data, std::allocator<Data>> vd; // fails
        Vect<Data> vd;                          // OK, uses std::allocator
    }

    template<typename Data,
             template <typename, typename> class Vect>
    void gun()
    {
        Vect<Data, std::allocator<Data>> vd;    // allocator type is required
    }

    template<typename Data,
             template <typename, typename = std::allocator<Data>> class Vect>
    void hun()
    {
        Vect<Data> vd;                          // uses default allocator type
    }

    int main()
    {
        fun<int, vector>();
        gun<int, vector>();
        hun<int, vector>();
    }
\end{verbatim}
Alternatively, \emph{alias templates}, introduced in section
        \ref{ALIASES}, can be used to define names for templates using
        predefined parameter types.
    \item  Following the bracketed list the keyword \index{class}\texttt{class} or \texttt{typename} 
        \emph{must} be specified. 
    \item  All parameters may be provided with default arguments. This is shown
        in the next example of a hypothetical class template:
        \begin{verbatim}
template <
    template <
        typename = std::string,
        int = 12,
        template <typename = int> class Inner = std::vector
    >
    class Policy
>
class Demo
{
   ...
};
\end{verbatim}
Here, the class template \texttt{Demo} expects a template template parameter
        named \texttt{Policy}, expecting three template parameters: a template type
        parameter (by default \texttt{std::string}); a template non-type parameter
        (by default having value 12); and \texttt{Policy} itself expects a template
        template parameter, called \texttt{Inner}, by default using an \texttt{int} as
        its template type parameter.
       \end{itemize}
    Policy classes are often an integral part of the class under
consideration. Because of this they are often deployed as base classes. In the
example the class \texttt{Policy} could be used as a base class of the class
\texttt{Storage}.

The policy operates on the class \texttt{Storage}'s data type. Therefore the
policy is informed about that data type as well. Our class \texttt{Storage} now
begins like this:
        \begin{verbatim}
    template <typename Data, template <typename> class Policy>
    class Storage: public Policy<Data>
\end{verbatim}
This automatically allows us to use \texttt{Policy}'s members when implementing
the members of the class \texttt{Storage}.

Our home-made allocation classes do not really provide us with many useful
members. Except for the extraction operator they offer no immediate access to
the data. This can easily be repaired by adding more members. E.g., the class
\texttt{NewAlloc} could be augmented with operators allowing access to and
modification of stored data:
            \begin{verbatim}
        operator Data &()   // optionally add a `const' member too
        {
            return *d_data;
        }
        NewAlloc &operator=(Data const &data)
        {
            *d_data = data;
        }
\end{verbatim}
The other allocation classes could be given comparable members.

Let's use the allocation schemes in some real code. The next
example shows how \texttt{Storage} can be defined using some data type and an
allocation scheme. We start out again with a class \texttt{Storage}:
        \begin{verbatim}
    template <typename Data, template <typename> class Allocate>
    class Storage: public std::vector<Data, Allocate<Data>>
    {};
\end{verbatim}
That's all we have to do. Note that \texttt{std::vector} formally has two
template parameters. The first one is the vector's data type, which is always
specified; the second one is the allocator used by the vector. Usually the
allocator is left unspecified (in which case the default STL allocator is
used), but here it is mentioned explicitly, allowing us to pass our own
allocation policy to \texttt{Storage}.

All required functionality is inherited from the \texttt{vector} base class, while
the policy is `factored into the equation' using a template template
parameter. Here's an example showing how this is done:
        \begin{verbatim}
    Storage<std::string, NewAlloc> storage;

    copy(istream_iterator<std::string>(cin), istream_iterator<std::string>(),
            back_inserter(storage));

    cout << "Element index 1 is " << storage[1] << '\n';
    storage[1] = "hello";

    copy(storage.begin(), storage.end(),
         ostream_iterator<NewAlloc<std::string> >(cout, "\n"));
\end{verbatim}
Since \texttt{Storage} objects are also \texttt{std::vector} objects the STL \texttt{copy}
function can be used in combination with the \emph{back\_inserter} iterator to add
some data to the \texttt{storage} object. Its elements can be accessed and modified
using the index operator. Then \texttt{NewAlloc$<$std::string$>$} objects are inserted
into \texttt{cout} (also using the \texttt{copy} function).

Interestingly, this is not the end of the story. Remember that our
intention was to create a class allowing us to specify the \emph{storage type} as
well. What if we don't want to use a \texttt{vector}, but instead would like to use
a \texttt{list}?

It's easy to change \texttt{Storage}'s setup so that a completely different
storage type can be used on request, like a \texttt{deque}. To implement this, the
storage class is parameterized as well, using yet another template template
parameter:
        \begin{verbatim}
    template <typename Data, template <typename> class AllocationPolicy,
              template <typename, typename> class Container = std::vector>
    class Storage: public Container<Data, AllocationPolicy<Data>>
    {};
\end{verbatim}
The earlier example using a \texttt{Storage} object can be used again without
requiring any modifications at all (except for the above redefinition). It
clearly can't be used with a \texttt{list} container, as the \texttt{list} lacks
\texttt{operator{[}{]}}. Trying to do so is immediately recognized by the compiler,
producing an error if an attempt is made to use \texttt{operator{[}{]}} on, e.g., a
    \texttt{list}.\footnote{A complete example showing the definition of the
allocation classes and the class \texttt{Storage} as well as its use is provided in
the \textbf{C++} Annotations's distribution in the file
\texttt{yo/advancedtemplates/examples/storage.cc}.} A \texttt{list} container, however
can still be specified as the container to use. In that case a \texttt{Storage} is
implemented as a \texttt{list}, offering \texttt{list}'s interface, rather than
\texttt{vector}'s interface, to its users.

\subsubsection{The destructor of Policy classes}
        \typeout{Original Yodl file: advancedtemplates/destructor}In the previous section policy classes were used as base classes of template
classes. This resulted in the interesting observation that a policy class
may serve as a \emph{base class}
        \index{class template: as base class}
    of a derived class.
    As a policy class may act as a base class, a pointer or reference to such
a policy class can be used to point or refer to the derived class using the
policy.

This situation, although legal, should be avoided for various reasons:
        \index{pointer: to policy base class}
    \begin{itemize}
    \item  Destruction of a derived class object using the base class's
destructor requires the implementation of a virtual destructor;
    \item  A virtual destructor introduces overhead to a class that normally has
no data members, but merely defines behavior: suddenly a \index{vtable}\texttt{vtable} is
required as well as a data member pointing to the vtable;
    \item  Virtual member functions somewhat reduce the efficiency of code;
virtual member functions use \index{dynamic polymorphism}\emph{dynamic polymorphism}, which in principle is
undoing the advantages of \index{static polymorphism}\emph{static polymorphism} as offered by templates;
    \item  Virtual member functions in templates may result in \index{code bloat}\emph{code bloat}:
once an instantiation of a class's member is required, the class's vtable and
\emph{all} its virtual members must be implemented too.
    \end{itemize}
    To avoid these drawbacks, it is good practice to \emph{prevent} the use of
references or pointers to policy classes to refer or point to derived
class objects. This is accomplished by providing policy classes with
        \index{destructor: for policy classes}
    \emph{non-virtual protected destructors}. With a non-virtual destructor there
is no performance penalty and since its destructor is protected users cannot
refer to classes derived from the policy class using a pointer or reference to
the policy class.

\subsection{Structure by Policy}
    \typeout{Original Yodl file: advancedtemplates/structure}Policy classes usually define behavior, not structure. Policy classes
        \index{policy class: defining structure}
 are normally used to parameterize some aspect of the behavior of classes that
are derived from them. However, different policies may require different data
members. These data members may also be defined by the policy classes. Policy
classes may therefore be used to define both behavior and structure.

By providing a well-defined interface a class derived from a policy class may
define member specializations using the different structures of policy classes
to their advantage. For example, a plain pointer-based policy class could
offer its functionality by resorting to \textbf{C}-style \index{pointer juggling}pointer juggling,
whereas a \texttt{vector}-based policy class could use the vector's members
directly.

In this example a generic class template \texttt{Size} could be designed
expecting a container-like policy using features commonly found in
containers, defining the data (and hence the structure) of the container
specified in the policy. E.g.:
        \begin{verbatim}
    template <typename Data, template <typename> class Container>
    struct Size: public Container<Data>
    {
        size_t size()
        {                           // relies on the container's `size()'
                                    // note: can't use `this->size()'
            return Container<Data>::size();
        }
    };
\end{verbatim}
A specialization can now be defined for a much simpler storage class
using, e.g., plain pointers (the implementation capitalizes on \texttt{first} and
\texttt{second}, data members of \texttt{std::pair}.  Cf. the example at the end of this
section):
        \begin{verbatim}
    template <typename Data>
    struct Size<Data, Plain>: public Plain<Data>
    {
        size_t size()
        {                           // relies on pointer data members
            return this->second - this->first;
        }
    };
\end{verbatim}
Depending on the intentions of the template's author other members could
be implemented as well.

To simplify the real use of the above templates, a generic wrapper class
can be constructed: it uses the \texttt{Size} template matching the actually used
storage type (e.g., a \texttt{std::vector} or some plain storage class) to define
its structure:
        \begin{verbatim}
    template <typename Data, template <typename> class Store>
    class Wrapper: public Size<Data, Store>
    {};
\end{verbatim}
The above classes could now be used as follows (\emph{en passant} showing an
extremely basic \texttt{Plain} class):
        \begin{verbatim}
    #include <iostream>
    #include <vector>

    template <typename Data>
    struct Plain: public std::pair<Data *, Data *>
    {};

    int main()
    {
        Wrapper<int, std::vector> wiv;
        std::cout << wiv.size() << "\n";

        Wrapper<int, Plain> wis;
        std::cout << wis.size() << "\n";
    }
\end{verbatim}
The \texttt{wiv} object now defines vector-data, the \texttt{wis} object merely
defines a \texttt{std::pair} object's data members.

\section{Alias Templates}\label{ALIASES}
\typeout{Original Yodl file: advancedtemplates/aliases}In addition to function and class templates, \textbf{C++} also uses templates to
define an alias for a set of types. This is called an
    \index{alias template}\emph{alias template}. Alias templates can be specialized. The name of an
alias template is a type name.

Alias templates can be used as arguments to template template parameters. This
allows us to avoid the `unexpected default parameters' you may encounter
(e.g., when using \textbf{C++} standards before the \texttt{c++23} standard) when using
template template parameters.  Defining a template specifying a \texttt{template
$<$typename$>$ class Container} is fine, but (before \texttt{c++23}) it was impossible
to specify a container like \texttt{vector} or \texttt{set} as template template
argument, as \texttt{vector} and \texttt{set} containers also define second template
parameters, specifying their allocation policies.

Alias templates are defined like \texttt{using} declarations, specifying an alias
for an existing (maybe partially or fully specialized) template type. In the
following example \texttt{Vector} is defined as an alias for \texttt{vector}:
        \begin{verbatim}
    template <typename Type>
    using Vector = std::vector<Type>;

    Vector<int> vi;             // same as std::vector<int>
    std::vector<int> vi2(vi);   // copy construction: OK
\end{verbatim}
So, what's the point of doing this?
    Looking at the \texttt{vector} container, we see that it defines two, rather
than one, template parameters, the second parameter being the allocation
policy \texttt{\_Alloc}, by default set to \texttt{std::allocator$<$\_Tp$>$}:
        \begin{verbatim}
    template<typename _Tp, typename _Alloc = std::allocator<_Tp> >
    class vector: ...
\end{verbatim}
Now define a class template \texttt{Generic} defining a template template
parameter:
        \begin{verbatim}
    template <typename Type, template <typename> class Container>
    class Generic: public Container<Type>
    {
        ...
    };
\end{verbatim}
Most likely, \texttt{Generic} offers members made available by the container
that is actually used to create the \texttt{Generic} object, and adds to those some
members of it own. However, a simple container like \texttt{std::vector} cannot be
used, as \texttt{std::vector} doesn't match a \texttt{template $<$typename$>$ class
Container$>$} parameter; it requires a \texttt{template $<$typename, typename$>$ class
Container$>$} template template parameter.

The \texttt{Vector} alias template, however, \emph{is} defined as a template
having one template type parameter, and it uses the vector's default
allocator. Consequently, passing a \texttt{Vector} to \texttt{Generic} works fine:
        \begin{verbatim}
    Generic<int, Vector> giv;       // OK
    Generic<int, std::vector> err;  // won't compile: 2nd argument mismatch
\end{verbatim}
With the aid of a small alias template it is also possible to use a
completely different kind of container, like a \texttt{map}, with \texttt{Generic}:
        \begin{verbatim}
    template <typename Type>
    using MapString = std::map<Type, std::string>;

    Generic<int, MapString> gim;    // uses map<int, string>
\end{verbatim}
\section{Trait classes}\label{TRAIT}
\typeout{Original Yodl file: advancedtemplates/trait}Scattered over the \texttt{std} namespace
    \index{trait class}\index{class: trait}
    \emph{trait classes} are found. E.g., most \textbf{C++} programmers have seen
the compiler mentioning `\texttt{std::char\_traits$<$char$>$}' when performing an
illegal operation on \texttt{std::string} objects, as in \texttt{std::string s(1)}.

Trait classes are used to make compile-time decisions about types. Trait
classes allow us to apply the proper code to the proper data type, be it a
pointer, a reference, or a plain value, all this maybe in combination with
\texttt{const}. The particular type of data to use can be inferred from the actual
type that is specified (or implied) when the template is used. This can be
fully automated, not requiring the template writer to make any decision.

Trait classes allow us to develop a \texttt{template $<$typename Type1, typename
Type2, ...$>$} without the need to specify many specializations covering all
combinations of, e.g., values, (const) pointers, or (const) references, which
would soon result in an unmaintainable exponential explosion of template
specializations (e.g., allowing these five different types for each template
parameter already results in 25 combinations when two template type parameters
are used: each must be covered by potentially different specializations).

Having available a trait class, the actual type can be inferred compile
time, allowing the compiler to deduce whether or not the actual type is a
pointer, a pointer to a member, or a const pointer, and to make comparable
deductions in case the actual type is, e.g., an lvalue or rvalue reference
type. This in turn allows us to write templates that define types like
    \index{generic algorithms: required types}
 \index{argument\_type}\texttt{argument\_type}, \index{first\_argument\_type}\texttt{first\_argument\_type}, \index{second\_argument\_type}\texttt{second\_argument\_type} and
\index{result\_type}\texttt{result\_type}, which are required by several generic algorithms (e.g.,
count\_if()).

A trait class usually performs no behavior. I.e., it has no constructor
and no members that can be called. Instead, it defines a series of types and
\texttt{enum} values that have certain values depending on the actual type that is
passed to the trait class template.  The compiler uses one of a set of
available specializations to select the one appropriate for an actual template
type parameter.

The point of departure when defining a trait template is a plain
vanilla \texttt{struct}, defining the characteristics of a plain value type like
an \texttt{int}.  This sets the stage for specific specializations, modifying the
characteristics for any other type that could be specified for the template.

To make matters concrete, assume the intent is to create a trait class
\texttt{BasicTraits} telling us whether a type is a plain value type, a pointer
type, an lvalue reference type or an rvalue reference type (all of which may
or may not be \texttt{const} types).

Whatever the actually provided type, we want to be able to determine the
`plain' type (i.e., the type without any modifiers, pointers or references),
the `pointer type' and the `reference type', allowing us to define in all
cases, e.g., an rvalue reference to its built-in type, even though we passed a
const pointer to that type.

Our point of departure, as mentioned, is a plain \texttt{struct} defining the
required parameter. Maybe something like this:
        \begin{verbatim}
        template <typename T>
        struct Basic
        {
            using Type = T;
            enum
            {
                isPointer = false,
                isConst = false,
                isRef = false,
                isRRef = false
            };
        };
\end{verbatim}
Although some conclusions can be drawn by combining various \texttt{enum}
values (e.g., a plain type is not a pointer or a reference or an rvalue
reference or a const), it is good practice to provide a full implementation of
trait classes, not requiring its users to construct these logical expressions
themselves. Therefore, the basic decisions in a trait class are usually made
by a
        \index{trait class: nested}\index{nested trait class}nested trait class,
    leaving the task of creating appropriate logical expressions to a
surrounding trait class.

So, the \texttt{struct Basic} defines the generic form of our inner trait
class. Specializations handle specific details. E.g., a pointer type is
recognized by the following specialization:
        \begin{verbatim}
        template <typename T>
        struct Basic<T *>
        {
            using Type = T;
            enum
            {
                isPointer = true,
                isConst = false,
                isRef = false,
                isRRef = false
            };
        };
\end{verbatim}
whereas a pointer to a const type is matched with the next specialization:
        \begin{verbatim}
        template <typename T>
        struct Basic<T const *>
        {
            using Type = T;
            enum
            {
                isPointer = true,
                isConst = true,
                isRef = false,
                isRRef = false
            };
        };
\end{verbatim}
Several other specializations should be defined: e.g., recognizing
\texttt{const} value types or (rvalue) reference types. Eventually all these
specializations are implemented as nested \texttt{struct}s of an outer class
\texttt{BasicTraits}, offering the public traits class interface. The outline of
the outer trait class is:
        \begin{verbatim}
    template <typename TypeParam>
    class BasicTraits
    {
        // Define specializations of the template `Basic' here

        public:
            BasicTraits(BasicTraits const &other) = delete;

            using ValueType = Basic<TypeParam>::Type;
            using PtrType = ValueType *;
            using RefType = ValueType &;
            using RvalueRefType = ValueType &&;

            enum
            {
                isPointerType = Basic<TypeParam>::isPointer,
                isReferenceType = Basic<TypeParam>::isRef,
                isRvalueReferenceType = Basic<TypeParam>::isRRef,
                isConst = Basic<TypeParam>::isConst,
                isPlainType = not (isPointerType or isReferenceType or
                                   isRvalueReferenceType or isConst)
            };
    };
\end{verbatim}
The trait class's public interface explicitly deletes its copy
constructor. As it therefore defines no constructor at all and as it has no
static members it does not offer any run-time executable code.
All the trait class's facilities must therefore be used compile time.

A trait class template can be used to obtain the proper type, irrespective
of the template type argument provided. It can also be used to select
a proper specialization that depends on, e.g., the \texttt{const}-ness of a
template type. Example:
        \begin{verbatim}
     cout <<
      "int: plain type? "     << BasicTraits<int>::isPlainType << "\n"
      "int: ptr? "            << BasicTraits<int>::isPointerType << "\n"
      "int: const? "          << BasicTraits<int>::isConst << "\n"
      "int *: ptr? "          << BasicTraits<int *>::isPointerType << "\n"
      "int const *: ptr? "    << BasicTraits<int const *>::isPointerType <<
                                                                      "\n"
      "int const: const? "    << BasicTraits<int const>::isConst << "\n"
      "int: reference? "      << BasicTraits<int>::isReferenceType << "\n"
      "int &: reference? "    << BasicTraits<int &>::isReferenceType << "\n"
      "int const &: ref ? "   << BasicTraits<int const &>::isReferenceType <<
                                                                        "\n"
      "int const &: const ? " << BasicTraits<int const &>::isConst << "\n"
      "int &&: r-reference? " << BasicTraits<int &&>::isRvalueReferenceType <<
                                                                        "\n"
      "int &&: const? " << BasicTraits<int &&>::isConst << "\n"
      "int const &&: r-ref ? "<< BasicTraits<int const &&>::
                                                isRvalueReferenceType << "\n"
      "int const &&: const ? "<< BasicTraits<int const &&>::isConst << "\n"
        "\n";

     BasicTraits<int *>::ValueType           value = 12;
     BasicTraits<int const *>::RvalueRefType rvalue = int(10);
     BasicTraits<int const &&>::PtrType      ptr = new int(14);
     cout << value << ' ' << rvalue << ' ' << *ptr << '\n';
\end{verbatim}
\subsection{Distinguishing class from non-class types}\label{CLASSORNOT}
    \typeout{Original Yodl file: advancedtemplates/distinguish.yo}In the previous section the \texttt{BasicTraits} trait class was developed. Using
specialized versions of a nested \texttt{struct Type} modifiers, pointers,
references and values could be distinguished.

Knowing whether a type is a class type or not (e.g., the type represents a
primitive type) could also be a useful bit of knowledge to a template
developer. The class template developer might want to define a
specialization when the template's type parameter represents a class
type (maybe using some member function that should be available)
and another specialization for non-class types.

This section addresses the question how a trait class can distinguish class
        \index{trait class: class detection}
    types from non-class types.

In order to distinguish classes from non-class types a distinguishing feature
that can be used at compile-time must be found. 
    \index{pointer: to member} It may require some thinking to
find such a distinguishing characteristic, but a good candidate eventually is
found in the pointer to members syntactic construct. Pointers to members
are only available for classes. Using the pointer to member construct as the
distinguishing characteristic, a specialization can be developed that uses the
pointer to member if available. Another specialization (or the generic
template) does something else if the pointer to member construction is not
available.

How can we distinguish a pointer to a member from `a generic situation',
not being a pointer to a member? Fortunately, such a distinction is
possible. A function template specialization can be defined having a parameter
which is a pointer to a member function. The generic function template
then accepts any other argument. The compiler \emph{selects} the former
(specialized) function when the provided type is a class type as class types
\emph{may} support a pointer to a member. The interesting verb here is `\emph{may}':
the class does not \emph{have} to define a pointer to member.

Furthermore, the compiler does not actually \emph{call} any function: we're
talking compile-time here. All the compiler does is to \emph{select} the
appropriate function by evaluating a constant expression.

So, our intended function template now looks like this:
        \begin{verbatim}
    template <typename ClassType>
    static `some returntype'  fun(void (ClassType::*)());
\end{verbatim}
The function's return type (`\texttt{(some returntype)}') will be defined
shortly. Let's first have a closer look at the function's parameter.  The
function's parameter defines a pointer to a member returning \texttt{void}. Such a
function does \emph{not} have to exist for the concrete class-type that's
specified when the function is used.  In fact, \emph{no} implementation is
provided. The function \texttt{fun} is only declared as a \emph{static} member in the
trait class. It's not implemented and no trait class object is required to
call it. What, then, is its use?

To answer the question we now have a look at the generic function
template that should be used when the template's argument is \emph{not} a class
type. The language offers a `worst case' parameter in its
        \index{parameter: ellipsis}
    \index{ellipsis}\emph{ellipsis} parameter list. The ellipsis is a final resort the compiler
may turn to if everything else fails. The generic function template specifies
a plain ellipsis in its parameter list:
        \begin{verbatim}
    template <typename NonClassType>
    static `some returntype' fun(...);
\end{verbatim}
It would be an error to define the generic alternative as a function
expecting an \texttt{int}. The compiler, when confronted with alternatives,
favors the simplest, most specified alternative over a more complex, generic
one. So, when providing \texttt{fun} with an argument it selects \texttt{int}
whenever possible and it won't select \texttt{fun(void (ClassType::$*$)())}. When
given the choice between \texttt{fun(void (ClassType::$*$)())} and \texttt{fun(...)} it
selects the former unless it can't do that.

The question now becomes: what argument can be used for both a pointer to
a member and for the ellipsis? Actually, there is such a `one size fits all'
argument: 0. The value 0 can be passed as argument value to functions defining
an ellipsis parameter and to functions defining a pointers-to-member
parameter.

But 0 does not specify a particular class. Therefore, \texttt{fun} must specify
an explicit template argument, appearing in our code as \texttt{fun$<$Type$>$(0)}, with
\texttt{Type} being the template type parameter of the trait class.

Now for the return type. The function's return type cannot be a simple
value (like \texttt{true} or \texttt{false}). Our eventual intent is to provide the
trait class with an enum telling us whether the trait class's template
argument represents a class type or not. That enum becomes something like
this:
        \begin{verbatim}
    enum { isClass = some class/non-class distinguishing expression } ;
\end{verbatim}
The distinguishing expression cannot be
        \begin{verbatim}
    enum { isClass = fun<Type>(0) } ;
\end{verbatim}
as \texttt{fun$<$Type$>$(0)} is not a constant expression and enum values \emph{must}
        \index{enum values: evaluated at compile-time}
 be defined by constant expressions so they can be determined at compile-time.

To determine \texttt{isClass}'s value we must find an expression allowing for
compile-time discriminations between \texttt{fun$<$Type$>$(...)}  and \texttt{fun$<$Type$>$(void
(Type::$*$)())}.

In situations like these the \index{sizeof}\texttt{sizeof} operator often is our tool of
choice as it is evaluated at compile-time. By defining different sized return
types for the two \texttt{fun} declarations we are able to distinguish (at
compile-time) which of the two \texttt{fun} alternatives is selected by the
compiler.

The \texttt{char} type is by definition a type having size 1. By defining
another type containing two consecutive \texttt{char} values a larger type is
obtained. A \texttt{char {[}2{]}} is of course not a type, but a \texttt{char{[}2{]}} can be
defined as a data member of a struct, and a struct \emph{does} define a
type. That struct then has a size exceeding 1. E.g.,
        \begin{verbatim}
    struct Char2
    {
        char data[2];
    };
\end{verbatim}
\texttt{Char2} can be defined as a nested type of our traits class. The
two \texttt{fun} function template declarations become:
        \begin{verbatim}
    template <typename ClassType>
    static Char2 fun(void (ClassType::*)());

    template <typename NonClassType>
    static char fun(...);
\end{verbatim}
Since \texttt{sizeof} expressions are evaluated at compile-time we can now
determine \texttt{isClass}'s value:
        \begin{verbatim}
    enum { isClass = sizeof(fun<Type>(0)) == sizeof(Char2) };
\end{verbatim}
This expression has several interesting implications:
    \begin{itemize}
    \item  no \texttt{fun} function template is ever instantiated;
    \item  the compiler considers \texttt{Type} and selects
\texttt{fun}'s function template specialization if \texttt{Type} is a class type and the
generic function template if not;
    \item  From the selected function it determines the return type and thus the
return type's size;
    \item  Resulting in the proper evaluation of \texttt{isClass}.
    \end{itemize}
    Without requiring any instantiation the trait class can now provide an
answer to the question whether a template type argument represents a class
type or not. Marvelous!

\subsection{Available type traits}\label{TYPETRAITS}
    \typeout{Original Yodl file: advancedtemplates/availabletraits}\textbf{C++} offers many facilities to identify and modifiy characteristics of
types. Before using these facilities the \index{type\_traits: header file}\texttt{$<$type\_traits$>$} header file must be
included.

All facilities offered by \texttt{type\_traits} are defined in the \texttt{std}
namespace (omitted from the examples given below), allowing programmers to
determine various characteristics of types and values.

In the description of available type traits the following concepts are
encountered: 
    \begin{itemize}
    \item  \index{arithmetic type}\emph{arithmetic type}:
       any integral or floating point type;

\item  \index{class type}\emph{class type}:
       not a union type, without non-static data members, without virtual
        members, without virtual or non-empty base classes;

\item  \index{compound type}\emph{compound type}:
      \begin{itemize}
       \item  arrays of objects of a given type;
       \item  functions, which have parameters of a given type returning
        \texttt{void} or objects;
       \item  pointers to \texttt{void}, to objects, to functions, or to 
        non-static class members;
       \item  references to objects or functions;
       \item  class, union or enumeration types;
       \end{itemize}

\item  \index{fundamental type}\emph{fundamental type}:
       a built-in type;

\item  \index{integral type}\emph{integral type}:
       all types whose values represent integral numbers, as well as \texttt{bool}
        and all built-in types representing (possibly unicode) characters;

\item  \index{literal type}\emph{literal type}:
       a literal type is a scalar type; a trivial class type; or an array of
        literal type elements;

\item  \index{is\_nothrow\_... type trait}\emph{is\_nothrow\_... type trait}:
       a type trait to determine whether its template argument supports the
        specified non-throwing member. Such type traits return \texttt{false}
        unless \texttt{noexcept(true)} is used at the function's declaration. E.g.,
       \begin{verbatim}
    struct NoThrow
    {
        NoThrow &operator=(SomeType const &rhs) noexept(true);
    };
\end{verbatim}
\item  \index{trivial type}\emph{trivial type}:
       trivial types are scalar types, trivial class types, arrays of such
        types and cv-qualified versions of these types;

\item  \index{trivial class type}\emph{trivial class type}: 
       a class type having a trivial copy constructor, no non-trivial move
        constructor, a trivial destructor, a trivial default constructor or at
        least one \texttt{constexpr} constructor other than the copy or move
        constructor, and only has non-static data members and base classes of
        literal types; 

\item  \index{trivial member function}\emph{trivial member function}: 
       trivial member functions are never declared (other than \texttt{default}) in
        their class interfaces and (for default constructors or assignment
        operators) only perform byte-by-byte actions. Here are two examples:
        \texttt{struct Pod} only has trivial members as it doesn't explicitly
        declare any member function and its data member is \emph{plain old
        data}. \texttt{struct Nonpod} is \emph{not} plain old data. Although it
        doesn't explictly declare any member function either, its data member
        is a \texttt{std::string}, which itself isn't plain old data as
        \texttt{std::string} has non-trivial constructors:
       \begin{verbatim}
    struct Pod
    {
        int x;
    };

    struct Nonpod
    {
        std::string s;
    };
\end{verbatim}
\end{itemize}

When \emph{type-condition} applies to a type, it must be a complete type,
\texttt{void}, or an array of unknown size;

The following type traits are provided:
    \begin{itemize}
    \item \texttt{add\_const$<$typename Type$>$::type}
       \index{add\_const} to add \texttt{const} to \texttt{Type};

\item \texttt{add\_cv$<$typename Type$>$::type}
       \index{add\_cv} to add \texttt{const volatile} to \texttt{Type};

\item \texttt{add\_lvalue\_reference$<$typename Type$>$::type}
       \index{add\_lvalue\_reference} to add an lvalue reference to \texttt{Type};

\item \texttt{add\_pointer$<$typename Type$>$::type}
       \index{add\_pointer} to add a pointer to \texttt{Type};

\item \texttt{add\_rvalue\_reference$<$typename Type$>$::type}
       \index{add\_rvalue\_reference} to add an rvalue reference to \texttt{Type};

\item \texttt{add\_volatile$<$typename Type$>$::type}
       \index{add\_volatile} to add \texttt{volatile} to \texttt{Type};

\item \texttt{conditional$<$bool cond, typename TrueType, typename FalseType$>$::type}
       \index{conditional} to conditionally use \texttt{TrueType} if \texttt{cond} is true,
        \texttt{FalseType} if not;

\item \texttt{template $<$typename Type$>$ struct decay}
       \index{decay} defines the typename \texttt{type} obtained from \texttt{Type} after
        removing all cv-qualifiers and references from the specified template
        type argument. Moreover, it converts lvalue types to rvalue types,
        and arrays and functions to pointers. It resembles what happens if an
        argument is passed to a value-type parameter.

\item \texttt{template $<$typename Type$>$ decay\_t}
       \index{decay\_t} is shorthand for \texttt{typename decay$<$Type$>$::type}.

\item \texttt{enable\_if$<$bool cond, typename Type$>$::type}
       \index{enable\_if} to conditionally define \texttt{Type} if \texttt{cond} is true;

\item \texttt{is\_abstract$<$typename Type$>$::value}
       \index{is\_abstract} to determine whether \texttt{Type} is an abstract type
        (e.g., an abstract base class) (\emph{type-condition} applies);

\item \texttt{is\_arithmetic$<$typename Type$>$::value}
       \index{is\_arithmetic} to determine whether \texttt{Type} is an arithmetic type;

\item \texttt{is\_array$<$typename Type$>$::value}
       \index{is\_array} to determine whether \texttt{Type} is an array type;

\item \texttt{is\_assignable$<$typename To, typename From$>$::value}
       \index{is\_assignable} to determine whether an object of type \texttt{From} can
        be assigned to an object of type \texttt{To} (\emph{type-condition} applies);

\item \texttt{is\_base\_of$<$typename Base, typename Derived$>$::value}
       \index{is\_base\_of} to determine whether \texttt{Base} is a base class
        of type \texttt{Derived};

\item \texttt{is\_class$<$typename Type$>$::value}
       \index{is\_class} to determine whether \texttt{Type} is a class type;

\item \texttt{is\_compound$<$typename Type$>$::value}
       \index{is\_compound} to determine whether \texttt{Type} is a compound type;

\item \texttt{is\_const$<$typename Type$>$::value}
       \index{is\_const} to determine whether \texttt{Type} is a const type;

\item \texttt{is\_constructible$<$typename Type, typename ...Args$>$::value}
       \index{is\_constructible} to determine whether \texttt{Type} is constructible
        from arguments in the \texttt{Args} parameter pack (\emph{type-condition}
        applies to all types in \texttt{Args});

\item \texttt{is\_convertible$<$typename From, typename To$>$::value}
       \index{is\_convertible} to determine whether a type \texttt{From} may be
        converted to a type \texttt{To} using a \texttt{static\_cast};

\item \texttt{is\_copy\_assignable$<$typename Type$>$::value}
       \index{is\_copy\_assignable} to determine whether \texttt{Type} supports copy
        assignment (\emph{type-condition} applies);

\item \texttt{is\_copy\_constructible$<$typename Type$>$::value}
       \index{is\_copy\_constructible} to determine whether \texttt{Type} supports copy
        construction (\emph{type-condition} applies);

\item \texttt{is\_default\_constructible$<$typename Type$>$::value}
       \index{is\_default\_constructible} to determine whether \texttt{Type} supports a
        default constructor (\emph{type-condition} applies);

\item \texttt{is\_destructible$<$typename Type$>$::value}
       \index{is\_destructible} to determine whether \texttt{Type} has a non-deleted
        destructor (\emph{type-condition} applies);

\item \texttt{is\_empty$<$typename Type$>$::value}
       \index{is\_empty} to determine whether \texttt{Type} is a class type (not a union
        type), without non-static data members, virtual members, virtual or
        non-empty base classes (\emph{type-condition} applies);

\item \texttt{is\_enum$<$typename Type$>$::value}
       \index{is\_enum} to determine whether \texttt{Type} is an enum type;

\item \texttt{is\_floating\_point$<$typename Type$>$::value}
       \index{is\_floating\_point} to determine whether \texttt{Type} is a floating point
        type;

\item \texttt{is\_function$<$typename Type$>$::value}
       \index{is\_function} to determine whether \texttt{Type} is a function type;

\item \texttt{is\_fundamental$<$typename Type$>$::value}
       \index{is\_fundamental} to determine whether \texttt{Type} is a fundamental type;

\item \texttt{is\_integral$<$typename Type$>$::value}
       \index{is\_integral} to determine whether \texttt{Type} is an integral type;

\item \texttt{is\_literal\_type$<$typename Type$>$::value}
       \index{is\_literal\_type} to determine whether \texttt{Type} is a literal type
        (\emph{type-condition} applies);

\item \texttt{is\_lvalue\_reference$<$typename Type$>$::value}
       \index{is\_lvalue\_reference} to determine whether \texttt{Type} is an lvalue
        reference;

\item \texttt{is\_member\_function\_pointer$<$typename Type$>$::value}
       \index{is\_member\_function\_pointer} to determine whether \texttt{Type} is a
        pointer to a non-static member function;

\item \texttt{is\_member\_object\_pointer$<$typename Type$>$::value}
       \index{is\_member\_object\_pointer} to determine whether \texttt{Type} is a pointer
        to a non-static data member;

\item \texttt{is\_member\_pointer$<$typename Type$>$::value}
       \index{is\_member\_pointer} to determine whether \texttt{Type} is a pointer to a
        member function;

\item \texttt{is\_move\_assignable$<$typename Type$>$::value}
       \index{is\_move\_assignable} to determine whether \texttt{Type} supports move
        assignment (\emph{type-condition} applies);

\item \texttt{is\_move\_constructible$<$typename Type$>$::value}
       \index{is\_move\_constructible} to determine whether \texttt{Type} supports move
        construction (\emph{type-condition} applies);

\item \texttt{is\_nothrow\_assignable$<$typename To, typename From$>$::value}
       \index{is\_nothrow\_assignable} to determine whether \texttt{Type} supports an
        assignment operator not throwing exceptions (\emph{type-condition}
        applies).

\item \texttt{is\_nothrow\_constructible$<$typename Type, typename ...Args$>$::value}
       \index{is\_nothrow\_constructible} to determine whether a \texttt{Type} object can
        be constructed from arguments of types mentioned in the parameter pack
        not throwing exceptions (\emph{type-condition} applies);

\item \texttt{is\_nothrow\_copy\_assignable$<$typename Type$>$::value}
       \index{is\_nothrow\_constructible} to determine whether \texttt{Type} supports a
        copy-assignment operator not throwing exceptions (\emph{type-condition}
        applies);

\item \texttt{is\_nothrow\_copy\_constructible$<$typename Type$>$::value}
       \index{is\_nothrow\_copy\_constructible} to determine whether \texttt{Type}
        supports copy construction not throwing exceptions (\emph{type-condition}
        applies);

\item \texttt{is\_nothrow\_default\_constructible$<$typename Type$>$::value}
       \index{is\_nothrow\_default\_constructible} to determine whether \texttt{Type}
        supports a default constructor not throwing exceptions
        (\emph{type-condition} applies);

\item \texttt{is\_nothrow\_destructible$<$typename Type$>$::value}
       \index{is\_nothrow\_destructible} to determine whether \texttt{Type} supports a
        destructor not throwing exceptions (\emph{type-condition} applies).

\item \texttt{is\_nothrow\_move\_assignable$<$typename Type$>$::value}
       \index{is\_nothrow\_move\_assignable} to determine whether \texttt{Type} supports
        move assignment not throwing exceptions (\emph{type-condition} applies);

\item \texttt{is\_nothrow\_move\_constructible$<$typename Type$>$::value}
       \index{is\_nothrow\_move\_constructible} to determine whether \texttt{Type}
        supports a move constructor not throwing exceptions
        (\emph{type-condition} applies);

\item \texttt{is\_object$<$typename Type$>$::value}
       \index{is\_object} to determine whether \texttt{Type} is an object (in contrast
        to scalar) type;

\item \texttt{is\_pod$<$typename Type$>$::value}
       \index{is\_pod} to determine whether \texttt{Type} is an \index{aggregate}\emph{aggregate} 
            (\index{plain old data}\emph{plain old data},
        \emph{type-condition} applies);

\item \texttt{is\_pointer$<$typename Type$>$::value}
       \index{is\_pointer} to determine whether \texttt{Type} is a pointer type;

\item \texttt{is\_polymorphic$<$typename Type$>$::value}
       \index{is\_polymorphic} to determine whether \texttt{Type} is a polymorphic type
        (\emph{type-condition} applies);

\item \texttt{is\_reference$<$typename Type$>$::value}
       \index{is\_reference} to determine whether \texttt{Type} is an (lvalue or rvalue)
        reference;

\item \texttt{is\_rvalue\_reference$<$typename Type$>$::value}
       \index{is\_rvalue\_reference} to determine whether \texttt{Type} is an rvalue
        reference;

\item \texttt{is\_same$<$typename First, typename Second$>$::value}
       \index{is\_same} to determine whether types \texttt{First} and \texttt{Second} are
        identical;

\item \texttt{is\_scalar$<$typename Type$>$::value}
       \index{is\_scalar} to determine whether \texttt{Type} is a scalar type (in
        contrast to an object type);

\item \texttt{is\_signed$<$typename Type$>$::value}
       \index{is\_signed} to determine whether \texttt{Type} is a signed type;

\item \texttt{is\_standard\_layout$<$typename Type$>$::value}
       \index{is\_standard\_layout} to determine whether \texttt{Type} offers the
        standard layout (\emph{type-condition} applies);

\item \texttt{is\_trivial$<$typename Type$>$::value}
       \index{is\_trivial} to determine whether \texttt{Type} is a trivial type
        (\emph{type-condition} applies);

\item \texttt{is\_trivially\_assignable$<$typename Dest, typename Src$>$::value}
       \index{is\_trivially\_assignable} to determine whether an object or value of
        type \texttt{Src} can trivially be assigned to an object of type \texttt{Dest}
        (\emph{type-condition} applies);

\item \texttt{is\_trivially\_constructible$<$typename Type, typename ...Args$>$::value}
       \index{is\_trivially\_constructible} to determine whether \texttt{Type} is
        trivially constructible from arguments in the \texttt{Args} parameter pack
        (\emph{type-condition} applies to all types in \texttt{Args});

\item \texttt{is\_trivially\_copy\_assignable$<$typename Type$>$::value}
       \index{is\_trivially\_copy\_assignable} to determine whether \texttt{Type} supports
        a trivial assignment operator (\emph{type-condition} applies);

\item \texttt{is\_trivially\_copy\_constructible$<$typename Type$>$::value}
       \index{is\_trivially\_copy\_constructible} to determine whether \texttt{Type} is
        trivially copy-constructible (\emph{type-condition} applies);

\item \texttt{is\_trivially\_copyable$<$typename Type$>$::value}
       \index{is\_trivially\_copyable} to determine whether \texttt{Type} is trivially
        copyable (\emph{type-condition} applies);

\item \texttt{is\_trivially\_default\_constructible$<$typename Type$>$::value}
       \index{is\_trivially\_default\_constructible} to determine whether \texttt{Type}
        supports a trivial default constructor (\emph{type-condition} applies);

\item \texttt{is\_trivially\_default\_destructible$<$typename Type$>$::value}
       \index{is\_trivially\_default\_destructible} to determine whether \texttt{Type}
        supports a trivial default destructor (\emph{type-condition} applies);

\item \texttt{is\_trivially\_move\_assignable$<$typename Type$>$::value}
       \index{is\_trivially\_move\_assignable} to determine whether \texttt{Type} supports
        a trivial assignment operator (\emph{type-condition} applies);

\item \texttt{is\_trivially\_move\_constructible$<$typename Type$>$::value}
       \index{is\_trivially\_move\_constructible} to determine whether \texttt{Type} is
        trivially move-constructible (\emph{type-condition} applies);

\item \texttt{is\_union$<$typename Type$>$::value}
       \index{is\_union} to determine whether \texttt{Type} is a union type;

\item \texttt{is\_unsigned$<$typename Type$>$::value}
       \index{is\_unsigned} to determine whether \texttt{Type} is an unsigned type;

\item \texttt{is\_void$<$typename Type$>$::value}
       \index{is\_void} to determine whether \texttt{Type} is \texttt{void};

\item \texttt{is\_volatile$<$typename Type$>$::value}
       \index{is\_volatile} to determine whether \texttt{Type} is a \texttt{volatile}
        qualified type;

\item \texttt{make\_signed$<$typename Type$>$::type}
       \index{make\_signed} to construct a signed type;

\item \texttt{make\_unsigned$<$typename Type$>$::type}
       \index{make\_unsigned} to construct an unsigned type;

\item \texttt{remove\_all\_extents$<$typename Type$>$::type}
       \index{remove\_all\_extents} if \texttt{Type} is a (possibly multidimensional)
        array of \texttt{ElementType} values or objects then \texttt{typedef type}
        equals \texttt{ElementType};

\item \texttt{remove\_const$<$typename Type$>$::type}
       \index{remove\_const} to remove \texttt{const} from \texttt{Type};

\item \texttt{remove\_cv$<$typename Type$>$::type}
       \index{remove\_cv} to remove \texttt{const} and/or \texttt{volatile} from \texttt{Type};

\item \texttt{remove\_extent$<$typename Type$>$::type}
       \index{remove\_extent} if \texttt{Type} is an array of \texttt{ElementType} values or
        objects then \texttt{typedef type} equals \texttt{ElementType}. With
        multi-dimensional arrays \texttt{ElementType} is the type of the array from
        which its first array dimension has been removed;

\item \texttt{remove\_pointer$<$typename Type$>$::type}
       \index{remove\_pointer} to remove a pointer from \texttt{Type};

\item \texttt{remove\_reference$<$typename Type$>$::type}
       \index{remove\_reference} to remove a reference from \texttt{Type};

\item \texttt{remove\_volatile$<$typename Type$>$::type}
       \index{remove\_volatile} to remove \texttt{volatile} from \texttt{Type};

\end{itemize}

\section{Defining `ErrorCodeEnum' and 'ErrorConditionEnum'
                          enumerations}\label{ERRCODEENUM} 
    \typeout{Original Yodl file: advancedtemplates/errorcodeenum}In section \ref{ERRORCODE} the class \texttt{std::error\_code} was introduced. One of
its constructors accepts \index{ErrorCodeEnum}\texttt{ErrorCodeEnum} values, where \texttt{ErrorCodeEnum} is
a template type name for enumerations that we may define ourselves containing
symbols that are used as error code values. Another constructor expects an
\texttt{int}-valued error code and a specification of an error category that uses
those error codes.

Several error code enumerations and error categories are predefined by \textbf{C++}
but it is also possible to define new \texttt{ErrorCodeEnums} and error
categories. In this section constructing new \texttt{ErrorCodeEnums} is covered, in
the next section designing new error categories is covered.

Defining new error code enumerations is an option when using \texttt{error\_code}
objects is attractive, but standard error code values (like the values defined
by \texttt{enum class errc}) aren't appropriate. For example, when designing an
interactive calculator, several errors may be encountered that are related to
the way expressions are entered by the user. For those situations you might
want to develop your own error code enumeration.

In this and the next section a bare bones approach to defining error code
enumerations and error categories is adopted. No concrete, real-life like
class is developed. I think the advantage of this is that this way it's easier
to apply the principles to new real-life situations than if you first have to
abstract the content of a real-life example yourself. Here we go:
   \begin{itemize}
   \item  Our first step consists of defining our own enumeration. The
    enumeration contains symbols listing causes of errors. Newly defined
    error code enumerations must not associate value 0 with any of its
    symbols, as by convention value 0 indicates `no error'. 

The \texttt{enum class CatErr} lists causes of errors that are associated
    with our (as yet to be designed) error category: 
        \begin{verbatim}
    enum class CatErr
    {
        Err1 = 1,           // causes of errors
        Err2,
        Err3
    };
\end{verbatim}
\item  By itself, defining an \texttt{enum class} does not allow us to pass its
    values to \texttt{error\_code} constructors. Before we can do that the \texttt{enum}
    must be `promoted' to an \index{error\_code\_enum}\emph{error\_code\_enum}. This `promotion' is
    realized by specializing the trait class
    \index{is\_error\_code\_enum}\texttt{std::is\_error\_code\_enum} after which the
    \texttt{error\_code(ErrorCodeEnum)} member template and the \texttt{make\_error\_code}
    function accept \texttt{CatErr} enumeration values. Interestingly, this
    requires us to add code to the \texttt{std} namespace. Normally this is not
    allowed, but in this case it is. The \textbf{C++} standard states:

\begin{quote}20.5.4.2.1 Namespace std

The behavior of a C++ program is undefined if it adds declarations or
        definitions to namespace std or to a namespace within namespace std
        unless otherwise specified.

A program may add a template specialization for any standard library
        template to namespace std only if the declaration depends on a
        user-defined type and the specialization meets the standard library
        requirements for the original template and is not explicitly
        prohibited.  
    \end{quote} 

Here is how the \texttt{is\_error\_code\_enum} trait class is specialized:
        \begin{verbatim}
    namespace std
    {
        template <>
        struct is_error_code_enum<CatErr>: public true_type
        {};
    }
\end{verbatim}
\end{itemize}

This completes the definition of our own error code enumeration, whose symbols
are now accepted by \texttt{error\_code's} constructor.

Before we're able to design our own error category we must also have a look at
`higher order' causes of errors as represented by objects of the class
\texttt{std::error\_condition} (cf. section \ref{ERRCOND}). Error conditions
represent platform independent errors like syntax errors or non-existing
requests.

In our bare bones implementation of an error category these higher order
causes of errors are enumerated in the \texttt{enum class Cond} enumeration. It's
defined similarly to \texttt{CatErr}.
   \begin{itemize}
   \item  Our first step consists of defining the enumeration. As with error
    code enums its symbols should not be given the value 0. Here is the
    enumeration \texttt{Cond} whose symbols presumably represent platform
    independent causes of errors: 
   \begin{verbatim}
    enum class Cond
    {
        NoCond = -1,
        Cond1 = 1,
        Cond2,
        Cond3,
    };
\end{verbatim}
\item  By itself, defining an \texttt{enum class} does not allow us to pass its
    values to \texttt{error\_condition} constructors. Before we can do that the
    \texttt{enum} must be `promoted' to an \index{error\_condition\_enum}\emph{error\_condition\_enum}. Also similar
    to \texttt{CatErr} this `promotion' is realized by specializing the trait class
    \index{is\_error\_condition\_enum}\texttt{std::is\_error\_condition\_enum}

Here is how the \texttt{is\_error\_condition\_enum} trait class is specialized:
        \begin{verbatim}
    namespace std
    {
        template <>
        struct is_error_condition_enum<Cond>: public true_type
        {};
    }
\end{verbatim}
\end{itemize}

We're now ready for designing our own \texttt{error\_category} class.

\subsection{Deriving classes from std::error\_category}\label{ERRCAT} 
    \typeout{Original Yodl file: advancedtemplates/errorcategory}In the previous section the error code enumerations \texttt{CatErr} and \texttt{Cond}
were developed.  The values of these enumerations specify, respectively, the
direct and the platform independent causes of errors that may be encountered
in the context of the new error category developed in this section.

Classes derived from \texttt{std::error\_category} are designed as singleton classes
and implement their own \texttt{name, message} and an \texttt{equivalent} members. Our
class \texttt{Category} also declares a static member \texttt{instance} returning a
reference to the class's singleton object, which is compile-time initialized
and is available by the time \texttt{instance} is called. Alternatively a dedicated
function (like \texttt{Category\_category}), analogously to the function
\texttt{generic\_category}, returning a reference to the \texttt{Category} object could
be defined.

\texttt{CatErr} values, \texttt{Cond} values and textual descriptions of \texttt{CatErr's}
values are combined in a \texttt{std::unordered\_map} using \texttt{CatErr} as key, and a
\texttt{struct POD} as value type. This map allows us to retrieve the platform
independent error types and the descriptions that are associated with
\texttt{CatErr} values.

Here is the interface of the class \texttt{Category}:
    \begin{verbatim}
    class Category: public std::error_category
    {
        static Category s_instance;
        struct POD
        {
            Cond        cond;
            char const *msg;
        };
    
        static std::unordered_map<CatErr, POD> s_map;
    
        public:
            Category(Category const &other) = delete;
    
            static Category &instance();
    
            bool equivalent(std::error_code const &ec, int condNr)
                                                const noexcept override;
            bool equivalent(int ev, std::error_condition const &condition)
                                                const noexcept override;
            std::error_condition default_error_condition(int ev)
                                                const noexcept override;
    
            std::string message(int ce) const override;
            char const *name() const noexcept override;
    
        private:
            Category() = default;
    
            template <typename Enum>
            static constexpr Enum as(int err);
    };
\end{verbatim}
Its \texttt{unordered\_map s\_map} provides the \texttt{Cond} values and verbal
descriptions of the \texttt{CatErr} values given those \texttt{CatErr} values:
    \begin{verbatim}
    unordered_map<CatErr, Category::POD> Category::s_map =
    {
        { CatErr::Err1, { Cond::Cond1, "Err1" } },
        { CatErr::Err2, { Cond::Cond2, "Err2" } },
        { CatErr::Err3, { Cond::Cond1, "Err3" } },
    };
\end{verbatim}
The functions \texttt{make\_error\_code} and \texttt{make\_error\_condition} return,
respectively, \texttt{error\_code} and \texttt{error\_condition} objects from,
respectively, \texttt{CatErr} values and \texttt{Cond} values.

Their declarations can be provided below the \texttt{Category} class interface and
their implementations pass the \texttt{Category} object to their constructors:
    \begin{verbatim}
    std::error_code make_error_code(CatErr ce)
    {
        return { static_cast<int>(ce), Category::instance() };
    }
\end{verbatim}
\begin{verbatim}
    std::error_condition make_error_condition(Cond ec)
    {
        return { static_cast<int>(ec), Category::instance() };
    }
\end{verbatim}
The member \texttt{name} \emph{must} be defined by classes derived from
\texttt{error\_category}. It simply returns a short string naming the category
(e.g., \texttt{"Category"} for our \texttt{Category} class). Likewise, the member
\texttt{message} \emph{must} be redefined. Its implementation usually is slightly more
complex than \texttt{name's} implementation: it expects a (cast to an \texttt{int})
\texttt{CatErr} value and uses that value to find the corresponding textual
description in \texttt{s\_map}. If found the description is returned; if not found
then a short fallback message is returned:
    \begin{verbatim}
    std::string Category::message(int ce) const
    {
        auto iter = s_map.find(static_cast<CatErr>(ce));
        return iter != s_map.end() ? iter->second.msg : "No CatErr value";
    }
\end{verbatim}
The member \texttt{default\_error\_condition} receives a (cast to \texttt{int}) \texttt{CatErr}
value. That value is used to find the associated \texttt{Cond} value. If the
\texttt{int} received by the function does not represent a valid \texttt{CatErr} value
then the fallback value \texttt{Cond::NoCond} is used.  The function returns an
\texttt{error\_condition} object created by \texttt{make\_error\_condition} which receives
the determined \texttt{Cond} value as its argument:
    \begin{verbatim}
    std::error_condition Category::default_error_condition(int ev)
                                                            const noexcept
    {
        auto iter = s_map.find(as<CatErr>(ev));
    
        return make_error_condition(
                    iter == s_map.end() ? Cond::NoCond : iter->second.cond
                );
    }
\end{verbatim}
What's left is implementing the two \texttt{equivalent} members. The first
\texttt{equivalent} member (receiving a reference to an \texttt{error\_code} object and a
(cast to \texttt{int}) \texttt{Cond} value) determines the equivalence of
    the \texttt{Cond} value that is associated with the \texttt{error\_code} object
and 
    the \texttt{Cond} value that is specified as the function's second argument.
 If these values are equal and the \texttt{error\_code} object's category is equal
to \texttt{Category} then the equivalence has been established and \texttt{true} is
returned.  Here is its implementation:
    \begin{verbatim}
    bool Category::equivalent(std::error_code const &ec, int condNr)
                                                            const noexcept
    {
        if (*this != ec.category())
            return false;
    
        if (ec.value() == 0)                            // no error in ec?
            return condNr == 0;                         // then condNr must
                                                        // also be 0
    
        auto iter = s_map.find(as<CatErr>(ec.value())); // info associated
                                                        // with ec's CatErr
    
        return iter == s_map.end() ?
                            false                       // not found or
                        :                               // compare Cond values
                            iter->second.cond == as<Cond>(condNr);
    }
\end{verbatim}
The second \texttt{equivalent} member (receiving (as an \texttt{int}) \texttt{CatErr} value 
and an \texttt{error\_condition} object) determines the equivalence of an
    \texttt{error\_condition} object that is constructed from the \texttt{Cond} value
    that is associated with the \texttt{CatErr} value that was passed (as \texttt{int})
    to the function
and 
    the \texttt{error\_condition} object that was passed to the function as its
    second argument.

Here a prerequisite for concluding equivalence is that the error condition's
category is \texttt{Category}. If that's the case then the function returns
\texttt{true} if its \texttt{int} argument equals zero and the \texttt{condition} object also
indicates no error. Alternatively, if the \texttt{condition} argument is equal to
the \texttt{error\_condition} object made from the \texttt{Cond} value associated with
the \texttt{CatErr} value passed to the function as its first argument the
equivalence has also been established and \texttt{true} is returned.  Here is its
implementation:
    \begin{verbatim}
    bool Category::equivalent(int ev, error_condition const &condition)
                                                            const noexcept
    {
        if (ev == 0)                                    // no error? then
            return condition.category() == *this and    // categories must
                   not static_cast<bool>(condition);    // be equal and
                                                        // condition must
                                                        // indicate no error
    
        auto iter = s_map.find(as<CatErr>(ev));     // find ev's Cond
    
        return iter == s_map.end()?
                    false                           // no such CatErr
                :                                   // or compare conditions
                    condition == make_error_condition(iter->second.cond);
    }
\end{verbatim}
So, in order to define your own category:
    \begin{itemize}
    \item  define an enumeration which is `promoted' to an \texttt{error\_code\_enum};
    \item  define an enumeration which is promoted to an
        \texttt{error\_condition\_enum}; 
    \item  define a new \texttt{error\_category} class by deriving a class from
        \texttt{std::error\_category}, define it as a singleton class and override
        its \texttt{default\_error\_condition, equivalent, message,} and \texttt{name}
        members. 
    \end{itemize}

\section{Using `noexcept' when offering the `strong guarantee'}\label{NOEXCEPT}
\typeout{Original Yodl file: advancedtemplates/noexcept}When throwing exceptions while trying to achieve the strong guarantee a
function's actions are usually split in two parts
    \begin{itemize}
    \item  First, usually on a temporary object, all operations that may throw
are performed (which doesn't affect the target object)
    \item  Then, the target object is modified using operations that offer the
\emph{nothrow} guarantee.
    \end{itemize}

The actions in the first step might be made \emph{move aware} by using
\texttt{std::move} (e.g., to assign the source's values to a (possibly temporary)
destination). However, using \texttt{std::move} can easily affect the source (e.g.,
when extending the source's memory, moving the existing data to its new
locations), which breaks the first step's assumption, as the target object is
now modified. 

In this case (and generally) the move operation should not be allowed to throw
exceptions. This, in turn, implies that it is difficult to write code which
must offer a non-throwing moving constructor, if it uses (external) 
data types over which the moving constructor has no control. E.g.,
        \begin{verbatim}
    template <typename Type>
    class MyClass
    {
        Type d_f;
        public:
            MyClass() = default;
            MyClass(MyClass &&tmp)
            :
                d_f(move(tmp.d_f))
            {}
    };
\end{verbatim}
Here, \texttt{MyClass}'s author has no control over the design of \texttt{Type}. If
\texttt{MyClass} is instantiated with the type \texttt{Foreign}, merely having a
(possibly throwing) copy constructor, then the following code breaks the
no-throw assumption underlying move constructors:
        \begin{verbatim}
    MyClass<Foreign> s2{ move(MyClass<Foreign>()) };
\end{verbatim}
If templates are able to detect whether \texttt{Type} has non-throwing move
constructors then their implementations may be optimized by
calling these move constructors (already modifying their targets in the first
part of code offering the strong guarantee) in situations where otherwise the
non-modifying, but more expensive copy constructor has to be used.

The \index{noexcept}\texttt{noexcept} keyword was introduced to allow such templates to perform
such optimizations. As with \texttt{throw} lists, checking for \texttt{noexcept} is
a run-time check, but the consequence of violating a \texttt{noexept} declaration
are more serious than violating a \texttt{throw} list: violating \texttt{noexcept}
results in calling \texttt{std::terminate}, terminating the program, possibly
without unwinding the stack. In the context of the previous example, the
following code is flawlessly accepted by the compiler, demonstrating that
there is no compile-time checking of \texttt{noexcept}:
        \begin{verbatim}
    class Foreign
    {
        public:
            Foreign() = default;
            Foreign(Foreign const &other) noexcept
            {
                throw 1;
            }
    };
\end{verbatim}
However, when this class's copy constructor is called, execution aborts
with the following message:
        \begin{verbatim}
    terminate called after throwing an instance of 'int'
    Abort
\end{verbatim}
Keep in mind that the current purpose of \texttt{noexcept} is to allow templates to
optimize their code by using move operations where the code must also be able
to offer the strong exception guarantee. Since \texttt{noexcept} also offers the
conditional \texttt{noexcept(condition)} syntax (with \texttt{noexcept(true)} and
\texttt{noexcept} having identical semantics), \texttt{noexcept} can be made
conditional to the `noexcepting' nature of template types. Note that this is
not possible with \texttt{throw} lists. 

The following \index{rule of thumb} rules of thumb may be used to decide whether
or not to use \texttt{noexcept} in your code:
    \begin{itemize}
    \item  General rule: don't use \texttt{noexcept} (this is identical to the advise
        given for \texttt{throw} lists);
    \item  Default implementations of constructors, copy- and move-assignment
        operators and destructors are provided with \texttt{noexcept(true)} if the
        compiler can deduce that composing types also offer
        \texttt{noexcept(true)}, allowing template optimizations using move
        operations where possible.
    \item  Functions provided with \texttt{noexcept} declarations may \emph{still} throw
        exceptions (see the example given above). In the end \texttt{noexcept}
        merely means that if such a function throws an exception
        \texttt{std::terminate} rather than \texttt{std::unexpected} is called. 
    \item  Functions previously provided with an empty throw list (\texttt{throw()})
        should be provided with \texttt{noexcept}.
    \item  \texttt{noexcept} specifications are required when using the following std
        traits (declared in the \index{type\_traits: header file}\texttt{$<$type\_traits$>$} header file):
        \begin{itemize}
        \item \index{is\_nothrow\_constructible}\texttt{is\_nothrow\_constructible}
        \item \index{is\_nothrow\_default\_constructible}\texttt{is\_nothrow\_default\_constructible}
        \item \index{is\_nothrow\_move\_constructible}\texttt{is\_nothrow\_move\_constructible}
        \item \index{is\_nothrow\_copy\_constructible}\texttt{is\_nothrow\_copy\_constructible}
        \item \index{is\_nothrow\_assignable}\texttt{is\_nothrow\_assignable}
        \item \index{is\_nothrow\_move\_assignable}\texttt{is\_nothrow\_move\_assignable}
        \item \index{is\_nothrow\_copy\_assignable}\texttt{is\_nothrow\_copy\_assignable}
        \item \index{is\_nothrow\_destructible}\texttt{is\_nothrow\_destructible}
        \end{itemize}
        These type traits provide the member constant \texttt{value} which is
        \texttt{true} if the class (and possibly its argument type list) matches
        the characteristic after which the trait was named. E.g., if
        \texttt{MyClass(string const \&) noexcept} is a constructor, then
        \begin{verbatim}
    std::is_nothrow_constructible<MyClass, string>::value
\end{verbatim}
equals \texttt{true}. For the named members (like
        \texttt{is\_nothrow\_move\_constructible}) parameter types do not have to be
        specified, as they are implied. E.g.,
        \begin{verbatim}
    std::is_nothrow_move_constructible<MyClass>::value
\end{verbatim}
returns \texttt{true} if the move constructor has the \texttt{noexcept}
        modifier. 
    \end{itemize}

\section{More conversions to class types}

\subsection{Types to types}
    \typeout{Original Yodl file: advancedtemplates/typetype}Although \emph{class} templates may be partially specialized, \emph{function}
templates may not. At times this is annoying. Assume a function template is
available implementing a certain unary operator that could be used with the
\texttt{transform} generic algorithm (cf. section \ref{TRANSFORM}):
        \begin{verbatim}
    template <typename Return, typename Argument>
    Return chop(Argument const &arg)
    {
        return Return{ arg };
    }
\end{verbatim}
Furthermore assume that if \texttt{Return} is \texttt{std::string} then the above
implementation should not be used. Instead, with \texttt{std::string} a second
argument \texttt{1} should always be provided. If \texttt{Argument} is a \textbf{C++} string,
this would allow us to, e.g., return a copy of \texttt{arg} from which its first
character has been chopped off.

Since \texttt{chop} is a function, it is not possible to define a partial
specialization like this:
        \begin{verbatim}
    template <typename Argument>        // This won't compile!
    std::string chop<std::string, Argument>(Argument const &arg)
    {
        return std::string{ arg, 1 };
    }
\end{verbatim}
Although a function template cannot be partially specialized it \emph{is}
possible to use overloading, defining a second,  dummy, \texttt{string} parameter:
        \begin{verbatim}
    template <typename Argument>
    std::string chop(Argument const &arg, std::string)
    {
        return std::string{ arg, 1 };
    }
\end{verbatim}
Instead of providing a \texttt{string} dummy argument the functions \emph{could}
use the \texttt{IntType} template (cf. section \ref{INTTYPE}) to select the proper
overloaded version. E.g., \texttt{IntType$<$0$>$} could be defined as the type of the
second argument of the first overloaded \texttt{chop} function, and \texttt{IntType$<$1$>$}
could be used for the second overloaded function. From the point of view of
program efficiency this is an attractive option, as the provided \texttt{IntType}
objects are extremely lightweight. \texttt{IntType} objects contain no data at
all. But there's also an obvious disadvantage as there is no intuitively clear
association between the \texttt{int} value used and the intended type.

Instead of defining arbitrary \texttt{IntType} types it is more attractive to
use another lightweight solution, using an automatic type-to-type
association. The \texttt{struct TypeType} is a lightweight type wrapper, much like
\texttt{IntType}. Here is its definition:
        \begin{verbatim}
    template <typename T>
    struct TypeType
    {
        using Type = T;
    };
\end{verbatim}
\texttt{TypeType} is also a lightweight type as it doesn't have any data fields
either. \texttt{TypeType} allows us to use a natural type association for
\texttt{chop}'s second argument. E.g, the overloaded functions can now be defined
as follows:
        \begin{verbatim}
    template <typename Return, typename Argument>
    Return chop(Argument const &arg, TypeType<Argument> )
    {
        return Return{ arg };
    }

    template <typename Argument>
    std::string chop(Argument const &arg, TypeType<std::string> )
    {
        return std::string{ arg, 1 };
    }
\end{verbatim}
Using the above implementations any type can be specified for
\texttt{Result}. If it happens to be a \texttt{std::string} the appropriate overloaded
version is automatically selected. The following additional overload of the
function \texttt{chop} capitalizes on this:
        \begin{verbatim}
    template <typename Result>
    Result chop(char const *txt)    // char const * could also be a 2nd
    {                               // template type parameter
        return chop(std::string{ txt }, TypeType<Result>{});
    }
\end{verbatim}
Using the third \texttt{chop} function, the following statement produces the
text `\texttt{ello world}':
        \begin{verbatim}
    cout << chop<string>{ "hello world" } << '\n';
\end{verbatim}
Template functions do not support partial specializations. But they can be
overloaded. By providing overloads with dummy type-arguments that depend
on other parameters and calling these overloads from a overloaded function
that does not require the dummy type argument a situation similar to partial
specializations with class templates can often be realized.

\subsection{An empty type}\label{NULLTYPE}
    \typeout{Original Yodl file: advancedtemplates/nulltype}At times (cf. section \ref{TEMPLIST}) an empty
        \index{empty struct}\index{struct: empty}\index{NullType}
    \texttt{struct} is a useful tool. It can be used as a \emph{type} acting
analogously to the final 0-byte in NTBSs.
It can simply be defined as:
        \begin{verbatim}
    struct NullType
    {};
\end{verbatim}
\subsection{Type convertibility}\label{TYPECONV}
    \typeout{Original Yodl file: advancedtemplates/conversion}In what situations can a type \texttt{T} be used as a `stand in' for another type
\texttt{U}? Since \textbf{C++} is a strongly typed language the answer is surprisingly
simple: \texttt{T}s can be used instead of \texttt{U}s if a \texttt{T} is accepted as
argument in cases where \texttt{U}s are requested.

This reasoning is behind the following class which can be used to determine
whether a type \texttt{T} can be used where a type \texttt{U} is expected. The
interesting part is that no code is actually generated or executed.  All
decisions are made by the compiler.

In the second part of this section we'll show how the code developed in
the first part can be used to detect whether a class \texttt{B} is a base class of
another class \texttt{D} (the \texttt{is\_base\_of} template (cf. section \ref{TYPETRAITS})
also provides an answer to this question). The code developed here closely
follows the example provided by Alexandrescu \index{Alexandrescu, A.} (2001,
p. 35).

First, a function \texttt{test} is designed accepting a type \texttt{U}.
The function \texttt{test} returns a value
of the as yet unknown type \texttt{Convertible}:
        \begin{verbatim}
    Convertible test(U const &);
\end{verbatim}
The function \texttt{test} is never implemented. It is only declared.  If a type
\texttt{T} can be used instead of a type \texttt{U} then \texttt{T} can also be passed as
argument to the above \texttt{test} function.

On the other hand, if the alternate type \texttt{T} cannot be used where a \texttt{U} is
expected, then the compiler won't be able to use the above \texttt{test}
function. Instead, it uses an alternative function that has a lower
selection priority but that can \emph{always} be used with \emph{any} \texttt{T} type.

\textbf{C} (and \textbf{C++}) offer a very general parameter list, a parameter list that
is always considered acceptable. This parameter list is the familiar
  \index{ellipsis}\emph{ellipsis} which represents the \emph{worst} case the compiler may
encounter.  If everything else fails, then the function defining an ellipsis
as its parameter list is selected.

Usually that's not a productive alternative, but in the current situation it
is \emph{exactly} what is needed. When confronted with two candidate functions,
one of which defines an ellipsis parameter, the compiler selects the
function defining the ellipsis parameter only if the alternative(s) can't be
used.

Following the above reasoning an alternative function \texttt{test(...)} is
declared as well. This alternate function does not return a \texttt{Convertible}
value but a \texttt{NotConvertible} value:
        \begin{verbatim}
    NotConvertible test(...);
\end{verbatim}
If \texttt{test}'s argument is of type \texttt{T} and if \texttt{T} can be converted to \texttt{U}
then \texttt{test}'s return type is \texttt{Convertible}.  Otherwise \texttt{NotConvertible}
is returned.

This situation clearly shows similarities with the situation encountered in
section \ref{CLASSORNOT} where the value \texttt{isClass} had to be determined
compile time. Here two related problems must be solved:
    \begin{itemize}
    \item  how do we obtain a \texttt{T} argument? This is more difficult than might
be expected at first sight as it might not be possible to define a \texttt{T}. If
type \texttt{T} does not define any constructor then no \texttt{T} object can be
defined.
    \item  how can \texttt{Convertible} be distinguished from \texttt{NotConvertible}?
    \end{itemize}
    The first problem is solved by realizing that no \texttt{T} \emph{needs} to be
defined. After all, the intent is to decide \emph{compile-time} whether a type is
convertible and not to define a \texttt{T} value or object. Defining objects is not
a compile-time but a \emph{run-time} matter.

By simply \emph{declaring} a function returning a \texttt{T} we can
tell the compiler where it should assume a \texttt{T}:
        \begin{verbatim}
    T makeT();
\end{verbatim}
This mysterious function has the magical power of enticing the compiler
into thinking that a \texttt{T} object comes out of it. However, this function
needs a small modification before it will actually suit our needs. If, for
whatever reason, \texttt{T} happens to be an array then the compiler will choke on
\texttt{T makeT()} as functions cannot return arrays. This, however, is easily
solved, as functions \emph{can} return \emph{references} to arrays. So the above
declaration is changed into:
        \begin{verbatim}
    T const &makeT();
\end{verbatim}
Next we pass a \texttt{T const \&} to \texttt{test}:
following code:
        \begin{verbatim}
    test(makeT())
\end{verbatim}
Now that the compiler sees \texttt{test} being called with a \texttt{T const \&}
argument it decides that its return value is \texttt{Convertible} if a
conversion is in fact possible. Otherwise it decides that its return value
is \texttt{NotConvertible} (as the compiler, in that case, selected \texttt{test(...)}).

The second problem, distinguishing \texttt{Convertible} from \texttt{NotConvertible}
is solved exactly the way \texttt{isClass} could be determined in section
\ref{CLASSORNOT}, \emph{viz.} by making their sizes different. Having done so the
following expression determines whether \texttt{T} is convertible from \texttt{U} or
not:
        \begin{verbatim}
    isConvertible = sizeof(test(makeT())) == sizeof(Convertible);
\end{verbatim}
By using \texttt{char} for \texttt{Convertible} and \texttt{Char2} (cf. section
\ref{CLASSORNOT}) for \texttt{NotConvertible} the distinction can be made.

The above can be summarized in a class template \texttt{LconvertibleToR},
having two template type parameters:
        \begin{verbatim}
    template <typename T, typename U>
    class LconvertibleToR
    {
        struct Char2
        {
            char array[2];
        };
        static T const &makeT();
        static char test(U const &);
        static Char2 test(...);

        public:
            LconvertibleToR(LconvertibleToR const &other) = delete;
            enum { yes = sizeof(test(makeT())) == sizeof(char) };
            enum { sameType = 0 };
    };

    template <typename T>
    class LconvertibleToR<T, T>
    {
        public:
            LconvertibleToR(LconvertibleToR const &other) = delete;
            enum { yes = 1 };
            enum { sameType = 1 };
    };
\end{verbatim}
    As the class template deletes its copy constructor no object can be
created. Only its \texttt{enum} values can be interrogated. The next example writes
\texttt{1 0 1 0} when run from a \texttt{main} function:
        \begin{verbatim}
    cout <<
        LconvertibleToR<ofstream, ostream>::yes << " " <<
        LconvertibleToR<ostream, ofstream>::yes << " " <<
        LconvertibleToR<int, double>::yes << " " <<
        LconvertibleToR<int, string>::yes <<
        "\n";
\end{verbatim}
\subsubsection{Determining inheritance}
        \typeout{Original Yodl file: advancedtemplates/inheritance}Now that it is possible to determine type convertibility, it's easy to
determine whether a type \texttt{Base} is a (public) base class of a type
\texttt{Derived}.

Inheritance is determined by inspecting convertibility of (const)
pointers. \texttt{Derived const $*$} can be converted to \texttt{Base const $*$} if
    \begin{itemize}
    \item  both types are identical;
    \item  \texttt{Base} is a public and unambiguous base class of \texttt{Derived};
    \item  and (usually not intended) if \texttt{Base} is void.
    \end{itemize}
    Assuming the last conversion isn't used inheritance can be determined
using the following trait class \texttt{LBaseRDerived}. \texttt{LBaseRDerived} provides
an enum \texttt{yes} which is 1 if the left type is a base class of the right type
and both types are different:
    \begin{verbatim}
    template <typename Base, typename Derived>
    struct LBaseRDerived
    {
        LBaseRDerived(LBaseRDerived const &) = delete;
        enum {
            yes =
                LconvertibleToR<Derived const *, Base const *>::yes &&
                not LconvertibleToR<Base const *, void const *>::sameType
        };
    };
\end{verbatim}
If code should not consider a class to be its own base class, then the
trait class \texttt{LBaseRtrulyDerived} can be used to perform a  strict test. This
trait class adds a test for type-equality:
    \begin{verbatim}
    template <typename Base, typename Derived>
    struct LBaseRtrulyDerived
    {
        LBaseRtrulyDerived(LBaseRtrulyDerived const &) = delete;
        enum {
            yes =
                LBaseRDerived<Base, Derived>::yes &&
                not LconvertibleToR<Base const *, Derived const *>::sameType
        };
    };
\end{verbatim}
    Example: the next statement displays \texttt{1: 0, 2: 1, 3: 0, 4: 1, 5: 0}
when executed from a \texttt{main} function:
    \begin{verbatim}
    cout << "\n" <<
        "1: " << LBaseRDerived<ofstream, ostream>::yes << ",  " <<
        "2: " << LBaseRDerived<ostream, ofstream>::yes << ",  " <<
        "3: " << LBaseRDerived<void, ofstream>::yes << ",  " <<
        "4: " << LBaseRDerived<ostream, ostream>::yes << ",  " <<
        "5: " << LBaseRtrulyDerived<ostream, ostream>::yes <<
        "\n";
\end{verbatim}
\section{Template TypeList processing}\label{TEMPLIST}
    \typeout{Original Yodl file: advancedtemplates/listintro}This section serves two purposes. It illustrates capabilities of the various
template meta-programming techniques, which can be used as a source of
inspiration when developing your own templates; and it offers a concrete
example, illustrating some of the power offered by these techniques.

This section itself was inspired by Andrei Alexandrescu's (2001) book
        \index{Alexandrescu, A.}
    \textbf{Modern C++ design}. It diverts from Alexandrescu's book in its use of
variadic templates which were not yet available when he wrote his book. Even
so, the algorithms used by Alexandrescu are still useful when using variadic
templates.

\textbf{C++} offers the tuple to store and retrieve
values of multiple types. Here the focus is merely on processing types.  A
simple struct \texttt{TypeList} is going to be used as our working horse for the
upcoming subsections. Here is its definition:
        \begin{verbatim}
    template <typename ...Types>
    struct TypeList
    {
        TypeList(TypeList const &) = delete;
        enum { size = sizeof ...(Types) };
    };
\end{verbatim}
    A typelist allows us to store any number of types. Here is an example
storing the three types \texttt{char, short, int} in a \texttt{TypeList}:
        \begin{verbatim}
    TypeList<char, short, int>
\end{verbatim}
\subsection{The length of a TypeList}
    \typeout{Original Yodl file: advancedtemplates/length}As the number of types in a parameter pack may be obtained using the \texttt{sizeof}
operator (cf. section \ref{VARIADIC}) it is easy to obtain the number of types
that were specified with a certain \texttt{TypeList}. For example, the following
statement displays the value 3:
        \begin{verbatim}
    std::cout << TypeList<int, char, bool>::size << '\n';
\end{verbatim}
However, it's illustrative to see how the number of types specified with a
\texttt{TypeList} could be determined if \texttt{sizeof} hadn't been available.

To obtain the number of types that were specified with a \texttt{TypeList}
the following algorithm is used:
    \begin{itemize}
    \item  If the \texttt{TypeList} contains no types, its size equals zero;
    \item  If the \texttt{TypeList} contains types, its size equals 1 plus the number
        of types that follow its  first type.
    \end{itemize}
    The algorithm uses recursion to define the length of a \texttt{TypeList}. In
executable \textbf{C++} recursion could also be used in comparable situations. For
example recursion can be used to determine the length of an NTBS:
        \begin{verbatim}
    size_t c_length(char const *cp)
    {
        return *cp == 0 ? 0 : 1 + c_length(cp + 1);
    }
\end{verbatim}
While \textbf{C++} functions usually use iteration rather than recursion,
iteration is not available to template meta programming algorithms. In
template meta programming repetition \emph{must} be implemented using
recursion. Furthermore, while \textbf{C++} run-time code may use conditions to
decide whether or not to start the next recursion template meta programming
cannot do so. Template meta programming algorithms must resort to (partial)
specializations. The specializations are used to select alternatives.

The number of types that are specified in a \texttt{TypeList} can be computed
using the following alternate implementation of \texttt{TypeList}, using a generic
\texttt{struct} declaration and two specialization for the empty and non-empty
\texttt{TypeList} (cf. the above description of the algorithm):
        \begin{verbatim}
    template <typename ...Types>
    struct TypeList;

    template <typename Head, typename ...Tail>
    struct TypeList<Head, Tail...>
    {
        enum { size = 1 + TypeList<Tail...>::size };
    };
    template <>
    struct TypeList<>
    {
        enum { size = 0 };
    };
\end{verbatim}
\subsection{Searching a TypeList}\label{SEARCHTYPE}
    \typeout{Original Yodl file: advancedtemplates/search}To determine whether a particular type (called \emph{SearchType} below) is
present in a given \texttt{TypeList}, an algorithm is used that either defines
`index' as -1 (if SearchType is not an element of the \texttt{TypeList} ) or it
defines `index' as the index of the first occurrence of SearchType in
the \texttt{TypeList}. The following algorithm is used:
    \begin{itemize}
    \item  If the \texttt{TypeList} is empty, `index' is -1;
    \item  If the \texttt{TypeList}'s first element equals   SearchType, `index' is 0;
    \item  Otherwise  `index' is:
        \begin{itemize}
        \item  -1 if searching for SearchType in \texttt{TypeList}'s tail results in
            `index' == -1;
        \item  Otherwise (SearchType was found in \texttt{TypeList}'s tail) index is
            set to 1 + the index obtained when searching for SearchType in the
            \texttt{TypeList}'s tail.
        \end{itemize}
    \end{itemize}
    The algorithm is implemented using a variadic template struct
\texttt{ListSearch} expecting a parameter pack:
        \begin{verbatim}
    template <typename ...Types>
    struct ListSearch
    {
        ListSearch(ListSearch const &) = delete;
    };
\end{verbatim}
    Specializations handle the alternatives mentioned with the algorithm:
    \begin{itemize}
    \item  If \texttt{TypeList} is empty, `index' is -1:
        \begin{verbatim}
    template <typename SearchType>
    struct ListSearch<SearchType, TypeList<>>
    {
        ListSearch(ListSearch const &) = delete;
        enum { index = -1 };
    };
\end{verbatim}
\item  If \texttt{TypeList}'s head  equals SearchType, `index'
        is 0. Note that \texttt{SearchType} is explicitly mentioned as the
            \texttt{TypeList}'s first element:
        \begin{verbatim}
    template <typename SearchType, typename ...Tail>
    struct ListSearch<SearchType, TypeList<SearchType, Tail...>>
    {
        ListSearch(ListSearch const &) = delete;
        enum { index = 0 };
    };
\end{verbatim}
\item  Otherwise a search is performed on the \texttt{TypeList}'s tail. The index
            value returned by this search is stored in a \texttt{tmp} enum value,
            which is then used to determine index's value.
        \begin{verbatim}
    template <typename SearchType, typename Head, typename ...Tail>
    struct ListSearch<SearchType, TypeList<Head, Tail...> >
    {
        ListSearch(ListSearch const &) = delete;
        enum {tmp = ListSearch<SearchType, TypeList<Tail...>>::index};
        enum {index = tmp == -1 ? -1 : 1 + tmp};
    };
\end{verbatim}
    \end{itemize}
    Here is an example showing  how \texttt{ListSearch} can be used:
        \begin{verbatim}
    std::cout <<
        ListSearch<char, TypeList<int, char, bool>>::index << "\n" <<
        ListSearch<float, TypeList<int, char, bool>>::index << "\n";
\end{verbatim}
\subsection{Selecting from a TypeList}\label{ATINDEX}
    \typeout{Original Yodl file: advancedtemplates/select}The inverse operation of determining the index of a certain type in a
\texttt{TypeList} is retrieving the type given its index. This inverse operation is
the topic of this section.

The algorithm is implemented using a struct \texttt{TypeAt}. \texttt{TypeAt} specifies a
using-declaration to define the type matching a given index. But the index
might be out of bounds. In that case we have several options:
    \begin{itemize}
    \item  Use a static\_assert to stop the compilation. This
is an appropriate action if the index should simply not be out of bounds;
    \item  Define a local type (e.g., \texttt{Null}) that should not be used as a
type in the \texttt{TypeList}. This type is going to be returned when the index is
out of bounds. Using this local type as one of the types in a \texttt{TypeList} is
considered an error as its would conflict with the special meaning of \texttt{Null}
as the type returned at an invalid index.\ \\ 
    To prevent \texttt{Null} from being returned by \texttt{TypeAt} a \texttt{static\_assert}
is used to catch the \texttt{Null} type when it is encountered while evaluating
\texttt{TypeAt};
    \item  The struct \texttt{TypeAt} may define an enum value \texttt{validIndex} set to
\texttt{true} if the index was valid and set to \texttt{false} if not.
    \end{itemize}
    The first alternative is implemented below. The other alternatives are not
difficult to implement and are left as exercises for the reader. Here's how
\texttt{TypeAt} works:
    \begin{itemize}
    \item  The foundation consists of a variadic template struct \texttt{TypeAt},
        expecting an index and a \texttt{TypeList}:
            \begin{verbatim}
    template <size_t index, typename Typelist>
    struct TypeAt;
\end{verbatim}
\item  If the typelist is empty a \texttt{static\_assert} ends the compilation
            \begin{verbatim}
    template <size_t index>
    struct TypeAt<index, TypeList<>>
    {
        static_assert(index < 0, "TypeAt index out of bounds");
        using Type = TypeAt;
    };
\end{verbatim}
\item  If the search index equals 0, define \texttt{Type} as the first type in
        the \texttt{TypeList}:
            \begin{verbatim}
    template <typename Head, typename ...Tail>
    struct TypeAt<0, TypeList<Head, Tail...>>
    {
        using Type = Head;
    };
\end{verbatim}
\item  Otherwise, \texttt{Type} is defined as \texttt{Type} defined by \texttt{TypeAt$<$index
        - 1$>$} operating on the \texttt{TypeList}'s tail:
            \begin{verbatim}
    template <size_t index, typename Head, typename ...Tail>
    struct TypeAt<index, TypeList<Head, Tail...>>
    {
        using Type = typename TypeAt<index - 1, TypeList<Tail...>>::Type;
    };
\end{verbatim}
    \end{itemize}
    Here is how \texttt{typeAt} can be used. Uncommenting the first variable
definition causes a \texttt{TypeAt index out of bounds} compilation error:
        \begin{verbatim}
    using list3 = TypeList<int, char, bool>;

//    TypeAt<3, list3>::Type invalid;
    TypeAt<0, list3>::Type intVariable = 13;
    TypeAt<2, list3>::Type boolVariable = true;

    cout << "The size of the first type is " <<
                sizeof(TypeAt<0, list3>::Type) << ", "
            "the size of the third type is " <<
                sizeof(TypeAt<2, list3>::Type) << "\n";

    if (typeid(TypeAt<1, list3>::Type) == typeid(char))
        cout << "The typelist's 2nd type is char\n";

    if (typeid(TypeAt<2, list3>::Type) != typeid(char))
        cout << "The typelist's 3nd type is not char\n";
\end{verbatim}
\subsection{Prefixing/Appending to a TypeList}
    \typeout{Original Yodl file: advancedtemplates/append}Prepending or appending a type to a \texttt{TypeList} is easy and doesn't require
recursive template meta programs. Two variadic template structs \texttt{Append} and
\texttt{Prefix} and two specializations are all it takes.

Here are the declarations of the two variadic template structs:
            \begin{verbatim}
    template <typename ...Types>
    struct Append;

    template <typename ...Types>
    struct Prefix;
\end{verbatim}
To append or prefix a new type to a typelist, specializations expect a
typelist and a type to add. Then, they simply define a new \texttt{TypeList} also
including the new type. The \texttt{Append} specialization shows that a template
pack does not have to be used as the first argument when defining another
variadic template type:
        \begin{verbatim}
    template <typename NewType, typename ...Types>
    struct Append<TypeList<Types...>, NewType>
    {
        using List = TypeList<Types..., NewType>;
    };

    template <typename NewType, typename ...Types>
    struct Prefix<NewType, TypeList<Types...>>
    {
        using List = TypeList<NewType, Types...>;
    };
\end{verbatim}
\subsection{Erasing from a TypeList}
    \typeout{Original Yodl file: advancedtemplates/erase}It is also possible to erase types from a \texttt{TypeList}. Again, there are
several possibilities, each resulting in a different algorithm.
    \begin{itemize}
    \item  The type to erase is specified, and the first
occurrence of that type is removed from the \texttt{TypeList};
    \item  The index of the type to erase is specified, and the type at that
index position  is erased from the \texttt{TypeList};
    \item  The type to erase is specified, and all
occurrences of that type are removed from the \texttt{TypeList}.
    \item  As a variant of erasure: we may want to erase all multiply
occurring types in a \texttt{TypeList}, keeping each type only once.
    \end{itemize}
    Doubtlessly there are other ways of erasing types from a
\texttt{TypeList}. Which ones are eventually  implemented depends of course on
the circumstances. As template meta programming is very powerful most if not
all algorithms can probably be implemented. As an illustration of how to erase
types from a \texttt{TypeList} the above-mentioned algorithms are now developed in
the upcoming subsections.

\subsubsection{Erasing the first occurrence}
        \typeout{Original Yodl file: advancedtemplates/erasefirst}To erase the first occurrence of a specified \texttt{EraseType} from a \texttt{TypeList}
a recursive algorithm is used once again. The template meta program uses a
generic \texttt{Erase} struct and several specializations. The specializations
define a type \texttt{List} containing the resulting \texttt{TypeList} after the
erasure. Here is the algorithm:
    \begin{itemize}
    \item  The foundation of the algorithm consists of a struct template
\texttt{Erase} expecting the type to erase and a \texttt{TypeList}:
            \begin{verbatim}
    template <typename EraseType, typename TypeList>
    struct Erase;
\end{verbatim}
    \item  If the typelist is empty, there's nothing to erase, and an empty
        \texttt{TypeList} results:
            \begin{verbatim}
    template <typename EraseType>
    struct Erase<EraseType, TypeList<>>
    {
        using List = TypeList<>;
    };
\end{verbatim}
    \item  If the \texttt{TypeList}'s head matches the type to erase, then \texttt{List}
        becomes a \texttt{TypeList} containing the original \texttt{TypeList}'s tail
        types:
            \begin{verbatim}
    template <typename EraseType, typename ...Tail>
    struct Erase<EraseType, TypeList<EraseType, Tail...>>
    {
        using List = TypeList<Tail...>;
    };
\end{verbatim}
    \item  In all other cases the erase operation is applied to the
        \texttt{TypeList}'s tail. This results in a \texttt{TypeList} to which the
        orginal \texttt{TypeList}'s head must be prefixed. The \texttt{TypeList}
        returned by the prefix operation is then returned as \texttt{Erase::List}:
            \begin{verbatim}
    template <typename EraseType, typename Head, typename ...Tail>
    struct Erase<EraseType, TypeList<Head, Tail...>>
    {
        using List =  typename
            Prefix<Head,
                typename Erase<EraseType, TypeList<Tail...>>::List
            >::List;
    };
\end{verbatim}
    \end{itemize}
    Here is a statement showing how \texttt{Erase} can be used:
            \begin{verbatim}
    cout <<
            Erase<int, TypeList<char, double, int>>::List::size << '\n' <<
            Erase<char, TypeList<int>>::List::size << '\n' <<
            Erase<int, TypeList<int>>::List::size << '\n' <<
            Erase<int, TypeList<>>::List::size << "\n";
\end{verbatim}
\subsubsection{Erasing a type by its index}
        \typeout{Original Yodl file: advancedtemplates/eraseindex}To erase a type from a \texttt{TypeList} by its index we again use a
recursive template meta program. \texttt{EraseIdx} expects a \texttt{size\_t} index value
and a \texttt{TypeList} from which its \texttt{idx}$^{th}$ (0-based) type must be
erased. \texttt{EraseIdx} defines the type \texttt{List} containing the resulting
\texttt{TypeList}. Here is the algorithm:
    \begin{itemize}
    \item  The foundation of the algorithm consists of a struct template
\texttt{EraseIdx} expecting the index of the type to erase and a \texttt{TypeList}:
            \begin{verbatim}
    template <size_t idx, typename TypeList>
    struct EraseIdx;
\end{verbatim}
    \item  If the typelist is empty, there's nothing to erase, and an empty
        \texttt{TypeList} results:
            \begin{verbatim}
    template <size_t idx>
    struct EraseIdx<idx, TypeList<>>
    {
        using List = TypeList<>;
    };
\end{verbatim}
    \item  The recursion otherwise ends once \texttt{idx} becomes 0. At that point
        the \texttt{TypeList}'s first type is ignored and \texttt{List} is initialized
        to a \texttt{TypeList} containing the types in the orginal \texttt{TypeList}'s
        tail:
            \begin{verbatim}
    template <typename EraseType, typename ...Tail>
    struct EraseIdx<0, TypeList<EraseType, Tail...>>
    {
        using List = TypeList<Tail...>;
    };
\end{verbatim}
    \item  In all other cases \texttt{EraseIdx} is applied to the \texttt{TypeList}'s
        tail, providing it with a decremented value of \texttt{idx}. To the
        resulting \texttt{TypeList} the orginal \texttt{TypeList}'s head is
        prefixed. The \texttt{TypeList} returned by the prefix operation is then
        returned as \texttt{EraseIdx::List}:
            \begin{verbatim}
    template <size_t idx, typename Head, typename ...Tail>
    struct EraseIdx<idx, TypeList<Head, Tail...>>
    {
        using List = typename Prefix<
                    Head,
                    typename EraseIdx<idx - 1, TypeList<Tail...>>::List
                >::List;
    };
\end{verbatim}
    \end{itemize}
    Here is a statement showing how \texttt{EraseIdx} can be used:
            \begin{verbatim}
    if
    (
        typeid(TypeAt<2,
                EraseIdx<1,
                   TypeList<int, char, size_t, double, int>>::List
                >::Type
        )
        == typeid(double)
    )
        cout << "the third type is now a double\n";
\end{verbatim}
\subsubsection{Erasing all occurrences of a type}
        \typeout{Original Yodl file: advancedtemplates/eraseall}Erasing all types \texttt{EraseType} from a \texttt{TypeList} can easily be accomplished
by applying the erasure procedure not only to the head of the \texttt{TypeList} but
also to the  \texttt{TypeList}'s tail.

Here is the algorithm, described in a slightly different order than
\texttt{Erase}'s algorithm:
    \begin{itemize}
    \item  If the \texttt{TypeList} is empty, there's nothing to erase, and an empty
        \texttt{TypeList} results. This is exactly what we do with \texttt{Erase}, so we
        can use inheritance to prevent us from having to duplicate elements of
        a template meta program:
            \begin{verbatim}
    template <size_t idx>
    struct EraseIdx<idx, TypeList<>>
    {
        using List = TypeList<>;
    };
\end{verbatim}
    \item  The foundation of the algorithm is therefore a struct template
        \texttt{EraseAll} expecting the type to erase and a \texttt{TypeList} that is
        derived from \texttt{Erase}, thus already offering the empty \texttt{TypeList}
        handling specialization:
            \begin{verbatim}
    template <typename EraseType, typename TypeList>
    struct EraseAll: public Erase<EraseType, TypeList>
    {};
\end{verbatim}
    \item  If \texttt{TypeList}'s head matches \texttt{EraseType} \texttt{EraseAll} is also
        applied to the \texttt{TypeList}'s tail, thus removing all occurrences of
        \texttt{EraseType} from \texttt{TypeList}:
            \begin{verbatim}
    template <typename EraseType, typename ...Tail>
    struct EraseAll<EraseType, TypeList<EraseType, Tail...>>
    {
        using List = typename EraseAll<EraseType, TypeList<Tail...>>::List;
    };
\end{verbatim}
    \item  In all other cases (i.e., \texttt{TypeList}'s head does \emph{not} match
        \texttt{EraseType}) \texttt{EraseAll} is applied to the \texttt{TypeList}'s tail.
        The returned \texttt{TypeList} consists of the original \texttt{TypeList}'s
        initial type and the types of the \texttt{TypeList} returned by the
        recursive \texttt{EraseAll} call:
            \begin{verbatim}
    template <typename EraseType, typename Head, typename ...Tail>
    struct EraseAll<EraseType, TypeList<Head, Tail...>>
    {
        using List = typename Prefix<
            Head,
            typename EraseAll<EraseType, TypeList<Tail...>>::List
        >::List;
    };
\end{verbatim}
    \end{itemize}
    Here is a statement showing how \texttt{EraseAll} can be used:
       \begin{verbatim}
    cout <<
        "After erasing size_t from "
            "TypeList<char, int, size_t, double, size_t>\n"
            "it contains " <<
                EraseAll<size_t,
                         TypeList<char, int, size_t, double, size_t>
                >::List::size << " types\n";
\end{verbatim}
\subsubsection{Erasing duplicates}
        \typeout{Original Yodl file: advancedtemplates/erasedup}To remove all duplicates from a \texttt{TypeList} all the \texttt{TypeList}'s first
elements must be erased from the \texttt{TypeList}'s tail, applying the procedure
recursively to the \texttt{TypeList}'s tail. The algorithm, outlined below, merely
expects a \texttt{TypeList}:
    \begin{itemize}
    \item  First, the generic \texttt{EraseDup} struct template is
declared. \texttt{EraseDup} structures define a type \texttt{List} representing the
\texttt{TypeList} that they generate. \texttt{EraseDup} calls expect a \texttt{TypeList} as
their template type parameters:
        \begin{verbatim}
    template <typename TypeList>
    struct EraseDup;
\end{verbatim}
    \item  If the \texttt{TypeList} is empty it can be returned empty and we're done:
        \begin{verbatim}
    template <>
    struct EraseDup<TypeList<>>
    {
        using List = TypeList<>;
    };
\end{verbatim}
    \item  In all other cases
        \begin{itemize}
        \item  \texttt{EraseDup} is first applied to the original \texttt{TypeList}'s
tail. By definition this results in a \texttt{TypeList} from which all
duplicates have been removed;
        \item  The \texttt{TypeList} returned by the previous step might contain the
original \texttt{TypeList}'s initial type. If so, it is removed by applying
\texttt{Erase} on the returned \texttt{TypeList}, specifying the original \texttt{TypeList}'s
initial type as the type to remove;
        \item  The returned \texttt{TypeList} consists of the original \texttt{TypeList}'s
initial type to which the types of the \texttt{TypeList} produced by the previous
step are appended.
        \end{itemize}
    This specialization is implemented like this:
        \begin{verbatim}
    template <typename Head, typename ...Tail>
    struct EraseDup<TypeList<Head, Tail...>>
    {
        using UniqueTail = typename EraseDup<TypeList<Tail...>>::List;
        using NewTail = typename Erase<Head, UniqueTail>::List;

        using List = typename Prefix<Head, NewTail>::List;
    };
\end{verbatim}
    \end{itemize}
    Here is an example showing how \texttt{EraseDup} can be used:
        \begin{verbatim}
    cout <<
        "After erasing duplicates from "
             "TypeList<double, char, int, size_t, int, double, size_t>\n"
        "it contains " <<
        EraseDup<
            TypeList<double, char, int, size_t, int, double, size_t>
        >::List::size << " types\n";
\end{verbatim}
\section{Using a TypeList}
\typeout{Original Yodl file: advancedtemplates/using}In the previous sections the definition and some of the features of typelists
were discussed. Most \textbf{C++} programmers consider typelists both
exciting and an intellectual challenge, honing their skills in the area of
recursive programming.

But there's more to typelist than a mere intellectual challenge. In the final
sections of this chapter the following topics are covered:
    \begin{itemize}
    \item  Creating classes from a typelist.\ \\ 
       Here the aim is to construct a new class consisting of instantiations
        of an existing basic template for each of the types mentioned in a
        provided typelist;
    \item  Accessing data members from the thus constructed conglomerate class
        by index, rather than name.
    \end{itemize}
    Again, much of the material covered by these sections was inspired by
        \index{Alexandrescu, A.}
    Alexandrescu's (2001) book.

\subsection{The Wrap and Multi class templates}
    \typeout{Original Yodl file: advancedtemplates/multi}To illustrate template meta programming concepts the template class \index{Multi}\texttt{Multi}
is now developed. The class template \texttt{Multi} \emph{creates} a new class from a
template template parameter \texttt{Policy} defining the data storage policy and a
series of types from which \texttt{Multi} is eventually derived. It does so by
passing its template parameters to its base class \texttt{MultiBase} that in turn
creates a final class inheritance tree. Since we don't know how many types are
going to be used \texttt{Multi} is defined as a variadic class template using a
template pack \texttt{...Types}.

In fact, the types that are specified with \texttt{Multi} aren't that
interesting. They primarily serve to `seed' the class \texttt{Policy}. Therefore,
rather than forwarding \texttt{Multi}'s types to \texttt{MultiBase} they are passed to
\texttt{Policy} and the sequence of \texttt{Policy$<$Type$>$} types is then forwarded to
\texttt{MultiBase}. \texttt{Multi}'s constructor expects initialization values for its
various \texttt{Policy$<$Type$>$}s which are perfectly forwarded to \texttt{MultiBase}.

The class \texttt{Multi} (implementing its constructor in-class to save some
space) shows how a
    \index{template pack: and template template parameters}
    \index{template template parameter: and template packs}
 template pack can be wrapped into a policy. Here is \texttt{Multi}'s definition:
    \begin{verbatim}
    template <template <typename> class Policy, typename ...Types>
    struct Multi: public MultiBase<0, Policy<Types>...>
    {
        using PlainTypes = TypeList<Types...>;
        using Base = MultiBase<0, Policy<Types>...>;

        enum { size = PlainTypes::size };

        Multi(Policy<Types> &&...types)
        :
            MultiBase<0, Policy<Types>...>(
                            std::forward<Policy<Types>>(types)...)
        {}
    };
\end{verbatim}
Unfortunately, the design as described contains some flaws.
    \begin{itemize}
    \item  As the \texttt{Policy} template template parameter is defined as
\texttt{template $<$typename$>$ class Policy} it can only accept policies expecting one
type argument. Contrary to this, \texttt{std::vector} is a template expecting two
template arguments, the second one defining the allocation scheme used by
\texttt{std::vector}. This allocation scheme is hardly ever changed, and most
applications merely define objects of types like \texttt{vector$<$int$>$,
vector$<$string$>$} etc.. Template template parameters must, however, be specified
with the correct number and types of required template parameters so
\texttt{vector} can't be specified as a policy for \texttt{Multi}. This can be solved by
    \index{class template: wrapped in simpler template}
\emph{wrapping} a more complex template in a simpler wrapper template, like so:
        \begin{verbatim}
    template <class Type>
    struct Vector: public std::vector<Type>
    {
        Vector(std::initializer_list<Type> iniValues)
        :
            std::vector<Type>(iniValues)
        {}
    };
\end{verbatim}
    Now \texttt{Vector} provides \texttt{std::vector}'s second parameter using its
default template argument. Alternatively, a \emph{template using declaration}
could be used.
    \item  If the \texttt{TypeList} contains two types like \texttt{int} and \texttt{double}
and the policy class is \texttt{Vector}, then the \texttt{MultiBase} class
eventually inherits from \texttt{vector$<$int$>$} and \texttt{vector$<$double$>$}. But if the
\texttt{TypeList} contains identical types, like two \texttt{int} type specifications
\texttt{MultiBase} would inherit from \emph{two} \texttt{vector$<$int$>$} classes. Classes
cannot be derived from identical base classes as that would make it impossible
to distinguish among their members. Regarding this, Alexandrescu (2001)
    \index{Alexandrescu, A.} writes (p.67):
    \begin{quote}
   \emph{There is one major source of annoyance...: you cannot use it when you
    have duplicate types in your \texttt{TypeList}.\ \\ 
   .... There is no easy way to solve the ambiguity, {[}as the eventually
    derived class/FBB{]} ends up inheriting {[}the same base class/FBB{]} twice.}
   \end{quote}
    \end{itemize}
    There is a way around the problem of duplicate base class types. If
instead of inheriting directly from base classes these base classes are first
wrapped in unique type defining classes, then these unique classes can be used
to access the base classes using principles of inheritance. As these unique
type-defining wrapper classes are merely classes that are derived from the
`real' base classes they inherit (and thus: offer) the functionality of their
base classes. A unique type defining wrapper class can be designed after the
class IntType, defined earlier.  The wrapper class we're
looking combines class derivation with the uniqueness offered by
\texttt{IntType}. The class template \texttt{UWrap} has two template parameters: one
non-type parameter \texttt{idx} and one type parameter. By ensuring that each
\texttt{UWrap} definition uses a unique \texttt{idx} value unique class types are
created. These unique class types are then used as base classes of the derived
class \texttt{MultiBase}:
    \begin{verbatim}
    template <size_t nr, typename Type>
    struct UWrap: public Type
    {
        UWrap(Type const &type)
        :
            Type(type)
        {}
    };
\end{verbatim}
    Using \texttt{UWrap} it's easy to distinguish, e.g., two \texttt{vector$<$int$>$}
classes: \texttt{UWrap$<$0, vector$<$int$>$$>$} could refer to the first \texttt{vector$<$int$>$},
\texttt{UWrap$<$1, vector$<$int$>$$>$} to the second vector.

Uniqueness of the various \texttt{UWrap} types is assured by the class
template \texttt{MultiBase} as discussed in the next section.

It must also be possible to initialize a  \texttt{Multi} class object. Its
constructor therefore expects the initialization values for all its \texttt{Policy}
values. So if a \texttt{Multi} is defined for \texttt{Vector, int, string} then its
constructor can receive the matching initialization values. E.g.,
        \begin{verbatim}
    Multi<Vector, int, string> mvis({1, 2, 3}, {"one", "two", "three"});
\end{verbatim}
\subsection{The MultiBase class template}
    \typeout{Original Yodl file: advancedtemplates/multibase}The class template \texttt{MultiBase} is \texttt{Multi}'s base class. It
defines a class that, eventually, is derived from the list of \texttt{Policy}
types that, in turn, were created by \texttt{Multi} using any additional types that
were  passed to it.

\texttt{MultiBase} itself has no concept of a \texttt{Policy}. To \texttt{MultiBase} the
world appears to consist of a simple template pack whose types are used to
define a class from. In addition to the \texttt{PolicyTypes} template pack,
\texttt{MultiBase} also defines a \texttt{size\_t nr} non-type parameter that is used to
create unique \texttt{UWrap} types. Here is \texttt{MultiBase}'s generic class
declaration:
    \begin{verbatim}
    template <size_t nr, typename ...PolicyTypes>
    struct MultiBase;
\end{verbatim}
Two specializations handle all possible \texttt{MultiBase} invocations. One
specialization is a recursive template. This template handles the first type
of \texttt{MultiBase}'s template parameter pack and recursively uses itself to
handle the remaining types. The second specialization is invoked once the
template parameter pack is exhausted and does nothing. Here is the definition
of the latter specialization:
    \begin{verbatim}
    template <size_t nr>
    struct MultiBase<nr>
    {};
\end{verbatim}
The recursively defined specialization is the interesting one. It performs
the following tasks:
    \begin{itemize}
    \item  It is derived from a unique \texttt{UWrap} type. The uniqueness is
guaranteed by using \texttt{MultiBase}'s \texttt{nr} parameter when defining
\texttt{UWrap}. In addition to \texttt{nr} the \texttt{UWrap} class receives the first type
of the template parameter pack made available to \texttt{MultiBase};
    \item  It is also recursively derived from itself. The recursive
\texttt{MultiBase} type is defined using as its first template argument an
incremented \texttt{nr} value (thus ensuring the uniqueness of the \texttt{UWrap} types
defined by recursive \texttt{MultiWrap} types). Its second template argument is the
tail of the template parameter pack made available to \texttt{MultiBase}
    \end{itemize}
    An illustration showing the layout of the \texttt{MultiBase} class
hierarchy is provided in figure \ref{MultiBaseFig}.

\begin{figure}[tbp]
\centerline{\epsffile{advancedtemplates/multibase.eps}}
\caption{\label{MultiBaseFig}Layout of a MultiBase class hierarchy}
\end{figure}

\texttt{MultiBase}'s constructor simply receives the initialization values that
were (originally) passed to the \texttt{Multi} object. Perfect forwarding is used
to accomplish this. \texttt{MultiBase}'s constructor passes its first parameter
value to its \texttt{UWrap} base class, also using perfect forwarding.
\texttt{MultiBase}'s recursive definition is:
        \begin{verbatim}
    template <size_t nr, typename PolicyT1, typename ...PolicyTypes>
    struct MultiBase<nr, PolicyT1, PolicyTypes...> :
                                public UWrap<nr, PolicyT1>,
                                public MultiBase<nr + 1, PolicyTypes...>
    {
        using Type = PolicyT1;
        using Base = MultiBase<nr + 1, PolicyTypes...>;

        MultiBase(PolicyT1 && policyt1, PolicyTypes &&...policytypes)
        :
            UWrap<nr, PolicyT1>(std::forward<PolicyT1>(policyt1)),
            MultiBase<nr + 1, PolicyTypes...>(
                              std::forward<PolicyTypes>(policytypes)...)
        {}
    };
\end{verbatim}
\subsection{Support templates}\label{GENSUPPORT}
    \typeout{Original Yodl file: advancedtemplates/support}The \texttt{Multi} class template defines \texttt{PlainTypes} as the \texttt{TypeList}
holding all the types of its parameter pack. Each \texttt{MultiBase} derived from a
\texttt{UWrap} type also defines a type \texttt{Type} representing the policy type that
was used to define the \texttt{UWrap} type and a type \texttt{Base} representing the
type of its nested \texttt{MultiBase} class.

These three type definitions allow us to access the types from which the
\texttt{Multi} object was created as well as the values of those types.

The class template \texttt{typeAt}, is a pure template meta program class template
(it has no run-time executable code). It expects a \texttt{size\_t idx} template
argument specifying the index of the policy type in a \texttt{Multi} type object as
well as a \texttt{Multi} class type. It defines the type \texttt{Type} as the \texttt{Type}
defined by \texttt{Multi}'s \texttt{MultiBase$<$idx, ...$>$} base class. Example:
        \begin{verbatim}
    typeAt<0, Multi<Vector, int, double>>::Type // Type is vector<int>
\end{verbatim}
The class template \texttt{typeAt} defines (and uses) a nested class template
\texttt{PolType} doing all the work. \texttt{PolType}'s generic definition specifies two
template parameters: an index used to specify the index of the requested type
and a typename initialized by a \texttt{MultiBase} type argument. \texttt{PolType}'s
recursive definition recursively reduces its index non-type parameter,
passing the next base class in \texttt{MultiBase}'s inheritance tree to the
recursive call. As \texttt{PolType} eventually defines the type \texttt{Type} to be the
requested policy type the recursive definition defines its \texttt{Type} as the
type defined by the recursive call. The final (non-recursive) specialization
defines the initial policy type of the \texttt{MultiBase} type as \texttt{Type}. Here is
\texttt{typeAt}'s definition:
        \begin{verbatim}
    template <size_t index, typename Multi>
    class typeAt
    {
        template <size_t idx, typename MultiBase>
        struct PolType;

        template <size_t idx,
                  size_t nr, typename PolicyT1, typename ...PolicyTypes>
        struct PolType<idx, MultiBase<nr, PolicyT1, PolicyTypes...>>
        {
            using Type = typename PolType< idx - 1, MultiBase<nr + 1,
                                           PolicyTypes...> >::Type;
        };

        template <size_t nr, typename PolicyT1, typename ...PolicyTypes>
        struct PolType<0, MultiBase<nr, PolicyT1, PolicyTypes...>>
        {
            using Type = PolicyT1;
        };
    public:
        typeAt(typeAt const &) = delete;
        using Type = typename PolType<index, typename Multi::Base>::Type;
    };
\end{verbatim}
The types specified by \texttt{Multi}'s parameter pack can also be retrieved using
a second helper class template: \texttt{plainTypeAt}. Example:
        \begin{verbatim}
    plainTypeAt<0, Multi<Vector, int, double>>::Type // Type is int
\end{verbatim}
The class template \texttt{plainTypeAt} uses a comparable (but simpler)
implementation than \texttt{typeAt}. It is also a pure template meta program class
template defining a nested class template \texttt{At}. \texttt{At} is implemented like
\texttt{typeAt} but it visits the types of the original template pack that was
passed to \texttt{Multi}, and made available by \texttt{Multi} as its \texttt{PlainTypes}
type. Here is \texttt{plainTypeAt}'s definition:
        \begin{verbatim}
    template <size_t index, typename Multi>
    class plainTypeAt
    {
        template <size_t idx, typename List>
        struct At;

        template <size_t idx, typename Head, typename ...Tail>
        struct At<idx, TypeList<Head, Tail...>>
        {
            using Type = typename At<idx - 1, TypeList<Tail...>>::Type;
        };

        template <typename Head, typename ...Tail>
        struct At<0, TypeList<Head, Tail...>>
        {
            using Type = Head;
        };

    public:
        plainTypeAt(plainTypeAt const &) = delete;
        using Type = typename At<index, typename Multi::PlainTypes>::Type;
    };
\end{verbatim}
Arguably the neatest support template is \texttt{get}. This is a function template
defining \texttt{size\_t idx} as its first template parameter and \texttt{typename Multi}
as its second template parameter. The function template \texttt{get} defines one
function parameter: a reference to a \texttt{Multi}, so it can deduce \texttt{Multi}'s
type by itself. Knowing that it's a \texttt{Multi}, we reason that it is also a
\texttt{UWrap$<$nr, PolicyType$>$} and therefore also a \texttt{PolicyType}, as the latter
class is defined as a base class of \texttt{UWrap}.

Since class type objects can initialize references to their base classes the
\texttt{PolicyType \&} can be initialized by an appropriate \texttt{UWrap} reference,
which in turn can be initialized by a \texttt{Multi} object. Since we can
determine \texttt{PolicyType} using \texttt{TypeAt} (note that evaluating \texttt{typename
typeAt$<$idx, Multi$>$::Type} is a purely compile-time matter), the \texttt{get}
function can very well be implemented \emph{inline} by a single \texttt{return}
statement:
        \begin{verbatim}
    template <size_t idx, typename Multi>
    inline typename typeAt<idx, Multi>::Type &get(Multi &multi)
    {
        return static_cast<
                UWrap<idx, typename typeAt<idx, Multi>::Type> &>(multi);
    }
\end{verbatim}
    The intermediate \texttt{UWrap} cast is required to disambiguate between
identical policy types (like two \texttt{vector$<$int$>$} types). As \texttt{UWrap} is
uniquely determined by its \texttt{nr} template argument and this is the number
argument that is passed to \texttt{get} ambiguities can easily be prevented.

\subsection{Using Multi}
    \typeout{Original Yodl file: advancedtemplates/usingmulti}Now that \texttt{Multi} and its support templates have been developed, how can a
\texttt{Multi} be used?

A word of warning is in place. To reduce the size of the developed classes
they were designed in a minimalist way. For example, the \texttt{get} function
template cannot be used with \texttt{Multi const} objects and there is no default,
or move constructor available for \texttt{Multi} types. \texttt{Multi} was designed to
illustrate some of the possibilities of template meta programming and
hopefully \texttt{Multi}'s implementation served that purpose well. But can it be
used? If so, how?

This section provides some annotated examples. They may be concatenated to
define a series of statements that could be placed in a \texttt{main} function's
body, which would result in a working program.

\begin{itemize}
    \item  A simple \texttt{Policy} could be defined:
        \begin{verbatim}
    template <typename Type>
    struct Policy
    {
        Type d_type;
        Policy(Type &&type)
        :
            d_type(std::forward<Type>(type))
        {}
    };
\end{verbatim}
    \texttt{Policy} defines a data member and it can be used to define \texttt{Multi}
objects:
        \begin{verbatim}
    Multi<Policy, string> ms{ Policy<string>{ "hello" } };
    Multi<Policy, string, string> ms2s{ Policy<string>{ "hello" },
                                       Policy<string>{ "world" } };


     using MPSI = Multi<Policy, string, int>;
     MPSI mpsi{ string{ "hello" }, 4 };
\end{verbatim}
\item  To obtain the number of types defined by a \texttt{Multi} class or object
    either use the \texttt{::size} enum value (using the \texttt{Multi} class) or the
\texttt{.size} member (using the \texttt{Multi} object):
        \begin{verbatim}
    cout << "There are " << MPSI::size << " types in MPSI\n"
            "There are " << mpsi.size << " types in mpsi\n";
\end{verbatim}
\item  Variables of constituting types can be defined using \texttt{plainTypeAt}:
        \begin{verbatim}
    plainTypeAt<0, MPSI>::Type sx = "String type";
    plainTypeAt<1, MPSI>::Type ix = 12;
\end{verbatim}
\item  Raw static casts can be used to obtain the constituent type:
        \begin{verbatim}
    cout << static_cast<Policy<string> &>(mpsi).d_type << '\n' <<
            static_cast<Policy<int> &>(mpsi).d_type << '\n';
\end{verbatim}
\item  However, this won't work when the template parameter pack contains
identical types, as a cast can't distinguish between identical
\texttt{Policy$<$Type$>$} types. In that case \texttt{get} still works fine:
        \begin{verbatim}
    using MPII = Multi<Policy, int, int>;
    MPII mpii{ 4, 18 };

    cout << get<0>(mpii).d_type << ' ' << get<1>(mpii).d_type << '\n';
\end{verbatim}
\item  Here is an example wrapping a \texttt{std::vector} in a \texttt{Vector}:
        \begin{verbatim}
    using MVID = Multi<Vector, int, double>;
    MVID mi{ {1, 2, 3}, {1.2, 3.4, 5.6, 7.8} };
\end{verbatim}
\item  Such a vector can be defined by its \texttt{Multi} type:
        \begin{verbatim}
    typeAt<0, Multi<Vector, int>>::Type vi = {1, 2, 3};
\end{verbatim}
\item  Knowing that a \texttt{Vector} is a \texttt{std::vector}, the reference
returned by \texttt{get} support index operators that can be used as left hand side
or right hand side operands:
        \begin{verbatim}
    cout << get<0>(mi)[2] << '\n';
    get<1>(mi)[3] = get<0>(mi)[0];
    cout << get<1>(mi)[3] << '\n';
\end{verbatim}
    \end{itemize}

\section{Expression Templates}
\typeout{Original Yodl file: advancedtemplates/expressiontemplates}

Assume we are processing \texttt{std::vector} objects. Vectors may be assigned to
each other, but that's about it. We've seen (cf. section \ref{VECTOR}) that its
member functions tend to operate on the current vector, but arithmetic
operations like addition, subtraction, multiplication and the like cannot
be applied to pairs of vectors.

Implementing the, e.g., addition operator for vectors is not difficult. If
\texttt{VecType} is our vector type, then implementing free functions like
    \texttt{VecType \&\&operator+(VecType const \&lhs, VecType const \&rhs)} and 
    \texttt{VecType \&\&operator+(VecType \&\&lhs, VecType const \&rhs)} 
        performing the additions is a simple exercise (cf. chapter
\ref{OVERLOADING}).

Now consider an expression like \texttt{one + two + three + four}. It takes four
steps to compute this sum: first, \texttt{tmp = one} is computed, creating the
eventual return value. The vector \texttt{tmp} becomes the eventual return
value. Once it is available \texttt{tmp += two} is computed, followed by \texttt{tmp +=
three}, and finally by \texttt{tmp += four} (of course
we shouldn't implement \texttt{std::vector::operator+=} as the std namespace is
off-limits to us, and we shouldn't derive a class from \texttt{std::vector}
offering \texttt{operator+=} according to Liskov's Substitution Principle
(cf. section \ref{INHERITWHY}), but we could get around that.
     
    Here we simply assume \texttt{operator+=} is available).

Here's how we might implement \texttt{operator+=} for \texttt{VecType}:
         \begin{verbatim}
    VecType &VecType::operator+=(VecType const &rhs)
    {
        for (size_t idx = 0, end = size(); idx != end; ++idx)
            (*this)[idx] += rhs[idx];
        return *this;
    }
\end{verbatim}
Consider this implementation: once we add \texttt{VecType} objects and such
objects have \texttt{N} elements then we have to perform \texttt{2 $*$ N} index
evaluations. When adding \texttt{k VecType} objects this adds up to \texttt{2 $*$ N $*$ k}
index expression evaluations (as eventually we also have to assign the
elements of the resulting temporary object to the destination object): lots
of index expression evaluations.

If instead we could manage to perform the evaluations `row by row', we
would only have to access each vector element only once (which in particular
applies to the temporary object). In that case, when adding k objects,
assigning the sums of their respective elements to a destination vector we
have to compute \texttt{N $*$ (k + 1)} index expressions (\texttt{`k'} for each of the
vectors, \texttt{`1'} for the destination vector).

For \texttt{k == 1} the two methods are equally efficient in terms of index
computations. But that's not addition, that is assignment. So when adding any
number of vectors, assigning their sum to a destination vector using expression
templates 
    \index{expression template}\index{template: expression template} 
  is more efficient than the ordinary implementation of the addition
operator. We'll have a look at the design and implementation of expression
templates in the coming sections.

\subsection{Designing an Expression Template}
    \typeout{Original Yodl file: advancedtemplates/designing}As we've seen, when using a standard implementation of an expression like
\texttt{one + two + three + four}, where the objects are vectors having \texttt{n}
elements, then if we have \texttt{k} vectors we have to perform a total of \texttt{k $*$ 2
$*$ n} index evaluations.

Expression templates allow us to avoid many of these evaluations. When using
expression templates these templates may access the vectors, but their
elements are not accessed during addition operations. 

Assuming our expression template is named ET, and we want to add \texttt{one + two
+ three}, then the first \texttt{+} operator merely creates \texttt{ET(one, two)}. Note
that no addition is actually performed, \texttt{ET} merely stores (constant)
references to \texttt{one} (becoming \texttt{ET's lhs} data member) and \texttt{two}
(becoming \texttt{ET's rhs} data member). In general, \texttt{ET} stores references to
the two arguments that are passed to its constructor.

At the next addition operator another \texttt{ET} is created. Its constructor
arguments are, respectively, the \texttt{ET} object that has just been constructed
for \texttt{one} and \texttt{two}, and the vector \texttt{three}. Again, no addition is
performed by the ET objects.

This algorithm easily generalizes to any number of vectors. Parentheses can
also be used. E.g., \texttt{(one + two) + (three + four)} results in
        \begin{verbatim}
    ET(ET(one, two), ET(three, four))
\end{verbatim}
Presumably, at some point we want to obtain the sum of the vectors. For this
the expression template is provided with a conversion operator, converting the
\texttt{ET} object to a vector, or maybe an assignment operator doing the same.

The conversion operator looks like this:
        \begin{verbatim}
    operator ET::VecType() const
    {                                                        
        VecType retVal;
        retVal.reserve(size());

        for (size_t ix = 0, end = size(); ix != end; ++ix)
            new(&retVal[ix]) value_type((*this)[ix]);
                                                     
        return retVal;
    }
\end{verbatim}
Placement new is used for efficiency reasons: there's no need to
initialize \texttt{retVal} with default values first. The really interesting part,
however, is hidden behind the \texttt{($*$this){[}idx{]}} expression: at this point the
real addition takes place.

\texttt{ET's} index operator simply adds the values returned by the
corresponding index expressions of its \texttt{lhs} and \texttt{rhs} data members. If a
data member refers to a vector then the corresponding vector element is used,
adding it to the other data member's value. If a data member itself refers to
an ET object, then that nested \texttt{ET} object's index operator performs the
same addition on its own data members, returning their sum. So, an expression
like \texttt{($*$this){[}0{]}} returns \texttt{first{[}0{]} + second{[}0{]} + third{[}0{]}}, and the
computed sum is then stored in \texttt{retVal{[}0{]}} using placement new.

In this case the required number of index expression evaluations are \texttt{n
$*$ k} (for the n elements of the k vectors) plus n (for the n elements of
\texttt{retVal}, adding up to \texttt{(k + 1) $*$ n}). 

Since \texttt{(k + 1) $*$ n $<$ 2 $*$ k $*$ n} for \texttt{k $>$ 1} expression templates evaluate
the requested addition more efficiently than the traditional implementation of
\texttt{operator+}. An additional benefit of using expression templates is that
they do not create additional temporary vector objects when parenthesized
expressions are used.

\subsection{Implementing an Expression Template}
    \typeout{Original Yodl file: advancedtemplates/implementing}In this section we specify \texttt{using IntVect = std::vector$<$int$>$} to illustrate
the construction of an expression template. 

Starting point is a simple \texttt{main} function, in which several \texttt{IntVect}
objects are added. E.g., 
        \begin{verbatim}
    int main()
    {
        IntVect one;
        IntVect two;
        IntVect three;
        IntVect four;
        
        // ... assume the IntVects somehow receive values

        four = one + two + three + four;
    }
\end{verbatim}
At this point the code does not suggest that expression templates are
going to be used. However, \texttt{operator+'s} implementation is special: it's a
template merely returning an object constructed by \texttt{operator+}:
        \begin{verbatim}
    template<typename LHS, typename RHS>
    BinExpr<LHS, RHS, plus> operator+(LHS const &lhs, RHS const &rhs)
    {
        return BinExpr<LHS, RHS, plus>{ lhs, rhs };
    }
\end{verbatim}
Our expression template is called \texttt{BinExpr}. It has three template type
parameters: two object types and a template template parameter performing the
requested operation. Its declaration looks like this:
        \begin{verbatim}
    template<typename LHS, typename RHS, template<typename> class Operation>
    struct BinExpr;
\end{verbatim}
Since \texttt{LHS} and \texttt{RHS} can either be the data type that is processed by
the expression template, or a \texttt{BinExpr} two different typenames are
required. \texttt{Operation} is the operation that is performed by the expression
template. By using a template template parameter we can use \texttt{BinExpr} to
perform any operation we want, not just addition. Predefined function
templates like \texttt{std::plus} can be used for the standard arithmetic
operators; for other operators we can define our own function templates.

\texttt{BinExpr's} constructor initializes constant references to \texttt{lhs} and
\texttt{rhs}. Its in-class implementation is
        \begin{verbatim}
    BinExpr(LHS const &lhs, RHS const &rhs)
    :
        d_lhs(lhs),
        d_rhs(rhs)
    {}
\end{verbatim}
To retrieve the resulting \texttt{IntVect} a conversion operator is defined. We
already encountered its implementation (in the previous section). Here is it,
as an in-class implemented \texttt{BinExpr} member:
        \begin{verbatim}
    operator ObjType() const
    {                                                        
        ObjType retVal;
        retVal.reserve(size());

        for (size_t idx = 0, end = size(); idx != end; ++idx)
            new(&retVal[idx]) value_type((*this)[idx]);
                                                     
        return retVal;
    }
\end{verbatim}
We return to the type \texttt{ObjType} below. At this point it can be
considered an \texttt{IntVect}. The member \texttt{size()} simply returns
\texttt{d\_lhs.size()}: in any sequence of \texttt{IntVect} additions \texttt{LHS} eventually
is an \texttt{IntVect}, and so every \texttt{BinExpr} defines a valid \texttt{size()} like
so:
        \begin{verbatim}
    size_t size() const
    {
        return d_lhs.size();
    }
\end{verbatim}
The only remaining member to implement is \texttt{operator{[}{]}}. Since it
receives an index, it only needs to perform the requested operation on the
corresponding index elements of its \texttt{d\_lhs} and \texttt{d\_rhs} data members. The
beauty of expression templates is that if either one itself is a \texttt{BinExpr}
that expression template in turn calls its \texttt{operator{[}{]}}, eventually
performing the requested operation on all corresponding elements of all
\texttt{IntVect} objects. Here is its implementation:
        \begin{verbatim}
    value_type operator[](size_t ix) const
    {
        static Operation<value_type> operation;

        return operation(d_lhs[ix], d_rhs[ix]);
    }
\end{verbatim}
This implementation uses another type: \texttt{value\_type} which is the 
type of the elements of the vector type that is processed by the expression
template. Like \texttt{ObjType} before, its definition is covered below. The static
data member \texttt{operation} simply is an instantiation of the \texttt{Operation} type
that is specified when constructing an \texttt{ExprType} object. 

In the next section we take a closer look at \texttt{ObjType} and \texttt{value\_type}.

\subsection{The BasicType trait class and ordering classes}
    \typeout{Original Yodl file: advancedtemplates/basictype}The \texttt{BinExpr} expression template needs to be aware of two types before it
can instantiate objects. First, \texttt{ObjType} must be known, as this is the 
type of object that is handled by the expression template. \texttt{ObjType} objects
contain values, and we require that the type of these values can be determined
as \texttt{ObjType::value\_type}. E.g., for our \texttt{IntVect} data type \texttt{value\_type}
is \texttt{int}. 

In expressions like \texttt{one + two + three}, the \texttt{BinExpr} expression template
receives two \texttt{IntVect} objects. This is always true: the \texttt{BinExpr} that is
first constructed receives two \texttt{IntVect} objects. In this case \texttt{ObjType}
is simply \texttt{LHS}, and \texttt{ObjType::value\_type} is also available: either
\texttt{value\_type} is already defined by \texttt{LHS} or \texttt{BinExpr} \emph{requires} that
it defines type \texttt{value\_type}. 

Since arguments to \texttt{BinExpr} objects are not \emph{always} of the basic
\texttt{ObjType} type (\texttt{BinExpr} objects at the next nesting level receive at
least one \texttt{BinExpr} argument) we need a way to determine \texttt{ObjType} from a
\texttt{BinExpr}. For this we use a \emph{trait class}. The 
trait class \texttt{BasicType} receives a typename template argument, and equates
its type \texttt{ObjType} to the received template type argument:
        \begin{verbatim}
    template<typename Type>
    struct BasicType
    {
        using ObjType = Type ;
    };
\end{verbatim}
A specialization handles the case where \texttt{Type} in fact is a \texttt{BinExpr}:
    template$<$typename LHS, typename RHS, template$<$typename$>$ class Operation$>$
        \begin{verbatim}
    template<typename LHS, typename RHS, template<typename> class Operation>
    struct BasicType<BinExpr<LHS, RHS, Operation>>
    {
        using ObjType = BinExpr<LHS, RHS, Operation>::ObjType ;
    };
\end{verbatim}
Since \texttt{BinExpr} \emph{requires} that \texttt{ObjType::value\_type} is a defined
type, \texttt{value\_type} has automatically been taken care of. 

As \texttt{BinExpr} refers to \texttt{BasicType} and \texttt{BasicType} refers to
\texttt{BinExpr} somewhere we must provide a forward declaration. As \texttt{BinExpr's}
declaration has already been provided, we start with that declaration,
resulting in:
        \begin{verbatim}
    BinExpr's declaration

    BasicType's definition

    BasicType's specialization (for BinExpr)

    template<typename LHS, typename RHS, template<typename> class Operation>
    class BinExpr 
    {
        LHS const &d_lhs;
        RHS const &d_rhs;

        public:
            using DataType = BasicType<RHS>::DataType ;
            using type = DataType::value_type value_;

            // all BinExpr member functions
    };
\end{verbatim}
\section{Concepts}\label{CONCEPTS}
\typeout{Original Yodl file: advancedtemplates/concepts/intro}

\textbf{C++} is a strongly typed language: a function \texttt{add(int lhs, int rhs)}
doesn't accept \texttt{std::string} arguments, even though the actual operations
(\texttt{lhs + rhs}) are identical for \texttt{ints} and \texttt{strings}. 

Templates were introduced so we could design \emph{recipes} for the compiler,
allowing it to construct type-safe overloaded versions of functions and
classes while keeping their type-safety. 

A basic addition function template adding two values looks like this:
        \begin{verbatim}
    template <typename Type>
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
When this function template is called with arguments of types that do not
support \texttt{operator+} then the compiler notices this, and it will generate an
error. E.g., when calling
        \begin{verbatim}
    add(std::cerr, std::cout);
\end{verbatim}
    the \texttt{g++} compiler produces some 140 lines of error messages. It notices
that there's no \texttt{operator+} for \texttt{std::ostream} objects, and then tells us
what else we might have done (like adding two \texttt{ints}), and where the
construction of the \texttt{add} function that should accept \texttt{std::ostream}
arguments went wrong. In fact, 140 lines of error messages is rather benign.
Getting several hundreds of lines is quite common, and sometimes the
location of the error isn't mentioned at the top but somewhere near the end of
the error message output. 

The \texttt{C++26} standard introduced \index{concept} \emph{concepts} allowing us to specify
\emph{requirements} for template types. When applying an appropriate concept to
the definition of the \texttt{add} function template the compiler immediately
pinpoints the error, telling us where and why the error occurred in some 15
instead of 140 lines of error messages.

The reduction of the number of lines of error messages by itself is a
boon. But the fact that concepts allow us to consciously develop our
templates, realizing what the precise requirements are for their use, is at
least as important: it improves the template's documentation, and thus our
understanding of templates.

Concepts may be considered the template's answer to the philosphy that lies
behind a strongly typed language. By applying concepts to templates we can
specify type-requirements rather than using the traditional `shotgun
empiricism' approach where templates are bluntly used, knowing that the
compiler will complain if things are incorrect. In that sense concepts provide
type definitions of types. Concepts have names and can (among other) be used
in template headers where the concept names replace the traditional
\texttt{typename} keywords. 

As an opening illustration, assume that a concept \texttt{Addable} exists
specifying that \texttt{operator+} must have been defined for the template's
type. The above function template \texttt{add} can now be formulated as:
        \begin{verbatim}
    template<Addable Type>
    Type add(Type const &lhs, Type const &rhs)
    {
        return lhs + rhs;
    }
\end{verbatim}
From now on every type that is actually passed to \texttt{add} must be 
satisfy the \texttt{Addable} requirements. Here are two expressions
using \texttt{add}:
        \begin{verbatim}
    add("first"s, "second"s);               // (1)
    add(map<int, int>{}, map<int, int>{});  // (2)
\end{verbatim}
Expression (1) flawlessly compiles as \texttt{string} objects can be added;
expression (2) fails with the compiler reporting something like
    \begin{verbatim}
    error: use of function `Type add(const Type&, const Type&)
    [with Type = std::unordered_map<int, int>]' with unsatisfied constraints
    add(unordered_map<int, int>{}, unordered_map<int, int>{});
    note: constraints not satisfied

    Type add(const Type&, const Type&) 
    ...
    note: the required expression `(lh + rh)' is invalid
\end{verbatim}
The error message's final `note' clearly states the cause of the problem:
you can't add maps. 

The difference between the compiler's report using concepts and not using
concepts again is impressive. When using the traditional \texttt{typename Type}
specification in the template header the compiler produces some 17 kB of error
messages, spread out over more than 200 lines.

In the following sections we cover how concepts are defined, what kind of
requirements can be formulated, and how they can be used in practice.

\subsection{Defining concepts}\label{CONDEF}
    \typeout{Original Yodl file: advancedtemplates/concepts/defining}As a prelude before actually looking at how concepts are defined it is noted
that concept names, like class names, type names, function names, and variable
names should suggest their purposes. Don't name a concept `\texttt{Constraint}' or
`\texttt{Concept}', but use names like `\texttt{Addable}' and `\texttt{HasValueType}'.

Concepts are templates. They start with a template header (the
template headers shown in the examples define a single template type
parameter, but multiple template parameters are also used). 

In the previous section we used the concept \texttt{Addable}. Here is how it can
be defined:
    \begin{verbatim}
    template <typename Type>
    concept Addable =
        requires(Type lh, Type rh)
        {
            lh + rh;
        };
\end{verbatim}
The concept's template header is followed by the keyword \texttt{concept}, the
concept's name, and the assignment operator. Following the assignment operator
\index{requires}\emph{requirement specifications} are provided.

Semicolons end concept definitions. This concept uses a
\emph{simple requirement} (cf. section \ref{REQSIMPLE}) indicating that
\texttt{operator+} must have been defined for \texttt{Addable} templates' types.

Requirements come in many forms. A very simple form consists of just a
\texttt{bool} value, which is sometimes useful when developing a concept. Such a
concept looks like this:
        \begin{verbatim}
template <typename Type>
    concept IsTrue = 
        true;
\end{verbatim}
    But in most situations \texttt{requires} specifications are used. They resemble
function definitions having parameter lists optionally defining variables of
the types that specified in the concept's template header and compound
statements specifying requirements.

Concepts are \emph{never} instantiated. They are used compile-time to verify that
template types satisfy the imposed requirements.  Thus there's no need
to use refererences in parameter lists of \texttt{requires} specifications. The
concept \texttt{Addable} simply uses
        \begin{verbatim}
    requires(Type lh, Type rh)
\end{verbatim}
and there's no need to specify
        \begin{verbatim}
    requires(Type const &lh, Type const &rh)
\end{verbatim}
    (That is, usually there is no need for this. In section \ref{REQNEST} we
encounter a situation where a more specific parameter definition might be
appropriate.)

Here are two examples of templates using \texttt{concept Addable}. The first
example uses \texttt{Addable} instead of \texttt{typename} when specifying the template
header, the second example appends the concept specification to the template
header itself:
    \begin{verbatim}
    template<Addable Type>
    Type add2(Type const &x, Type const &y)
    {
        return x + y;
    }
    
    template<typename Type>
        requires Addable<Type>
    Type add(Type const &x, Type const &y)
    {
        return x + y;
    }
\end{verbatim}
Template declarations using concepts are specified accordingly. Simply replace
the function template's body by a semicolon.

Concepts may also be defined by extending or combining existing concepts. 
\emph{Nesting} concepts is covered in section \ref{REQNEST}.

Although concepts are templates, they cannot be specialized. If a concept
should recognize specializations then these specializations must be handled by
the concepts' definitions. See section \ref{REQCOMP} for an illustration.

\subsection{Requirements}
    \typeout{Original Yodl file: advancedtemplates/concepts/requirements}The bodies of \texttt{requires} declarations contain define constraints to apply to
template parameters. There are four types of requirements:
    \begin{itemize}
    \item  \emph{Simple requirements}: constraints on \emph{facilities} (like
        requiring the availability of \texttt{operator+});
    \item  \emph{Type requirements}: requiring the availability of (sub)types (like 
        the sub-type \texttt{value\_type}) which must be available when using
        standard \texttt{push\_back} functions;
    \item  \emph{Compound requirements}: requiring types resulting from applying
        operators or returned by called (member) functions;
    \item  \emph{Nested requirements}: defining concepts in terms of already
        existing concepts. 
    \end{itemize}

Constraints must be compile-time verifiable.

When multiple constraints are specified, they must \emph{all} be compile-time
verifiable, and an actual type is only accepted by the compiler if all
requirements could be satisfied. 

\subsubsection{Simple requirements}\label{REQSIMPLE}
        \typeout{Original Yodl file: advancedtemplates/concepts/simple}We've already encountered various examples of \emph{simple requirements}: they
specify the operations that must be supported by the variable(s) declared in
the parameter lists of \texttt{requires} specifications. When the requirements
refer to single variables single \texttt{Type} parameters suffice; when 
requirements involve different types then the concept's template head declares
those different types and the \texttt{requires} parameter list will usually define
variables of those different types. The \texttt{concept BasicMath} specifies two
types, and uses four simple requirements to specify the four basic arithmetic
operations:
    \begin{verbatim}
    template <typename LhsType, typename RhsType>
    concept BasicMath =
        requires(LhsType lhs, RhsType rhs)
        {
            lhs + rhs;      // addition must be available
            lhs - rhs;      // subtraction must be available
            lhs * rhs;      // multiplication must be available
            lhs / rhs;      // division must be available
        };
\end{verbatim}
Specifying constraints does not necessarily mean that the constraints as
specified literally apply to run-time situations. To require the existence of
the index operator the following simple requirement can be used:
    \begin{verbatim}
    template <typename Type>
    concept HasIndex =
        requires(Type tp)
        {
            tp[0];
        };
    
    template <HasIndex Type>
    auto idx(Type const &obj, size_t idx)
    {
        return obj[idx];
    }
\end{verbatim}
Here the \emph{stand-in argument} 0 is used to specify the index operator's
argument. The argument value used in the simple requirement really is a
stand-in. The following code fragment compiles, as \texttt{string} supports the
index operator. Although argument 0 is used in the simple requirement
specification the argument 5 is in fact being used:
        \begin{verbatim}
    string str;
    idx(str, 5);
\end{verbatim}
Other than \texttt{int} index types can be specified analogously. Here is an
example showing how to define and use a concept \texttt{HasStrIndex} requiring the
availability of \texttt{std::string} arguments of index operators:
    \begin{verbatim}
    template <typename Type>
    concept HasStrIndex =
        requires(Type tp)
        {
            tp[std::string{}];
        };
    
    template <HasStrIndex Type>
    auto value(Type &obj, std::string const &key)
    {
        return obj[key];
    }
    
    int main()
    {
        std::map<std::string, double> msd;
        value(msd, "hi");
    }
\end{verbatim}
\subsubsection{Type requirements}
        \typeout{Original Yodl file: advancedtemplates/concepts/type}Sometimes templates must use sub-types of template types. Examples are
templates assuming the existence of \texttt{iterator} (like
\texttt{vector$<$int$>$::iterator}) or \texttt{value\_type} which is used when calling
\texttt{std::push\_back}.

To specify that a sub-type must be available the concept's \texttt{requires}
specification needs no parameters, but can directly refer to the subtype. It's
also possible to combine type requirements with requirements that \emph{do}
define a non-empty parameter list, and so the \texttt{requires's} parameter list
does not \emph{have} to be empty. Here is a concept that specifies a plain type
requirement:
        \begin{verbatim}
    template <typename Type> 
    concept HasValueType =
        requires()
        {
            typename Type::value_type;
        };
\end{verbatim}
    and here's a concept that combines a simple requirement with a type
requirement: 
        \begin{verbatim}
    template <typename Type>
    concept Iteratable =
        requires(Type tp)
        {
            typename Type::iterator;
            tp.begin();
        };
    
    template <Iteratable Type>
    auto iter(Type const &obj)
    {
        return obj.begin();
    }
\end{verbatim}
Calling \texttt{iter} with a \texttt{string} argument succeeds, calling it with a
\texttt{queue} argument results in two error notes: no \texttt{Type::iterator} and no
\texttt{tp.begin()}.

Types specified in type requirements don't necessarily have to refer to
\emph{types}. They may also specify be the names of nested classes or
enumerations defined by \texttt{Type}. When specifying enumerations they do not
have to be strongly typed.

\subsubsection{Compound requirements}\label{REQCOMP}
        \typeout{Original Yodl file: advancedtemplates/concepts/compound}When return types of operations must satisfy certain requirements then
\emph{compound requirements} should be used. Compound requirements define type
constraints on expressions embedded in compound statements.  The \texttt{C++26} standard
defines several concepts that can be used to specify such requirements (see
also section \ref{CXXCONCEPTS} below). Here is an example:
        \begin{verbatim}
    template <typename Type, typename ReturnType> 
    concept Return =
        requires(Type par)
        {
                          // par[..] must return a `ReturnType'
            { par[0] } -> std::same_as<ReturnType>; 
        };
\end{verbatim}
This concept can now be used to specify requirements of template type
parameters. E.g.,
        \begin{verbatim}
    template <typename Type, typename RetType> 
        requires Return<Type, RetType>
    RetType fun(Type tp)
    {
        return tp[0];
    }
\end{verbatim}
Here arguments passed to \texttt{fun} must satify two requirements:
    \begin{itemize}
    \item  they must provide an index operator accepting integral argument
        values; 
    \item  their index operators must return \texttt{std::string} values.
    \end{itemize}

You may have noticed that the \texttt{std::same\_as} concept receives only one
template type argument, which (as if by magic) compares it with the type
returned by the \texttt{par{[}0{]}} expression. When peeking at the available concepts
in section \ref{CXXCONCEPTS} you will see that several of those concepts in
fact define two template type parameters. When these concepts are used in
compound requirements then the compiler passes the deduced type of the
expression in the concept's compound statement (so that's the type of
\texttt{par{[}0{]}} in the above example) to the concept's first type, and passes the
explicitly specified type to the concept's second type.

Knowing this we can define our own concepts to use in compound
expressions. We may define our own \texttt{same\_as} concept as follows, using a
separate class template \texttt{SameTypes}. \texttt{SameTypes} defines a
\texttt{bool} value `\texttt{value}' which is used to decide about the concept's
requirement. The class template \texttt{SameTypes} uses a specialization to handle
the situation where both types are equal. Note that concepts 
    \index{concept: specialization} themselves cannot be specialized:
        \begin{verbatim}
    template <typename Lhs, typename Rhs>
    struct SameTypes            // generic: any two types
    {
        static bool const value = false;
    };
    template <typename Lhs>
    struct SameTypes<Lhs, Lhs>  //specialization: equal types
    {
        static bool const value = true;
    };

    template<typename Compound, typename Specified>
    concept Same = SameTypes::value;
\end{verbatim}
Now the concept \texttt{Same} can be used instead of \texttt{std::same\_as} by merely
specifying the required type:
        \begin{verbatim}
    template <typename Type, typename ReturnType> 
    concept Return =
        requires(Type par)
        {
                          // par[..] must return a `ReturnType'
            { par[0] } -> Same<ReturnType>; 
        };
\end{verbatim}
    Although in this case it isn't important which actual type is used as
argument for which concept type parameter, the compiler specifies the compound
expression's type as template argument for \texttt{Same's Compound} parameter
whereas \texttt{ReturnType} is used as template argument for \texttt{Same's Specified}
parameter.

Multiple type requirements can be specified by providing multiple compound
requirements as in the following example:
        \begin{verbatim}
    template <typename Type> 
    concept MultiArgs =
        requires(Type lhs, Type rhs)
        {
            { lhs + rhs   } -> std::same_as<Type>;  
            { lhs += rhs  } -> std::same_as<Type &>;
            { lhs.c_str() } -> std::same_as<char const *>;
        };
\end{verbatim}
If it is required that the compound operation doesn't throw exceptions then
\texttt{noexcept} can be written immediately following the compound requirement's
late return type arrow (\texttt{-$>$}). The \texttt{noexcept} specification itself may
then optionally be followed by a type constraint.

Finally, the late return type specifications itself is optional, in which case
the compound requirement acts like a simple requirement: it requires the
existence of the expression that's specified in the compound statement. In
this case: don't forget to add the semicolon following the closing parenthesis
of the compound requirement:
        \begin{verbatim}
    template <typename Type> 
    concept Increment =
        requires(Type par)
        {
            { ++par };  
            // same as:
            ++par;
        };
\end{verbatim}
\subsubsection{Nested requirements}\label{REQNEST}
        \typeout{Original Yodl file: advancedtemplates/concepts/nested}Concepts can be nested. Being able to nest concepts is very useful as it
allows us to hierarchically order concepts and to define concepts in terms of
existing concepts.

In chapter \ref{STL} iterators were introduced (section
\ref{ITERATORS}). Commonly five conceptually different iterator types are
distinguished:
    \begin{itemize}
    \item  Input iterators are incrementable, and they support dereferencing to
        const values;
    \item  Output iterators are like Input iterators, but they refer to
        non-const values;
    \item  Forward iterators combine Input and Output iterators;
    \item  Bidirectional iterators are like Forward iterators, but 
        they also support decrement operators;
    \item  RandomAccess iterators are like Bidirectional iterators, but these
        iterators also support addition and subtraction by any stepsize.
    \end{itemize}

\begin{figure}[tbp]
\centerline{\epsffile{advancedtemplates/concepts/nested.eps}}
\caption{\label{ConceptFig}Concept Hierarchy}
\end{figure}

All iterator types support (in)equality checks and increment operators. Thus,
at the basis of all iterators we find the requirements that iterators must be
comparable and incrementable. Concepts covering those requirements are easily
constructed (see also figure \ref{ConceptFig}):
        \begin{verbatim}
    template <typename Type>
    concept Comparable =
        requires (Type lhs, Type rhs)
        {
            lhs == rhs;
            lhs != rhs;
        };
    
    template <typename Type>
    concept Incrementable =
        requires (Type type)
        {
            ++type;
            type++;
        };
\end{verbatim}
Note that no type is specified following the \texttt{lhs == rhs} and \texttt{lhs !=
rhs} requirements, as those types are implied by their operators.

Two more concepts are defined: one allowing dereferencing pointers
returning constant references and one returning modifiable references. To
allow the compiler to verify those requirements we also implicitly require the
(commonly encountered) existence of typename \texttt{Type::value\_type}:
        \begin{verbatim}
    template <typename Type>
    concept Dereferenceable =
        requires(Type type)
        {
            { *type } -> std::same_as<typename Type::value_type &>;
        };
\end{verbatim}
\begin{verbatim}
    template <typename Type>
    concept ConstDereferenceable =
        requires(Type type)
        {
            { *type } -> std::same_as<typename Type::value_type const &>;
        };
\end{verbatim}
Not much of a hierarchy so far, but that changes now that we're about to
define concepts for iterators. 

An input iterator is an iterator that is comparable, incrementable and
const-dereferenceable.  For each of these requirements concepts were defined
which can be combined using boolean operators when defining the concept
\texttt{InIterator}. Note that template type parameters of concepts \emph{must} use
the \texttt{typename} keyword. Concepts'
    \index{concept: constraints} template parameters cannot be constrained by
specifying them in terms of existing concepts (which \emph{is} possible when
defining function and class templates). 

Here is the definition of the concept \texttt{InIterator}. The function template
\texttt{inFun} (below the concept \texttt{InIterator}) illustrates how a
constrained template parameter type can be specified in template headers:
        \begin{verbatim}
    template <typename Type>
    concept InIterator =
        Comparable<Type> and Incrementable<Type> and
        ConstDereferenceable<Type>;
    
    template <InIterator Type>
    void inFun(Type tp)
    {}
\end{verbatim}
The concept for output iterators (and its use, as in the function
template \texttt{outFun}) is defined analogously. This time requiring
dereferenceable types rather than const-dereferenceable types:
        \begin{verbatim}
    template <typename Type>
    concept OutIterator =
        Comparable<Type> and Incrementable<Type> and
        Dereferenceable<Type>;
    
    template <OutIterator Type>
    void outFun(Type tp)
    {}
\end{verbatim}
For forward iterators the concept \texttt{FwdIterator} is defined. A forward
iterator combines the characteristics of input and output iterators, and we
may want to define a forward iterator by requiring the requirements of the
\texttt{InIterator} and \texttt{OutIterator} concepts.

However, there's a slight problem. The following class (struct) defines const
and non-const dereference operators and may be therefore be passed to
functions expecting input or output iterators:
        \begin{verbatim}
    struct Iterable
    {
        using value_type = int;
    
        Iterable &operator++();
        Iterable operator++(int);
    
        int const &operator*() const;
        int &operator*();
    };
    
    bool operator==(Iterable const &lh, Iterable const &rh);
    bool operator!=(Iterable const &lh, Iterable const &rh);
    int  operator-(Iterable const &lh, Iterable const &rh);
\end{verbatim}
But when a function template requires \texttt{ConstDerefenceable} arguments then
the compiler notices that the overloaded member \texttt{int \&operator$*$()} doesn't
return an \texttt{int const \&}. Even though \texttt{int const \&operator$*$() const} is
available compilation fails. This problem can be solved in two ways: noting
that an \texttt{int \&} can be converted to an \texttt{int const \&} the predefined
concept \texttt{std::convertible\_to} instead of \texttt{std::same\_as} can be used in
\texttt{ConstDereferenceable}; alternatively its \texttt{requires} clause can specify
\texttt{Type const \&type} instead of just \texttt{Type type}. Here is a definition of
\texttt{ConstDereferenceable} that, when defining the concept \texttt{FwdIter}, can be
used in combination with \texttt{Dereferenceable}:
        \begin{verbatim}
    template <typename Type>
    concept ConstDereferenceable =
        requires(Type const &type)
        {
            { *type } -> std::same_as<typename Type::value_type const &>;
        };
\end{verbatim}
The final two iterator types pose no problems: the concept \texttt{BiIterator}
requires the constraints of the concept \texttt{FwdIterator} as well as decrement
operators, and finally the concept \texttt{RndIterator} requires the constraints of
\texttt{BiIterator} and in addition iterator increments decrements for any step
size as well as the possibility to subtract iterators:
        \begin{verbatim}
    template <typename Type>
    concept BiIterator =
        FwdIterator<Type> and
        requires(Type type)
        {
            --type;
            type--;
        };
    
    template <typename Type>
    concept RndIterator =
        BiIterator<Type>
        and
        requires(Type lhs, Type rhs)
        {
            lhs += 0;
            lhs -= 0;
            lhs + 0;
            lhs - 0;
            { lhs - rhs } -> std::same_as<int>;
        };
\end{verbatim}
\subsection{Predefined concepts}\label{CXXCONCEPTS}
    \typeout{Original Yodl file: advancedtemplates/concepts/predefined}In the previous section we covered defining concept requirements. When
specifying some of the requirements already available concepts were used, like
\texttt{std::same\_as}. The \texttt{C++26} standard provides some 30 predefined concepts which
may be used to specify type requirements, to specify conversion requirements,
and to specify more advanced requirements, sometimes accepting variadic
template parameters. The currently predefined concepts are covered in the
following subsections.

\subsubsection{Concepts specifying one template type parameter}
        \typeout{Original Yodl file: advancedtemplates/concepts/oneparam}The following concepts specify just one template type parameter. Their generic
form is 
    \begin{verbatim}
    template <typename Type>
    concept Name = 
        ... requirements ...
        ;
\end{verbatim}
    When used in compound requirements only their names have to be
specified. For example (using the concept \texttt{std::boolean} (see below)), to
require that a function \texttt{fun} receiving an argument of some type \texttt{Type}
returns a boolean value, the following concept could be defined:
        \begin{verbatim}
template<typename Type>
    concept BoolFun = 
        requires(Type param)
        {
            { fun(param) } -> std::boolean;
        };
\end{verbatim}
\begin{itemize}
\item \texttt{boolean}:\ \\ requires that its type can be used in boolean expressions

\item \texttt{copy\_constructible}:\ \\ requires that objects of its type supports copy- and
    move-construction;

\item \texttt{copyable}:\ \\ requires that objects of its type support copy- and move-
    construction and assignment, and that two objects of its type can be
    swapped; 

\item \texttt{default\_initializable}:\ \\ requires that objects of its type support default
    constructors; 

\item \texttt{destructible}:\ \\ requires that the destructor of its type is defined as
    \texttt{noexcept(true)};

\item \texttt{equality\_comparable}:\ \\ requires that \texttt{operator==} is available to compare
    two objects of its type;

\item \texttt{floating\_point}:\ \\ requires that its type is a floating-point type;

\item \texttt{integral}:\ \\ requires that its type is an integral  type;

\item \texttt{movable}:\ \\ requires that its type supports moving and swapping. Note that
    full support for moving requires that its type supports move construction
    and move assignment;

\item \texttt{move\_constructible}:\ \\ requires that its type supports move construction;

\item \texttt{regular}:\ \\ requires that its type satisfies the requirements of the
    \texttt{semiregular} and \texttt{equality\_comparable} concepts;

\item \texttt{semiregular}:\ \\ requires that its type supports default construction,
    copying, moving, and swapping;

\item \texttt{signed\_integral}:\ \\ requires that its type is a signed integral type;

\item \texttt{swappable}:\ \\ requires that two objects of the same type can be swapped. The
    generic variant (see below) is named \texttt{swappable\_with};

\item \texttt{unsigned\_integral}:\ \\ requires that its type is an unsigned integral type;

\item \texttt{totally\_ordered}:\ \\ requires that two objects of identical
    types can be ordered using the operators \texttt{==, !=, $<$, $<$=, $>$,} and
    \texttt{$>$=}. The requirements for ordering is \index{ordering: strict}\emph{strict}:
    for any two objects \texttt{one} and \texttt{two} either \texttt{one $<$ two, one == two,}
    or \texttt{one $>$ two} is true. The generic variant is named
    \texttt{totally\_ordered\_with}.
\end{itemize}

\subsubsection{Concepts specifying two template type parameters}
        \typeout{Original Yodl file: advancedtemplates/concepts/twoparams}The following concepts define two template type parameters. Their generic
form is 
    \begin{verbatim}
    template <typename LHS, typename RHS>
    concept Name = 
        ... requirements ...
        ;
\end{verbatim}
    When used in compound requirements the compiler deduces the type of the
compound expression, and then uses that type as LHS. In the type requirement
following the compound statement only the RHS type is specified. For example
(using the concept \texttt{std::same\_as} (see below)), to require that a function
\texttt{fun}, receiving an argument of some type \texttt{Type}, returns a
\texttt{std::string} the following concept can be defined:
        \begin{verbatim}
template<typename Type>
    concept StringFun = 
        requires(Type param)
        {
            { fun(param) } -> std::same_as<std::string>;
        };
\end{verbatim}
\begin{itemize}
\item \texttt{assignable\_from}:\ \\ requires that RHS-typed expressions
    can be assigned to LHS-typed expressions;

\item \texttt{common\_reference\_with}:\ \\ requires that both types can be converted to an
    identical (reference) type. The concept is satisfied for two identical
    types, but also for two types where one of them is derived from the
    other. E.g., 
   \begin{verbatim}
template <typename LHS, typename RHS>
concept CommonRef = std::common_reference_with<LHS, RHS>;

template <typename T1, typename T2>
    requires CommonRef<T1, T2>
void fun(T1 &&t1, T2 &&t2)
{}

struct B
{};

struct D1: public B
{
};

int main()
{
    fun(4, 'a');
    fun(4.5, 'a');

    D1 d1;
    B b;

    fun(b, d1);     // objects, rvalue refs:
    fun(D1{}, B{}); // all OK
}
\end{verbatim}
\item \texttt{common\_with}:\ \\ works like the previous concept;

\item \texttt{convertible\_to}:\ \\ requires that the LHS type can automatically be converted
    to the RHS type:
   \begin{verbatim}
template <typename LHS, typename RHS>
concept Convertible =
    requires(LHS lhs)
    {
        { lhs } -> std::convertible_to<RHS>;
    };

template <typename RHS, typename LHS>
    requires Convertible<LHS, RHS>
void fun(LHS lhs)
{}

int main()
{                           // note: LHS is the <...>'s type
    fun<double>(12);        // from int to double
    fun<int>(12.5);         // from double to int
    fun<std::string>("a");  // from NTBS to string
//  fun<std::string>(12);   // constraints not satisfied
}
\end{verbatim}
\item \texttt{derived\_from}:\ \\ requires that the LHS type is derived from the RHS type;

\item \texttt{equality\_comparable\_with}:\ \\ requires that operators \texttt{operator==} and
    \texttt{operator!=} are available to compare LHS- and RHS-type variables (in
    any order);

\item \texttt{same\_as}:\ \\ requires that the LHS type is the same as the RHS type. Note
    that this concept acts rather strictly. For example, \texttt{std::same\_as$<$long
    int, int$>$} does not satisfy the requirement. If such a strict equality
    isn't really required then \texttt{convertible\_to} might offer a workable
    alternative;

\item \texttt{swappable\_with}:\ \\ requires that two objects of possibly different types can
    be swapped. The more restrictive variant requiring objects of identical
    types is named \texttt{swappable};

\item \texttt{totally\_ordered\_with}:\ \\ requires that two objects of possibly different
    types can be ordered using the operators \texttt{==, !=, $<$, $<$=, $>$,} and
    \texttt{$>$=}. The requirements for ordering is \index{ordering: strict}\emph{strict}:
    for any two objects \texttt{one} and \texttt{two} either \texttt{one $<$ two, one == two,}
    or \texttt{one $>$ two} is true. The more restrictive variant requiring objects
    of identical types is named \texttt{totally\_ordered}.
\end{itemize}

\subsubsection{Concepts specifying multiple template type parameters}\label{CXXMULTI} 
        \typeout{Original Yodl file: advancedtemplates/concepts/multipleparams}Most predefined concepts expecting more than two parameters are variadic
(cf. section \ref{CONPACK}). 

\begin{itemize}
\item \texttt{constructible\_from}:\ \\ requires a LHS type and a variadic template parameter
    representing the types from which LHS can be constructed (which may be
    empty if a default constructor is suppported). Here is an example:
   \begin{verbatim}
template <typename LHS, typename ...Args>
concept Constructible = std::constructible_from<LHS, Args...>;

template <typename T1, typename ...Args>
    requires Constructible<T1, Args...>
T1 fun(Args &&...t2)
{
    return T1( std::forward<Args>(t2)... );
}

int main()
{
    std::string s{ fun<std::string>(5, 'a') };
    std::string s2{ fun<std::string>() };   // slightly weird...
}
\end{verbatim}
\item \texttt{equivalence\_relation}:\ \\ this concept defines three template type
    parameters. It is a synonym of the concept \texttt{std::relation} (see below);

\item \texttt{invocable}:\ \\ requires a LHS type and a variadic template parameter
    representing the types which are forwared as arguments to the function or
    functor specified as \texttt{invocable's} first argument. Here is an example:
   \begin{verbatim}
template <typename Function, typename ...Params>
void fun(Function &&fun, Params &&...params)
    requires std::invocable<Function, Params ...>
{
    fun(std::forward<Params>(params)...);
}

void hello(int value, char const *txt, std::string const &str)
{
    std::cout << value << ' ' << txt << ' ' << str << '\n';
}

int main()
{
    fun(hello, 1, "text", "string");    // promotions are still OK
    // fun(hello, 1);                   // WC: not invocable
}
\end{verbatim}
\item \texttt{predicate}:\ \\ requires a LHS type which is a predicate (functor or function
    returning a \texttt{bool} value), expecting arguments of the variadic template
    parameter RHS. Here is an example:
   \begin{verbatim}
template <typename Container, typename Predicate>
concept Find_ifConcept =
    std::predicate<Predicate, typename Container::value_type>
    and
    requires(Container container)
    {
        { container.begin() } -> Iter;
        { container.end() }   -> Iter;
        { container.size() }  -> std::same_as<size_t>;
    };

template <typename Container, typename Predicate>
size_t findIdx_if(Container const &cont, size_t from, Predicate const &pred)
    requires Find_ifConcept<Container, Predicate>
{
    auto iter = std::find_if(cont.begin() + from, cont.end(), pred);
    return iter == cont.end() ? cont.size() : iter - cont.begin();
}

int main()
{
    std::cout << "Index at " <<
        findIdx_if(std::string{ "hello world" }, 0,
            [&](int ch)
            {
                return ch == ' ';
            }
        ) << '\n';

    int target = 4;
    fun(
        [&](int value)
        {
            return value == target;
        },
        4
    );
}
\end{verbatim}
\item \texttt{regular\_invocable}:\ \\ synonym of \texttt{invocable};

\item \texttt{relation}:\ \\ this concept defines three template type parameters. The first
    parameter is a predicate whose function call operator expects
    two arguments. The arguments are of the types of the second and/or third
    template type parameters (any combination, any order). 
    For example, the requirements of the \texttt{std::relation} concept are
    satisfied if the predicate's first template argument is \texttt{std::less}, the
    second argument is \texttt{int} and the third argument is \texttt{double}. 

In the following example \texttt{struct Less} is a functor comparing the
    two arguments of its function call operator. Next, the function \texttt{cmp}
    accepts such a struct type as predicate, verifying that the predicate and
    the arguments that are passed to the function satisfy the requirements of
    the \texttt{std::relation} concept. If so the functor's return value is
    returned.

Finally, in main \texttt{cmp} is first called with \texttt{int} and \texttt{double}
    arguments (which succeeds) and then with an \texttt{int} and a NTBS arguments:
    for the second call the constraints are not satisfied as \texttt{ints} and
    \texttt{NTBSs} can't be compared, and consequently compilation fails:
   \begin{verbatim}
template <typename LHS, typename RHS>
struct Less
{
    bool operator()(LHS lhs, RHS rhs) const
    {
        return lhs < rhs;
    }
};

template <template<typename LHS, typename RHS> typename Pred,
          typename LHS, typename RHS>
bool cmp(LHS lhs, RHS rhs)
    requires std::relation<Pred<LHS, RHS>, LHS, RHS>
{
    return Pred<LHS, RHS>{}(lhs, rhs);
}

int main()
{
    std::cout << cmp <Less>(5, 4.9) << '\n';
    std::cout << cmp <Less>(5, "hello world") << '\n';
}
\end{verbatim}
\item \texttt{strict\_weak\_order}:\ \\ this concept defines three template type
    parameters. The first parameter is the type of a predicate whose function
    call operator expects two arguments. The arguments are of the types of the
    second and/or third template type parameters (any combination, any
    order). The concept is satisfied if the predicate can verify that a strict
    weak order applies to its argument types. A relation is a strict weak
    ordering if 
    \begin{itemize}
    \item  the predicate returns false if an object is compared to itself;
    \item  the relation is transitive: if \texttt{pred(one, two)} and \texttt{pred(two,
        three)} are both true, then \texttt{pred(one, three)} is also true;
    \end{itemize}
\end{itemize}

\subsection{Applying concepts to template parameter packs}\label{CONPACK}
    \typeout{Original Yodl file: advancedtemplates/concepts/parampack}As we have seen (cf. section \ref{CXXMULTI}) concepts may process 
template parameter packs. Such concepts are called 
    \index{concept: variadic} \index{variadic concepts}\emph{variadic concepts}.  When defining
concept-protected variadic function or class templates variadic concepts
aren't always required. Consider the following function:
    \begin{verbatim}
    template <HasSize ...Types>
    void fun(Types &&...obj)
    {
        sum(std::forward<Types &&>(obj)...);
    }
\end{verbatim}
Here we see a variadic template, but it defines all its parameters as
constrained types by simply mentioning the concept \texttt{HasSize} instead of just 
\texttt{typename}. The \texttt{HasSize} concept is very basic: it merely requires that
\texttt{type.size()} exists, returning a \texttt{size\_t}:
    \begin{verbatim}
    template <typename Types>
    concept HasSize =
        requires (Types type)
        {
            { type.size() } -> std::same_as<size_t>;
        };
\end{verbatim}
Once \texttt{fun} has verified that all its argument types satisfy the \texttt{HasSize}
requirements no additional checks are necessary. The \texttt{fun} function
template merely forwards its arguments to \texttt{sum}, a variadic template, that
simply adds the return values of the \texttt{size()} members of its arguments:
    \begin{verbatim}
    size_t sum()
    {
        return 0;
    }
    
    template <typename First, typename  ...Types>
    size_t sum(First &&first, Types &&...types)
    {
        return first.size() + sum(std::forward<Types>(types)...);
    }
\end{verbatim}
The wrapper function \texttt{fun} isn't really required. The variadic template
function summing the various \texttt{size()} values itself can also be defined so
that its types themselves must satisfy the \texttt{HasSize} concept. Here is the
definition of the variadic function template \texttt{sum2} requiring precisely
that:
    \begin{verbatim}
    size_t sum2()
    {
        return 0;
    }
    
    template <HasSize First, HasSize  ...Types>
    size_t sum2(First &&first, Types &&...types)
    {
        return first.size() + sum2(std::forward<Types>(types)...);
    }
\end{verbatim}
And here is a \texttt{main} function calling \texttt{fun} and \texttt{sum2}:
    \begin{verbatim}
    int main()
    {
        fun(queue<int>{}, vector<int>{}, string{});
        cout << sum2(queue<int>{}, vector<int>{}, string{}) << '\n';
    }
\end{verbatim}
On the other hand, the predefined concept \texttt{std::constructible\_from} \emph{is} a
variadic concept, as it accepts a LHS template parameter and a RHS parameter
pack. This concept is satisfied if the LHS parameter can be constructed
from the types specified in its RHS parameter pack. After including
\texttt{type\_trait} defining and using such a concept is not very hard:
    \begin{verbatim}
    template <typename Class, typename ...Params>
    concept Constructible = std::is_constructible<Class, Params ...>::value;
    
    template <typename Class, typename ...Params>
        requires Constructible<Class, Params ...>
    void fun(Class &&type, Params &&...params)
    {}
\end{verbatim}
The recipe for writing variadic concepts is not very complex:
    \begin{itemize}
    \item  start the concept's definition with a template header specifying a
        parameter pack; 
    \item  pass the parameters to a type trait handling the pack;
    \end{itemize}
    To use the variadic concept in a function or class template its template
parameters are simply forwarded to the concept (as shown in the above
example). 

When no predefined variadic type trait is available the variadic concept must
use other means to determine whether its constraints are satisfied or not. In
those cases define your own variadic type traits. For illustration let's
assume we are looking for a variadic concept that can be used to verify that
the types of all the arguments that are passed to a variadic function template
are integral types. In this case there is no predefined type trait we can use,
so we have to define it ourselves. We define the concept \texttt{IntegralOnly} as a
variadic concept using our self-defined type trait \texttt{allIntegralTypes}, and
thereupon use it when defining a function requiring that all of its arguments
are integral values:
    \begin{verbatim}
    template <typename ...Types>
    concept IntegralOnly = allIntegralTypes<Types ...>::value;
    
    template <IntegralOnly ...Types>
    void fun(Types ...types)
    {}
\end{verbatim}
The generic type trait \texttt{allIntegralTypes} merely specifies that it accepts
any number of type parameters and uses specializations to handle specific
cases. One specific case is the case were no types are specified which simply
defines a \texttt{true static bool const} value:
    \begin{verbatim}
    template <typename ...Types>
    struct allIntegralTypes;
    
    template <>
    struct allIntegralTypes<>
    {
        static bool const value = true;
    };
\end{verbatim}
The type trait's partial specialization does the hard work: it determines
whether the first type is integral and combines that (using \texttt{and}) with the
\texttt{value} made available by the \texttt{struct allIntegralType} receiving the
remaining types:
    \begin{verbatim}
    template <typename First, typename ...Types>
    struct allIntegralTypes<First, Types ...>
    {
        static bool const value = std::is_integral<First>::value and
                                  allIntegralTypes<Types ...>::value;
    };
\end{verbatim}
The function \texttt{fun} can now be called with any number of arguments. As long
as the arguments are integral types the compilation succeeds and \texttt{fun} can
safely do its job.

\subsection{Applying concepts to free functions}
    \typeout{Original Yodl file: advancedtemplates/concepts/freefunctions}    \index{concept: used for function parameters}
Concepts are most often used in combination with classes. But concepts can
also be used with mere function templates, restricting their argument types.
Once a concept is applied to a function that function automatically becomes a
function template. Usually that's clear as a template header is used, but
a function can also define constrained parameter types without having to
provide its definition with a template header.

To illustrate the various ways concepts can be used when defining function
templates the concept \texttt{Addable} (cf. section \ref{CONDEF}) is used in the
following examples.
    \begin{itemize}
    \item  The requirement can be specified immediately following the template
        header: 
    \begin{verbatim}
    template <typename Type>
        requires Addable<Type>
    auto add(Type const &lhs, Type const &rhs) 
    {
        return lhs + rhs;
    }
\end{verbatim}
\item  The requirement can also be specified immediately following the
        function header: 
    \begin{verbatim}
    template <typename Type>
    auto add(Type const &lhs, Type const &rhs) requires Addable<Type>
    {
        return lhs + rhs;
    }
\end{verbatim}
    \end{itemize}

These variants allow us to specify the requirements in the most flexible
way. E.g., if the parameters should also be integral values, then the
\texttt{Addable} requirement is not enough, by we also need the \texttt{std::integral}
requirement, resulting in a function definition like
    \begin{verbatim}
    template <typename Type>
        requires Addable<Type> and std::integral<Type>
    auto add(Type const &lhs, Type const &rhs) 
    {
        return lhs + rhs;
    }
\end{verbatim}
    (which can also be used with the trailing \texttt{requires} specification).

If the \texttt{Addable} concept completely covers the arguments' requirements, then
the following abbreviated definitions can be used:
    \begin{itemize}
    \item  The template header uses the concept name instead of \texttt{typename}:
    \begin{verbatim}
    template <Addable Type>
    auto add(Type const &lhs, Type const &rhs) 
    {
        return lhs + rhs;
    }
\end{verbatim}
\item  \index{concept: using 'ConceptName auto'} The concept name itself is used
        as the parameter type. Note that in this form the template header
        isn't used, and the keyword \texttt{auto} follows the concept's name:
        \texttt{auto} informs the compiler that \texttt{Addable} is not the name of a
        plain type but the name of a concept:
    \begin{verbatim}
    auto add(Addable auto const &lhs, Addable auto const &rhs) 
    {
        return lhs + rhs;
    }
\end{verbatim}
    \end{itemize}

\subsection{Implementing constrained class members}
    \typeout{Original Yodl file: advancedtemplates/concepts/constrained}When defining members of class templates outside of their class interfaces the
members' template headers must match the class templates' template
headers. This is no different when using concepts.

In the following example the concept \texttt{Addable} is used when defining the
class template \texttt{Data}. The class \texttt{Data} declares a 
member \texttt{process}, implemented below the class interface. Like the class of
which it is a member its header must also specify \texttt{Addable} (cf. section
\ref{CONDEF}): 
        \begin{verbatim}
    template <Addable Type>
    class Data
    {
        void process();
    };

    template <Addable Tp>       // The concept must be specified,
    void Data<Tp>::process()    // but the formal type name 
    {                           // doesn't have to be `Type'
        ...
    }
\end{verbatim}
Comparably, if a class template member function can only be used when a
constraint has been satisfied (but no additional constraints apply to other
class members), the class template's header can use \texttt{typename} and the
(additional) constraint can be tailored to members where applicable:
        \begin{verbatim}
    template <typename Type>    // generic template type parameter
    class Data
    {
        void process() requires Addable<Type>;  // additional requirement
    };

    template <typename X>
    void Data<X>::process() requires Addable<X>
    ...
\end{verbatim}
Types of member templates themselves may also be constrained. Here too the
rule applies that the template headers of member implementations must match
those of their declarations:
        \begin{verbatim}
    template <typename Type>
    class Data
    {
        template <Addable Tp>       // constraint applied to
        void process(Tp par);       // a member template
    };

    template <typename Type>
    template <Addable Tp>
    void Data<Type>::process(Tp par)
    {
        ...
    }
\end{verbatim}
\subsection{Constrained partial specializations}
    \typeout{Original Yodl file: advancedtemplates/concepts/specializations}Class templates can be (partially) specialized. Specializations are commonly
used to fine-tune implementations for specific types. Concepts can also be
used when specializations are defined. Consider a \texttt{struct Handler} having
the following generic implementation:
    \begin{verbatim}
    template <typename Tp>
    struct Handler
    {
        Handler()
        {
            std::cout << "Generic Handler\n";
        }
    };
\end{verbatim}
In addition to possibly type-related specializations (like a \texttt{struct
Handler$<$Tp $*$$>$ ...}) a specialization requiring the availability of the
addition operator on \texttt{Tp} can be defined by requiring the concept
\texttt{Addable}:
    \begin{verbatim}
    template <Addable Tp>       // constrain Tp to addable types
    struct Handler<Tp>
    {
        Handler()
        {
            std::cout << "Handler for types supporting operator+\n";
        }
    };
\end{verbatim}
When used in the following program (assuming all required headers were
included), the first line of the output shows \emph{Generic Handler}, while
the second line shows \emph{Handler for types supporting operator+}:
    \begin{verbatim}
    int main()
    {
        Handler<std::vector<int>>{};    // generic
        Handler<int>{};                 // specialized
    }
\end{verbatim}
The compiler, compiling \texttt{main's} first statement, first looks for
a specialized version of \texttt{Handler}. Although it finds one, that
specialization requires the availability of \texttt{operator+}. As that operator is
not available for \texttt{std::vector} the compiler does not use that
specialization. Had this been the only available implementation, then the
compiler would have reported a \texttt{constraints not satisfied} error. However,
there's still the generic definition which \emph{can} be used for
\texttt{std::vector}. Therefore the compiler uses the generic definition (which is
at the same time provides a nice illustration of the SFINAE (cf. section
\ref{SFINAE}) principle). 

When instantiating the second \texttt{Handler} object the addition operator \emph{is}
available, and so in that case the compiler selects the specialized version:
where available, specializations are used; if not, then generic template
definitions are used.

\subsubsection{Function- and class template declarations}
        \typeout{Original Yodl file: advancedtemplates/concepts/declarations}Constrained function- or class-templates can be declared as usual:
instead of the implementations semicolons are used. When declaring a function-
or class-template without constraint specifications then the function or class
template is unconstrained and won't match existing constrained overloaded
versions of such function or class templates. On the other hand,
    \index{concept: declaration} concepts can\emph{not} be declared. So if a concept
definition must be used in multiple source or header files then the concept
definition normally is provided in a header file of its own which is then
included by files using the concept.

Here are some simple examples illustrating how constrained 
function templates are declared:
    \begin{verbatim}
    template <typename Type>    // advice: define concepts in
    concept Addable =           // separate headers.
        requires(Type lh, Type rh)
        {
            lh + rh;
        };
    
    template <typename Type>    // declares an unconstrained
    void fun();                 // function template
    
    template <Addable Type>     // declares a constrained overloaded
    void fun();                 // function template
    
    template <typename Type>    // same, requirement follows fun
    void fun() requires Addable<Type>;
    
    template <typename Type>    // same, requirement precedes fun
    requires Addable<Type> void fun();
\end{verbatim}
When declaring class templates their requires-clauses must precede the class
names. Also, when unconstrained class templates are available the constrained
class templates are in fact specializations and must be declared accordingly:
    \begin{verbatim}
    template <typename Type>    // unconstrained
    struct Data;                // declaration
    
    template <Addable Type>     // constrained declaration
    struct Data<Type>;          // (i.e., a specialization)
    
    template <typename Type>    // same specialization
    requires Addable<Type> struct Data<Type>;
\end{verbatim}
Multiple constraints can also be declared:
    \begin{verbatim}
    template <typename Type>        // used concepts
    concept C1 = true;
    template <typename Type>
    concept C2 = true;
    
    template <C1 Type>              // multiply constrained
    requires C2<Type> void fun();   //    function template
    
    template <typename Type>        // same, using 'and'
    requires C1<Type> and C2<Type> void fun();
    
    template <typename Type>        // same, trailing 'requires'
    void fun() requires C1<Type> and C2<Type>;
    
    template <typename Type>
    struct Multi;
    
    template <C1 Type>              // multiply constrained
    requires C2<Type> struct Multi<Type>; // class template
\end{verbatim}
Although specializations may define different constraints (e.g., there may
also be a concept \texttt{Subtractable}), a \texttt{Data} specialization for
subtractable types might also be defined:
        \begin{verbatim}
    template <Subtractable Type>
    struct Data<Type>
    {};
\end{verbatim}
But this is probably not what you want: when defining \texttt{Data$<$vector$<$int$>$$>$\{\}},
where \texttt{template$<$typename Type$>$ Data} is merely declared, the compiler
complains about an \emph{incomplete type `struct Data$<$std::vector$<$int$>$$>$'} as it
cannot use the specialization for either \texttt{Addable} or \texttt{Subtractable}. So
it falls back on the generic template, but for that one no implementation is
available, and hence it's incomplete.

Defining a template requiring two types, the first being \texttt{Addable} and the
second template argument being unrestricted, while a specialization is defined
requiring a \texttt{Subtractable} type and an \texttt{int}, then that also
does'n work as intended. In that case, the templates might be:
    \begin{verbatim}
    template <typename t1, typename t2> requires Addable<t1>
    struct Data
    {};
    
    template <Subtractable Type>
    struct Data<Type, int>
    {};
\end{verbatim}
Here, if the first template argument isn't a subtractable type (like a
\texttt{vector$<$int$>$}), and the second argument \emph{is} an \texttt{int} then the compiler
simply won't use it because the 1st argument isn't a subtractable type. 

Therefore it falls back to the first (generic) template definition. However,
that one doesn't work either, because the first argument also isn't
addable, and you receive complaints about \texttt{(lh + rh)} being ill-formed. 

Now, as you specified \texttt{int} as the template's second argument chances are
that you expected a complaint about \texttt{(lh - rh)} being ill formed, but that
doesn't happen.  In other words: using concepts still requires you to
understand what's going on. Concepts help the compiler to pinpoint reasons
for compilation failures, but in the end it's you who has to understand what
you're doing in order to grasp what the compiler is trying to tell you.

\subsubsection{Bound free-operators}\label{BOUNDCONCEPT}
        \typeout{Original Yodl file: advancedtemplates/concepts/boundfriends}Earlier, in section \ref{FREEBOUND} the construction of free operators of
nested classes of template classes was covered. There the nested classes
defined typenames which were thereupon used to select the appropriate free
operators by defining template parameters of the typenames that were defined
by the nested classes.

Concepts provide yet another way to define free operators, bound to the types of
the nested classes' template types. When using concepts the class
templates and their nested classes can be defined in their most basic form, as
in: 
    \begin{verbatim}
    template <typename Data>
    struct String
    {
        struct iterator
        {
            using value_type        = Data;
    
            std::string::iterator d_iter;
    
                // Note the <>: operator== is a function template
                // specialization as 'iterator' is a class template
            friend bool operator==<>(iterator const &lhs, iterator const &rhs);
        };
        iterator begin()
        {
            return iterator{};
        }
    };
\end{verbatim}
Once the class interface (\texttt{struct String}) has been specified the concept
can be formulated. It simply requires that the arguments of the free operators
are \texttt{String$<$Data$>$::iterator} objects:
    \begin{verbatim}
    template<typename Type>
    concept StringIterator =
        std::same_as<Type,
                     typename String<typename Type::value_type>::iterator>;
\end{verbatim}
The free operator(s) can now be defined as a function template using the
abbreviated \texttt{StringIterator auto} type specification:
    \begin{verbatim}
    inline bool operator==(StringIterator auto const &lhs,
                           StringIterator auto const &rhs)
    {
        return lhs.d_iter == rhs.d_iter;
    }
\end{verbatim}
By using concepts when defining free operators of nested classes of class
templates we achieve that those operators are bound to the template types of
those class templates, and that the free operators perfectly match those
(nested) classes. Furthermore, when designing the class templates the software
engineer can concentrate on the class's essential characteristics without
having to consider special type-definitions, which are required when using the
\emph{sfinae} approach covered in section \ref{FREEBOUND}.


\cleardoublepage\chapter{Coroutines}\label{COROUTINES}
\typeout{Original Yodl file: coroutines}\typeout{Original Yodl file: coroutines/intro.yo}Consider the following assignment: design a program that offers a function
\texttt{next} returning the next fibonacci number at subsequent
calls.\footnote{Fibonacci numbers start with 0 and 1. The next fibonacci number
is the sum of the last two fibonacci numbers. The sequence, therefore, starts
with 0, 1, 1, 2, 3, 5, etc. In this and the following examples fibonacci
sequences are frequently used for illustration, and not because they are
inherently related to coroutines.}

Here is an example of how such a program could be designed: it defines a class
\texttt{Fibo} and in \texttt{main Fibo::next} is called to compute the next fibonacci
number (for brevity the program uses a single source file):
        \begin{verbatim}
    #include <iostream>
    #include <string>

    using namespace std;

    class Fibo
    {
        size_t d_return = 0;
        size_t d_next = 1;

        public:
            size_t next();
    };

    size_t Fibo::next()
    {
        size_t ret = d_return;      // the next fibonacci number

        d_return = d_next;          // at the next call: return d_next;
        d_next += ret;              // prepare d_next as the sum of the
                                    // original d_return and d_next
        return ret;
    }

    int main(int argc, char **argv)
    {
        Fibo fibo;                  // create a Fibo object

        size_t sum = 0;

                                    // use its 'next' member to obtain
        for (                       // the sequence of fibonacci numbers
            size_t begin = 0, end = argc == 1 ? 10 : stoul(argv[1]);
                begin != end;
                    ++begin
        )
            sum += fibo.next();

        cout << sum << '\n';
    }
\end{verbatim}
Clearly the \texttt{next} member isn't all that complicated. But when it's called
several actions are performed which themselves are unrelated to computing
fibonacci numbers:
    \begin{itemize}
    \item  Calling a function boils down to (ignoring
            the complications when copying and destroying value type argument
            objects and value type local objects):
        \begin{itemize}
        \item  pushing its arguments on the stack (note that \texttt{next} is a
            member function, so it \emph{does} have an argument: the address of
            the object for which \texttt{next} is called); 
        \item  pushing the number of bytes required for those arguments on the
            stack; 
        \item  pushing the location of the next instruction to execute after
            completing the \texttt{next} function call on the stack;
        \item  pushing the location of the current function's stack frame on the
            stack;
        \item  copying the current stack pointer's value to a register (commonly
            called the \emph{base pointer}), which register is then used to
            access \texttt{next's} arguments and local variables;
        \item  continuing execution at \texttt{next's} first instruction;
        \item  which first makes room on the stack for all of \texttt{next's}
            local variables.
       \end{itemize}
    \item  once \texttt{next's return} statement has been executed:
        \begin{itemize}
        \item  the stack pointer is reset to the value stored in the base
            pointer, thus removing local variables from the stack;
        \item  popping the base pointer, thus restoring access to the caller's
            stack frame;
        \item  popping the value of the caller's next instruction to execute
            from the stack;
        \item  reducing the size of the stack by the value currently at the top
            of the stack, holding the size of the function's arguments.
        \end{itemize}
    \end{itemize}

These steps, although they look like a lot, in practice don't take that much
time, because most of them are performed by very fast register operations, and
the computer' architecture is usually highly optimized for these steps. 

Nonetheless, in situations where the functions themselves are short and simple
(like \texttt{Fibo::next}) these steps, requiring stack- and register
manipulations, might be considered unwelcome, raising the question whether
they may be avoided.

\textbf{C++} \emph{coroutines} allow us to avoid executing the steps that are required
when calling ordinary functions. The upcoming sections cover coroutines in
depth, but here is, for starters, the coroutine's equivalent of
\texttt{Fibo::next}:
        \label{FIBOCORO}
        \begin{verbatim}
     1: #include "main.ih"
     2: 
     3: Fibo fiboCoro()
     4: {
     5:     size_t returnFibo = 0;
     6:     size_t next = 1;
     7: 
     8:     while (true)
     9:     {
    10:         size_t ret = returnFibo;
    11: 
    12:         returnFibo = next;
    13:         next += ret;
    14: 
    15:         co_yield ret;
    16:     }
    17: }
\end{verbatim}
Already now we can observe some characteristics of the \texttt{fiboCoro} coroutine:
    \begin{itemize}
    \item  although coroutines \emph{can} be defined as class members, this
        particular coroutine is not. It's a free function, which therefore
        doesn't have a (hidden) pointer pointing to the object calling the
        coroutine;
    \item  more importantly: it defines local variables (especially those in
        lines 5, 6), which \emph{keep their values} between successive
        calls. Such local variables are like static variables, but they're
        not. Each coroutine-call receives its own instances of its local
        variables;
    \item  Lines 8 thru 16 define a continuous loop where each cycle computes
        the next fibonacci number;
    \item  Once a fibonacci number is available the coroutine is \emph{suspended}
        (at line 15) without loosing the just computed values, passing \texttt{ret}
        to the coroutine's caller (the keyword \index{co\_yield}\texttt{co\_yield} is one of three
        new keywords which can be used by coroutines; the other two being
        \index{co\_await}\texttt{co\_await} and \index{co\_return}\texttt{co\_return}).
    \end{itemize}

While \texttt{fiboCoro} lays the foundation for obtaining a sequence of
fibonacci numbers, resuming a coroutine doesn't mean calling a function the
way the above member \texttt{Fibo::next} is called: there are no arguments; there
is no preparation of local variables; and there is no stack
handling. Instead there's merely a direct jump to the instruction just beyond
the coroutine's suspension point. When the coroutine's code encounters the
next suspension point (which occurs in \texttt{fiboCoro} at it's next cycle,
when it again reaches its \texttt{co\_yield} statement) then the program's execution
simply jumps back to the instruction following the instruction that resumed
the coroutine.

The \texttt{main} function using the coroutine looks very similar to the \texttt{main}
function using the class \texttt{Fibo}:
        \begin{verbatim}
     1: #include "main.ih"
     2: 
     3: int main(int argc, char **argv)
     4: {
     5:     Fibo fibo = fiboCoro();
     6: 
     7:     size_t sum = 0;
     8: 
     9:     for (                       // the sequence of fibonacci numbers
    10:         size_t begin = 0, end = argc == 1 ? 10 : stoul(argv[1]);
    11:             begin != end;
    12:                 ++begin
    13:     )
    14:         sum += fibo.next();
    15: 
    16:     cout << sum << '\n';
    17: }
\end{verbatim}
At line 5 \texttt{fiboCoro} is called, returning an (as yet not covered)
\texttt{fibo} thing. This \texttt{fibo} thing is called a \index{coroutine handle}
\emph{coroutine handler}, and when (in line 14) \texttt{fibo.next()} is called, then
\emph{that} call resumes \texttt{fiboCoro}, which is then again suspended at its
\texttt{co\_yield} statement, returning the next available value through the
handler's \texttt{next} function.

The core feature of coroutines is thus that they may suspend their execution,
while keeping their current state (values of variables, location of the next
instruction to be executed, etc.). Normally, once suspended, the coroutine's
caller resumes its work beyond the instruction that returned the coroutine's
next value, so those two functions (the coroutine and its caller) closely
cooperate to complete the implemented algorithm. Co-routines are therefore
also known as
    \index{cooperating routines}\emph{cooperating routines}, which should not be confused with
\emph{concurrent} (multi-threaded) routines.

How this whole process works, and what its characteristics are, is covered in
the upcoming sections. 

\section{Defining a coroutine}
\typeout{Original Yodl file: coroutines/defining.yo}

When defining coroutines the \index{coroutine: header file}\texttt{$<$coroutine$>$} header file must be included.

A function is a coroutine once it uses the keywords \index{co\_yield}\texttt{co\_yield},
\index{co\_await}\texttt{co\_await}, or \index{co\_return}\texttt{co\_return}. A coroutines cannot use the \texttt{return}
keyword, cannot define variadic parameters, and its return type must be an
existing type, which defines the \index{handler (coroutine)} \emph{coroutine's
handler}.

Although coroutines appear to return objects (as suggested by the \texttt{Fibo}
return type of the \texttt{Fibo fiboCoro()} coroutine defined in the
previous section), in fact they do not. Instead coroutines return
so-called `handlers'. Such a handler is \texttt{fibo}, defined and used in the
previous section's \texttt{main} function:
        \begin{verbatim}
    int main(int argc, char **argv)
    {
        auto fibo = fiboCoro();
        ...
        sum += fibo.next();
        ...
    }
\end{verbatim}
The class \texttt{Fibo} itself defines the characteristics allowing the compiler to
generate code storing the coroutine's arguments, its local variables, the
location of the next instruction to execute when the coroutine returns or is
suspended, and its so-called \index{promise\_type}\emph{promise\_type} object on the heap. This only
happens once, so when the coroutine is activated (as in \texttt{sum +=
fibo.next()}) the steps which are normally taken when a function is called are
avoided, and instead the coroutine is immediately executed, using its already
available local variables and arguments.
    \index{future (coroutine)}\index{promise\_type (coroutine)}\index{cooperating routine} 
    Coroutine's handler classes are sometimes called \texttt{Future}, and their
nested state classes \emph{must} be known as the handler's \texttt{promise\_type}. The
names \emph{future} and \emph{promise\_type} are completely unrelated to the
\texttt{std::future} (cf. section \ref{FUTURE}) and \texttt{std::promise} (cd. section
\ref{PROMISE}) types which are used in the context of multi threading. In fact,
coroutines themselves are unrelated to multi threading, but are known as
\emph{cooperating routines}. Because the coroutines' handler and state classes
are unrelated to the \texttt{future} and \texttt{promise} classes used in the context of
multi threading in this chapter the terms \emph{Handler} and \texttt{State} are
generally used.

It's one thing to define a coroutine, but when using a coroutine its
handler-class (the \texttt{Fibo} class in the current example) must also be
defined. In addition, \index{promise\_type} such a handler-class \emph{must} define a
nested class whose name \emph{must} be publicly available as the handler's
\texttt{promise\_type}. The name \texttt{promise\_type} doesn't very well cover its
purpose, and using a more descriptive class name might be preferred. In that
case a simple using declaration in the handler class's public section can be
used, as shown in the following basic design of the \texttt{Fibo} handler-class:
        \begin{verbatim}
    #include <coroutine>

    class Fibo
    {
        class State     // keeps track of the coroutine's state
        {
            ...
        };

        std::coroutine_handle<State> d_handle;

        public:
            using promise_type = State;

            explicit Fibo(std::coroutine_handle<State> handle);
            ~Fibo();

            size_t next();
    };
\end{verbatim}
The coroutine's handler class has the following characteristics:
    \begin{itemize}
    \item  it has a nested class (here: \texttt{State}) keeping track of the
        couroutine's state;
    \item  it commonly defines a private data member of the type
        \index{std::coroutine\_handle\textless{}State\textgreater{}}\texttt{std::coroutine\_handle$<$State$>$}, e.g.,
        \texttt{std::coroutine\_handle$<$State$>$ d\_handle}, whose members are covered
        below;
    \item  Unless the handling class's nested class is called \texttt{promise\_type} a
        using declaraction must be specified to make the nested class name
        also known as \texttt{promise\_type};
    \item  Other members are optional, although usually there is at least a
        member returning a value that's available in the coroutine's state,
        like the member \texttt{next} which was used in the example's \texttt{main}
        function: 
       \begin{verbatim}
    sum += fibo.next();
\end{verbatim}
       The \texttt{next} member's current implementation resumes the coroutine.
        This doesn't mean that when \texttt{next} is called for the first time,
        that it's the very first activation of the coroutine: the call \texttt{auto
        fibo = fiboCoro()} comes first, and constructing and returning the
        coroutine's handler (thereby suspending the coroutine at its very
        first statement) is done automatically. At that point the caller
        receives the coroutine's handler object, and constructing and
        returning the handler object isn't visible in the coroutine's code
        (more about that in the next section). Once suspended at \texttt{co\_yield}
        the value that's available in the coroutine's \texttt{State} is returned
        and made available to the coroutine's caller:
       \begin{verbatim}
    size_t Fibo::next()
    {
        d_handle.resume();
        return d_handle.promise().value();
    }
\end{verbatim}
\end{itemize}

The following members can be called via the Handler's \texttt{d\_handle} data
        member:
    \begin{itemize}
    \item \texttt{void $*$address()} \index{address} returning the address of the handler's
        \texttt{State} object;
    \item \texttt{void destroy()}, \index{destroy} returning the \texttt{State} object's memory
        to the operating system. It ends the \texttt{State} object's
        existence. Usually the handler class's destructor calls
        \texttt{d\_handle.destroy()};
    \item \texttt{bool done(),} \index{done} returning \texttt{true} when the coroutine has
        returned, and \texttt{false} if it's currently suspended;
    \item \texttt{coroutine\_handle from\_address(void $*$address)} \index{from\_address} returns
        a \texttt{coroutine\_handle} corresponding to the address of a handler's
        \texttt{State} object, which address is passed to the function as its
        argument. A \texttt{nullptr} can also be passed to \texttt{from\_address};
    \item \texttt{explicit operator bool(),} \index{operator bool [coroutine]} returning
        \texttt{true} if \texttt{d\_handle} is not a null-pointer. It's commonly used in
        the handler's destructor's \texttt{if (d\_handle)} phrase. It returns
        \texttt{false} after assigning 0 (or \texttt{nullptr}) to \texttt{d\_handle}. This
        operator and \texttt{static\_cast$<$bool$>$(d\_handle.address())} act identically
        (note that \texttt{d\_handle.address()} is still valid after assigning 0 to
        \texttt{d\_handle}, in which case it returns 0);
    \item \texttt{State \&promise(),} \index{promise [coroutine]} returning a reference to
        the \texttt{Handler's State} class;
    \item \texttt{void resume()} \index{resume} \index{operator() [coroutine]}
        (or \texttt{void operator()()}) resumes the execution of a suspended
        coroutine. Resuming a coroutine is only defined if the coroutine is
        actually suspended.
    \end{itemize}

The \texttt{Handler's State} class keeps track of the coroutine's state. Its basic
elements are covered in the next section.

\subsection{The coroutine's State class (promise\_type)}
    \typeout{Original Yodl file: coroutines/state.yo}The class \texttt{Handler::State} keeps track of the coroutine's state. It must
publicly be known as the class \texttt{Handler::promise\_type}, which can be
realized using a public using-declaration associating a more appropriately
named class with `\texttt{promise\_type}'.

In the current example the class name \texttt{State} is used, having the following
interface:
        \begin{verbatim}
        class State
        {
            size_t d_value;

            public:
                Fibo get_return_object();

                std::suspend_always yield_value(size_t value);

                static std::suspend_always initial_suspend();
                static std::suspend_always final_suspend() noexcept;
                static void unhandled_exception();

                static void return_void();

                size_t value() const;
        };
\end{verbatim}
This \texttt{State} class doesn't declare a constructor, so its default
constructor is used. It's also possible to declare and define the default
constructor. Alternatively, by declaring and defining a constructor that has
the same parameters as its coroutine (or parameters that can be initialized by
the coroutine's parameters) that constructor is called when the coroutine
returns its handling object. E.g., if a coroutine's signature is
        \begin{verbatim}
    Handler coro(int value, string const &str);
\end{verbatim}
    and the \texttt{State} class has a constructor
        \begin{verbatim}
    Handler::State::State(int value, string const &str);
\end{verbatim}
    then that constructor is called. \texttt{State's} default constructor is called
if such a constructor is not available. In addition to calling \texttt{State's}
constructor a coroutine can also use an \emph{awaiter} to pass arguments to the
handler's \texttt{State} class. This method is covered in section \ref{SETSTATE}.

The data member \texttt{d\_value} and member function \texttt{value()} are specifically
used by the class \texttt{Fibo}, and other coroutine state classes might declare
other members. The remaining members are required, but the members returning
\index{suspend\_always (std::)} \texttt{std::suspend\_always} could also be declared
as members returning \index{suspend\_never (std::)} \texttt{std::suspend\_never}. 

By returning the (empty) structs \texttt{suspend\_always} the coroutine's actions
are suspended until resumed. In practice \texttt{suspend\_always} is used, and so
the \texttt{...\_suspend} members can be declared \texttt{static}, using these basic
implementations:
        \begin{verbatim}
    inline std::suspend_always Fibo::State::initial_suspend() 
    { 
        return {}; 
    }
    inline std::suspend_always Fibo::State::final_suspend() noexcept
    { 
        return {}; 
    }
\end{verbatim}
    Likewise, the \texttt{unhandled\_exception} member can be declared static when
it simply retrows exceptions that may be thrown by the coroutine:
        \begin{verbatim}
    inline void Fibo::State::unhandled_exception()
    {               // don't forget: #include <future>
        std::rethrow_exception(std::current_exception());
    }
\end{verbatim}
    The (required) member \texttt{Fibo::State::get\_return\_object} returns an
object of the coroutine's handling class (so: \texttt{Fibo}). The recipe is:
    \begin{itemize}
    \item  pass the current object (which is the coroutine's state
        object) to the member \texttt{from\_promise} of an anonymous object of the
        class \texttt{std::coroutine\_handle$<$State$>$};
    \item  that anonymous object is a \emph{handle} which is passed as argument to
        the constructor of the coroutine's handler class (i.e., the class
        \texttt{Fibo});
    \item  this \texttt{Fibo} object is then returned by
        \texttt{State::get\_return\_object}.
    \end{itemize}

Here is \texttt{Fibo::State::get\_return\_object's} implementation:
        \begin{verbatim}
    inline Fibo Fibo::State::get_return_object()
    {
        return Fibo{ std::coroutine_handle<State>::from_promise(*this) };
    }
\end{verbatim}
  The member \texttt{Fibo:State::yield\_value} can be overloaded for different
argument types. In our \texttt{Fibo::State} there's only one \texttt{yield\_value}
member, storing its parameter value in the \texttt{State::d\_value} data member. It
also suspends the coroutine's execution as it returns \texttt{std::suspend\_always}:
   \begin{verbatim}
    inline std::suspend_always Fibo::State::yield_value(size_t value) 
    {
        d_value = value;
        return {};
    }
\end{verbatim}
  Now that the coroutine's handling class and its \texttt{State} subclass have been
covered, let's have a closer look at what happens when the \texttt{main} function
from the introductory section is executed. Here's \texttt{main} once again:
        \begin{verbatim}
     1: int main(int argc, char **argv)
     2: {
     3:     auto fibo = fiboCoro();
     4: 
     5:     size_t sum = 0;
     6: 
     7:     for (                       // the sequence of fibonacci numbers
     8:         size_t begin = 0, end = argc == 1 ? 10 : stoul(argv[1]);
     9:             begin != end;
    10:                 ++begin
    11:     )
    12:         sum += fibo.next();
    13: 
    14:     cout << sum << '\n';
    15: }
\end{verbatim}
When called with argument `2' the following happens:
    \begin{itemize}
    \item  at line 2 the program starts;
    \item  at line 3 it looks as though \texttt{fiboCoroutine} is called (see the
        introduction section \ref{FIBOCORO} for its definition),
        but before that: 
       \begin{itemize}
        \item \texttt{State::get\_return\_object} is called, returning a \texttt{Fibo}
            object. Note here that \texttt{fiboCoroutine} itself nowhere returns a
            \texttt{Fibo} object, even though its definition suggests that it does.
            The \texttt{get\_return\_object} member \emph{does} call \texttt{Fibo's}
            constructor though, and this \texttt{Fibo} object is returned at line
            3.
        \item  immediately after constructing the \texttt{Fibo} object the
            coroutine's execution is suspended (as 
            \texttt{Fibo::State::initial\_suspend} is automatically called).
        \end{itemize}
       Next, still at line 3, the returned \texttt{Fibo} object is assigned to
        \texttt{fibo}. The current implementation uses \texttt{auto fibo = ...}, but
        \texttt{Fibo fibo = ...} may also be used. Using \texttt{auto} might be
        attractive if the name of the coroutine handling class's type is
        rather convoluted;
    \item \texttt{main's} execution continues at line 12 where \texttt{fibo.next()} is
        called;
    \item \texttt{fibo.next()} resumes the coroutine by calling \texttt{d\_handle.resume()}.
        As this is the very first time that the coroutine is explicitly called
        it now starts its execution at the first statement written by the
        coroutine's author;
    \item  the coroutine continues its execution until it reaches a
        \texttt{co\_yield, co\_await}, or \texttt{co\_return} keyword. In this case it's
        \texttt{co\_yield}, returning the current fibonacci value (\texttt{size\_t ret});
    \item  since a \texttt{State::yield\_value} member whose parameter type matches
        \texttt{ret's} type exists, that member is called, receiving \texttt{ret's}
        value as its argument. As \texttt{yield\_value} returns
        \texttt{std::suspend\_always} the coroutine is again suspended;
    \item  once suspended control is returned to \texttt{Fibo::next's} next
        statement, where \item \texttt{Fibo's d\_handle} uses its member \texttt{promise()} to
        reach the handler's \texttt{State} object, allowing \texttt{next} to return 
        \texttt{State::value()} (which is the most recently computed fibonacci
        value, stored in the \texttt{State} 
        object when \texttt{State::yield\_value} was called). 
        \texttt{Fibo::next()} returns that value;
    \item  after completing line 12 the \texttt{for}-statement continues at line 7,
        once again reaching line 12.
    \item  at subsequent iterations the coroutine continues beyond the statement
        where it was suspended (at its \texttt{co\_yield} statement). So it doesn't
        continue at the coroutine's first statement but continues its
        execution by performing the statements of its \texttt{while (true)}
        statement until again reaching its \texttt{co\_yield} statement, as
        described above; 
    \item  after two iterations the \texttt{for}-statement ends, and just before the
        program ends (at line 15) \texttt{Fibo's} destructor is automatically
        called, returning the memory allocated for the coroutine's data to the
        common pool.
    \end{itemize}

\subsubsection{What if `suspend\_never' is used?}
        \typeout{Original Yodl file: coroutines/suspendnever.yo}What if, instead of returning \texttt{std::suspend\_always State's} members return
\texttt{std::suspend\_never}? In that case the coroutine, once it has started, is is
never suspended. If the program computing fibonacci numbers is then called
with argument 2, the following happens:
    \begin{itemize}
    \item  at line 2 the program starts;
    \item  at line 3 it looks as though \texttt{fiboCoroutine} is called,
        but before that: 
       \begin{itemize}
        \item \texttt{State::get\_return\_object} is called, returning a \texttt{Fibo} object
            at line 3.
        \item  immediately after constructing the \texttt{Fibo} object the
            coroutine's execution continues, as this time
            \texttt{Fibo::State::initial\_suspend} doesn't suspend. The \texttt{fibo}
            object, however, has been constructed since \texttt{auto fibo = ...}
            isn't an assignment but an initialization of the \texttt{fibo} object.
        \end{itemize}
    \item  Since the coroutine's execution isn't suspended, it starts to
        iterate, and so it calls \texttt{co\_yield}. But although
        \texttt{Fibo::State::yield\_value} is called at \texttt{co\_yield} calls the
        coroutine isn't suspended, as \texttt{yield\_value} now returns
        \texttt{suspend\_never}.
    \item  So the coroutine continues its loop, assigning the next fibonacci
        number to \texttt{State::d\_value} at each subsequent iteration.  Since the
        loop isn't suspended and since there's no other exit from the
        loop, the program continues until it's terminated by some signal (like
        ctrl-C).
    \end{itemize}

\subsection{Simplifying the state class}\label{STATEBASE}
    \typeout{Original Yodl file: coroutines/statebase1.yo}Since the coroutine handler's state classes can often use the shown minimal
implementations for its members, it might be attractive to define those
members in a separate base-class, thus simplifying the state class's interface
and implementation.

Looking at the \texttt{Fibo::State} class, its members \texttt{initial\_suspend,
final\_suspend} and \texttt{unhandled\_exception} are good candidates for such a base
class. By defining the base class as a class template, receiving the coroutine
handler's class name and the handler's state class name as its template type
parameters then it can also provide the handler's \texttt{get\_return\_object}
member. 

Here is how this base class can be defined. It is used by the coroutine
handler's state classes developed in this chapter:
    \begin{verbatim}
    #include <cstddef>
    #include <future>
    #include <coroutine>
    
    template <typename Handler, typename State>
    struct PromiseBase
    {
        Handler get_return_object();
    
        static std::suspend_always initial_suspend();
        static std::suspend_always final_suspend() noexcept;
        static void unhandled_exception();
        static void return_void();
    };
    
    
    template <typename Handler, typename State>
    inline void PromiseBase<Handler, State>::return_void()
    {}
    
    template <typename Handler, typename State>
    inline std::suspend_always PromiseBase<Handler, State>::initial_suspend()
    {
        return {};
    }
    
    template <typename Handler, typename State>
    inline std::suspend_always PromiseBase<Handler, State>::final_suspend() noexcept
    {
        return {};
    }
    
    template <typename Handler, typename State>
    inline void PromiseBase<Handler, State>::unhandled_exception()
    {
        std::rethrow_exception(std::current_exception());
    }
    
    template <typename Handler, typename State>
    inline Handler PromiseBase<Handler, State>::get_return_object()
    {
        return Handler{ std::coroutine_handle<State>::from_promise(
                                                    static_cast<State &>(*this) )
                      };
    }
\end{verbatim}
\section{Embedding coroutines in classes}
\typeout{Original Yodl file: coroutines/embedding.yo}Coroutines do not have to be free functions (i.e., outside of classes). They
can also very well be defined as class members, in which case they have full
access to the members of their class.

In this section we develop a class \texttt{Floats} that can either write or read 
binary \texttt{float} values to or from files. An object of this
class is used in \texttt{main}, calling its member \texttt{run} to either write or read
a binary file\footnote{the full program is available in the distribution's
\texttt{coroutines/demo/readbinary} directory}:
    \begin{verbatim}
    int main(int argc, char **argv)
    {
        Floats floats(argc, argv);
        floats.run();
    }
\end{verbatim}
The program is called with two arguments: \texttt{r} for reading, or \texttt{w} for
writing, and the name of the binary file as its second argument.

The member \texttt{Floats:run} uses pointers to members to call either \texttt{read} or
\texttt{write}:
    \begin{verbatim}
    class Reader;
    class Writer;
    
    class Floats
    {
        enum Action
        {
            READ,
            WRITE,
            ERROR,
        };
    
        Action d_action;
        std::string d_filename;                     // name of the binary file
    
        static void (Floats::*s_action[])() const;  // pointers to read and write
    
        public:
            Floats(int argc, char **argv);
            void run() const;
    
        private:
            void read() const;
            Reader coRead() const;
    
            void write() const;
            static Writer coWrite();
    
    };
    
    inline void Floats::run() const
    {
        (this->*s_action[d_action])();
    }
\end{verbatim}
The member \texttt{read} reads the binary file, using the coroutine
\texttt{coRead}. When \texttt{coRead} is called the usual actions are performed:
implicitly the coroutine \texttt{Reader's State} member \texttt{get\_return\_object} is
called to obtain the coroutine's handler, and the coroutine is suspended. Next
the handler returned by \texttt{get\_return\_object} is made available as the
\texttt{read} function's \texttt{reader} object:
    \begin{verbatim}
    void Floats::read() const
    {
        Reader reader = coRead();           // coRead: the coroutine
                                            // reader: the coroutine's handler
        while (auto opt = reader.next())    // retrieve the next value
            cout << opt.value() << ' ';
    
        cout << '\n';
    }
\end{verbatim}
Once the \texttt{reader} object is available the member \texttt{read} enters a \texttt{while}
loop repeatedly calling \texttt{reader.next()}. At this point the following
happens:
    \begin{itemize}
    \item  the coroutine is resumed, reading the next value from the binary file
        (if it's available);
    \item  the coroutine suspends itself again, returning the just obtained
        value (or it indicates that all values have been processed);
    \item  once \texttt{next} has returned, the \texttt{read} function again continues,
        either ending its \texttt{while-}statement or showing the retrieved
        \texttt{float}. 
    \end{itemize}

When resumed for the first time (so when \texttt{reader.next()} is called for the
first time) the \texttt{coRead} coroutine opens the file, and then, in a
\texttt{while-}statement, determines the next available value. If that succeeds the
coroutine is again suspended, using \texttt{co\_yield} to pass the just read value
on to \texttt{read}, or (if no value could be obtained) the coroutine ends by
calling \texttt{co\_return}. Here is the \texttt{Floats::coRead} coroutine:
    \begin{verbatim}
    Reader Floats::coRead() const
    {
        ifstream in{ d_filename };
    
        while (true)
        {
            float value;
            in.read(reinterpret_cast<char *>(&value), sizeof(float));
    
            if (not in)
                co_return;          // if not: end the coroutine
    
            co_yield value;
        }
    }
\end{verbatim}
Likewise, the member \texttt{write} (re)writes the binary file, using the coroutine
\texttt{coWrite}, following the same procedure as used by \texttt{read} to obtain the
\texttt{writer} coroutine handler:
    \begin{verbatim}
    void Floats::write() const
    {
        ofstream out{ d_filename };
    
        Writer writer = coWrite();          // coWrite: the coroutine,
                                            // writer: the coroutine's handler
        cout << "Enter values (one per prompt), enter 'q' to quit\n";
    
        while (true)
        {
            cout << "? ";
            auto opt = writer.next();       // retrieve the next value
            if (not opt)                    // stop if no more values
                break;
            out.write(&opt.value()[0], sizeof(float));
        }
    }
\end{verbatim}
The member \texttt{Floats::coWrite} behaves like \texttt{Floats::coRead}, but writes
instead of reads values to the binary file. Here is \texttt{coWrite}, defined as a
normal (non-static) member, as it uses \texttt{Floats::d\_filename}:
    \begin{verbatim}
    Writer Floats::coWrite()
    {
        while (true)
        {
            float value;
            if (not (cin >> value))       // get the next value
                co_return;          // if not: end the coroutine
    
    
            Writer::ValueType ret;  // value to return
    
            ret = Writer::ValueType{ string{
                        reinterpret_cast<char const *>(&value),
                        reinterpret_cast<char const *>(&value + 1) }
                    };
    
            co_yield ret;
        }
    }
\end{verbatim}
The \texttt{Reader} and \texttt{Writer} handler classes are covered next.

\subsection{The `Reader' coroutine handler}
    \typeout{Original Yodl file: coroutines/reader.yo}The essence of the \texttt{Reader} class is that its \texttt{State} subclass receives a
value from the coroutine (\texttt{coRead}) at the coroutine's \texttt{co\_yield}
statement. \texttt{Reader::State} receives the value that's passed to \texttt{co\_yield}
as argument of its \texttt{yield\_value} member, which stores the received \texttt{float}
value in its \texttt{std::optional$<$float$>$ d\_value} data member.

The \texttt{Reader} class itself must define a constructor receiving a handle to
its \texttt{State} class , and should define a destructor. Its \texttt{next} member
simply returns the value that's stored in its \texttt{State} class to \texttt{next's}
caller. Here is \texttt{Reader's} complete header file:
        \begin{verbatim}
    #include <iostream>
    #include <optional>
    
    #include "../../promisebase/promisebase.h"
    
    struct Reader
    {
        using ValueType = std::optional<float>;
    
        private:
            class State: public PromiseBase<Reader, State>
            {
                ValueType d_value;
    
                public:
                    std::suspend_always yield_value(float value);
                    void return_void();
                    ValueType const &value() const;
            };
    
            std::coroutine_handle<State> d_handle;
    
        public:
            using promise_type = State;
    
            explicit Reader(std::coroutine_handle<State> handle);
            ~Reader();
    
            ValueType const &next();
    };
\end{verbatim}
\texttt{Reader's} and \texttt{Reader::State's} members have (except for \texttt{Reader::next})
very short implementations which can very well be defined inline:
        \begin{verbatim}
    inline std::suspend_always Reader::State::yield_value(float value)
    {
        d_value = value;
        return {};
    }
    
    inline void Reader::State::return_void()
    {
        d_value = ValueType{};
    }
    
    inline Reader::ValueType const &Reader::State::value() const
    {
        return d_value;
    }
    
    inline Reader::Reader(std::coroutine_handle<State> handle)
    :
        d_handle(handle)
    {}
    
    inline Reader::~Reader()
    {
        if (d_handle)
            d_handle.destroy();
    }
\end{verbatim}
\texttt{Reader::next} performs two tasks: it resumes the coroutine, and then, once
the coroutine is again suspended (at its \texttt{co\_yield} statement), it returns
the value stored in the \texttt{Reader::State} object. 
    \index{promise (coroutine)} It can access its \texttt{State} class object via
\texttt{d\_handle.promise()}, returning the value stored in that object:
        \begin{verbatim}
    Reader::ValueType const &Reader::next()
    {
        d_handle.resume();
        return d_handle.promise().value();
    }
\end{verbatim}
\subsection{The `Writer' coroutine handler}
    \typeout{Original Yodl file: coroutines/writer.yo}The \texttt{Writer} class closely resembles the \texttt{Reader} class. It uses a
different value type, as it must write \texttt{float} values to the output stream
using their binary representations, but other than that there aren't that many
difference with the \texttt{Reader} class. Here is its interface and the
implementations of its \texttt{yield\_value} member that differs from that of the
\texttt{Reader} class:
        \begin{verbatim}
    struct Writer
    {
        using ValueType = std::optional<std::string>;
    
        private:
            class State: public PromiseBase<Writer, State>
            {
                ValueType d_value;
    
                public:
                    std::suspend_always yield_value(ValueType &value);
                    void return_void();
                    ValueType const &value() const;
            };
    
            std::coroutine_handle<State> d_handle;
    
        public:
            using promise_type = State;
    
            explicit Writer(std::coroutine_handle<State> handle);
            ~Writer();
    
            ValueType const &next();
    };
    
    inline std::suspend_always Writer::State::yield_value(ValueType &value)
    {
        d_value = std::move(value);
        return {};
    }
\end{verbatim}
\section{`Awaitables', `Awaiters' and `co\_await'}
\typeout{Original Yodl file: coroutines/coawait.yo}So far we've encountered \texttt{co\_yield} and \texttt{co\_return}. What about
\texttt{co\_await}? The verb \emph{to await} is more formal than \emph{to wait}, but the
two verbs mean the same. The added level of formality of \emph{to await} is
illustrated by a second description offered by the \emph{Merrian Webster}
dictionary: \emph{to remain in abeyance until}, and \emph{abeyance's} meaning takes
us home again: \emph{a state of temporary inactivity} or \emph{suspension}. So when
\texttt{co\_await} is used the coroutine enters a state of temporary inactivity,
i.e., it is suspended. In that sense \texttt{co\_yield} is no different, as it also
suspends the coroutine, but different from \texttt{co\_yield co\_await} expects a
so-called \index{awaitable}\emph{awaitable} expression. I.e., an expression resulting in an
\texttt{Awaitable}, or that is convertible to an \texttt{Awaitable}
object (see also figure \ref{CoAwaitFig}).
    \begin{figure}[tbp]
\centerline{\epsffile{coroutines/coawait.eps}}
\caption{\label{CoAwaitFig}co\_await}
\end{figure}
    Figure \ref{CoAwaitFig} shows that the expression that's passed to
\texttt{co\_await} may be an \texttt{Awaitable} object, or if the coroutine handle's
\texttt{State} class has a member \index{await\_transform}\texttt{await\_transform} accepting an argument of some
\texttt{expr's} type, the value returned by \texttt{await\_transform} is the \texttt{
Awaitable} (cf. figure \ref{AwaitableFig}). These \texttt{await\_transform} members
may be overloaded, so in any concrete situation several \texttt{Awaitable} types
could be used.
    \begin{figure}[tbp]
\centerline{\epsffile{coroutines/awaitable.eps}}
\caption{\label{AwaitableFig}awaitable}
\end{figure}

The \texttt{Awaiter} type that's eventually used is either an object of
\texttt{co\_await's expr's} type, or it is the return type of the (implicitly called
when defined) coroutine handler's \texttt{State::await\_transform(expr)} member.

Thus, the \texttt{Awaitable} object is a \emph{middle-man}, that's only used to obtain
an \texttt{Awaiter} object. The \texttt{Awaiter} is the real work-horse in the context
of \texttt{co\_await}.

\index{operator co\_await} \texttt{Awaitable} classes may define a member
\texttt{Awaiter Awaitable::operator co\_await()}, which may also be provided as a
free function (\texttt{Awaiter operator co\_await(Awaitable \&\&)}). If such a
\texttt{co\_await} conversion operator is available then it is used to obtain the
\texttt{Awaiter} object from the \texttt{Awaitable} object. If such a conversion
operator is \emph{not} available then the \texttt{Awaitable} object \emph{is} the
\texttt{Awaiter} object.

As an aside: the types \texttt{Awaitable} and \texttt{Awaiter} are used here as formal
class names, and in actual programs the software engineer is free to use other
(maybe more descriptive) names.

\section{The class `Awaiter'}\label{AWAITER}
    \typeout{Original Yodl file: coroutines/awaiter.yo}\index{await\_ready} Once the \texttt{Awaiter} object is available its member \texttt{bool
await\_ready()} is called. If it returns \texttt{true} then the coroutine is not
suspended, but continues beyond its \texttt{co\_await} statement (in which case
the \texttt{Awaitable} object and \texttt{Awaiter::await\_ready} were apparently able to
avoid suspending the coroutine).

\index{await\_suspend} If \texttt{await\_ready} returns \texttt{false}
\texttt{Awaiter::await\_suspend(handle)} is called. Its \texttt{handle} argument is the
handle (e.g., \texttt{d\_handle}) of the current coroutine's handler object. Note
that at this point the coroutine has already been suspended, and the
coroutine's handle could even be transferred to another thread (in which case
the current thread must of course not be allowed to resume the current
coroutine). The member \texttt{await\_suspend} may return \texttt{void, bool,} or some
coroutine's handle (optionally its own handle). As illustrated in figure
\ref{AwaiterFig}, when returning \texttt{void} or \texttt{true} the coroutine is
suspended and the coroutine's caller continues its execution beyond the
statement that activated the coroutine. If \texttt{false} is returned the coroutine
is not suspended, and resumes beyond the \texttt{co\_await} statement. If a
coroutine's handle is returned (not a reference return type, but value return
type) then the coroutine whose handle is returned is resumed (assuming that
another coroutine's handle is returned than the current coroutine is
suspended, and the other coroutine (which was suspended up to now) is resumed;
in the next section this process is used to implement a finite state automaton
using coroutines)

\begin{figure}[tbp]
\centerline{\epsffile{coroutines/awaiter.eps}}
\caption{\label{AwaiterFig}awaiter}
\end{figure}

\index{await\_resume} If, following \texttt{await\_suspend}, the current coroutine is
again resumed, then just before that the \texttt{Awaiter} object calls
\texttt{Awaiter::await\_resume()}, and \texttt{await\_resume's} return value is returned
by the \texttt{co\_await} expression (\texttt{await\_resume}) frequently defines a
\texttt{void} return type, as in
        \begin{verbatim}
    static void Awaiter::await_resume() const
    {}
\end{verbatim}
In the next section a finite state automaton is implemented using
coroutines. Their handler classes are also \texttt{Awaiter} types, with
\texttt{await\_ready} returning \texttt{false} and \texttt{await\_resume} doing nothing. Thus
their definitions can be provided by a class \texttt{Awaiter} acting as base class
of the coroutines' handler classes. \texttt{Awaiter} only needs a simple header
file: 
        \begin{verbatim}
    struct Awaiter
    {
        static bool await_ready();
        static void await_resume();
    };
    
    inline bool Awaiter::await_ready()
    {
        return false;
    }
    
    inline void Awaiter::await_resume()
    {}
\end{verbatim}
\section{Accessing State from inside coroutines}\label{SETSTATE}
    \typeout{Original Yodl file: coroutines/access.yo}As we've seen, when a coroutine starts it constructs and returns an object of
its handler class. The handler class contains a subclass whose object keeps
track of the coroutine's state. In this chapter that subclass is named
\texttt{State}, and a using declaration is used to make it known as
\texttt{promise\_type} which is required by the standard facilities made available
for coroutines.

When coroutines are suspended at \texttt{co\_yield} statements, the yielded values
are passed to \texttt{State} class's \texttt{yield\_value} members whose parameter
types match the types of the yielded values.

In this section we reverse our point of view, and discuss a method allowing
the coroutine to reach facilities of the \texttt{State} class. We've already
encountered one way to pass information from the coroutine to the \texttt{State}
class: if the \texttt{State} class's constructor defines the same parameters as the
coroutine itself then that constructor is used, receiving the coroutine's
parameters as arguments.

But let's assume that the coroutine performs a continuous loop containing
several, maybe conditional, \texttt{co\_yield} statements, and we want to inform the
\texttt{State} class what the current iteration cycle is. In that case a parameter
is less suitable, as tracking the cycle number is in fact a job for one of the
local variables of the coroutine, which would look something like this:
        \begin{verbatim}
    Handler coroutine()
    {
        size_t cycleNr = 0;
        // make cycleNr available to tt(Handler's State) class
        while (true)
        {
            ++cycleNr;      // now also known to tt(Handler's State)
            ...             // the coroutine at work, using various co_yield
                            // statements
        }
    }
\end{verbatim}
    Awaiters can also be used in these kinds of situations, setting up
communication lines between coroutines and the \texttt{State} classes of their
\texttt{Handler} class objects. As an illustration, the original 
 fibocoro coroutine \ref{FIBOCORO} was slightly modified:
     \begin{verbatim}
     1: Fibo fiboCoroutine()
     2: {
     3:     size_t returnFibo = 0;
     4:     size_t next = 1;
     5:     size_t cycle = 0;
     6: 
     7:     co_await Awaiter{ cycle };
     8:     cerr << "Loop starts\n";
     9: 
    10:     while (true)
    11:     {
    12:         ++cycle;
    13: 
    14:         size_t ret = returnFibo;
    15: 
    16:         returnFibo = next;
    17:         next += ret;
    18: 
    19:         co_yield ret;
    20:     }
    21: }
\end{verbatim}
\begin{itemize}
    \item  At line 5 \texttt{size\_t cycle} is defined, keeping track of the
        coroutine's iteration cycle;
    \item  Line 7 contains a \texttt{co\_await} statemenent, passing \texttt{co\_await} an
        object that receives the \texttt{cycle}, which is the variable the
        \texttt{Handler's State} should know about;
    \item  At line 12 \texttt{cycle} is incremented, so it contains the current
        iteration cycle.
    \end{itemize}

The \texttt{Awaiter} object, since there's no \texttt{State::await\_transform} member,
is an awaitable. Neither does \texttt{Awaiter} have a \texttt{Type operator
co\_await()}, so the anonymous \texttt{Awaiter} object is indeed an Awaiter.

Being the Awaiter, it defines three members: \texttt{await\_ready}, merely returning
\texttt{false}, as the coroutine's execution must be suspended at the \texttt{co\_await}
statement; \texttt{await\_suspend(handle)}, receiving a handle to the coroutine's
\texttt{Handler's State} object; and \texttt{await\_resume}, which doesn't have to do
anything at all:
     \begin{verbatim}
    class Awaiter
    {
        size_t const &d_cycle;
    
        public:
            Awaiter(size_t const &cycle);
    
            bool await_suspend(Fibo::Handle handle) const;
    
            static bool await_ready();
            static void await_resume();
    };
    
    inline Awaiter::Awaiter(size_t const &cycle)
    :
        d_cycle(cycle)
    {}
    
    inline bool Awaiter::await_ready()
    {
        return false;
    }
    
    inline void Awaiter::await_resume()
    {}
\end{verbatim}
The member \texttt{await\_suspend} uses the received handle to access the \texttt{State}
object, passing \texttt{cycle} to \texttt{State::setCycle}:
   \begin{verbatim}
    bool Awaiter::await_suspend(Fibo::Handle handle) const
    {
        handle.promise().setCycle(d_cycle);
        return false;
    }
\end{verbatim}
In the next section (\ref{FSACORO}) we use \texttt{await\_suspend} to switch from
one coroutine to another, but that's not required here. So the member returns
\texttt{false}, and thus continues its execution once it has passed \texttt{cycle} to
\texttt{State::setCycle}.  This way coroutines can pass information to the
\texttt{Handler's State} object, which could define a data member \texttt{size\_t const
$*$d\_cycle} and a member \texttt{setCycle}, using \texttt{d\_cycle} in, e.g.,
\texttt{yield\_value}:
   \begin{verbatim}
    inline void Fibo::State::setCycle(size_t const &cycle)
    {
        d_cycle = &cycle;
    }
\end{verbatim}
\begin{verbatim}
    std::suspend_always Fibo::State::yield_value(size_t value)
    {
        std::cerr << "Got " << value << " at cycle " << *d_cycle << '\n';
        d_value = value;
        return {};
    }
\end{verbatim}
\section{Finite State Automatons via coroutines}\label{FSACORO}
\typeout{Original Yodl file: coroutines/fsa.yo}Finite state automatons (FSAs) are usually implemented via \emph{state x input}
matrices. For example, when using \texttt{Flexc++} to recognize letters, digits or
other characters it defines three input categories, and 4 states (the first
state being the INITIAL state determining the next state based on the
character read from the scanner's input stream, the other three being the
states that handle characters from their specific categories).

FSAs can also be implemented using coroutines. When using coroutines each
coroutine handles a specific input category, and determines the category to
use next, given the current input category. Figure \ref{FSAFig} shows a simple
FSA: at \texttt{Start} a digit takes us to \texttt{Digit}, a letter to \texttt{Letter}, at
any other character we remain in \texttt{Start}, and at end of file (EOF) we end
the FSA at state \texttt{Done}. \texttt{Digit} and \texttt{Letter} act analogously.

\begin{figure}[tbp]
\centerline{\epsffile{coroutines/fsa.eps}}
\caption{\label{FSAFig}Finite State Automaton}
\end{figure}

This FSA uses four coroutines: \texttt{coStart, coDigit, coLetter}, and \texttt{coDone},
each returning their own handlers (like a \texttt{Start} handler returned by
\texttt{coStart}, a \texttt{Digit} handler by \texttt{coDigit}, etc.).  Here is 
\texttt{coStart}:
        \begin{verbatim}
     1: Start coStart()
     2: {
     3:     char ch;
     4:     while (cin.get(ch))
     5:     {
     6:         if (isalpha(ch))
     7:         {
     8:             cout << "at `" << ch << "' from start to letter\n";
     9:             co_await g_letter;
    10:         }
    11:         else if (isdigit(ch))
    12:         {
    13:             cout << "at `" << ch << "' from start to digit\n";
    14:             co_await g_digit;
    15:         }
    16:         else
    17:             cout << "at char #" << static_cast<int>(ch) <<
    18:                     ": remain in start\n";
    19:     }
    20:     co_await g_done;
    21: }
\end{verbatim}
The flow of this coroutine is probably self-explanatory, but note the
\texttt{co\_await} statements at lines 9, 14, and 20: at these lines the
\texttt{co\_awaits} realize the switch from the current coroutine to another. How
that's realized is soon described.

The coroutines \texttt{coDigit} and \texttt{coLetter} perform similar actions, but
\texttt{coDone}, called at EOF, simply returns, thus ending the coroutine-based
processing of the input stream. Here's \texttt{coDone}, simply using \texttt{co\_return}
to end its lifetime:
        \begin{verbatim}
    Done coDone()
    {
        cout << "at EOF: done\n";
        co_return;
    }
\end{verbatim}
Now take a look at this short input file to be processed by the program:
        \begin{verbatim}
    a
    1
    a1
    1a
\end{verbatim}
when processing this input the program shows its state changes:
        \begin{verbatim}
    at `a' from start to letter
    at char #10: from letter to start
    at `1' from start to digit
    at char #10: from digit to start
    at `a' from start to letter
    at `1' from letter to digit
    at char #10: from digit to start
    at `1' from start to digit
    at `a' from digit to letter
    at char #10: from letter to start
    at EOF: done
\end{verbatim}
Since coroutines are normally suspended once activated, the \texttt{Start} handler
privides a member \texttt{go} starting the FSA by resuming its coroutine:
        \begin{verbatim}
    void  Start::go()
    {
        d_handle.resume();      // maybe protect using 'if (d_handle)'
    }
\end{verbatim}
The \texttt{main} function merely activates the \texttt{Start} coroutine, but the
coroutines might of course also be embedded in something like a \texttt{class FSA},
and \texttt{main} might offer an option to process a file argument instead of using
redirection. Here's \texttt{main}:
        \begin{verbatim}
    int main()
    {
        g_start.go();
    }
\end{verbatim}
\subsection{The `Start' handler class}
    \typeout{Original Yodl file: coroutines/starthandler.yo}As illustrated, there are various ways to obtain an Awaiter from a \texttt{co\_await
expr} statement. The shortest route goes like this:
    \begin{itemize}
    \item  According to figure \ref{CoAwaitFig} \texttt{expr} is an awaitable if the
        \emph{current} coroutine's \texttt{State} class does \emph{not} have an
        \texttt{await\_transform} member. In that case \texttt{expr} is the awaitable;
    \item  According to figure \ref{AwaitableFig} if \texttt{expr's} type does \emph{not}
        have an \texttt{operator co\_await} member then \texttt{expr's} type is the
        \texttt{Awaiter}. 
    \end{itemize}

So, the nested \texttt{Start::State} class only has to provide the standard
members of the coroutine handler's \texttt{State} class. As those are all provided
by the generic \texttt{PromiseBase} class (section \ref{STATEBASE}) \texttt{State} needs
no additional members:
        \begin{verbatim}
                // nested under the Start handler class:
    struct State: public PromiseBase<Start, State> 
    {};
\end{verbatim}
    Similar considerations apply to the other three handler classes: their
\texttt{State} classes are also derived from \texttt{PromiseBase$<$Handler,
State$>$}. However, as the \texttt{coDone} coroutine also uses \texttt{co\_return}, the
\texttt{Done::State} state class must have its own a \texttt{return\_void} member:
        \begin{verbatim}
                // nested under the Done handler class:
    struct State: public PromiseBase<Done, State> 
    {
        void return_void() const;
    };
                // implementation in done.h:
    inline void Done::State::return_void() const
    {}
\end{verbatim}
    As our FSA allows transitions from \texttt{Digit} and \texttt{Letter} back to
\texttt{Start} the \texttt{Start} handler class itself is an Awaiter (as are \texttt{Digit,
Letter,} and \texttt{Done}). Section \ref{AWAITER} described the requirements and
basic definition of Awaiter classes.

From the point of view of FSAs the most interesting part is how to switch from
one coroutine to another. As illustrated in figure \ref{AwaiterFig} this
requires a member \texttt{await\_suspend} which \emph{receives} the handle of the
coroutine using the \texttt{co\_await} statement, and returns \emph{some coroutine's}
handle. So:
    \begin{itemize}
    \item \texttt{co\_await expr} is used, where \texttt{expr} is a coroutine's handler, which
        is also an Awaiter;
    \item  the current coroutine passes its own handle to \texttt{expr's
        await\_suspend} member;
    \item  the handle returned by \texttt{expr's await\_suspend} member determines
        which coroutine is resumed, suspending the coroutine using
        \texttt{co\_await};
    \item \texttt{expr} returns its own handle, thereby realizing the FSA's state switch
        from the current coroutine to \texttt{expr's} coroutine.
    \end{itemize}

Here is the interface of \texttt{coStart's} handler class as well as the definition
of its \texttt{await\_suspend} member. Since the \texttt{coStart} coroutine may be
resumed by several other coroutines it is unknown which coroutine's handle was
passed to \texttt{Start::await\_suspend}, and so \texttt{await\_suspend} is a member
template, which simply returns \texttt{Start's} handle.
        \begin{verbatim}
    class Start: public Awaiter
    {
        struct State: public PromiseBase<Start, State>
        {};
    
        std::coroutine_handle<State> d_handle;
    
        public:
            using promise_type = State;
            using Handle = std::coroutine_handle<State>;
    
            explicit Start(Handle handle);
            ~Start();
    
            void go();
    
                    // this and the  members in Awaiter are required for Awaiters
            template <typename HandleType>
            std::coroutine_handle<State> await_suspend(HandleType &handle);
    };
    
    template <typename HandleType>
    inline std::coroutine_handle<Start::State>
                                      Start::await_suspend(HandleType &handle)
    {
        return d_handle;
    }
\end{verbatim}
As the member \texttt{Start's wait\_suspend} returns \texttt{Start's d\_handle}, the
coroutine containing the \texttt{co\_await g\_start} statement is suspended, and the
\texttt{co\_start} coroutine is resumed (see also figure \ref{AwaiterFig}).

The implementations of the \texttt{Start} handler's constructor and destructor are
straightforward: the constructor stores the coroutine's handle in its
\texttt{d\_handle} data member, the destructor uses the (language provided) member
\texttt{destroy} to properly end the \texttt{Start::State's} coroutine handle. Here are
their implementations:
        \begin{verbatim}
    Start::Start(Handle handle)
    :
        d_handle(handle)
    {}
\end{verbatim}
\begin{verbatim}
    Start::~Start()
    {
        if (d_handle)
            d_handle.destroy();
    }
\end{verbatim}
\subsection{Completing the Finite State Automaton}
    \typeout{Original Yodl file: coroutines/completingfsa.yo}The \texttt{Digit} and \texttt{Letter} coroutines handler classes are implemented
like \texttt{Start}. Like \texttt{coStart}, which continues its execution when a
non-digit and non-letter character is received, \texttt{coDigit} continues for as
long as digit characters are received, and \texttt{coLetter} continues for as long
as letter characters are received.

As we've seen in section \ref{FSACORO} the implementation of \texttt{coDone} is a
bit different: it doesn't have to do anything, and the \texttt{coDone} coroutine
simply ends at its \texttt{co\_return} statement. Coroutine execution (as well as
the FSA program) then ends following \texttt{main's g\_start.go()} call.

The complete implementation of the coroutine-based FSA program is available in
the Annotation's distribution under the directory
\texttt{yo/coroutines/demo/fsa}. 

\section{Recursive coroutines}
\typeout{Original Yodl file: coroutines/recursive.yo}Like ordinary functions coroutines can recursively be called. An
    \index{coroutine: essential characteristic} essential characteristic of
coroutines is that when they're used they look no different than ordinary
functions. It's merely in the implementation that coroutines differ from
ordinary functions.

For starters, consider a very simple interactive program that produces a
series of numbers until the user ends the program or enters \texttt{q}:
    \begin{verbatim}
     1: int main()
     2: {
     3:     Recursive rec = recursiveCoro(true);
     4: 
     5:     while (true)
     6:     {
     7:         cout << rec.next() << "\n"
     8:                 "? ";
     9: 
    10:         string line;
    11:         if (not getline(cin, line) or line == "q")
    12:             break;
    13:     }
    14: }
\end{verbatim}
At line 3 the \texttt{recursiveCoro} coroutine is called, returning its handler
\texttt{rec}. In line 7 its member \texttt{next} is called, returning the next value
produced by \texttt{recursiveCoro}. The function \texttt{recursiveCoro} could
have been any function returning an object of a class that has a \texttt{next}
member. For now ignoring recursion, \texttt{recursiveCoro} could look like this:
    \begin{verbatim}
     1: namespace
     2: {
     3:     size_t s_value = 0;
     4: }
     5: 
     6: Recursive recursiveCoro(bool recurse)
     7: {
     8:     while (true)
     9:     {
    10:         for (size_t idx = 0; idx != 2; ++idx)
    11:             co_yield ++s_value;
    12: 
    13:         // here recursiveCoro will recursively be called 
    14: 
    15:         for (size_t idx = 0; idx != 2; ++idx)
    16:             co_yield ++s_value;
    17:     }
    18: }
\end{verbatim}
The coroutine merely produces the sequence of non-negative integral
numbers, starting at 0. Its two for-loops (lines 10 and 15) are there merely
for illustrative purposes, and the recursive call will be placed between those
for-loops. The variable \texttt{s\_value} is defined outside the coroutine (instead
of using \texttt{static s\_value = 0} inside), as recursively called coroutines must
all access the same \texttt{s\_value} variable. There's no magic here: just two
for-statements in a continuously iterating while-statement.

The interface of the returned \texttt{Recursive} object isn't complex either:
    \begin{verbatim}
     1: class Recursive
     2: {
     3:     class State: public PromiseBase<Recursive, State>
     4:     {
     5:         size_t d_value;
     6: 
     7:         public:
     8:             std::suspend_always yield_value(size_t value);
     9:             size_t value() const;
    10:     };
    11: 
    12:     private:
    13:         using Handle = std::coroutine_handle<State>;
    14:         Handle d_handle;
    15: 
    16:     public:
    17:         using promise_type = State;
    18: 
    19:         explicit Recursive(Handle handle);
    20:         ~Recursive();
    21: 
    22:         size_t next();
    23:         bool done() const;
    24: };
\end{verbatim}
The required members of its \texttt{State} class are available in
\texttt{PromiseBase} (cf. section \ref{STATEBASE}) and do not have to be
modified. As \texttt{recursiveCoro co\_yields} values, the \texttt{State::yield\_value} 
member stores those values in its \texttt{d\_value} data member:
    \begin{verbatim}
    std::suspend_always Recursive::State::yield_value(size_t value)
    {
        d_value = value;
        return {};
    }
\end{verbatim}
Its member \texttt{value} is an accessor, returning \texttt{d\_value}. When recursion
is used the recursive calls end at some point. When \texttt{recursiveCoro}
functions end \texttt{State::return\_void} is called. It doesn't have to do
anything, so \texttt{PromiseBase's} empty implementation perfectly does the job.

The \texttt{Recursive} handling class's own interface starts at line 12. Its
\texttt{d\_handle} data member (line 14) is initialized by its constructor (line
19), which is all the constructor has to do. The handler's destructor only has
to call \texttt{d\_handle.destroy()} to return the memory used by its \texttt{State}
object.

The remaining members are \texttt{next} and \texttt{done}. These, too, are implemented
straight-forwardly. The member \texttt{done} will shortly be used in the recursive
implementation of \texttt{recursiveCoro}, and it just returns the value returned by
\texttt{d\_handle.done()}.

When the member \texttt{next} is called the coroutine is in its suspended state
(which is what happens when it's initially called (cf. line 3 in the above
\texttt{main} function) and thereafter when it uses \texttt{co\_yield} (lines 11 and 16
in the above implementation of \texttt{recursiveCoro})). So it resumes the
coroutine, and when the coroutine is again suspended, it returns the (next
available) value stored in the handler's \texttt{State} object:
    \begin{verbatim}
    size_t Recursive::next()
    {
        d_handle.resume();
        return d_handle.promise().value();
    }
\end{verbatim}
\subsection{Recursively calling recursiveCoro}
    \typeout{Original Yodl file: coroutines/recursively.yo}Now we change the non-recursive \texttt{recursiveCoro} coroutine into a recursively
called coroutine. To activate recursion \texttt{recursiveCoro} is modified by
adding some extra statements below line 8:
    \begin{verbatim}
     1: Recursive recursiveCoro(bool recurse)
     2: {
     3:     while (true)
     4:     {
     5:         for (size_t idx = 0; idx != 2; ++idx)
     6:             co_yield ++s_value;
     7: 
     8:         // here recursiveCoro will recursively be called
     9: 
    10:         if (not recurse)
    11:             break;
    12: 
    13:         Recursive rec = recursiveCoro(false);
    14: 
    15:         while (true)
    16:         {
    17:             size_t value = rec.next();
    18:             if (rec.done())
    19:                 break;
    20: 
    21:             co_yield value;
    22:         }
    23: 
    24:         for (size_t idx = 0; idx != 2; ++idx)
    25:             co_yield ++s_value;
    26:     }
    27: }
\end{verbatim}
Recursion is activated when the parameter \texttt{recurse} is \texttt{true}, which is
passed to \texttt{recursiveCoro} when initially called by \texttt{main}. It is then
recursively called in line 13, now using \texttt{false} as its argument.  Consider
what happens when it's recursively called: the while-loop is entered and the
for-statement at line 5 is executed, `co\_yielding' two values. Next, in line
10, the loop ends, terminating the recursion. This implicitly calls
\texttt{co\_return}. It's also possible to do that explicitly, using
        \begin{verbatim}
    if (not recurse)
        co_return;
\end{verbatim}
    Going back to the initial call: once \texttt{rec} (line 13) is available, a
nested while-loop is entered (line 15), receiving the next value obtained by
the recursive call (line 17). That \texttt{next} call resumes the nested coroutine,
which, as just described, returns two values when executing line 5's
for-statement. But then, when it's resumed for the third time, it doesn't
actually \texttt{co\_yield} a newly computed value, but calls \texttt{co\_return} (because
of lines 10 and 11), thus \emph{ending} the recursive call. At that point 
the coroutine's \texttt{State} class's member \texttt{done} returns \texttt{true}, which
value is available through \texttt{ret.done()} (line 18). Once that happens the
while loop at line 15 ends, and the non-recursive coroutine continues at line
24. If the recursively called coroutine \emph{does} compute a value,
\texttt{rec.done()} returns \texttt{false}, and \texttt{value} produced by \texttt{rec} is
`co\_yielded' by the non-recursively called coroutine, making it available to
\texttt{main}. So in that latter case the value co\_yielded by the recursively
called coroutine is co\_yielded by the initially called coroutine, where it is
retrieved by \texttt{main}: there's a sequence of \texttt{co\_yield} statements from the
most deeply nested coroutine to the coroutine that's called by \texttt{main},
at which point the value is finally collected in \texttt{main}.

The \texttt{next..done} implementation used here resembles the way streams are
read: first try to extract information from a stream. If that succeeds, use
the value; if not, do something else:
        \begin{verbatim}
    while (true)
    {
        cin >> value;
        if (not cin)
            break;
        process(value);
    }
\end{verbatim}
    Functions like \texttt{getline} and overloaded extraction operators may combine
the extraction and the test. That's of course also possible when using
coroutines. Defining \texttt{next} as
        \begin{verbatim}
    bool Recursive::next(size_t *value) 
    {
        d_handle.resume();
        if (d_handle.done())        // no more values
            return false;
        *value = d_handle.promise().value();
        return true;
    }
\end{verbatim}
  allows us to change the while loop at line 15 into:
        \begin{verbatim}
    size_t value;
    while (rec.next(&value))
        co_yield value;
\end{verbatim}
\subsection{Beyond a single recursive call}
    \typeout{Original Yodl file: coroutines/beyond.yo}In the introductory section the \texttt{fiboCoro} coroutine was presented. In 
this section the \texttt{fiboCoro} coroutine is going to be used by the
\texttt{recursiveCoro} coroutine, using multiple levels of recursion.

To concentrate on the recursion process the \texttt{fiboCoroutine's} handler is
defined in \texttt{main} as a global object, so it can directly be used by every
recursive call of \texttt{recursiveCoro}. Here is the \texttt{main} function, using
\texttt{bool Recursive::next(size\_t $*$value)}, and it also defines the global object
\texttt{g\_fibo}:
    \begin{verbatim}
    Fibo g_fibo = fiboCoro();
    
    int main()
    {
        Recursive rec = recursiveCoro(0);
    
        size_t value;
        while (rec.next(&value))
        {
            cout << value << "\n"
                    "? ";
    
            string line;
            if (not getline(cin, line) or line == "q")
                break;
        }
    }
\end{verbatim}
The \texttt{Recursive} class interface is identical to the one developed in the
previous section, except for the \texttt{Recursive::done} member (which is not used
anymore and was therefore removed from the interface), and changing \texttt{next}
member's signature as shown. It's implementation was altered accordingly:
    \begin{verbatim}
    bool Recursive::next(size_t *value)
    {
        d_handle.resume();
    
        if (d_handle.done())
            return false;
    
        *value = d_handle.promise().value();
        return true;
    }
\end{verbatim}
In fact, the only thing that has to be modified to process deeper recursion
levels is the \texttt{recursiveCoro} coroutine itself. Here is its modified
version:
    \begin{verbatim}
     1: Recursive recursiveCoro(size_t level)
     2: {
     3:     while (true)
     4:     {
     5:         for (size_t idx = 0; idx != 2; ++idx)
     6:             co_yield g_fibo.next();
     7: 
     8:         if (level < 5)
     9:         {
    10:             Recursive rec = recursiveCoro(level + 1);
    11:             size_t value;
    12:             while (rec.next(&value))
    13:                 co_yield value;
    14:         }
    15: 
    16:         for (size_t idx = 0; idx != 2; ++idx)
    17:             co_yield g_fibo.next();
    18: 
    19:         if (level > 0)
    20:             break;
    21:     }
    22: }
\end{verbatim}
This implementation strongly resembles the 1-level recursive coroutine. Now
multiple levels of recursion are allowed, and the maximum recursion level is
set at 5. The coroutine knows its own recursion level via its \texttt{size\_t level}
parameter, and it recurses as long as \texttt{level} is less than 5 (line 8). At
each level two series of two fibonacci values are computed (in the
for-statements at lines 5 and 16). After the second for-statement the
coroutine ends unless it's the coroutine that's called from \texttt{main}, in which
case \texttt{level} is 0. The decision to end (recursively called) coroutines is
made in line 19.

In this implementation the maximum recursion level is set to a fixed
value. It's of course also possible that the coroutine itself decides that
further recursion is pointless. Consider the situation where 
directory entries are examined, and where subdirectories are handled
recursively. The recursive directory visiting coroutine might then have an
implementation like this:
    \begin{verbatim}
     1: Recursive recursiveCoro(string const &directory)
     2: {
     3:     chdir(directory.c_str());               // change to the directory
     4: 
     5:     while ((entry = nextEntry()))           // visit all its entries
     6:     {
     7:         string const &name = entry.name();
     8:         co_yield name;                      // yield the entry's name
     9: 
    10:         if (entry.type() == DIRECTORY)      // a directory?
    11:         {                                   // get the full path
    12:             string path = pathName(directory, name);
    13:             co_yield path;                  // yield the full path
    14: 
    15:             auto rec = recursiveCoro(path); // visit the entries of 
    16:             string next;                    // the subdir (and of its
    17:             while (rec.next(&next))         // subdirs)
    18:                 co_yield next;              // and yield them
    19:         }
    20:     }
    21: }
\end{verbatim}
In this variant the (not implemented here) function \texttt{nextEntry} (line 5)
produces all directory entries in sequence, and if an entry represents a
directory (line 10), the same process is performed recursively (line 15),
yielding its entries to the current coroutine's caller (line 18).

\section{Coroutine iterators}
\typeout{Original Yodl file: coroutines/iterators.yo}The previous examples predominantly used while-statements to obtain the values
returned by coroutines, many generic algorithms (as well as range-based
for-loops) depend on the availability of \texttt{begin} and \texttt{end} members
returning iterators. 

Coroutines (or actually, their handling classes) may also define \texttt{begin} and
\texttt{end} members returning iterators. In practice those iterators are input
iterators (cf. section \ref{ITERATORS}), providing access to the values
co\_yielded by their coroutines. Section \ref{ITERATORCONS} specifies their
requirements. For plain types (like \texttt{size\_t} which is co\_yielded by
\texttt{Fibo::next}) iterators should provide the following members:
    \begin{itemize}
    \item  a prefix increment operator (\texttt{Iterator \&operator++()});
    \item  a dereference operator (\texttt{Type \&operator$*$()});
    \item  comparison operators (\texttt{bool operator==(Iterator const \&other)}) 
        (and maybe \texttt{operator!=} returning its complement).
    \end{itemize}

The \texttt{Iterator} class is a value class. However, except for copy- and
move-constructions, \texttt{Iterator} objects can only be constructed by
\texttt{Recursive's begin} and \texttt{end} members. It has a private constructor
and declares \texttt{Recursive} as its friend:
    \begin{verbatim}
    class Iterator
    {
        friend bool operator==(Iterator const &lhs, Iterator const &rhs);
        friend class Recursive;

        Handle d_handle;

        public:
            Iterator &operator++();
            size_t operator*() const;

        private:
            Iterator(Handle handle);
    };
\end{verbatim}
\texttt{Iterator's} constructor receives \texttt{Recursive::d\_handle}, so it can use 
its own \texttt{d\_handle} to control \texttt{recursiveCoro's} behavior:
    \begin{verbatim}
    Recursive::Iterator::Iterator(Handle handle)
    :
        d_handle(handle)
    {}
\end{verbatim}
The member \texttt{Recursive::begin} ensures that \texttt{Iterator::operator$*$} can
immediately provide the next available value by resuming the coroutine. If
that succeeds it passes \texttt{d\_handle} to \texttt{Iterator's} constructor. If
there are no values it returns 0, which is the \texttt{Iterator} that's also
returned by \texttt{Recursive::end}:
    \begin{verbatim}
    Recursive::Iterator Recursive::begin()
    {
        if (d_handle.promise().level() == 0)
            g_fibo.reset();
    
        d_handle.resume();
        return Iterator{ d_handle.done() ? 0 : d_handle };
    }
    
    Recursive::Iterator Recursive::end()
    {
        return Iterator{ 0 };
    }
\end{verbatim}
The dereference operator simply calls and returns the value returned by
\texttt{State::value()} and the prefix increment operator resumes the coroutine. If
no value was produced it assigns 0 to its \texttt{d\_handle}, resulting in \texttt{true}
when compared to the iterator returned by \texttt{Recursive::end}:
    \begin{verbatim}
    size_t Recursive::Iterator::operator*() const
    {
        return d_handle.promise().value();
    }
    
    Recursive::Iterator &Recursive::Iterator::operator++()
    {
        d_handle.resume();
    
        if (d_handle.done())
            d_handle = 0;
    
        return *this;
    }
\end{verbatim}
\section{Visiting directories using coroutines}
\typeout{Original Yodl file: coroutines/visiting.yo}Because coroutines are usually suspended once they have produced some
intermediate but useful result they offer an alternative to stack-based
approaches in which recursion is often used.

This section covers a coroutine that visits all elements of (nested)
directories, listing all their path-names relative to the original starting
directory. First a more traditional approach is covered, using a class having
a member that recursively visits directory elements. Thereafter a
coroutine is described performing the same job. Finally, some statistics about
execution times of both approaches are discussed.

\subsection{The `Dir' class showing directory entries}
    \typeout{Original Yodl file: coroutines/dir.yo}Here a class \texttt{Dir} is developed (recursively) showing all entries
in and below a specified directory. The program defines a class \texttt{Dir},
used by \texttt{main}:
    \begin{verbatim}
    int main(int argc, char **argv)
    {
        Dir dir{ argc == 1 ? "." : argv[1] };
    
        while (char const *entryPath = dir.entry())
            cout << entryPath << '\n';
    }
\end{verbatim}
The class \texttt{Dir}, like the coroutine based implementation in the next
section, uses the \texttt{`dirent'} \textbf{C} struct. As we prefer typenames starting
with capitals, \texttt{Dir} specifies a simple \texttt{using DirEntry = dirent}
so \textbf{C}'s typename doesn't have to be used.

\texttt{Dir} defines just a few data members: 
    \texttt{d\_dirPtr} stores the pointer returned by \textbf{C}'s function \texttt{opendir};
    \texttt{d\_recursive} points to a \texttt{Dir} entry that's used to handle a
        sub-directory of the current directory;
    \texttt{d\_entry} is the name of the directory
        returned by \texttt{Dir::entry} member, which is refreshed at each call;
    \texttt{d\_path} stores the name of the directory visited by a \texttt{Dir} object;
    and \texttt{d\_entryPath} is \texttt{d\_entry's} path name, starting at the initial
        directory name.
    Here is \texttt{Dir's} class interface:
    \begin{verbatim}
    class Dir
    {
        using DirEntry = dirent;
    
        DIR *d_dirPtr = 0;
        Dir *d_recursive = 0;
    
        char const *d_entry;        // returned by entry()
        std::string d_path;         // Dir's directory name, ending in '/'
        std::string d_entryPath;
    
        public:
            Dir(char const *dir);   // dir: the name of the directory to visit
            ~Dir();
    
            char const *entry();
    };
\end{verbatim}
\texttt{Dir's} constructor prepares its object for inspection of the entries of the
directory whose name is received as its argument: it calls
\texttt{opendir} for that directory, and prepares its \texttt{d\_path} data member:
        \begin{verbatim}
    Dir::Dir(char const *dir)
    :
        d_dirPtr(opendir(dir)),             // prepare the entries
        d_path( dir )
    {
        if (d_path.back() != '/')           // ensure that dirs end in '/'
            d_path += '/';
    }
\end{verbatim}
Once a \texttt{Dir} object's lifetime ends its destructor simply calls
\texttt{closedir} to return the memory allocated by \texttt{opendir}:
    \begin{verbatim}
    inline Dir::~Dir()
    {
        closedir(d_dirPtr);
    }
\end{verbatim}
The member \texttt{entry} performs two tasks: first, if a recursion is active then
\emph{if} a recursive entry is available, that entry is returned. Otherwise, if
no recursive entry is available \texttt{d\_recursive's} memory is deleted, and
\texttt{d\_recursive} is set to 0:
    \begin{verbatim}
        // first part
    if (d_recursive)                                    // recursion active
    {
        if (char const *entry = d_recursive->entry())   // next entry
            return entry;                               // return it

        delete d_recursive;                             // delete the object
        d_recursive = 0;                                // end the recursion
    }
\end{verbatim}
The second part is executed if there's no recursion or once all the recursive
entries have been obtained. In that case all entries of the current directory
are retrieved, skipping the two mere-dot entries. If the thus obtained entry
is the name of a directory then \texttt{d\_recursive} stores the address of a newly
allocated \texttt{Dir} object (which is then handled at \texttt{Dir::entry's} next call)
and the just received entry name is returned:
    \begin{verbatim}
        // second part
    while (DirEntry const *dirEntry = readdir(d_dirPtr))// visit all entries
    {
        char const *name = dirEntry->d_name;            // get the name

        if (name == "."s or name == ".."s)              // ignore dot-names
            continue;

        name = (d_entryPath = d_path + name).c_str();   // entry-name
                                                        // (as path)

        if (dirEntry->d_type == DT_DIR)                 // a subdir?
            d_recursive = new Dir{ name };              // handle it next

        return name;                                    // return the entry
    }
\end{verbatim}
The member \texttt{Dir::entry} itself consists of these two parts, returning zero
(no more entries) once the second part's while-loop ends:
    \begin{verbatim}
    char const *Dir::entry()
    {
        // first part here
    
        // second part here
    
        return 0;
    }
\end{verbatim}
Thus, the \texttt{class Dir} essentially requires one single member function, using
recursion to visit all directory entries that exist in or below the specified
starting directory. All sources of this program are available in the
distribution's \texttt{yo/coroutines/demo/dir} directory.

\subsection{Visiting directories using coroutines}
    \typeout{Original Yodl file: coroutines/corodir.yo}In this section a coroutine-based implementation of a program recursively
showing all directory entries is discussed. The program was based on
facilities offered by Lewis Baker's 
    \texttt{cppcoro library}\footnote{https://github.com/lewissbaker/cppcoro}.

The source files of this program are available  in the distribution's
\texttt{yo/coroutines/demo/corodir} directory. It uses the same \texttt{DirEntry}
type definition as used in the previous section, and specifies
    \texttt{using Pair = std::pair$<$DirEntry, char const $*$$>$} to access a
\texttt{DirEntry} and its path name.

The program's \texttt{main} function strongly resembles the \texttt{main} function using
the class \texttt{Dir}, but this time \texttt{main} uses the \texttt{visitAllEntries}
coroutine:
    \begin{verbatim}
    int main(int argc, char **argv)
    {
        char const *path = argc == 1 ? "." : argv[1];
    
        for (auto [entry, entryPath ]: visitAllEntries(path))
            cout << entryPath << '\n';
    }
\end{verbatim}
The \texttt{main} function uses a range-based for-loop to show the entries produced
by the \texttt{visitAllEntries} coroutine, which are the files and directories that
are (recursively) found in a specified starting directory. 

Three coroutines are used to process directories. The \texttt{visitAllEntries}
coroutine returns a \texttt{RecursiveGenerator$<$Pair$>$} as its handler.  Like
\texttt{main}, the \texttt{visitAllEntries} coroutine also uses a range-based for-loop
(line 3) to retrieve directory entries. The coroutine yields \texttt{Pair} objects
(line 5) or the results from nested directories (line 9). Its handler (a
\texttt{RecursiveGenerator}) is a class template, defined in Lewis Baker's
\texttt{cppcoro} library:
        \begin{verbatim}
     1: RecursiveGenerator<Pair> visitAllEntries(char const *path)
     2: {
     3:     for (auto &entry_pair: dirPathEntries(path))
     4:     {
     5:         co_yield entry_pair;
     6: 
     7:         auto [entry, entry_path] = entry_pair;
     8:         if (entry.d_type == DT_DIR)
     9:             co_yield visitAllEntries(entry_path);
    10:     }
    11: }
\end{verbatim}
Directory entries are made available by a second coroutine,
\texttt{dirPathEntries}. At each entry \texttt{visitAllEntries} is suspended (line 5),
allowing \texttt{main} to show its full path. At lines 7 and 8 the types of the
entries are inspected. If the received entry refers to a sub-directory then
\texttt{visitAllEntries} yields, recursively calling itself, and thus yielding the
sub-directory's entries. Once all entries have been processed the range-based
for-loop ends, and the coroutine ends by automatically calling \texttt{co\_return}.

The coroutine yielding directory entries is \texttt{dirPathEntries}, whose handler
is an object of another \texttt{cppcoro} class, \texttt{Generator$<$Pair$>$}:
        \begin{verbatim}
     1: Generator<Pair> dirPathEntries(char const *path)
     2: {
     3:     for (auto const &entry: dirEntries(path))
     4:         co_yield make_pair(entry,
     5:                     (string{path} + '/' + entry.d_name).c_str());
     6: }
\end{verbatim}
The \texttt{dirPathEntries} coroutine performs a cosmetic task: it receives the
path name of a directory, and calls a third coroutine (\texttt{dirEntries}) to
retrieve the successive elements of that directory (line 3). As long as there
are entries the coroutine is suspended, yielding \texttt{Pair} objects consisting
of the values returned by \texttt{dirEntry} and the full path names of those
entries (lines 4 and 5). Eventually, as with \texttt{visitAllEntries, co\_return}
ends the coroutine.

The third coroutine is \texttt{dirEntries}, returning a \texttt{Generator$<$DirEntry}
handler:
        \begin{verbatim}
     1: Generator<DirEntry> dirEntries(char const *path)
     2: {
     3:     DIR *dirPtr = opendir(path);
     4: 
     5:     while (auto entry = readdir(dirPtr))
     6:     {
     7:         if (accept(*entry))
     8:             co_yield *entry;
     9:     }
    10:     closedir(dirPtr);
    11: }
\end{verbatim}
This coroutine, like the \texttt{Dir} class from the previous section, uses
\textbf{C}'s \texttt{opendir, readdir}, and \texttt{closedir} triplet of functions. As
coroutines resume their actions beyond their suspension points these functions
can now all be used in a single coroutine. When \texttt{dirEntries} starts, it
calls \texttt{opendir} (line 3). Then, as long as there are entries (line 5) and
those entries are neither the current nor the parent directory (line 7,
checked by \texttt{accept}, not listed here), the coroutine is suspended, yielding
the obtained entry (line 8). Its while-loop ends once all entries have been
retrieved. At that point \texttt{closedir} is called (line 10), and the coroutine
ends.

\subsection{Functions vs. coroutines}
    \typeout{Original Yodl file: coroutines/comparing.yo}Coroutines might be considered severe competitors of ordinary functions. After
all, there's no repeated stack handling required between successive
activations: \texttt{co\_yields} simply suspend coroutines, leaving all their data,
ready to be (re)used, in the heap.

In many situations coroutines are considered more attractive at an intuitive
level: already in the introductory section of this chapter they were
characterized as \emph{cooperating routines}, where the coroutine cooperates with
its caller, producing the caller's requested information as if the coroutine
is part of the caller's code. But although it formally isn't it \emph{can}
conceptually be considered part of the caller's code, as it doesn't have to be
called again and again during the caller's lifetime: once activated the
coroutine remains available in memory and doesn't have to be called again when
it's resumed. Coroutines are \emph{cooperating} in that sense: they can in fact
be considered part of the caller's code. In this way they really differ from
independent functions which, when called repeatedly, are called again and
again `from scratch', implying intensive stack operations.

On the other hand, using coroutines is way more complex than using
`traditional' functions. The source files of the discussed \texttt{Dir} class
required some 100 lines of source code, whereas the coroutine based
implementation needed about 700 lines of code. But maybe that's not a fair
comparison. Maybe the \texttt{cppcoro} library's sources shouldn't be considered,
like when we're using -{}-{}say-{}-{} strings, streams and vectors, in which case we
also ignore the sizes of their sources when they're used in our programs. If
we \emph{do} ignore the sizes of \texttt{cppcoro's} sources, then the coroutine based
implementation in fact requires \emph{fewer} lines of code than the \texttt{Dir}
class, as the \texttt{Generator} and \texttt{RecursiveGenerator} handler classes are
provided by the \texttt{cppcoro} library.

Eventually, implementing parts of algorithms with coroutines, instead of using
the (functions based) structured programming approach, might simply be a
matter of taste. But maybe, as coroutines allow us to split up algorithms in
separate parts which are not using stack-based activations, the efficiency of
coroutine-based implementations exceeds the efficiency of implementations
using separate supoprt functions. To get some information about the efficiency
of programs using coroutines vs. programs that use separate support functions
the \texttt{class Dir} based program and the \texttt{coroDir} based program was each run
five times, processing a large multi-directory, multi-file structure,
containing over 400.000 entries. The execution times of each of the five runs
are highly comparable. The following table shows the average clock-times, the
average user-times, and the average system-times for the \texttt{class Dir} based
program and the \texttt{coroDir} based program:

\begin{center}
    \begin{tabular}{rcccc}

            \hline

            \multicolumn{2}{c}{\makecell[c]{}}  & 
                     \multicolumn{3}{c}{\makecell[c]{time}} 
 \\

            \cline{3-5}
            \makecell[r]{}  & 
              \makecell[c]{}  & 
           \makecell[c]{real}  & 
     \makecell[c]{user}  & 
        \makecell[c]{system} 
 \\

            \cline{1-5}
            \makecell[r]{class Dir}  & 
     \makecell[c]{~}  & 
     \makecell[c]{82}  & 
      \makecell[c]{22}  & 
          \makecell[c]{59} 
 \\

            \makecell[r]{coroDir}  & 
       \makecell[c]{}  & 
           \makecell[c]{88}  & 
      \makecell[c]{25}  & 
          \makecell[c]{62} 
 \\

            \cline{1-5}
    \end{tabular}

  \end{center}
    Although the \texttt{class Dir} implementation uses slightly less time than the
\texttt{coroDir} implementatin, the differences are small, and should not be
interpreted as an indication that (maybe different from what was expected)
coroutine based implementations are inherently slower than function based
implementations. Furthermore, coroutines themselves often call ordinary
functions (like \texttt{readdir} called by \texttt{coroDir's } coroutine
\texttt{dirEntries}), which still require stack-handling.

The conclusion at the end of this chapter is therefore that, yes, coroutines
are available in \textbf{C++}, but they require lots of effort before they can be
used.  Some libraries (like \texttt{cppcoro}) are available, but they're not (yet?)
part of the software that comes standard with your \textbf{C++} compiler.  However,
the underlying philosophy (being able to use cooperating routines) certainly
is attractive, although it doesn't necessarily result in more efficient
programs than programs which are developed using the traditional structured
programming approach. And so, in the end, whether or not to use coroutines
might simply boil down to a matter of taste.


\cleardoublepage\chapter{Modules}\label{MODULES}
\typeout{Original Yodl file: modules}

\typeout{Original Yodl file: modules/intro.yo}Since the introduction of header files in the \textbf{C} programming language
header files have been the main tool for declaring elements that are not
defined but are used in source files. E.g., to use \texttt{printf} in \texttt{main}
the preprocessor directive \texttt{\#include $<$stdio.h$>$} had to be specified.

Header files are still extensively used in \textbf{C++}, but gradually some
drawbacks emerged. One minor drawback is that, in \textbf{C++}, header files
frequently not merely contain function and variable declarations but often
also type definitions (like class interfaces and enum definitions). When
designing header files the software engineer therefore commonly distinguishes
headers which are merely used inside a local (class) context (like the
internal-header approach advocated in the \textbf{C++} Annotations) and header files
which are used externally. Those latter header files need include guards to
prevent them from being processed repeatedly by sources (indirectly) including
them. Another, important, drawback is that a header file is processed again
for every source file including it. Such a task is not a trivial one. E.g., if
a header file includes \texttt{iostream} and \texttt{string} then that forces a compiler
like \texttt{g++ 14.2.0} to process over 900,000 bytes of code for every source
file including that header.

To speed up compilations precompiled headers \index{header: precompiled} were
introduced. Although the binary format of precompiled headers does indeed
allow the compiler to parse the content of header files much faster than
their standard text format, they are also very large. A precompiled header
merely including \texttt{iostream} and \texttt{string} exceeds 25 MB: a bit more
than its uncompiled text-file equivalent....

Modules were introduced to avoid those complications. Although modules can
still include header files, it's a good design principle to avoid including
header files when designing modules. In general: once a module has been
designed its use doesn't require processing header files anymore, and
consequenly programs that merely use modules are compiled much faster than
corresponding programs that use header files.

There is another, conceptual, feature of modules. The initial high-level
programming languages (like Fortran and Algol) (but also assembly languages)
provided functions (a.k.a. subroutines and procedures) to distinguish
conceptually different task levels.  Functions implement specific tasks. A
program reading data, then processing the data, and finally showing the
results can easily be designed using functions, and is much easier to
understand than replacing the function calls by their actual implementations:
        \begin{verbatim}
    int main()
    {
        readData();
        processData();
        showResults();
    }
\end{verbatim}
    Often such functions use their own support functions, etc, etc, until
trivial decomposition levels are reached where simple flow control and
expression statements are used.

This decomposition methodology works very good. It still does. But at the
\emph{global} level a problem does exist: there's little integrity
protection. Function parameters may help to maintain the program's data
integrity, but it's difficult to ensure the integrity of global data.

In this respect \emph{classes} do a much better job. Their \texttt{private} sections
offer means for class-designers to guarantee the integrity of the classes'
data.

Modules allow us to take the next step up the (separation or integrity)
ladder. Conceptually modules offer program sections which are completely
separated from the rest of the program. Modules define what the outside world
can use and reach, whether they are variables, functions, or types (like
classes). Modules resemble factories: visitors can go to showrooms and meeting
halls, but the locations where the actual products are being designed and
constructed are not open to the public.

In this chapter we cover the syntax, design, and implementation of modules as
offered by the \textbf{C++} programming language. To use modules with the current
edition of the Gnu \texttt{g++} compiler (version 14.2.0) \texttt{+NOTRANS(-\{\}-\{\})std=c++26} (or more
recent) should be specified as well as the \index{module flag} module compilation
flag \index{-fmodules-ts}\texttt{-fmodules-ts}. E.g.,
        \begin{verbatim}
    g++ -c --std=c++26 -fmodules-ts -Wall modsource.cc
\end{verbatim}
Unfortunately, currently it's not all sunshine and roses. One (current?)
consequence of using modules is that the standard that was specified when
compiling those modules is also required when compiling sources using those
modules. If the specified standards differ (e.g., the modules were compiled
with option \texttt{+NOTRANS(-\{\}-\{\})std=c++26}, but for a source file using those modules
\texttt{+NOTRANS(-\{\}-\{\})std=c++23} was specified) then the compilation fails with an error like
    \begin{verbatim}
    error: language dialect differs 'C++26/coroutines', expected 'C++23/coroutines'
\end{verbatim}
    A similar error is reported when the modules were compiled with
\texttt{+NOTRANS(-\{\}-\{\})std=c++23} and the module using source file is compiled specifying
\texttt{+NOTRANS(-\{\}-\{\})std=c++26}. Therefore, once a new standard becomes available, and a
module defining source files is recompiled using the new standard then module
source files using that module must also be recompiled using that standard.

At \texttt{https://gcc.gnu.org/bugzilla/show\_bug.cgi?id=103524} an overview is
published of the (many) currently reported compiler bugs when modules are
compiled by Gnu's \texttt{g++} compiler. Many of those bugs refer to internal
compiler errors, sometimes very basic code that correctly compiles when
modules are not used but that won't compile when using modules. Sometimes
reported errors are completely incomprehensible. Another complexity is
introduced by the fact that, e.g., a class which is defined inside a module is
no longer declared in an interface providing header file. Instead, it is
defined in a module defining source file. Consequently, those module-interface
defining source files must be compiled before the member functions of such a
class can be compiled. But it's not the module's interface's object file
that's important at that point. When the module-interface defining source file
is compiled the compiler defines a \texttt{`module-name'.gcm} file in a
sub-directory \texttt{gcm.cache} (cf. section \ref{GCMCACHE}). Whenever a source
file that uses the module is compiled the compiler must be able to read that
\texttt{gcm.cache/module-name.gcm} file. As a software engineer you cannot simply
compile such module using source files, but \emph{you} must ensure that the
compiler has access to the proper \texttt{module-name.gcm} files.

\section{Syntax}
\typeout{Original Yodl file: modules/syntax.yo}Modules introduce new syntax to \textbf{C++}. In this section the new syntax is
summarized. Note that each of the following syntax specifications end in 
semicolons.

Modules may define sub-components (partitions) defining facilities which
\emph{may} be completely inaccessible outside of the modules
themselves. Partitions are covered in section \ref{PARTITIONS}.

\index{export import Name:Partition;}

\begin{itemize}
\item \texttt{export module Name;}\ \\ 
    defines a \index{module interface unit}\emph{module interface unit}. It must be specified on the source
    file's first line. \texttt{Name} is the module's name, its module-compiled
    interface unit becomes available in \texttt{./gcm.cache/Name.gcm};

\item \texttt{module Name;}\ \\ 
   source files implementing a module (partition) component must start with
    the line \texttt{module Name;}, where \texttt{Name} is the module's name.

\item \texttt{export import Name;}\ \\ 
   inside module (partition) interface units or module (partition) source
    files existing modules are made available using \texttt{export import Name;}
    specifications. Using \texttt{export} is optional. In module interface units
    specifying \texttt{export} means that the exported module is also available
    when sources import the module.  E.g.,
 \begin{verbatim}
    // module interface unit:
    export module Group;
    export import <iostream>;
    ...

    // source file:
    import Group;
    int main()
    {           // cout available via Group
        std::cout << "hello world\n";
    }        
\end{verbatim}
\item \texttt{export module Name:Partition;}\ \\  
   defines a \index{module partition interface unit}\emph{module partition interface unit}. It must be specified on the
    source file's first line. \texttt{Name} is the module's name, \texttt{Partition} is
    a \emph{partition} of module \texttt{Name}. Its compiled interface unit becomes
    available in \texttt{./gcm.cache/Name-Partition.gcm};

\item \texttt{export import :Partition;}\ \\ 
   inside module (partition) interface units or module (partition) source files
    existing module partitions are made available using \texttt{export import
    :Partition;}. In module interface units using \texttt{export} is required,
    otherwise using \texttt{export} is optional.
\end{itemize}

\section{Modules}\label{MODINIT}
\typeout{Original Yodl file: modules/initial.yo}Modules (and partitions, cf. section \ref{PARTITIONS}) are designed using
source files instead of header files. A module always defines a 
    \index{module interface unit}\emph{module interface unit}. The module's interface unit is the module's
equivalent of a header file. Consider (as used in the \textbf{C++} Annotations) defining
the module's interface in a file named `\texttt{modname.cc}' (where \texttt{name} is the
(possibly lowercase) module's name), located in a sub-directory having the
(possibly lowercase) module's name. Using plain (internal) header files should
be avoided when defining and/or using modules.

Here's an example of a module's interface. The module's name is \texttt{Square} and
it declares a function, a class, and a variable:
        \begin{verbatim}
    export module Square;                           // source: modsquare.cc

    export
    {
        double square(double value);

        class Square
        {
            double d_amount;

            public:
                Square(double amount = 0);          // initialize
                void amount(double value);          // change d_amount
                double amount() const;              // return d_amount

                double lastSquared() const;         // returns g_squared
                double square() const;              // returns sqr(d_amount)
        };
    }

    extern double g_squared;
\end{verbatim}
    This module interface merely serves as an illustration. In practice module
interfaces don't contain many different items, but usually just a single
class or, alternatively, a series of utility functions. For now, however, the
slightly overpopulated module \texttt{Square} is used as an initial illustration.

The interface's top-line exports and defines the module name. This must be the
first line of the module's interface unit. Next, the function \texttt{square} and
\texttt{class Square} are declared inside an 
    \index{export compound} \texttt{export} compound. It is possible to export
componentsindividually, but using an `export compound' is convenient. Exported
components can be used outside of the module. Non-exported components (like
\texttt{g\_squared}) are only available to the module's components, and are
therefore like global components, albeit with a restricted (module) scope.

Also note that the variable \texttt{g\_squared} is listed in the interface as
\texttt{extern double g\_squared}: it is therefore a \emph{declaration}, not a
definition. To \emph{define} variables in a module omit \texttt{extern} (as in 
\texttt{double g\_squared}), but to avoid overpopulating modules it's advised to
merely put declarations in module interface units. 

The \texttt{modsquare.cc} file can now be compiled, requiring the \texttt{-fmodules-ts}
compiler option:
        \begin{verbatim}
   g++ -c --std=c++26 -fmodules-ts -Wall modsquare.cc
\end{verbatim}
Compiling \texttt{modsquare.cc} not only produces the file \texttt{modsquare.o}, but
also a sub-directory \index{gcm.cache}\texttt{gcm.cache}, containing the `module compiled interface
file' \texttt{Square.gcm}, which is somewhat comparable to a traditional
pre-compiled header file.  This \texttt{.gcm} file must be available when compiling
source files implementing components of module \texttt{Square}, and it must also be
available to other source files that \emph{import} (i.e., use) module
\texttt{Square}. Consequently, the directories containing such files must therefore
also have \texttt{gcm.cache} sub-directories containing the \texttt{Square.gcm}
file. This requirement is complex, and in practice a so-called \emph{modmapper}
(cf. section \ref{MODMAPPER}) is used to handle the complexity. A simple way to
make module compiled interface files available to all sections of a project is
by defining a top-level directory \texttt{gcm.cache} and using soft-links (like
\texttt{square/gcm.cache}) to the top-level's \texttt{gcm.cache} directory. The
top-level \texttt{gcm.cache} directory and the soft-links in the project's
sub-directories can be prepared before compiling \texttt{square/modsquare.cc}
resulting in the following directory structure:
        \begin{verbatim}
    .
    +-- gcm.cache
    |   +-- Square.gcm
    |
    +-- square
        +-- gcm.cache -> ../gcm.cache
\end{verbatim}
All components of the module \texttt{Square} must specify that they're part of
that module. Traditionally this is realized by using (internal) header
files. But projects using modules should no longer need header files. Instead
of the (traditionally used) \texttt{square.h} and \texttt{square.ih} files a module
    \index{module: frame} \emph{frame} file, tailored to the modules' requirements
can be used when defining source files belonging to modules. In this example
the requirement for the remaining source files of the \texttt{Square} module is
simple: just specify that the source file belongs to the \texttt{Square}
module. Here's a basic \texttt{frame} file, tailored to the members of the \texttt{class
Square}:
        \begin{verbatim}
    module Square;

    Square::()
    {
    }
\end{verbatim}
The \emph{function} square isn't part of the \texttt{class Square}, so when it's
defined the \texttt{Square::} scope is omitted:
        \begin{verbatim}
    module Square;

    double square(double value)
    {
        return g_squared = value * value;
    }
\end{verbatim}
But the members of the \texttt{class Square} can be defined as usual after copying
the \texttt{frame} file to the source filew defining those members. Here is
\texttt{Square's} constructor:
        \begin{verbatim}
    module Square;

    Square::Square(double amount)
    :
        d_amount(amount)
    {}
\end{verbatim}
and the other members are defined analogously:
        \begin{verbatim}
    module Square;

    void Square::amount(double value)
    {
        d_amount = value;
    }
\end{verbatim}
        \begin{verbatim}
    module Square;

    double Square::amount() const
    {
        return d_amount;
    }
\end{verbatim}
        \begin{verbatim}
    module Square;

    double Square::lastSquared() const
    {
        return g_squared;
    }
\end{verbatim}
        \begin{verbatim}
    module Square;

    double square(double value)
    {
        return g_squared = value * value;
    }
\end{verbatim}
As an aside: the members of this class \texttt{Square} are all very simple, and
instead of defining them in separate source files they \emph{could} also be
defined \texttt{inline} in the \texttt{module.cc} file itself. Since the class
\texttt{Square's} interface is exported its members are too, and inline
implementations of its members don't have to be provided in the export 
compound.

The module can now be used by, e.g., the program's \texttt{main} function. Source
files importing a module must \index{import}\emph{import} that module, and if multiple source
files are defined in the top-level directory (like \texttt{main.cc, usage.cc,}
etc.), that directory can define its own \texttt{frame} file. In this initial
example there's only a single \texttt{main.cc} source file, which merely has to
import module \texttt{Square}. But since it also uses \texttt{std::cout} it must import
the
    \index{module compiled system header}\emph{module compiled system header} \texttt{iostream} (cf. section \ref{MODHDR}):
    \begin{verbatim}
    import Square;
    import <iostream>;

    int main(int argc, char **argv)
    {
        std::cout << "the square of " << argc << " is " << square(argc) << '\n';
        Square obj{12};
        std::cout << "the square of 12 is " << obj.square() << "\n"
                    "the last computed square is " << obj.lastSquared() << '\n';

    }
\end{verbatim}
The \texttt{gcm.cache} directories are only required during compilation time.  The
\emph{linker} doesn't use them and once the source files have been compiled a
program can be constructed as before, by linking the object files, resulting
in a binary program.

This example illustrates several characteristics of modules:
    \begin{itemize}
    \item  module interfaces start with \texttt{export module} followed by the
        module's name. Module names are identifiers, possibly followed by
        `\texttt{. identifier}' sequences (like \texttt{My.Module}). 

\item  module names containing a colon (like \texttt{:name} or \texttt{name1:name2})
        are also encountered. Such names refer to module \emph{partitions},
        covered in section \ref{PARTITIONS}.

\item  module interface units \emph{must} begin with an \texttt{export module
        'module-name'} line. Therefore module interface files cannot define
        multiple modules;

\item  components which are accessible to sources outside of the module
        itself must be specified in an \texttt{export} compound or must be
        specified using their own initial \texttt{export} keyword. If no \texttt{export}
        is used the component is only accessible to the components of the
        module;

\item  When using modules project header files are not used anymore.  Module
        compiled system headers (like in \texttt{import $<$iostream$>$;}) \emph{are} 
        used, but preprocessor directives like \texttt{\#include $<$iostream$>$} aren't.

\item  Since module interface units are source files include guards aren't
        required anymore.

\item  Since header files are not used anymore the compiler doesn't have to
        read thousands of lines of header files anymore, significantly
        reducing compilation times.
    \end{itemize}

\section{The gcm.cache directory}\label{GCMCACHE}
\typeout{Original Yodl file: modules/gcmcache.yo}When using modules the module interface units must be compiled before other
sources using the modules or implementing their components can be
compiled. This also holds true for partition interface units (cf. section
\ref{PARTITIONS}). When a module interface unit is compiled the compiler stores
the module's \texttt{.gcm} file (the equivalent of a compiled header file) in the
\index{gcm.cache}\texttt{gcm.cache} sub-directory of the module interface unit. If the module's name
is \texttt{Square}, defined in the \texttt{modsquare.cc} source file then the compiler
produces \texttt{gcm.cache/Sqaure.gcm} as well as the \texttt{modsquare.o} object
file. The \texttt{.gcm} file must be available to any source file importing the
module or implementing one of the module's components.

Usually projects define several sub-directories, and files in those
sub-directories (as well as files in the top-level directory) may import
modules defined in other sub-directories. To ensure that module-compiled
interface units are available to all of the program's source files the
following setup can be adopted:
    \begin{itemize}
    \item  The top-level directory defines a \texttt{gcm.cache} sub-directory
    \item  Each of the project's sub-directories defines a soft-link
        \texttt{gcm.cache -$>$ ../gcm.cache}
    \end{itemize}

This setup works fine as long as all the project's modules have different
names, but that by itself is a good design principle.

\subsection{Module-compiled system header files}\label{MODHDR}
    \typeout{Original Yodl file: modules/modhdr.yo}Traditionally system header files were included to declare classes like
\texttt{std::string} and \texttt{std:ostream}. But when using modules including headers
is deprecated and instead their module-compiled equivalents should be imported
using \texttt{import} statements.

\index{module: system header} 
To avoid recompiling system header files for different projects consider
storing module-compiled headers in \texttt{/usr/include/c++/14} (here, '14' is
\texttt{g++'s} main version number: update it to your actually installed
version). Using the procedure described in this section project source files
can import module-compiled system headers (assuming that projects have defined
\texttt{./gcm.cache} directories as described in the previous section).
    \begin{itemize}
    \item  In the project's \texttt{gcm.cache} directory define the soft-link 
        \texttt{usr -$>$ /usr}; 
    \item  To construct the module-compiled version of a system header file
        (e.g., \texttt{iostream -$>$ iostream.gcm}) then as execute \emph{root} in
        \texttt{/usr/include/c++/14} execute the command
 \begin{verbatim}
    g++ --std=c++26 -fmodules-ts -x c++-system-header iostream
\end{verbatim}
       (if the \textbf{C++} standard isn't \texttt{c++26} then adapt it to the 
        \textbf{C++} standard that should be used)
    \item  Then move the file \texttt{iostream.gcm} to the current directory:
 \begin{verbatim}
    mv gcm.cache/usr/include/c++/14/iostream.gcm .
\end{verbatim}
    \end{itemize}

The same procedure can also be used to module-comile header files of installed
libraries. E.g., the \textbf{bobcat}(7) library stores its headers in
\texttt{/usr/include/bobcat}. To module-compile its \texttt{arg} header file:
    \begin{itemize}
    \item \texttt{cd /usr/include}
    \item \texttt{g++ +NOTRANS(-\{\}-\{\})std=c++26 -fmodules-ts -x c++-system-header bobcat/arg}
    \item \texttt{mv gcm.cache/usr/include/bobcat/arg.gcm bobcat/}
    \end{itemize}

Note: currently (using \texttt{g++} version 14.2.0) compilation sequence issues may
be encountered when module-compiling system headers. For some system headers
module-compilation fails if some other module-compiled system headers are
already available. Those issues can usually be `solved' by first moving all
existing .gcm files to, e.g., a \texttt{./tmp} sub-directory, followed by the
module-compilation of the intended system header file, and then moving the
\texttt{tmp/$*$.gcm} files back to the current directory.

\subsection{Module-compiled headers of locally developed libraries}\label{LOCHDR}
    \typeout{Original Yodl file: modules/locallib.yo}In addition to header files used for system libraries locally developed
libaries exist. Such libraries may very well have traditionally been
developed, using standard header files. But once project start using modules
it might be attractive to convert the traditional header files to
module-compiled header files. 

To module-compile a standard header file (e.g., an existing \texttt{support.h}
header file in a \texttt{support} sub-directory) to a module-compiled header file
issue the command
 \begin{verbatim}
    g++ --std=c++26 -Wall -fmodules-ts -x c++-header support.h
\end{verbatim}
    The compiler then writes the module-compiled header file \texttt{support.h.gcm}
in the \texttt{./gcm.cache/,/} sub-directory (note: in \texttt{gcm.cache's} `comma'
sub-directory).  

When a library is constructed there are usually multiple header files, between
which some hierarchy may exist. Consider a library consisting of three
classes: \texttt{Top}, depending on \texttt{Middle}, which in turn depends on \texttt{Base}
Each class is defined in its own sub-directory. E.g., \texttt{base/base.h}:
    \begin{verbatim}
    #ifndef INCLUDED_BASE_
    #define INCLUDED_BASE_

    #include <fstream>

    class Base
    {
        std::ifstream d_in;
        public:
            Base();
    };

    inline Base::Base()
    :
        d_in("demo.in")
    {}

    #endif
\end{verbatim}
\texttt{middle/middle.h}:
    \begin{verbatim}
    #ifndef INCLUDED_MIDDLE_
    #define INCLUDED_MIDDLE_

    #include <string>

    #include "../base/base.h"

    class Middle
    {
        std::string d_text;
        Base d_base;
    };

    #endif
\end{verbatim}
and \texttt{top/top.h}:
    \begin{verbatim}
    #ifndef INCLUDED_TOP_
    #define INCLUDED_TOP_

    #include <vector>
    #include "../middle/middle.h"

    class Top
    {
        std::vector<std::string> d_vect;
        Middle d_middle;
    };

    #endif
\end{verbatim}
To module-compile the library's headers the \texttt{gcm.cache} organization as
described in section \ref{MODINIT} is used (a \texttt{gcm.cache} directory is
defined at the project's top-level directory, while sub-directories define
\texttt{gcm.cache} soft-links to the top-level \texttt{gcm.cache} directory). Next each
header file is module-compiled whereafter the \texttt{gcm.cache} subdirectory
contains: 
 \begin{verbatim}
    ,/base.h.gcm
    ,/middle.h.gcm
    ,/top.h.gcm
    usr -> /usr
\end{verbatim}
This, however, is not the organization which is expected by programs that need
to use the module-compiled headers. To compare: the module-compiled system
header files are, together with the system header files themselves, located in
\texttt{/usr/include/c++/14} (like \texttt{iostream} and \texttt{iostream.gcm}). When 
module-compiled headers should be used by programs a similar organization is
expected. But that's easily realized by defining a sub-directory (e.g.,
\texttt{hdrs}) containing soft-links to each of the library's header files and
to each of the library's module-compiled header files. If \texttt{hdrs} is a
sub-directory of the libraary's top-level directory then it contains
 \begin{verbatim}
    base.h       -> ../base/base.h
    base.h.gcm   -> ../gcm.cache/,/base.h.gcm
    middle.h     -> ../middle/middle.h
    middle.h.gcm -> ../gcm.cache/,/middle.h.gcm
    top.h        -> ../top/top.h
    top.h.gcm    -> ../gcm.cache/,/top.h.gcm
\end{verbatim}
As elaborated in the following two sub-sections there are two ways programs
using the local library can import the library's module-compiled headers: by
using a relative path to the \texttt{hdrs} sub-directory or by using an absolute
path to the \texttt{hdrs} subdirectory.

\subsubsection{Using a relative location}
        \typeout{Original Yodl file: modules/relative.yo}Once the local library's headers and module-compiled headers are available via
the local library's \texttt{hdr} sub-directory they can be imported by source
files which do not belong to the library. 

Suppose the library's header files are imported by \texttt{main.cc}, defined in the
directory \texttt{\textasciitilde{}/project}:
    \begin{verbatim}
    import "base.h";
    import "middle.h";
    import "top.h";

    int main()
    {
        Base base;
        Middle middle;
        Top top;
    }
\end{verbatim}
Furthermore, assume the local library's top-level directory is
\texttt{\textasciitilde{}/support/locallib} (and so \texttt{\textasciitilde{}/support/locallib/hdrs} contains the
soft-links to its header files and module-compiled header files).

To make the library's headers available to \texttt{main.cc} two soft-links to
relative destinations can be defined:
    \begin{itemize}
    \item  in \texttt{\textasciitilde{}/project} define a soft-link to the library's \texttt{hdrs}
        directory: 
 \begin{verbatim}
    ln -s ../support/locallib/hdrs .
\end{verbatim}
    \item  in the \texttt{\textasciitilde{}/project/gcm.cache/,/} (note: comma!) sub-directory define
        a soft-link to the just defined \texttt{hdrs} soft-link:
 \begin{verbatim}
    ln -s ../../hdrs .
\end{verbatim}
    \end{itemize}

Once these links are available \texttt{main.cc} can be compiled using
 \begin{verbatim}
    g++ -c --std=c++26 -fmodules-ts -isystem hdrs main.cc
\end{verbatim}
\begin{itemize}
    \item  In practice the program using the library's headers also needs linker
        options: these are used as always, and need no further modifications.
    \item  The soft-links must be relative links: if the local library's \texttt{hdr}
        is located in a completely different location then the soft-link
        \texttt{\textasciitilde{}/project/hdrs} must point to that directory using a relative path
        specification. 
    \item  The names of the two soft-links must be identical, but the name of
        the project's soft-link to the library's \texttt{hdrs} directory does not
        have to be \texttt{hdrs}.
    \end{itemize}

\subsubsection{Using an absolute location}
        \typeout{Original Yodl file: modules/absolute.yo}When importing a local library's header using two soft-links to relative
destinations it's also possible to define a single soft-link to the absolute
location of the directory containing the library's headers. There's no
compelling reason for using relative or absolute destinations. Maybe if the
relative path specification becomes complex using the absolute destination is
slightly more attractive. 

Using the \texttt{\textasciitilde{}/project/main.cc} from the previous section define a soft-link
to the absolute location of the library's \texttt{hdrs} sub-directory in the
project's \texttt{gcm.cache} sub-directory (note: here no comma is used):
 \begin{verbatim}
    ln -s ~/support/locallib/hdrs gcm.cache
\end{verbatim}
    Next compile \texttt{main.cc} using
 \begin{verbatim}
g++ -c -fmodules-ts -isystem ~/support/locallib/hdrs main.cc
\end{verbatim}
\begin{itemize}
\item  In \texttt{gcm.cache} the full path to \texttt{hdrs} is not required, but at least
    first sub-directory name must be be specified (since \texttt{\textasciitilde{}/...} refers to
    the user's home directory, which commonly begins at \texttt{/home/...} the link
    could be defined as \texttt{ln -s /home gcm.cache/}).
\item  The soft-link name itself can freely be chosen and doesn't have to be
    equal to the final destination. E.g., after defining the links
 \begin{verbatim}
    ln -s ~/support/locallib/hdrs /tmp/locallib
    ln -s /tmp gcm.cache
\end{verbatim}
    the compilation command is:
 \begin{verbatim}
    g++ -c -fmodules-ts -isystem /tmp/locallib main.cc
\end{verbatim}
\end{itemize}

\subsection{Local header files}
    \typeout{Original Yodl file: modules/localhdr.yo}Although local header files can also be module-compiled doing so is deprecated 
as using (local) headers is probably a left-over from the traditional program
development era.

But, for the sake of completeness, local header files \emph{can} be
module-compiled. But note that once a header file is compiled \texttt{using
namespace} declarations specified in header files are lost when the header
file is either included or imported. Compiled local header files are
stored in the \texttt{gcm.cache/,/} (note: a comma) sub-directory.  They're
automatically used when either their header files are included (e.g.,
\texttt{\#include "header.h"}) or imported (using \texttt{import "header.h";}).

\section{Namespaces}
\typeout{Original Yodl file: modules/namespaces.yo}Modules and namespaces are mutually independent. Modules (and/or partitions,
cf. section \ref{PARTITIONS})
can define (contain) namespaces and/or they can define components in
namespaces. Source files importing such modules must either explicitly specify
the namespace of such components or they can specify a \texttt{using namespace}
declarations avoiding the explicit namespace specification when referring to
components living in those namespaces.

Here is a simple example of a module exporting a variable which is defined in
a namespace:
    \begin{verbatim}
    export module NS;

    export import <cstddef>;

    export namespace FBB
    {
        extern size_t g_count;
    }
\end{verbatim}
  It's a very basic example, illustrating the essence of defining a namespace
completely covering the module's export compound. Variations are possible: a
namespace could completely surround the export compund, a namespace could be
defined inside the export compound, only some of the module's components could
belong to a namespace, non-exported components could belong to a namespace,
multiple namespaces could be used, etc., etc..

To use the variable \texttt{g\_count}, its module is imported and its namespace is
specified as usual. E.g.,
    \begin{verbatim}
    import NS;

    import <iostream>;

    int main()
    {
        ++FBB::g_count;

        std::cout << FBB::g_count << '\n';
    }
\end{verbatim}
Alternatively the source file could specify some \texttt{using namespace}
declarations so the repeated namespace specifications can be avoided:
    \begin{verbatim}
    import NS;
    import <iostream>;

    using namespace std;
    using namespace FBB;

    int main()
    {
        ++g_count;
        cout << g_count << '\n';
    }
\end{verbatim}
Some notes:
    \begin{itemize}
    \item  Since module interfaces \emph{must} start with \texttt{export module} modules
        cannot be defined inside namespaces.  Constructions like
 \begin{verbatim}
    namespace Area
    {
        export module Nested;
        ... declarations of components of Nested
    }
\end{verbatim}
        won't compile. But as shown, defining a namespace section inside a
        module is fine.
    \item  Modules cannot be imported inside a namespace area as \texttt{import}
        declarations cannot be nested (i.e., they must be at global scope) So
        constructions like the following also won't compile:
 \begin{verbatim}
    namespace FBB
    {
        import NS;
    }
\end{verbatim}
    \end{itemize}

\section{Templates}
\typeout{Original Yodl file: modules/templates.yo}Templates are recipes used by the compiler to construct code tailored to
specific types. Since they're recipes they cannot be compiled to running
code. Traditionally templates are implemented in header files, and when used
the compiler instantiates templates with the correct types using the
templates' recipes.

Since modules are defined in source files there are no header files anymore
when using modules. Modules specify their components in source files,
replacing the traditional header files: by defining templates in a module
interface unit the template's recipe character is kept, and they are
instantiated when needed.

Here's an initial example. A \texttt{module Adder} exports a function template
\texttt{add} adding two values and returning their sum:
    \begin{verbatim}
    export module Adder;

    export
    {
        template <typename Type>
        Type add(Type const &t1, Type const &t2)
        {
            return t1 + t2;
        }
    }
\end{verbatim}
Source files importing \texttt{Adder} can now add values of types supporting the
\texttt{+} operator:
    \begin{verbatim}
    import Adder;

    import <iostream>;
    import <string>;

    using namespace std;

    int main()
    {
        cout << add(1, 2) << '\n' <<
                add(1.1, 2.2) << '\n' <<
                add("hello "s, "world"s) << '\n';
    }
\end{verbatim}
producing the following output:
        \begin{verbatim}
    3
    3.3
    hello world
\end{verbatim}
\subsection{Class templates}\label{MODTEMP}
    \typeout{Original Yodl file: modules/classtemplates.yo}In the previous section a function template was defined in a module interface
unit. This section covers the definition of a class template. The class
template \texttt{SortMap} offers the facilities of an \texttt{unordered\_map}, but also
has two \texttt{sort} members. Both return a vector with pointers to the elements
of the unordered map. One member returns pointers to the elements sorted by
their key values, the other member receives a functor, returning a vector of
pointers to the elements which are sorted according to the functor's
decisions.

The module interface unit defines the \texttt{SortMap} module. It declares the
class template \texttt{SortMap}. The module, like any module, can be imported in
other source files, like a source file \texttt{main.cc}. The \texttt{main} function
inserts its arguments into \texttt{SortMap} and then shows the inserted values:
first ordered by the map's keys, then ordered by the map's values:
    \begin{verbatim}
    import SortMap;

    import <iostream>;
    import <string>;

    using namespace std;

    int main(int argc, char **argv)
    {
        SortMap<string, size_t> sortMap;

        for (; argc--; )                                    // fill sortMap
            sortMap.emplace(argv[argc], argc);

        for (auto const *ptr: sortMap.sort())               // sort by key
            cout << ptr->first << ' ' << ptr->second << "; ";
        cout.put('\n');

        for (auto const *ptr: sortMap.sort(                 // sort by value
                                    [&](auto const &lhs, auto const &rhs)
                                    {
                                        return lhs->second < rhs->second;
                                    }
                                )
        )
            cout << ptr->first << ' ' << ptr->second << "; ";
        cout.put('\n');
    }
\end{verbatim}
When calling \texttt{a.out one two three four five six} it outputs
 \begin{verbatim}
    a.out 0; five 5; four 4; one 1; six 6; three 3; two 2
    a.out 0; one 1; two 2; three 3; four 4; five 5; six 6
\end{verbatim}
All members of class templates are templates, and as with header files
containing class templates there's only one source file defining the module
interface unit: it contains the class template's interface and also the
implementations of its members. There is, however, an escape route: it's
covered in section \ref{PARTITIONS}. But in this section the standard way to 
implement class templates is covered. 

When using a single file there's maybe one drawback: the module interface
unit, as it must contain the full implementation of the class template, may
quickly grow to a very large file, which is hard to maintain. To simplify
maintenance it is advised to adopt here the \emph{one function, one file} design
principle also: the module interface unit itself exports the class interface,
and then uses an \texttt{\#include} preprocessor directive to add the class members'
implementations:
    \begin{verbatim}
    export module SortMap;

    export import <unordered_map>;
    export import <vector>;
    import <algorithm>;

    export
    {
        template <typename Key, typename Value>
        class SortMap: public std::unordered_map<Key, Value>
        {
            using UMap = std::unordered_map<Key, Value>;
            using ValueType = typename UMap::value_type;
            using Vect = std::vector<ValueType const *>;

            private:
                Vect d_sortVect;

            public:
                Vect const &sort();             // sort the keys        // 1.f

                template <typename Functor>     // use a functor        // 2.f
                Vect const &sort(Functor const &functor);
        };
    }

    #include "sortmap.f"
\end{verbatim}
The design of the \texttt{class SortMap} itself is standard. At the top of the
module interface unit the \texttt{SortMap} module name is defined followed by
importing some module compiled system header files. Since \texttt{algorithm} is
only used internally by the member functions it's not exported. But imported
components \emph{must} be specified at the top of module source files, and so
\texttt{algorithm} cannot be imported by, e.g., \texttt{sortmap.f}. 

The file \texttt{sortmap.f} itself merely includes the files implementing the two
\texttt{sort} members, keeping the module interface unit as clean as possible. Here
is \texttt{sortmap.f}:
    \begin{verbatim}
    #include "sort1.f"
    #include "sort2.f"
\end{verbatim}
Each of its included files contain the definition of one member
function. A comment in the class's interface indicates which function is
defined in which file. Here's the first \texttt{sort} member (\texttt{sort1.f}):
    \begin{verbatim}
    template <typename Key, typename Value>
    SortMap<Key, Value>::Vect const &SortMap<Key, Value>::sort()
    {
        d_sortVect.clear();

        for (auto const &el: *this)
            d_sortVect.push_back(&el);

        std::sort(d_sortVect.begin(), d_sortVect.end(), 
            [&](auto const *lhs, auto const *rhs)
            {
                return lhs->first < rhs->first;
            }
        );

        return d_sortVect;
    }
\end{verbatim}
And here's the second \texttt{sort} member, accepting a functor (\texttt{sort2.f})
    \begin{verbatim}
    template <typename Key, typename Value>
    template <typename Functor>
    SortMap<Key, Value>::Vect const &SortMap<Key, Value>::sort(
                                            Functor const &functor)
    {
        d_sortVect.clear();

        for (auto const &el: *this)
            d_sortVect.push_back(&el);

        std::sort(d_sortVect.begin(), d_sortVect.end(), functor);

        return d_sortVect;
    }
\end{verbatim}
\section{Partitions}\label{PARTITIONS}
\typeout{Original Yodl file: modules/partitions.yo}

In the introduction section of this chapter it was stated that modules offer
new, conceptual features: modules offer program sections which are completely
separated from the rest of the program, but modules themselves can define
subsections (called \index{partition}\emph{partitions}) which can define components
(classes, types, variables, etc.) which are \emph{only} accessible to the module
and its partitions.

Within the restriction that partitions can be defined so that they're only
accessible to their module and their sibling-partitions the access rights of
\emph{classes} defined in partitions are identical to those of classes in
general: public members are accessible to their users, protected members are
available to classes derived from those classes, while private members cannot
be accessed from outside of those classes.

\begin{figure}[tbp]
\centerline{\epsffile{modules/partition.eps}}
\caption{\label{MathPart}Partitions of the `Math' module}
\end{figure}

Figure \ref{MathPart} illustrates a simple module (\texttt{Math}) having two
partitions. It shows the relationships between the module and its partitions
in the same way as commonly used for classes: the most basic (least dependent)
partition is on top, the partition depending on the topmost partition is in
the middle, and the module itself, depending on both partitions, is at the
bottom. The \texttt{Math} module defines a class \texttt{Math}, having a member
returning the sum of two \texttt{size\_t} values and a member \texttt{count} returning
the number of performed additions. It's a very basic design merely
illustrating the way partitions are designed. 

The object of \texttt{class Add} performs an addition, and the object of \texttt{class
Utility} keeps track of the number of additions that were performed.
Both \texttt{Add} and \texttt{Utility} are defined as classes in their own partitions:
\texttt{Math:Utility} and \texttt{Math:Add}.

\index{partition: syntax} Note that partitions themselves are not classes. When
defining a \index{partition interface unit}\emph{partition interface unit} only a single colon is used instead
of two, as used then defining cass member functions (so \texttt{Math:Utility} and
not \texttt{Mat::Utility}).

The \texttt{Math} interface unit exports \texttt{class Math}, allowing code which does
not belong to the module \texttt{Math} itself to define \texttt{Math} objects after
importing the \texttt{Math} module:
    \begin{verbatim}
    import Math;
    void fun()
    {
        Math math;
        ...
    }
\end{verbatim}
Since the \texttt{class Math} has data members \texttt{Utility d\_util} and \texttt{Add d\_add}
these classes must be known inside the \texttt{Math} module interface unit
(\texttt{modmath.cc}), but also by software defining objects of \texttt{class Math}
(comparable to the requirement to, e.g., include \texttt{$<$string$>$} when a class
defines a \texttt{std::string} data member). Therefore the \texttt{Math} module
interface unit specifies \texttt{export import} for the \texttt{Utility} and \texttt{Add}
partitions. As we'll shortly see these \texttt{export} specifications do not imply
that software merely using the facilities of the \texttt{Math} module can also
define, e.g., \texttt{Math:Utility} objects: the partitions can still remain
`private' to the \texttt{Math} module. Here is the \texttt{Math} module interface unit,
defined in \texttt{math/modmath.cc}:
    \begin{verbatim}
    export module Math;

    export import :Utility;
    export import :Add;

    export
    {
        class Math
        {
            Utility d_util;
            Add d_add;

            public:
                Math();
                size_t count() const;
                size_t add(size_t lhs, size_t rhs);
        };
    }
\end{verbatim}
The design of the module \texttt{Math} defining partitions introduces a completely
new level of separation: the components of partitions are like nested classes
but don't result in `class overpopulation': partitions are not defined
\emph{inside} modules but are completely separately defined from their modules,
while making their facilities \emph{only} available to their modules and sibling
partitions. And although probably not illustrating good design: by defining
\texttt{export} compounds in partition interface units the elements in those
compounds become directly available to using software essentially turning the
partition into a module.

\subsection{The Math:Utility partition}
    \typeout{Original Yodl file: modules/utility.yo}The \texttt{Math:Utility} partition is the most basic of the two \texttt{Math}
partitions. It does not depend on features of either the \texttt{Math} module or
the \texttt{Math:Add} partition. Since it \emph{does} use the \texttt{size\_t} type, it
specifies \texttt{export import $<$cstddef$>$}. Here, because of its \texttt{export}
specification, the definitions in \texttt{cstddef} are also available when
\texttt{Utility} is imported, and since the \texttt{Math} module itself exports
\texttt{:Utility} also to software importing \texttt{Math}.

As \texttt{Utility} is a \texttt{Math} partition its partition interface unit starts by
specifing this:
    \begin{verbatim}
    export module Math:Utility;
\end{verbatim}
    The colon indicates that this is not a plain module but a partition (note
that the first line \emph{must} start by specifying \texttt{export}). It contains
\emph{only} non-exported components, but as it's a partition of a module, all the
partition's components are fully available to its module and its sibling
partitions. Its \texttt{class Utility} has two simple members, both very simple,
never changing one-liners. Because of that they're implemented in-line. Here's
the \texttt{Utility} partition interface unit:
    \begin{verbatim}
    export module Math:Utility;

    export import <cstddef>;

    class Utility
    {
        size_t d_count;

        public:
            Utility();

            void inc();
            size_t count() const;
    };

    inline void Utility::inc()
    {
        ++d_count;
    }

    inline size_t Utility::count() const
    {
        return d_count;
    }
\end{verbatim}
Defining members inline is not required, but is an option. For example, its
constructor could very well also have been defined inline, but (for
illustration purposes) is defined in a separate source file. As \texttt{Utility's}
constructor is a partition source file it starts by specifying its module
(\texttt{Math}), followed by importing the partition component (\texttt{:Utility}) which
is defined in this source file:
    \begin{verbatim}
    module Math;
    import :Utility;

    Utility::Utility()
    :
        d_count(0)
    {}
\end{verbatim}
\subsection{The Math:Add partition}
    \typeout{Original Yodl file: modules/add.yo}Different from the \texttt{Math:Utility} partition the \texttt{Math:Add} partition
\emph{does} depend on another partition: it depends on \texttt{Math:Utility}. Like
\texttt{Utility's modutility.cc} it starts its \texttt{modadd.cc} file by exporting its
partition name. But then it imports \texttt{:Utility}, since that partition is used
by \texttt{Math:Add}, making available \emph{all} components of that partition. 

Since \texttt{:Utility} already imports \texttt{$<$sstddef$>$ :Add} can also use
\texttt{size\_t}. For \texttt{:Add} the \texttt{:Utility} partition wouldn't have to specify
\texttt{export} in front of \texttt{import $<$stddef$>$} since all components of imported
partitions are available to both the module and its partitions. But by using
\texttt{export import $<$cstddef$>$} users of the \texttt{Math} module automatically receive
\texttt{$<$cstddef$>$'s} definitions (among which \texttt{size\_t}). Here's the \texttt{Math::Add}
partition interface unit (again: notice that the interface doesn't contain an
export compound):
    \begin{verbatim}
    export module Math:Add;

    import :Utility;

    class Add
    {
        Utility &d_utility;

        public:
            Add(Utility &utility);
            size_t sum(size_t lhs, size_t rhs);
    };
\end{verbatim}
For this partition no members were defined inline (although that would also
have been possible). Instead all members were defined in separate source
files. Here is \texttt{class Add's} constructor:
    \begin{verbatim}
    module Math;
    import :Add;

    // export import :Utility;  OK, but superfluous

    Add::Add(Utility &utility)
    :
        d_utility(utility)
    {}
\end{verbatim}
and its \texttt{sum} member:
    \begin{verbatim}
    module Math;
    import :Add;

    size_t Add::sum(size_t lhs, size_t rhs)
    {
        d_utility.inc();
        return lhs + rhs;
    }
\end{verbatim}
\subsection{The Math module's members}
    \typeout{Original Yodl file: modules/math.yo}Now that the interfaces of the \texttt{Math} module and its partitions have been
defined (cf. figure \ref{MathPart}) the \texttt{Math} module's members can be 
defined. The constructor of \texttt{class Add} in the \texttt{Math:Add} partition
needs a reference to a \texttt{Utility} object which it receives from \texttt{Math}
constructor:
    \begin{verbatim}
    #include "math.i"
    //import Math;

    Math::Math()
    :
        d_add(d_util)
    {}
\end{verbatim}
Since \texttt{class Utility's count} member is public, it can be called by the
\texttt{Math::count} member:
    \begin{verbatim}
    import Math;

    size_t Math::count() const
    {
        return d_util.count();
    }
\end{verbatim}
and finally, \texttt{Math's add} member calls \texttt{Add's sum} member, defined in the
\texttt{Math:Add} partition to obtain the sum of two positive integral values:
    \begin{verbatim}
    import Math;

    size_t Math::add(size_t lhs, size_t rhs)
    {
        return d_add.sum(lhs, rhs);
    }
\end{verbatim}
\subsection{Using the Math module}
    \typeout{Original Yodl file: modules/usingmath.yo}Now that the \texttt{Math} module has been developed it can be used by a
program. The exported facilities offered by a module are available after
importing the module. Note that although a module may \texttt{export import} its
partitions only partition components defined in their \texttt{export} compound are
available to source files not belonging to the module itself. As
\texttt{Math:Utility} exports \texttt{$<$cstddef$>$} source files importing \texttt{Math}
automatically also can use \texttt{cstddef's} features.

Here's a \texttt{main} function importing \texttt{Math} and using its facilities to add
two positive integral numbers. Header files are not used anymore, and the
implementation of the \texttt{main} function is equal to the implementation when
using header files. However, compared to the latter implementation the
compilation of a program using modules requires significantly less time, and
the design of modules using partitions may offer better isolation of
components that are mere building blocks of the those modules. 

Here is the implementation of the \texttt{main} function using the \texttt{Math} module:
    \begin{verbatim}
    import Math;
    import <iostream>;

    using namespace std;

    int main()
    {
        Math math;

        cout << "Initial number of additions: " << math.count() << "\n"
                "Enter two pos. values to add: ";

        size_t lhs;
        size_t rhs;
        cin >> lhs >> rhs;
        cout << "their sum is " << math.add(lhs, rhs) << "\n"
                "total number of performed additions: " << math.count() << '\n';
    }
\end{verbatim}
\subsection{Partitioned class templates}
    \typeout{Original Yodl file: modules/classtemplates2.yo}In section \ref{MODTEMP} the a class template \texttt{SortMap} was defined in a
module interface unit. Like class templates in header files class templates in
a module interface files may grow large because the file not only contains the
class template's interface but also the implementations of its
members. Consequently a full recompilation is required when only a single
member function is modified. Recompilations cannot completely be avoided, but
by using module partitions complete recompilation can often be avoided.

Some maintenance complications, however, remain: once a class template's
member is modified the modification is not visible in members that use that
member. But this dependency issue always plays a role when using templates:
once a template has been modified all code using the template needs to be
recompiled.

In the current section class templates are implemented using module
partitions, each containing a member of the class template. The previously
developed \texttt{SortMap} module consists of three components: the class interface
and two \texttt{sort} members functions. Now when using partitions each
component will be defined in its own partition, and the module itself contains
\texttt{export import} statements for each partition which must be accessible by
code using the module. Consequently the \texttt{modsortmap.cc} module interface
unit is remarkably simple:
    \begin{verbatim}
    export module SortMap;

    export import :Interface;
    export import :Sort1;
    export import :Sort2;
\end{verbatim}
Note that even the class interface is defined in a partition: it cannot be
defined in the module interface unit itself, since partitions \emph{can} depend
on other partitions, but not on the module itself as the partitions must (as
they are imported by the module) be available before the module itself can be
compiled. Partitions, however, \emph{can} depend on other partitions, so a
partition implementing a \texttt{sort} function can import a partition providing
the class's interface.

As the \texttt{:Interface} partition merely specifies what's offered by the
\texttt{class SortMap} it doesn't depend on the other partitions. So it merely
declares but does not contain the implementations of the \texttt{sort} members, and
thus it does not itself have to import the \texttt{alorithm} module-compiled
header:
    \begin{verbatim}
    export module SortMap:Interface;

    export import <unordered_map>;
    export import <vector>;

    export
    {
        template <typename Key, typename Value>
        class SortMap: public std::unordered_map<Key, Value>
        {
            using UMap = std::unordered_map<Key, Value>;
            using ValueType = typename UMap::value_type;
            using Vect = std::vector<ValueType const *>;

            private:
                Vect d_sortVect;

            public:
                Vect const &sort();             // sort the keys        // 1.f

                template <typename Functor>     // use a functor        // 2.f
                Vect const &sort(Functor const &functor);
        };
    }
\end{verbatim}
On the other hand, the implementations of the two \texttt{sort} members \emph{do}
depend on the interface, since they implement their declarations. They
also depend on the facilities provided by the \texttt{algorithm} module-compiled
header. Both are therefore imported. Here's the implementation of the first
\texttt{sort} member in the \texttt{:Sort1} partition:
    \begin{verbatim}
    export module SortMap:Sort1;

    import :Interface;
    import <algorithm>;

    export
    {
        template <typename Key, typename Value>
        SortMap<Key, Value>::Vect const &SortMap<Key, Value>::sort()
        {
            d_sortVect.clear();

            for (auto const &el: *this)
                d_sortVect.push_back(&el);

            std::sort(d_sortVect.begin(), d_sortVect.end(),
                [&](auto const *lhs, auto const *rhs)
                {
                    return lhs->first < rhs->first;
                }
            );

            return d_sortVect;
        }
    }
\end{verbatim}
The second \texttt{sort} member is implemented analogously:
    \begin{verbatim}
    export module SortMap:Sort2;

    import :Interface;
    import <algorithm>;

    export
    {
        template <typename Key, typename Value>
        template <typename Functor>
        SortMap<Key, Value>::Vect const &SortMap<Key, Value>::sort(
                                                Functor const &functor)
        {
            d_sortVect.clear();

            for (auto const &el: *this)
                d_sortVect.push_back(&el);

            std::sort(d_sortVect.begin(), d_sortVect.end(), functor);

            return d_sortVect;
        }
    }
\end{verbatim}
The \texttt{main} function can remain as provided in section \ref{MODTEMP}. When
constructing the program the partition dependencies must be taken into
account:
    \begin{itemize}
    \item  first the \texttt{:Interface} partition is compiled;
    \item  then, in any order, the \texttt{:Sort1} and \texttt{:Sort2} partitions are
        compiled; 
    \item  finaly \texttt{main.cc} is compiled and the compiled object files are
        linked resulting in the final program.
    \end{itemize}

\section{Module mapping}\label{MODMAPPER}
\typeout{Original Yodl file: modules/modmap.yo}Modules cannot mutually import each other. Consequently there's always a
linear, non-circular module hierarchy, which should be acknowledged when
compiling files defining and using modules. In this section the requirements
for projects using modules are covered, as well as a procedure that can be
adopted when constructing such projects.

With modules traditional headers (\texttt{.h} files) should be avoided.  System
header files (cf. section \ref{MODHDR}) still exist, but for those \texttt{import}
statements should be used or made available. For locally developed libraries
module-compiled header files can also be used (cf. section \ref{LOCHDR}).

It can be difficult to determine which module sections can
immediately be compiled, and which ones depend on already compiled
sections. Moreover, source files belonging to modules but not defining their
interface units may import modules which aren't yet available when
compiling the module's interface unit. For example, module
\texttt{Basic's} interface unit is independent of other modules:
        \begin{verbatim}
    export module Basic;

    export
    {
        class Basic
        {
            public:
                void hello() const;
         };
    }
\end{verbatim}
But a module \texttt{Second} imports \texttt{Basic} and therefore the compilation of
its module interface file depends on the availability of
\texttt{gcm.cache/Basic.gcm}:
        \begin{verbatim}
    export module Second;

    export import Basic;
    export import <iosfwd>;

    export
    {
        class Second
        {
            public:
                static std::string hello();
        };
    }
\end{verbatim}
Consequently \texttt{basic/modbasic.cc} must be compiled before compiling
\texttt{second/modsecond.cc}. However, \emph{module} \texttt{Second} may export a \emph{class}
\texttt{Second}, and an object of \texttt{class Second} \emph{could} be defined by a member
of the \emph{class} \texttt{Basic}, exported by the \texttt{Basic} module:
        \begin{verbatim}
    module Basic;

    import Second;
    import <iostream>;
    import <string>;

    using namespace std;

    void Basic::hello() const
    {
        cout << Second::hello() << '\n';
    }
\end{verbatim}
In such situations the module interface units must first, and in the right
order, be compiled. Then, once they are available the remaining source files
of the modules can be compiled.

This two-step process (first compile the module interface units in the right
order and then compile the remaining source files) quickly becomes a
challenge, which is commonly handled by using a \index{module mapper}\emph{module mapper}. Module
mappers inspect the modules of a project, building their dependency tree, and
maybe compiling the module interface units in the right order. The module
mapper \textbf{icmodmap}(1), a utility program of the \textbf{icmake}(1) project, is
such a module mapper.

By default (but configurable via options) \textbf{icmodmap}(1) expect projects
using modules to be organized as follows:
    \begin{itemize}
    \item  The project's top-level directory contains a file \texttt{CLASSES}, where
        each line (ignoring empty lines and \textbf{C++} comment) specifies the
        name of a sub-directory implementing one of the project's
        components. Partitions can be defined in their own sub-directories or
        in sub-directories of the module to which they belong. Sub-directories
        do not have to define modules, but all of the project's source files
        \emph{may} import modules;
    \item  The top-level directory itself may also define a module;
    \item  If the project defines a program, the project's top-level directory
        contains source files (like \texttt{main.cc} defining the \texttt{main}
        function);
    \item  To simplify locating source files defining module or partition
        interface units it is advises to start their names with \texttt{mod},
        followed by the (optionally lower-case) name of the module or
        partition they define. Following this convention a module \texttt{Support}
        is defined in the file \texttt{modsupport.cc};
    \item  It's considered good practice to export only a single class from a
        module or parition unit, but (like traditional header files) this is
        not a formal requirement.
    \end{itemize}

\textbf{Icmodmap}(1) inspects each of the source files in the project's top-level
directory and in each sub-directory specified in the \texttt{CLASSES} file. If a
source file's first line starts with \texttt{export module} it's a module or
partition interface unit. If so, its module or partition name is stored in a
data-base. Since module and partition interface units may themselves import
modules and/or partitions the current interface depends on those imported
components. Those imported components are declared in its data-base
registering that the current interface unit depends on those imported
components.

Likewise, if another source file imports modules or implements a component of
a module or partition then those modules (and/or paritions) are also declared
in its data-base.

Once all source files were inspected \textbf{icmodmap}(1) determines the module
dependencies: its data-base must indicate that each imported module or
partition also has a module/partition interface unit, and that there are no
circular dependencies among the module/partition interface units. If these
requirement are satified then \textbf{icmodmap} by default calls the compiler to
compile the interface units in their proper order. By default the object files
are stored in the standard \textbf{icmake}(1) fashion: each compiled interface unit
is stored in the project's \texttt{tmp/o} sub-directory and their names begin with
a number which is equal to the line number in the \texttt{CLASSES} file specifying
the inspected sub-directory (like \texttt{1modfirst.o, 2modsecond.o,}) using prefix
0 for module(s) defined in the project's top-level directory.

When the inspection and compilation successfully completes then the interface
units' object files are stoed in \texttt{tmp/o}, and the project's top-level
directory contains a sub-directory \texttt{gcm.cache} containing the \texttt{.gcm} files
of all modules and partitions. In addition each inspected sub-directory has
received a soft-link \texttt{gcm.cache} to its parent's \texttt{gcm.cache}
sub-directory, so each of the project's source files can import each module.

Now that the module and parition interface files are available the remaining
source files can be compiled as usual. They can import and use the components
of the the defined modules (and where applicable the defined paritions).

\subsection{Modifying interface units}
    \typeout{Original Yodl file: modules/modiface.yo}When module/partition interface units are modified components are
added, removed, or altered. E.g., an interface unit may declare a class which
is modified: the ordering of its data members may change, new data members may
be added, existing data members may be removed.

When a module interface unit is modified and it's recompiled then the modified
definition replaces the old one. Consider this interface unit:
 \begin{verbatim}
    export module Demo;
    export
    {
        class Demo
        {
            int d_value = 100;
            public:
                int value() const;
        };
    }
\end{verbatim}
    The member function \texttt{Demo::value} (returning \texttt{d\_value}) is implemented
in its own source file, and is called by \texttt{main}:
    \begin{verbatim}
    import Demo;
    import <iostream>;

    using namespace std;

    int main()
    {
        Demo demo;
        cout << demo.value() << '\n';
    }
\end{verbatim}
When the program is run it outputs 100. Now the module interface unit is
modified: \texttt{d\_first} is added to the class as its first data member:
    \begin{verbatim}
    export module Demo;

    export
    {
        class Demo
        {
            int d_first = 13;
            int d_value = 100;
            public:
                int value() const;
        };
    }
\end{verbatim}
Next \texttt{moddemo.cc} and \texttt{main.cc}, are recompiled and the three object files
are linked constructing the binary program. The new binary outputs 13: 
\texttt{value's} object file returns the first bytes of the \texttt{Demo} object as an
\texttt{int}, but since the class \texttt{Demo} was modified those bytes no longer
contain the value 100.

Such complications are familiar: when using a traditional header declaring a
class and the class changes the organization of its data members then in
practice all source files using the class must be recompiled (and recursively:
if another class is derived from, or contains a data member of the modified
class then all source files using the other class must also be
recompiled). When using modules such recompilations are also required. The
\textbf{icmodmap}(1) support program has an option to recompile module (partition)
interface units depending on modified interface units and either to modify the
last write times of source files using those modules or to write their names
to a file so a build utility can recompile those module using source files.

\subsection{External modules}
    \typeout{Original Yodl file: modules/external.yo}Modules can import module-compiled system header files (cf. section
\ref{MODHDR}) and/or module-compiled header files of locally developed libraties
(cf. section \ref{LOCHDR}).

What if a library's design merely uses modules? In that case the library must
make available its module-compiled interface files (i.e., \texttt{.gcm} files) to
its users. Copying the library's \texttt{.gcm} files to the \texttt{gcm.cache}
sub-directory of a using project is not necessary (and probably a bad design
anyway, since modifications of the library's \texttt{.gcm} files will not be
noted), but soft-links should be used. However, often modules import other
modules or partitions, and consequently such library-modules in turn may
depend on other modules (or partitions). When a project must import a
library's module not only the module's \texttt{.gcm} file must be available but
also (recursively) the module/partition \texttt{.gcm} files that module depends
on. 

As an illustration consider the situation where a project defines three
modules: \texttt{Module1, Module2,} and \texttt{Module3. Module1} imports \texttt{External},
which is a module offered by some library; \texttt{Module2} imports
\texttt{Module1}, and \texttt{Module3} imports \texttt{Module2} (cf. figure \ref{threemods}). 

\begin{figure}[tbp]
\centerline{\epsffile{modules/threemods.eps}}
\caption{\label{threemods}Three modules and an external module}
\end{figure}

The \texttt{External} module doesn't belong to the current project, and so the
\texttt{External.gcm} file lives elsewhere. When constructing the project its
\texttt{gcm.cache} directory must make \texttt{External.gcm} available. This is realized
by defining a soft-link to the actual location of \texttt{External.gcm}. But in
addition soft-links to the modules/partitions imported by \texttt{External.gcm}
must be made available in the project's \texttt{gcm.cache} sub-directory. 

The \textbf{icmodmap}(1) support program can be used to determine and to satisfy
the requirements of externally defined modules.
     
    To determine the modules' dependencies \texttt{icmodmap} is called in the
project's top-level directory specifying its \texttt{+NOTRANS(-\{\}-\{\})dependencies} (or \texttt{-d})
option. It shows the dependencies amount the modules and reports an error as
the module \texttt{External} isn't found:
 \begin{verbatim}
    [Error 1] 1 UNKNOWN module
    Dependencies:
       LOCAL module Module1
           imports UNKNOWN module External
       UNKNOWN module External
       LOCAL module Module2
           imports LOCAL module Module1
       LOCAL module Module3
           imports LOCAL module Module2
\end{verbatim}
    And indeed, there's an error: the \texttt{External} module wasn't developed in
the context of the current project. It's defined in an external library,
offering its module/partition compiled interface units to its users. By
informing \texttt{icmodmap} where the external \texttt{.gcm} files are located the error
is solved. The relative or absolute path to the directory containing the
library's \texttt{.gcm} files is either specified as a command-line option or it's
specified in a file. Either of these can be passed to \texttt{icmodmap} using its
\texttt{+NOTRANS(-\{\}-\{\})extern} (or \texttt{-e}) option. E.g., if the library's \texttt{.gcm} files are in
\texttt{/tmp/library/gcm.cache} then by calling
 \begin{verbatim}
    icmodmap -d -e /tmp/library/gcm.cache
\end{verbatim}
    the error disappears and \texttt{icmodmap} reports:
 \begin{verbatim}
    Dependencies:
       LOCAL module Module1
           imports EXTERN module External
       EXTERN module External
       LOCAL module Module2
           imports LOCAL module Module1
       LOCAL module Module3
           imports LOCAL module Module2
\end{verbatim}
    specifying \texttt{+NOTRANS(-\{\}-\{\})extern} also defines the soft-links to the external
modules: the project's \texttt{gcm.cache} sub-directory now contains the soft-link
 \begin{verbatim}
    External.gcm -> /tmp/library/gcm.cache/External.gcm
\end{verbatim}
    Now that the requirements of the project's module interface files are all
satisfied they can be compiled (they are compiled by \texttt{icmodmap} if the
\texttt{-d} option isn't specified), followed by the compilation of the project's 
remaining source files. Finally, all object files can be linked to the used
object files of the external library in the usual way (specifying, e.g., the
linker's \texttt{-L} and \texttt{-l} options).

\section{Design}
\typeout{Original Yodl file: modules/design.yo}When designing projects using modules the same approach as used with
traditional projects (using headers) can be followed. Some additional
conventions are suggested that specifically apply to modules. Filenames are just
filenames. In the \textbf{C++} Annotations following conventions are adopted:
    \begin{itemize}
    \item  the names of files containing module- or partition-interface units
       begin with \texttt{mod}, followed by the lower-case module- or
       partition-names, using \texttt{.cc} extensions (e.g. \texttt{modgroup.cc});
    \item  module's source files are in sub-directories having
        their lower-case module names (e.g., \texttt{./group}) 
    \item  partitions are defined in sub-directories of their modules'
       directories. E.g., if the module \texttt{Group} is defined in \texttt{./group},
       than its partiton \texttt{Group:Support} is defined in \texttt{./group/support};
    \item  the project's main directory has a sub-directory \texttt{gcm.cache},
        initially containing a soft-link \texttt{usr/} to the system's \texttt{/usr}
        sub-directory allowing source files to import module-compiled
        system header files (e.g., \texttt{import $<$iostream$>$;});
    \item  module or partition sub-directories have a soft-link \texttt{gcm.cache}
        to \texttt{../gcm.cache}, so all compiled module- and partition-interface
        units are available in the (top-level) \texttt{gcm.cache} sub-directory.
    \end{itemize}

The compiler writes compiled interface units in their \texttt{gcm.cache}
sub-directories. The \texttt{.gcm} filenames of modules are equal to the names of the
modules (e.g., for \texttt{Group} it is \texttt{Group.gcm}). The filename of
a module-compiled partition starts with its module name, followed by a dash
(\texttt{-}), followed by the partitions's name (e.g., for \texttt{Group:Support} it is 
\texttt{Group-Support.gcm}).

To avoid overfilling interface units they should (like class headers) not
\emph{define} components but merely \emph{declare} them.  Their definitions are
provided in separate source files, defined in their interface unit's
sub-directory, using the familiar the \emph{one component, one source file}
design principle.

\subsection{'header' and 'frame' files}
    \typeout{Original Yodl file: modules/frame.yo}Modules and partitions usually their components in separate source files. The
initial lines of those source files are identical: they specify the module or
the partition to which they belong. Since these source files do not include
(internal) header files, they may also declare namespaces. E.g., the member
implementations of the \texttt{Math:Add} partition (cf. section \ref{PARTITIONS})
all start with
 \begin{verbatim}
    module Math;
    import :Add;
\end{verbatim}
    Since the \texttt{Math:Add} partition interface unit declares a \texttt{class Add}
most or all of its source files implement a member of \texttt{class Add}. In these
cases it's convenient to have a predefined \texttt{frame} file containing the
essential elements of its source files. E.g., for \texttt{Math::Add} sources this
could be
 \begin{verbatim}
    module Math;
    import :Add;

    using namespace std;

    void Add::()
    {
    }
\end{verbatim}
    When implementing a member copy the \texttt{frame} to the intended source file,
specify the member's name, define its body and maybe change its return type.


\cleardoublepage\chapter{Concrete Examples}\label{CONCRETE}
\typeout{Original Yodl file: concrete}\typeout{Original Yodl file: concrete/intro}In this chapter concrete examples of \textbf{C++} programs, classes and templates
are presented.  Topics covered by the \textbf{C++} Annotations such as virtual
functions, \texttt{static} members, etc. are illustrated in this chapter. The
examples roughly follow the organization of earlier chapters.

As an additional topic, not just providing examples of \textbf{C++} the subjects of
\index{scanner}scanner and \index{parser}parser generators are covered. We show how these tools may
be used in \textbf{C++} programs. These additional examples assume a certain
familiarity with the concepts underlying these tools, like grammars,
parse-trees and
        \index{grammar}
        \index{parse-tree}
    parse-tree decoration. Once the input for a program exceeds a certain
level of complexity, it's attractive to use scanner- and parser-generators to
create the code doing the actual input processing. One of the
examples in this chapter describes the usage of these
tools in a \textbf{C++} environment.

\section{Using file descriptors with `streambuf' classes}\label{FDSTREAMBUFFER}

\subsection{Classes for output operations}\label{OFDNBUF}
    \typeout{Original Yodl file: concrete/fdout}    Reading and writing from and to \emph{file descriptors}\index{file descriptor}
are not part of the \textbf{C++} standard. But on most operating systems file
descriptors \emph{are} available and can be considered a \index{device}device. It seems
natural to use the class \index{streambuf}\texttt{std::streambuf} as the starting point
for constructing classes interfacing such file descriptor devices.

Below we'll construct classes that can be used to write to a device given
its file descriptor. The devices may be files, but they could also be \index{pipe}pipes
or \index{socket}sockets. Section \ref{STRBUF} covers reading from such devices; section
\ref{REDIRECTION} reconsiders redirection, discussed earlier in section
\ref{REDIR}.

Using the \texttt{streambuf} class as a base class it is relatively easy to
design classes for output operations. The only member function that \emph{must}
be overridden is the (virtual) member
 \index{overflow}
    \texttt{int streambuf::overflow(int c)}. This member's responsibility is to
write characters to the device. If \texttt{fd} is an output file descriptor and if
output should not be buffered then the member \texttt{overflow()} can simply be
implemented as:
        \begin{verbatim}
    class UnbufferedFD: public std::streambuf
    {
        public:
            int overflow(int c) override;
            ...
    };

    int UnbufferedFD::overflow(int c)
    {
        if (c != EOF)
        {
            if (write(d_fd, &c, 1) != 1)
                return EOF;
        }
        return c;
    }
\end{verbatim}
The argument received by \texttt{overflow} is either written to the file
descriptor (and returned from \texttt{overflow}), or \texttt{EOF} is returned.

This simple function does not use output buffering. For various reasons,
using a buffer is usually a good idea (see also the next section).

When output buffering is used, the \texttt{overflow} member is a bit more
complex as it is only called when the buffer is full. Once the buffer is full,
we \emph{first} have to flush the buffer. Flushing the buffer is the
responsibility of the (virtual) function \index{sync}\texttt{streambuf::sync}.  Since
\texttt{sync} is a virtual function, classes derived from \texttt{streambuf} may
redefine \texttt{sync} to flush a buffer \texttt{streambuf} itself doesn't know about.

Overriding \texttt{sync} and using it in \texttt{overflow} is not all that has to be
done. When the object of the class defining the buffer reaches the end of its
lifetime the buffer may be only partially full. In that situation the buffer
must also be flushed. This is easily done by simply calling \texttt{sync} from the
class's destructor.

Now that we've considered the consequences of using an output buffer,
we're almost ready to design our derived class. Several more features
are added as well, though:
    \begin{itemize}
    \item  First, we should allow the user of the class to specify the size of
the output buffer.
    \item  Second, it should be possible to construct an object of our class
before the file descriptor is actually known. Later, in section \ref{FORK}
we'll encounter a situation where this feature is actually used.
    \end{itemize}
    To save some space in the \textbf{C++} Annotations, the successful completion of the
functions designed here is not checked in the example code. In `real life'
implementations these checks should of course not be omitted.  Our class
\texttt{OFdnStreambuf} has the following characteristics:
    \begin{itemize}
    \item  Its member functions use low-level functions operating on file
descriptors. So apart from \texttt{streambuf} the \index{unistd.h: header file}\texttt{$<$unistd.h$>$} header file must
have been read by the compiler before its member functions can be compiled.
    \item  The class is derived from \texttt{std::streambuf}.
    \item  It defines three data members. These data members keep track of,
respectively, the size of the buffer, the file descriptor, and the buffer
itself. Here is the full class interface
        \begin{verbatim}
    class OFdnStreambuf: public std::streambuf
    {
        int     d_fd = -1;
        size_t  d_bufsize = 0;
        char   *d_buffer = 0;

        public:
            OFdnStreambuf() = default;
            OFdnStreambuf(int fd, size_t bufsize = 1);
            ~OFdnStreambuf() override;
            void open(int fd, size_t bufsize = 1);
        private:
            int sync() override;
            int overflow(int c) override;
    };
\end{verbatim}
    \item  Its default constructor merely initializes the buffer to 0. Slightly
more interesting is its constructor expecting a file descriptor and a buffer
size. This constructor passes its arguments on to the class's \texttt{open}
member (see below). Here are the constructors:
        \begin{verbatim}
    inline OFdnStreambuf::OFdnStreambuf(int fd, size_t bufsize)
    {
        open(fd, bufsize);
    }
\end{verbatim}
    \item  The destructor calls \texttt{sync}, flushing any characters stored in the
output buffer to the device. In implementations not using a buffer the
destructor can be given a default implementation:
        \begin{verbatim}
    inline OFdnStreambuf::~OFdnStreambuf()
    {
        if (d_buffer)
        {
            sync();
            delete[] d_buffer;
        }
    }
\end{verbatim}
    This implementation does not close the device. It is left as an exercise
to the reader to change this class in such a way that the device is optionally
closed (or optionally remains open). This approach was adopted by, e.g., the
        \texttt{Bobcat library}\footnote{http://fbb-git.gitlab.io/bobcat/}.
        \index{Bobcat library}\index{http://fbb-git.gitlab.io/bobcat/} See also section
\ref{IFDNBUF}.
    \item  The \index{open}\texttt{open} member initializes the buffer.  Using
\index{setp}\texttt{streambuf::setp}, the begin and end points of the buffer are
defined. This is used by the \texttt{streambuf} base class to initialize
\index{pbase}\texttt{streambuf::pbase}, \index{pptr}\texttt{streambuf::pptr}, and
\index{epptr}\texttt{streambuf::epptr}:
        \begin{verbatim}
    inline void OFdnStreambuf::open(int fd, size_t bufsize)
    {
        d_fd = fd;
        d_bufsize = bufsize == 0 ? 1 : bufsize;
        delete[] d_buffer;
        d_buffer = new char[d_bufsize];
        setp(d_buffer, d_buffer + d_bufsize);
    }
\end{verbatim}
    \item  The member \index{sync}\texttt{sync} flushes the as yet unflushed content of the
buffer to the device. After the flush the buffer is reinitialized using
\texttt{setp}. After successfully flushing the buffer \texttt{sync} returns 0:
        \begin{verbatim}
    inline int OFdnStreambuf::sync()
    {
        if (pptr() > pbase())
        {
            write(d_fd, d_buffer, pptr() - pbase());
            setp(d_buffer, d_buffer + d_bufsize);
        }
        return 0;
    }
\end{verbatim}
    \item  The member \index{overflow}\texttt{streambuf::overflow} is also
overridden. Since this member is called from the \texttt{streambuf} base class when
the buffer is full it should first call \texttt{sync} to flush the buffer to the
device. Next it should write the character \texttt{c} to the (now empty)
buffer. The character \texttt{c} should be written using \texttt{pptr} and
\index{pbump}\texttt{streambuf::pbump}.  Entering a character into the buffer should be
implemented using available \texttt{streambuf} member functions, rather than `by
hand' as doing so might invalidate \texttt{streambuf}'s internal bookkeeping. Here
is \texttt{overflow}'s implementation:
        \begin{verbatim}
    inline int OFdnStreambuf::overflow(int c)
    {
        sync();
        if (c != EOF)
        {
            *pptr() = c;
            pbump(1);
        }
        return c;
    }
\end{verbatim}
    \end{itemize}
    The next program uses the \texttt{OFfdStreambuf} class to copy its standard
input to file descriptor \index{STDOUT\_FILENO}\texttt{STDOUT\_FILENO}, which is the symbolic name of the
file descriptor used for the standard output:
        \begin{verbatim}
    #include <string>
    #include <iostream>
    #include <istream>
    #include "fdout.h"
    using namespace std;

    int main(int argc, char **argv)
    {
        OFdnStreambuf   fds(STDOUT_FILENO, 500);
        ostream         os(&fds);

        switch (argc)
        {
            case 1:
                for (string  s; getline(cin, s); )
                    os << s << '\n';
                os << "COPIED cin LINE BY LINE\n";
            break;

            case 2:
                cin >> os.rdbuf();      // Alternatively, use:  cin >> &fds;
                os << "COPIED cin BY EXTRACTING TO os.rdbuf()\n";
            break;

            case 3:
                os << cin.rdbuf();
                os << "COPIED cin BY INSERTING cin.rdbuf() into os\n";
            break;
        }
    }
\end{verbatim}
\subsection{Classes for input operations}\label{STRBUF}
    \typeout{Original Yodl file: concrete/fdinput}    When classes for input operation are derived from
\index{streambuf}\texttt{std::streambuf}, they should be provided with an input buffer
of at least one character. The one-character input buffer allows for the use
of the member functions \texttt{istream::putback} or \texttt{istream::ungetc}.  Strictly
speaking it is not necessary to implement a buffer in classes derived from
\texttt{streambuf}. But using buffers in these classes is strongly advised. Their
implementation is very simple and straightforward and the applicability of
such classes is greatly improved. Therefore, all our classes derived from the
class \texttt{streambuf} define a buffer of \emph{at least} one character.

\subsubsection{Using a one-character buffer}\label{IFDBUF}
        \typeout{Original Yodl file: concrete/fdinbuf}    When deriving a class (e.g., \index{IFdStreambuf}\texttt{IFdStreambuf}) from \texttt{streambuf} using a
buffer of one character, at least its member
 \index{underflow}
    \texttt{streambuf::underflow} should be overridden, as this member eventually
receives all requests for input. The member
 \index{setg}
    \texttt{streambuf::setg} is used to inform the \texttt{streambuf} base class of the
size and location of the input buffer, so that it is able to set up its input
buffer pointers accordingly. This ensures that \index{eback}
\texttt{streambuf::eback}, \index{gptr} \texttt{streambuf::gptr}, and \index{egptr}
\texttt{streambuf::egptr} return correct values.

The class \texttt{IFdStreambuf} is designed like this:
    \begin{itemize}
    \item  Its member functions use low-level functions operating on file
descriptors. Therefore, in addition to \texttt{streambuf}, the \index{unistd.h: header file}\texttt{$<$unistd.h$>$}
header file must have been read by the compiler before its member functions
can be compiled.
    \item  Like most classes designed for input operations, this class is derived
from \index{streambuf}\texttt{std::streambuf} as well.
    \item  The class defines two data members, one of them a fixed-sized one
character buffer. The data members are defined as \index{protected}\texttt{protected} data members
so that derived classes (e.g., see section \ref{IFDSEEK}) can access them. Here
is the full class interface:
        \begin{verbatim}
    class IFdStreambuf: public std::streambuf
    {
        protected:
            int     d_fd;
            char    d_buffer[1];
        public:
            IFdStreambuf(int fd);
        private:
            int underflow() override;
    };
\end{verbatim}
    \item  The constructor initializes the buffer. However, the initialization
sets \index{gptr}\texttt{gptr}'s return value equal to \index{egptr}\texttt{egptr}'s return value. This
implies that the buffer is empty so \texttt{underflow} is immediately called
to fill the buffer:
        \begin{verbatim}
    inline IFdStreambuf::IFdStreambuf(int fd)
    :
        d_fd(fd)
    {
        setg(d_buffer, d_buffer + 1, d_buffer + 1);
    }
\end{verbatim}
    \item  Finally \texttt{underflow} is overridden. The buffer is refilled by
reading from the file descriptor. If this fails (for whatever reason),
\texttt{EOF} is returned. More sophisticated implementations could act more
intelligently here, of course. If the buffer could be refilled, \index{setg}\texttt{setg} is
called to set up \texttt{streambuf}'s buffer pointers correctly:
        \begin{verbatim}
    inline int IFdStreambuf::underflow()
    {
        if (read(d_fd, d_buffer, 1) <= 0)
            return EOF;

        setg(d_buffer, d_buffer, d_buffer + 1);
        return static_cast<unsigned char>(*gptr());
    }
\end{verbatim}
    \end{itemize}
    The following \texttt{main} function shows how \texttt{IFdStreambuf} can be used:
        \begin{verbatim}
    int main()
    {
        IFdStreambuf fds(STDIN_FILENO);
        istream      is(&fds);

        cout << is.rdbuf();
    }
\end{verbatim}
\subsubsection{Using an n-character buffer}\label{IFDNBUF}
        \typeout{Original Yodl file: concrete/fdninbuf}    How complex would things get if we decided to use a buffer of
substantial size? Not that complex. The following class allows us to specify
the size of a buffer, but apart from that it is basically the same class as
\texttt{IFdStreambuf} developed in the previous section. To make things a bit more
interesting, in the class \index{IFdNStreambuf}\texttt{IFdNStreambuf} developed here, the member
\index{xsgetn}\texttt{streambuf::xsgetn} is also overridden, to optimize reading a
series of characters. Also a default constructor is provided that can be used
in combination with the \texttt{open} member to construct an \texttt{istream} object
before the file descriptor becomes available. In that case, once the
descriptor becomes available, the \texttt{open} member can be used to initiate
the object's buffer. Later, in section \ref{FORK}, we'll encounter such a
situation.

To save some space, the success of various calls was not checked. In `real
life' implementations, these checks should of course not be omitted. The
class \texttt{IFdNStreambuf} has the following characteristics:
    \begin{itemize}
    \item  Its member functions use low-level functions operating on file
descriptors. So apart from \texttt{streambuf} the \index{unistd.h: header file}\texttt{$<$unistd.h$>$} header file must
have been read by the compiler before its member functions can be compiled.
    \item  As usual, it is derived from \index{streambuf}\texttt{std::streambuf}.
    \item  Like the class \texttt{IFdStreambuf} (section \ref{IFDBUF}), its data
members are protected. Since the buffer's size is configurable, this size is
kept in a dedicated data member, \texttt{d\_bufsize}:
            \begin{verbatim}
    class IFdNStreambuf: public std::streambuf
    {
        protected:
            int         d_fd = -1;
            size_t      d_bufsize = 0;
            char*       d_buffer = 0;
        public:
            IFdNStreambuf() = default;
            IFdNStreambuf(int fd, size_t bufsize = 1);
            ~IFdNStreambuf() override;
            void open(int fd, size_t bufsize = 1);
        private:
            int underflow() override;
            std::streamsize xsgetn(char *dest, std::streamsize n) override;
    };
\end{verbatim}
    \item  The default constructor does not allocate a buffer. It can be used
to construct an object before the file descriptor becomes known. A second
constructor simply passes its arguments to \texttt{open}. \texttt{Open} will then
initialize the object so that it can actually be used:
            \begin{verbatim}
    inline IFdNStreambuf::IFdNStreambuf(int fd, size_t bufsize)
    {
        open(fd, bufsize);
    }
\end{verbatim}
    \item  Once the object has been initialized by \texttt{open}, its destructor will
both delete the object's buffer and use the file descriptor to close the
device:
            \begin{verbatim}
    IFdNStreambuf::~IFdNStreambuf()
    {
        if (d_bufsize)
        {
            close(d_fd);
            delete[] d_buffer;
        }
    }
\end{verbatim}
    Even though the device is closed in the above implementation this may not
always be desirable. In cases where the open file descriptor is already
available the intention may be to use that descriptor repeatedly, each time
using a newly constructed \texttt{IFdNStreambuf} object. It is left as an exercise
to the reader to change this class in such a way that the device may
optionally be closed. This approach was followed in, e.g., the
        \texttt{Bobcat library}\footnote{http://fbb-git.gitlab.io/bobcat/}.
        \index{Bobcat library}\index{http://fbb-git.gitlab.io/bobcat/}
    \item  The \texttt{open} member simply allocates the object's buffer. It is
assumed that the calling program has already opened the device. Once the
buffer has been allocated, the base class member \index{setg}\texttt{setg} is used to ensure
that \index{eback} \texttt{streambuf::eback} \index{gptr} \texttt{streambuf::gptr} and \index{egptr}
\texttt{streambuf::egptr} return correct values:
            \begin{verbatim}
    void IFdNStreambuf::open(int fd, size_t bufsize)
    {
        d_fd = fd;
        d_bufsize =  bufsize == 0 ? 1 : bufsize;
        delete[] d_buffer;
        d_buffer = new char[d_bufsize];
        setg(d_buffer, d_buffer + d_bufsize, d_buffer + d_bufsize);
    }
\end{verbatim}
    \item  The overridden member \texttt{underflow} is implemented almost
identically to \texttt{IFdStreambuf}'s (section \ref{IFDBUF}) member. The only
difference is that the current class supports buffers of larger
sizes. Therefore, more characters (up to \texttt{d\_bufsize}) may be read from the
device at once:
            \begin{verbatim}
    int IFdNStreambuf::underflow()
    {
        if (gptr() < egptr())
            return *gptr();

        int nread = read(d_fd, d_buffer, d_bufsize);

        if (nread <= 0)
            return EOF;

        setg(d_buffer, d_buffer, d_buffer + nread);
        return static_cast<unsigned char>(*gptr());
    }
\end{verbatim}
    \item  Finally \index{xsgetn}\texttt{xsgetn} is overridden. In a loop, \texttt{n} is reduced until
0, at which point the function terminates. Alternatively, the member returns
if \texttt{underflow} fails to obtain more characters. This member optimizes the
reading of series of characters. Instead of calling \index{sbumpc}
\texttt{streambuf::sbumpc} \texttt{n} times, a block of \texttt{avail} characters is copied
to the destination, using \index{gbump}\texttt{streambuf::gbump} to consume \texttt{avail}
characters from the buffer using one function call:
            \begin{verbatim}
    std::streamsize IFdNStreambuf::xsgetn(char *dest, std::streamsize n)
    {
        int nread = 0;

        while (n)
        {
            if (!in_avail())
            {
                if (underflow() == EOF)
                    break;
            }

            int avail = in_avail();

            if (avail > n)
                avail = n;

            memcpy(dest + nread, gptr(), avail);
            gbump(avail);

            nread += avail;
            n -= avail;
        }

        return nread;
    }
\end{verbatim}
    \end{itemize}
    The member function \index{xsgetn}\texttt{xsgetn} is called by \index{sgetn}\texttt{streambuf::sgetn},
which is a \texttt{streambuf} member. Here is an example illustrating the use of
this member function with an \texttt{IFdNStreambuf} object:
        \begin{verbatim}
    #include <unistd.h>
    #include <iostream>
    #include <istream>
    #include "ifdnbuf.h"
    using namespace std;

    int main()
    {
                                    // internally: 30 char buffer
        IFdNStreambuf fds(STDIN_FILENO, 30);

        char buf[80];               // main() reads blocks of 80
                                    // chars
        while (true)
        {
            size_t n = fds.sgetn(buf, 80);
            if (n == 0)
                break;
            cout.write(buf, n);
        }
    }
\end{verbatim}
\subsubsection{Seeking positions in `streambuf' objects}\label{IFDSEEK}
        \typeout{Original Yodl file: concrete/fdinseek}    When devices support \emph{seek operations}, classes derived from
\index{streambuf} \texttt{std::streambuf} should override the members \index{seekoff}
\texttt{streambuf::seekoff} and \index{seekpos}\texttt{streambuf::seekpos}. The class
\index{IFdSeek}\texttt{IFdSeek}, developed in this section, can be used to read information from
devices supporting seek operations. The class \texttt{IFdSeek} was derived from
\texttt{IFdStreambuf}, so it uses a character buffer of just one character. The
facilities to perform seek operations, which are added to our new class
\texttt{IFdSeek}, ensure that the input buffer is reset when a seek operation is
requested. The class could also be derived from the class
\texttt{IFdNStreambuf}. In that case the arguments to reset the input buffer
must be adapted so that its second and third parameters point beyond the
available input buffer. Let's have a look at the characteristics of
\texttt{IFdSeek}:
    \begin{itemize}
    \item  As mentioned, \texttt{IFdSeek} is derived from \texttt{IFdStreambuf}. Like the
latter class, \texttt{IFdSeek}'s member functions use facilities declared in
\texttt{unistd.h}. So, the header file \index{unistd.h: header file}\texttt{$<$unistd.h$>$} must have been read by the
compiler before it can compile the class's members functions.  To reduce the
amount of typing when specifying types and constants from \texttt{streambuf} and
\index{ios}\texttt{std::ios}, several using-declarations are defined by the class.
These using-declarations refer to types that are defined in the header file
\index{ios: header file}\texttt{$<$ios$>$}, which must therefore also be included before the compiler can
compile \texttt{IFdSeek}'s class interface:
        \begin{verbatim}
    class IFdSeek: public IFdStreambuf
    {
        using pos_type = std::streambuf::pos_type;
        using off_type = std::streambuf::off_type;
        using seekdir = std::ios::seekdir;
        using openmode = std::ios::openmode;

        public:
            IFdSeek(int fd);
        private:
            pos_type seekoff(off_type offset, seekdir dir, openmode);
            pos_type seekpos(pos_type offset, openmode mode);
    };
\end{verbatim}
    \item  The class has a very basic interface. Its (only)
constructor expects the device's \index{file descriptor}file descriptor. It has no special tasks
to perform and just calls its \index{base class}base class constructor:
        \begin{verbatim}
    inline IFdSeek::IFdSeek(int fd)
    :
        IFdStreambuf(fd)
    {}
\end{verbatim}
    \item  The member \index{seek\_off}\texttt{seek\_off} is responsible for performing the actual
seek operations. It calls \index{lseek}\texttt{lseek} to seek a new position in a device whose
file descriptor is known. If seeking succeeds, \index{setg}\texttt{setg} is called to define
an already empty buffer, so that the base class's \texttt{underflow} member
refills the buffer at the next input request.
        \begin{verbatim}
    IFdSeek::pos_type IFdSeek::seekoff(off_type off, seekdir dir, openmode)
    {
        pos_type pos =
            lseek
            (
                d_fd, off,
                (dir ==  std::ios::beg) ? SEEK_SET :
                (dir ==  std::ios::cur) ? SEEK_CUR :
                                          SEEK_END
            );

        if (pos < 0)
            return -1;

        setg(d_buffer, d_buffer + 1, d_buffer + 1);
        return pos;
    }
\end{verbatim}
    \item  Finally,  the companion function \index{seekpos}\texttt{seekpos} is overridden as well:
it is actually defined as a call to \texttt{seekoff}:
        \begin{verbatim}
    inline IFdSeek::pos_type IFdSeek::seekpos(pos_type off, openmode mode)
    {
        return seekoff(off, std::ios::beg, mode);
    }
\end{verbatim}
    \end{itemize}
    Here is an example of a program using the class \texttt{IFdSeek}. If
this program is given its own source file using input redirection then
seeking is supported (and with the exception of the first line, every other
line is shown twice):
        \begin{verbatim}
    #include "fdinseek.h"
    #include <string>
    #include <iostream>
    #include <istream>
    #include <iomanip>
    using namespace std;

    int main()
    {
        IFdSeek fds(0);
        istream is(&fds);
        string  s;

        while (true)
        {
            if (!getline(is, s))
                break;

            streampos pos = is.tellg();

            cout << setw(5) << pos << ": `" << s << "'\n";

            if (!getline(is, s))
                break;

            streampos pos2 = is.tellg();

            cout << setw(5) << pos2 << ": `" << s << "'\n";

            if (!is.seekg(pos))
            {
                cout << "Seek failed\n";
                break;
            }
        }
    }
\end{verbatim}
\subsubsection{Multiple `unget' calls in `streambuf' objects}
        \typeout{Original Yodl file: concrete/fdunget}\texttt{Streambuf} classes and classes derived from \index{streambuf}\texttt{streambuf} should support
\emph{at least} ungetting the last read character. Special care must be taken
when \emph{series} of \index{unget}\texttt{unget} calls must be supported. In this section the
construction of a class supporting a configurable number of \texttt{istream::unget}
or \index{putback}\texttt{istream::putback} calls is discussed.

Support for multiple (say `\texttt{n}') \texttt{unget} calls is implemented by
reserving an initial section of the input buffer, which is gradually filled up
to contain the last \texttt{n} characters read. The class is implemented as
follows:
    \begin{itemize}
    \item  Once again, the class is derived from \texttt{std::streambuf}. It
defines several data members, allowing the class to perform the bookkeeping
required to maintain an unget-buffer of a configurable size:
        \begin{verbatim}
    class FdUnget: public std::streambuf
    {
        int     d_fd;
        size_t  d_bufsize;
        size_t  d_reserved;
        char   *d_buffer;
        char   *d_base;
        public:
            FdUnget(int fd, size_t bufsz, size_t unget);
            ~FdUnget() override;
        private:
            int underflow() override;
    };
\end{verbatim}
    \item  The class's constructor expects a \index{file descriptor}file descriptor, a buffer size
and the number of characters that can be ungot or pushed back as its
arguments. This number  determines the size of a \emph{reserved} area,
defined as the first \texttt{d\_reserved} bytes of the class's input buffer.
        \begin{itemize}
        \item  The input buffer will always be at least one byte larger than
\texttt{d\_reserved}. So, a certain number of bytes may be read. Once \texttt{d\_reserved}
bytes have been read at most \texttt{d\_reserved} bytes can be ungot.
        \item  Next, the starting point for reading operations is configured. It
is called \texttt{d\_base}, pointing to a location \texttt{d\_reserved} bytes beyond the
location represented by \texttt{d\_buffer}. This is always the location where buffer
refills start.
        \item  Now that the buffer has been constructed, we're ready to define
\texttt{streambuf}'s buffer pointers using \texttt{setg}. As no characters have been
read yet, all pointers are set to point to \texttt{d\_base}. If \texttt{unget} is
called at this point, no characters are available, and \texttt{unget}
(correctly) fails.
        \item  Eventually, the refill buffer's size is determined as the
number of allocated bytes minus the size of the reserved area.
        \end{itemize}
        Here is the class's constructor:
            \begin{verbatim}
    FdUnget::FdUnget(int fd, size_t bufsz, size_t unget)
    :
        d_fd(fd),
        d_reserved(unget)
    {
        size_t allocate =
                bufsz > d_reserved ?
                    bufsz
                :
                    d_reserved + 1;

        d_buffer = new char[allocate];

        d_base = d_buffer + d_reserved;
        setg(d_base, d_base, d_base);

        d_bufsize = allocate - d_reserved;
    }
\end{verbatim}
    \item  The class's destructor simply returns the memory allocated for the
buffer to the common pool:
            \begin{verbatim}
    inline FdUnget::~FdUnget()
    {
        delete[] d_buffer;
    }
\end{verbatim}
    \item  Finally,  \texttt{underflow} is overridden as follows:
        \begin{itemize}
        \item  First \texttt{underflow} determines the number of characters that
could potentially be ungot. If that number of characters are ungot, the input
buffer is exhausted. So this value may be any value between 0 (the initial
state) or the input buffer's size (when the reserved area has been filled up
completely, and all current characters in the remaining section of the buffer
have also been read);
        \item  Next the number of bytes to move into the reserved area is
computed. This number is at most \texttt{d\_reserved}, but it is set equal to the
actual number of characters that can be ungot if this value is smaller;
        \item  Now that the number of characters to move into the reserved area
is known, this number of characters is moved from the input buffer's end to
the area immediately before \texttt{d\_base};
        \item  Then the buffer is refilled. This all is standard, but notice
that reading starts from \texttt{d\_base} and not from \texttt{d\_buffer};
        \item  Finally, \texttt{streambuf}'s read buffer pointers are set up.
                \index{eback}
            \texttt{Eback} is set to \texttt{move} locations before \texttt{d\_base}, thus
defining the guaranteed unget-area,
            \index{gptr}\texttt{gptr} is set to \texttt{d\_base}, since that's the location of the
first read character after a refill, and
            \index{egptr}\texttt{egptr} is set just beyond the location of the last character
read into the buffer.
        \end{itemize}
        Here is \texttt{underflow}'s implementation:
            \begin{verbatim}
    int FdUnget::underflow()
    {
        size_t ungetsize = gptr() - eback();
        size_t move = std::min(ungetsize, d_reserved);

        memcpy(d_base - move, egptr() - move, move);

        int nread = read(d_fd, d_base, d_bufsize);
        if (nread <= 0)       // none read -> return EOF
            return EOF;

        setg(d_base - move, d_base, d_base + nread);

        return static_cast<unsigned char>(*gptr());
    }
\end{verbatim}
    \end{itemize}

\textbf{An example using FdUnget}

The next example program illustrates the use of the class \texttt{FdUnget}. It
reads at most 10 characters from the standard input, stopping at
\texttt{EOF}. A guaranteed unget-buffer of 2 characters is defined in a buffer
holding 3 characters. Just before reading a character, the program tries to
unget at most 6 characters. This is, of course, not possible; but the program
nicely ungets as many characters as possible, considering the actual
number of characters read:
        \begin{verbatim}
    #include "fdunget.h"
    #include <string>
    #include <iostream>
    #include <istream>
    using namespace std;

    int main()
    {
        FdUnget fds(0, 3, 2);
        istream is(&fds);
        char    c;

        for (int idx = 0; idx < 10; ++idx)
        {
            cout << "after reading " << idx << " characters:\n";
            for (int ug = 0; ug <= 6; ++ug)
            {
                if (!is.unget())
                {
                    cout
                    << "\tunget failed at attempt " << (ug + 1) << "\n"
                    << "\trereading: '";

                    is.clear();
                    while (ug--)
                    {
                        is.get(c);
                        cout << c;
                    }
                    cout << "'\n";
                    break;
                }
            }

            if (!is.get(c))
            {
                cout << " reached\n";
                break;
            }
            cout << "Next character: " << c << '\n';
        }
    }
    /*
        Generated output after 'echo abcde | program':

        after reading 0 characters:
                unget failed at attempt 1
                rereading: ''
        Next character: a
        after reading 1 characters:
                unget failed at attempt 2
                rereading: 'a'
        Next character: b
        after reading 2 characters:
                unget failed at attempt 3
                rereading: 'ab'
        Next character: c
        after reading 3 characters:
                unget failed at attempt 4
                rereading: 'abc'
        Next character: d
        after reading 4 characters:
                unget failed at attempt 4
                rereading: 'bcd'
        Next character: e
        after reading 5 characters:
                unget failed at attempt 4
                rereading: 'cde'
        Next character:

        after reading 6 characters:
                unget failed at attempt 4
                rereading: 'de
        '
         reached
    */
\end{verbatim}
\subsection{Fixed-sized field extraction from istream objects}
    \typeout{Original Yodl file: concrete/fistream}Usually when extracting information from \texttt{istream} objects \texttt{operator}$>>$, the
standard extraction operator is perfectly suited for the task as in most
cases the extracted fields are white-space (or otherwise clearly) separated
from each other. But this does not hold true in all situations. For example,
when a web-form is posted to some processing script or program, the receiving
program may receive the form field's values as \emph{url-encoded}
characters: letters and digits are sent unaltered, blanks are sent as \texttt{+}
characters, and all other characters start with \texttt{\%} followed by the
character's
    \index{ascii-value}ascii-value represented by its two digit hexadecimal value.

When decoding url-encoded information, simple hexadecimal extraction won't
work, as  that extracts as many hexadecimal characters as available,
instead of just two. Since the letters \texttt{a-f`} and \texttt{0-9} are legal
hexadecimal characters, a text like \texttt{My name is `Ed'}, url-encoded as
        \begin{verbatim}
    My+name+is+%60Ed%27
\end{verbatim}
results in the extraction of the hexadecimal values \texttt{60ed} and \texttt{27},
instead of \texttt{60} and \texttt{27}. The name \texttt{Ed} disappears from view, which is
clearly not what we want.

In this case, having seen the \texttt{\%}, we could extract 2 characters, put
them in an \index{istringstream}\texttt{istringstream} object, and extract the hexadecimal value from
the \texttt{istringstream} object. A bit cumbersome, but doable. Other approaches
are possible as well.

The class \index{Fistream}\texttt{Fistream} for \emph{fixed-sized field istream} defines
an \texttt{istream} class supporting both fixed-sized field extractions and
blank-delimited extractions (as well as unformatted \texttt{read} calls). The
class may be initialized as a \index{wrapper}\emph{wrapper} around an existing \texttt{istream}, or
it can be initialized using the name of an existing file. The class is derived
from \texttt{istream}, allowing all extractions and operations supported by
\texttt{istream}s in general. \texttt{Fistream} defines the following data members:
    \begin{itemize}
    \item \texttt{d\_filebuf}: a filebuffer used when \texttt{Fistream} reads its information
        from a named (existing) file. Since the filebuffer is only needed in
        that case, and since it must be allocated dynamically, it is defined
        as a \texttt{unique\_ptr$<$filebuf$>$} object.
    \item \texttt{d\_streambuf}: a pointer to \texttt{Fistream}'s \texttt{streambuf}. It points
        to \texttt{d\_filebuf} when \texttt{Fistream} opens a file by name. When an
        existing \texttt{istream} is used to construct an \texttt{Fistream}, it
        points to the existing \texttt{istream}'s \texttt{streambuf}.
    \item \texttt{d\_iss}: an \texttt{istringstream} object used for the fixed field
        extractions.
    \item \texttt{d\_width}: a \texttt{size\_t} indicating the width of the field to
        extract. If 0 no fixed field extractions is used, but
        information is extracted from the \texttt{istream} base class object
        using standard extractions.
    \end{itemize}
    Here is the initial section of \texttt{Fistream}'s class interface:
        \begin{verbatim}
    class Fistream: public std::istream
    {
        std::unique_ptr<std::filebuf> d_filebuf;
        std::streambuf *d_streambuf;
        std::istringstream d_iss;
        size_t d_width;
\end{verbatim}
    As stated, \texttt{Fistream} objects can be constructed from either a
filename or an existing \texttt{istream} object. The class interface therefore
declares two constructors:
        \begin{verbatim}
            Fistream(std::istream &stream);
            Fistream(char const *name,
                std::ios::openmode mode = std::ios::in);
\end{verbatim}
    When an \texttt{Fistream} object is constructed using an existing \texttt{istream}
object, the \texttt{Fistream}'s \texttt{istream} part simply uses the \texttt{stream}'s
\texttt{streambuf} object:
        \begin{verbatim}
Fistream::Fistream(istream &stream)
:
    istream(stream.rdbuf()),
    d_streambuf(rdbuf()),
    d_width(0)
{}
\end{verbatim}
    When an \texttt{fstream} object is constructed using a filename, the
\texttt{istream} base initializer is given a new \texttt{filebuf} object to be used as
its \texttt{streambuf}. Since the class's data members are not initialized before
the class's base class has been constructed, \texttt{d\_filebuf} can only be
initialized thereafter. By then, the \texttt{filebuf} is only available as
\texttt{rdbuf}, returning a \texttt{streambuf}. However, as it is actually a
\texttt{filebuf}, a \texttt{static\_cast} is used to cast the \texttt{streambuf} pointer
returned by \texttt{rdbuf} to \texttt{a filebuf $*$}, so \texttt{d\_filebuf} can be initialized:
        \begin{verbatim}
Fistream::Fistream(char const *name, ios::openmode mode)
:
    istream(new filebuf()),
    d_filebuf(static_cast<filebuf *>(rdbuf())),
    d_streambuf(d_filebuf.get()),
    d_width(0)
{
    d_filebuf->open(name, mode);
}
\end{verbatim}
\subsubsection{Member functions and example}
        \typeout{Original Yodl file: concrete/fistreamexample}    There is only one additional public member: \texttt{setField(field const
\&)}. This member defines the size of the next field to extract. Its
parameter is a reference to a \texttt{field} class, a \emph{manipulator class}
defining the width of the next field.

Since a \texttt{field \&} is mentioned in \texttt{Fistream}'s interface, \texttt{field}
must be declared before \texttt{Fistream}'s interface starts. The class \texttt{field}
itself is simple and declares \texttt{Fistream} as its friend. It has two data
members: \texttt{d\_width} specifies the width of the next field, and \texttt{d\_newWidth}
which is set to \texttt{true} if \texttt{d\_width}'s value should actually be used. If
\texttt{d\_newWidth} is false, \texttt{Fistream} returns to its standard extraction
mode. The class \texttt{field} has two constructors: a default
constructor, setting \texttt{d\_newWidth} to \texttt{false}, and a second constructor
expecting the width of the next field to extract as its value. Here is the
class \texttt{field}:
        \begin{verbatim}
    class field
    {
        friend class Fistream;
        size_t d_width;
        bool     d_newWidth;

        public:
            field(size_t width);
            field();
    };

    inline field::field(size_t width)
    :
        d_width(width),
        d_newWidth(true)
    {}

    inline field::field()
    :
        d_newWidth(false)
    {}
\end{verbatim}
    Since \texttt{field} declares \texttt{Fistream} as its friend, \texttt{setField} may
inspect \texttt{field}'s members directly.

Time to return to \texttt{setField}. This function expects a reference to a
\texttt{field} object, initialized in one of three different ways:
    \begin{itemize}
    \item \texttt{field()}: When \texttt{setField}'s argument is a \texttt{field} object
        constructed by its default constructor the next extraction will use
        the same field width as the previous extraction.
    \item \texttt{field(0)}: When this \texttt{field} object is used as \texttt{setField}'s
        argument, fixed-sized field extraction stops, and the \texttt{Fistream}
        acts like any standard \texttt{istream} object again.
    \item \texttt{field(x)}: When the \texttt{field} object itself is initialized by a
        non-zero size\_t value \texttt{x}, then the next field width is \texttt{x}
        characters wide. The preparation of such a field is left to
        \texttt{setBuffer}, \texttt{Fistream}'s only private member.
    \end{itemize}
    Here is \texttt{setField}'s implementation:
        \begin{verbatim}
std::istream &Fistream::setField(field const &params)
{
    if (params.d_newWidth)                  // new field size requested
        d_width = params.d_width;           // set new width

    if (!d_width)                           // no width?
        rdbuf(d_streambuf);                 // return to the old buffer
    else
        setBuffer();                        // define the extraction buffer

    return *this;
}
\end{verbatim}
The private member \texttt{setBuffer} defines a buffer of \texttt{d\_width + 1}
characters and uses \texttt{read} to fill the buffer with \texttt{d\_width}
characters. The buffer is an NTBS. This buffer is used to initialize the
\texttt{d\_iss} member. \texttt{Fistream}'s \texttt{rdbuf} member is used to extract the
\texttt{d\_str}'s data via the \texttt{Fistream} object itself:
        \begin{verbatim}
void Fistream::setBuffer()
{
    char *buffer = new char[d_width + 1];

    rdbuf(d_streambuf);                         // use istream's buffer to
    buffer[read(buffer, d_width).gcount()] = 0; // read d_width chars,
                                                // terminated by a 0-byte
    d_iss.str(buffer);
    delete[] buffer;

    rdbuf(d_iss.rdbuf());                       // switch buffers
}
\end{verbatim}
Although \texttt{setField} could be used to configure \texttt{Fistream} to use or
not to use fixed-sized field extraction, using manipulators is probably
preferable. To allow \texttt{field} objects to be used as manipulators an
overloaded extraction operator was defined. This extraction operator accepts
\texttt{istream \&} and a \texttt{field const \&} objects. Using this extraction
operator, statements like
        \begin{verbatim}
fis >> field(2) >> x >> field(0);
\end{verbatim}
are possible (assuming \texttt{fis} is a \texttt{Fistream} object). Here is the
overloaded \texttt{operator}$>>$, as well as its declaration:
        \begin{verbatim}
istream &std::operator>>(istream &str, field const &params)
{
    return static_cast<Fistream *>(&str)->setField(params);
}
\end{verbatim}
    Declaration:
        \begin{verbatim}
namespace std
{
    istream &operator>>(istream &str, FBB::field const &params);
}
\end{verbatim}
Finally, an example. The following program uses a \texttt{Fistream} object to
url-decode url-encoded information appearing at its standard input:
        \begin{verbatim}
    int main()
    {
        Fistream fis(cin);

        fis >> hex;
        while (true)
        {
            size_t x;
            switch (x = fis.get())
            {
                case '\n':
                    cout << '\n';
                break;
                case '+':
                    cout << ' ';
                break;
                case '%':
                    fis >> field(2) >> x >> field(0);
                // FALLING THROUGH
                default:
                    cout << static_cast<char>(x);
                break;
                case EOF:
                return 0;
            }
        }
    }
    /*
        Generated output after:
            echo My+name+is+%60Ed%27 | a.out

        My name is `Ed'
    */
\end{verbatim}
\section{The `fork' system call}\label{FORK}
\typeout{Original Yodl file: concrete/fork}From the \textbf{C} programming language the \index{fork}\texttt{fork} system call is well
known. When a program needs to start a new process, \index{system}\texttt{system} can be used.
The function \texttt{system} requires the program to wait for the
        \index{child process}\emph{child process}
    to terminate. The more general way to spawn subprocesses is to use
\texttt{fork}.

In this section we investigate how \textbf{C++} can be used to wrap classes around
a complex system call like \texttt{fork}. Much of what follows in this section
directly applies to the Unix operating system, and the discussion therefore
focuses on that operating system. Other systems usually provide
comparable facilities. What follows is closely related to the
 \emph{Template Design Pattern}\index{design pattern} (cf. \emph{Gamma et al.} (1995)
    \index{Gamma, E.} \index{Design Patterns}Design Patterns, Addison-Wesley)

When \texttt{fork} is called, the current program is duplicated in memory, thus
creating a new process. Following this duplication both processes continue
their execution just below the \texttt{fork} system call. The two processes may
inspect \texttt{fork}'s return value: the return value in the
original process (called the \index{parent process}\emph{parent process}) differs from the return
value in the newly created process (called the \index{child process}\emph{child process}):
    \begin{itemize}
    \item  In the \emph{parent process} \texttt{fork} returns the \index{process ID}\emph{process ID} of the
(child) process that was created by the \texttt{fork} system call. This is a
positive integer value.
    \item  In the \emph{child process} \texttt{fork} returns 0.
    \item  If \texttt{fork} fails, -1 is returned.
    \end{itemize}

\subsection{A basic Fork class}
    \typeout{Original Yodl file: concrete/basicfork}
    A basic \texttt{Fork} class should hide all bookkeeping details of a system
call like \texttt{fork} from its users. The class \texttt{Fork} developed here does
just that. The class itself only ensures the proper execution of the \texttt{fork}
system call. Normally, \texttt{fork} is called to start a child process, usually
boiling down to the execution of a separate process. This child process may
expect input at its standard input stream and/or may generate output to its
standard output and/or standard error streams. \texttt{Fork} does not know all
this, and does not have to know what the child process will do. \texttt{Fork}
objects should be able to start their child processes.

\texttt{Fork}'s constructor cannot know what actions its child
process should perform. Similarly, it cannot know what actions the parent
process should perform. For these kind of  situations, the
        \index{template method design pattern}\emph{template method design pattern}
        \index{design pattern: template method}
    was developed. According to Gamma c.s., the \emph{template method design
pattern}
    \begin{quote}
    ``Define(s) the skeleton of an algorithm in an operation, deferring some
    steps to subclasses. {[}The{]} Template Method (design pattern) lets
    subclasses redefine certain steps of an algorithm, without changing
    the algorithm's structure.''
    \end{quote}

This design pattern allows us to define an \index{abstract base class}\emph{abstract base class}
        \index{base class}
    already providing the essential steps related to the \texttt{fork} system call,
deferring the implementation of other parts of the \texttt{fork} system call to
subclasses.

The \texttt{Fork} abstract base class has the following characteristics:
    \begin{itemize}
    \item  It defines a data member \texttt{d\_pid}. In the parent process this data
member contains the child's \index{process id}\emph{process id} and in the child process it has
the value 0. Its public interface declares only two members:
    \begin{itemize}
    \item  a \index{fork}\texttt{fork} member function, responsible for the actual forking (i.e.,
        it creates the (new) child process);
    \item  a \texttt{virtual} destructor \texttt{\textasciitilde{}Fork} (having an empty body).
    \end{itemize}
    Here is \texttt{Fork}'s interface:
            \begin{verbatim}
    class Fork
    {
        int d_pid;

        public:
            virtual ~Fork();
            void fork();

        protected:
            int pid() const;
            int waitForChild();                 // returns the status

        private:
            virtual void childRedirections();
            virtual void parentRedirections();

            virtual void childProcess() = 0;    // pure virtual members
            virtual void parentProcess() = 0;
    };
\end{verbatim}
    \item  All other non-virtual member functions are declared in the class's
\texttt{protected} section and can thus \emph{only} be used by derived classes. They
are:
        \begin{itemize}
        \item \texttt{pid()}: The member function \texttt{pid} allows derived classes to
            access the system \texttt{fork}'s return value:
                \begin{verbatim}
    inline int Fork::pid() const
    {
        return d_pid;
    }
\end{verbatim}
        \item \texttt{waitForChild()}: The member \texttt{int waitForChild} can be called by
            parent processes to wait for the completion of their child
            processes (as discussed below). This member is declared in the
            class interface. Its implementation is:
                \begin{verbatim}
    #include "fork.ih"

    int Fork::waitForChild()
    {
        int status;

        waitpid(d_pid, &status, 0);

        return WEXITSTATUS(status);
    }
\end{verbatim}
            This simple implementation returns the child's \index{exit status}\emph{exit status} to
            the parent. The called system function \index{waitpid}\texttt{waitpid} \emph{blocks}
            until the child terminates.
        \end{itemize}
    \item  When \texttt{fork} system calls are used,
            \emph{parent processes} \index{parent process}
        and
            \emph{child processes} \index{child process}
        must always be distinguished. The main distinction between these
        processes is that \texttt{d\_pid} becomes the child's process-id in the
        parent process, while \texttt{d\_pid} becomes 0 in the child process
        itself. Since these two processes must always be distinguished (and
        present), their implementation by classes derived from \texttt{Fork} is
        enforced by \texttt{Fork}'s interface: the members \texttt{childProcess},
        defining the child process' actions and \texttt{parentProcess}, defining
        the parent process' actions were defined as pure virtual functions.

\item  communication between parent- and child processes
        may use standard streams or other facilities, like \emph{pipes}
        (cf. section \ref{PIPE}). To facilitate this inter-process
        communication, derived classes \emph{may} implement:
        \begin{itemize}
        \item \texttt{childRedirections()}: this member should be overridden by derived
            classes if any standard stream (\texttt{cin, cout,}) or \texttt{cerr} must
            be redirected in the \emph{child} process (cf. section
            \ref{REDIRECTION}). By default it has an empty implementation;
        \item \texttt{parentRedirections()}: this member should be overridden by derived
            classes if any standard stream (\texttt{cin, cout,}) or \texttt{cerr} must
            be redirected in the \emph{parent} process. By default it has an
            empty implementation.
        \end{itemize}
    Redirection of the standard streams is necessary if parent and
child processes must communicate with each other via the standard streams.
Here are their default definitions. Since these functions are virtual
functions they should not be implemented inline, but in their own source file:
            \begin{verbatim}
    void Fork::childRedirections()
    {}
    void Fork::parentRedirections()
    {}
\end{verbatim}
    \end{itemize}

\subsection{Parents and Children}
    \typeout{Original Yodl file: concrete/parents}    The member function \texttt{fork} calls the system function \texttt{fork}
(Caution: since the system function \texttt{fork} is called by a member
function having the same name, the \texttt{::} scope resolution operator must be
used to prevent a recursive call of the member function itself).
The function \texttt{::fork}'s  return value determines whether \texttt{parentProcess}
or  \texttt{childProcess} is called. Maybe redirection is
necessary. \texttt{Fork::fork}'s implementation calls \texttt{childRedirections}
just before calling \texttt{childProcess}, and \texttt{parentRedirections} just
before calling \texttt{parentProcess}:
        \begin{verbatim}
    #include "fork.ih"

    void Fork::fork()
    {
        if ((d_pid = ::fork()) < 0)
            throw "Fork::fork() failed";

        if (d_pid == 0)                 // childprocess has pid == 0
        {
            childRedirections();
            childProcess();
            exit(1);                    // we shouldn't come here:
        }                               // childProcess() should exit

        parentRedirections();
        parentProcess();
    }
\end{verbatim}
    In \texttt{fork.cc} the class's \emph{internal header file}\index{internal header}
\texttt{fork.ih} is included. This header file takes care of the inclusion of the
necessary system header files, as well as the inclusion of \texttt{fork.h}
itself. Its implementation is:
        \begin{verbatim}
    #include "fork.h"
    #include <cstdlib>
    #include <unistd.h>
    #include <sys/types.h>
    #include <sys/wait.h>
\end{verbatim}
Child processes should not return: once they have completed their tasks,
they should terminate. This happens automatically when the child process
performs a call to a member of the \index{exec...}\texttt{exec...} family, but if the child
itself remains active, then it must make sure that it terminates properly. A
child process normally uses \index{exit}\texttt{exit} to terminate itself, but note that
\texttt{exit} prevents the activation of destructors of objects
        \index{destructor: called at exit}
        \index{exit: calling destructors}
    defined at the same or more superficial nesting levels than the level at
which \texttt{exit} is called. Destructors of globally defined objects \emph{are}
activated when \texttt{exit} is used. When using \texttt{exit} to terminate
\texttt{childProcess}, it should either itself call a support member function
defining all nested objects it needs, or it should define all its objects in a
compound statement (e.g., using a \texttt{throw} block) calling \texttt{exit} beyond
the compound statement.

Parent processes should normally wait for their children to complete.
Terminating child processes inform their parents that they are about to
terminate by sending a \index{signal}\emph{signal} that should be caught by their parents.  If
child processes terminate and their parent processes do not catch those
signals then such child processes remain visible as so-called \index{zombie}\emph{zombie}
processes.

If parent processes must wait for their children to complete, they may
call the member \texttt{waitForChild}. This member returns the exit status of a
child process to its parent.

There exists a situation where the \emph{child} process \emph{continues} to
live, but the \emph{parent} dies. This is a fairly natural event: parents tend to
die before their children do. In our context (i.e. \textbf{C++}), this is called a
\index{daemon}\emph{daemon} program. In a daemon the parent process dies and the child program
continues to run as a child of the basic \index{init}\texttt{init} process. Again, when the
child eventually dies a signal is sent to its `step-parent' \index{init}\texttt{init}. This
does not create a zombie as \texttt{init} catches the termination signals of all
its (step-) children.  The construction of a daemon process is very simple,
given the availability of the class \texttt{Fork} (cf. section \ref{DAEMON}).

\subsection{Redirection revisited}\label{REDIRECTION}
    \typeout{Original Yodl file: concrete/redirection}    Earlier, in section \ref{REDIR} streams were \index{redirection} redirected
using the \index{rdbuf}\texttt{ios::rdbuf} member function. By assigning the
\texttt{streambuf} of a stream to another stream, both stream objects access the
same \texttt{streambuf}, thus implementing redirection at the level of the
programming language itself.

This may be fine within the context of a \textbf{C++} program, but once we
leave that context the redirection terminates.  The operating system does not
know about \texttt{streambuf} objects. This situation is encountered, e.g., when a
program uses a \index{system}\texttt{system} call to start a subprogram. The example program at
the end of this section uses \textbf{C++} redirection to redirect the information
inserted into \index{cout}\texttt{cout} to a file, and then calls
        \begin{verbatim}
    system("echo hello world")
\end{verbatim}
to echo a well-known line of text. Since \texttt{echo} writes its information
to the standard output, this would be the program's redirected file if the
operating system would recognize \textbf{C++}'s redirection.

But redirection doesn't happen. Instead, \texttt{hello world} still appears at
the program's standard output and the redirected file is left untouched.  To
write \texttt{hello world} to the redirected file redirection must be realized at
the operating system level.  Some operating systems (e.g., \index{Unix}Unix and
friends) provide system calls like \index{dup}\texttt{dup} and \index{dup2}\texttt{dup2} to accomplish
this. Examples of the use of these system calls are given in section
\ref{PIPE}.

Here is the example of the \emph{failing redirection} at the system level
following  \textbf{C++} redirection using \texttt{streambuf} redirection:
        \begin{verbatim}
    #include <iostream>
    #include <fstream>
    #include <cstdlib>
    using namespace std;

    int main()
    {
        ofstream of("outfile");

        streambuf *buf = cout.rdbuf(of.rdbuf());
        cout << "To the of stream\n";
        system("echo hello world");
        cout << "To the of stream\n";
        cout.rdbuf(buf);
    }
    /*
        Generated output: on the file `outfile'

        To the of stream
        To the of stream

        On standard output:

        hello world
    */
\end{verbatim}
\subsection{The `Daemon' program}\label{DAEMON}
    \typeout{Original Yodl file: concrete/daemon}    Applications exist in which the only purpose of \index{fork}\texttt{fork} is to start a
child process. The parent process terminates immediately after spawning the
child process. If this happens, the child process continues to run as a child
process of \index{init}\texttt{init}, the always running first process on \index{Unix}Unix systems. Such
a process is often called a \index{daemon}\emph{daemon}, running as a \index{background process}background process.

Although the next example can easily be constructed as a plain \textbf{C}
program, it was included in the \textbf{C++} Annotations because it is so closely
related to the current discussion of the \texttt{Fork} class. I thought about
adding a \texttt{daemon} member to that class, but eventually decided against it
because the construction of a daemon program is very simple and requires no
features other than those currently offered by the class \texttt{Fork}.  Here is an
example illustrating the construction of such a daemon program. Its child
process doesn't do \index{exit}\texttt{exit} but \texttt{throw 0} which is caught by the \texttt{catch}
clause of the child's \texttt{main} function. Doing this ensures that any objects
defined by the child process are properly destroyed:
        \begin{verbatim}
    #include <iostream>
    #include <unistd.h>
    #include "fork.h"

    class Daemon: public Fork
    {
        void parentProcess() override       // the parent does nothing.
        {}
        void childProcess() override        // actions by the child
        {
            sleep(3);
                                            // just a message...
            std::cout << "Hello from the child process\n";
            throw 0;                        // The child process ends
        }
    };

    int main()
    try
    {
        Daemon{}.fork();
    }
    catch (...)
    {}

    /*
        Generated output:
    The next command prompt, then after 3 seconds:
    Hello from the child process
    */
\end{verbatim}
\subsection{The class `Pipe'}\label{PIPE}
    \typeout{Original Yodl file: concrete/pipes}    Redirection at the system level requires the use of 
        \emph{file descriptor}\index{file descriptor}, created by the \index{pipe}\texttt{pipe} system
call. When two processes want to communicate using such file descriptors, the
following happens:
    \begin{itemize}
    \item  The process constructs two \emph{associated file descriptors} using the
\texttt{pipe} system call. One of the file descriptors is used for writing, the
other file descriptor is used for reading.
    \item  Forking takes place (i.e., the system \texttt{fork} function is called),
duplicating the file descriptors. Now we have four file descriptors as
the child process and the parent process both have their own copies of the two
file descriptors created by \texttt{pipe}.
    \item  One process (say, the parent process) uses the file descriptors
for \emph{reading}. It should close its file descriptor intended for \emph{writing}.
    \item  The other process (say, the child process) uses the file descriptors
for \emph{writing}. It should therefore close its file descriptor intended for
\emph{reading}.
    \item  All information written by the child process to the file
descriptor intended for writing, can now be read by the parent process from
the corresponding file descriptor intended for reading, thus establishing a
communication channel between the child and the parent process.
    \end{itemize}
    Though basically simple, errors may easily creep in. Functions of file
descriptors available to the two processes (child or parent) may easily get
mixed up. To prevent bookkeeping errors, the bookkeeping may be properly set
up once, to be hidden thereafter inside a class like the \texttt{Pipe} class
developed here. Let's have a look at its characteristics (before using
functions like \texttt{pipe} and \texttt{dup} the compiler must have read the
\index{unistd.h: header file}\texttt{$<$unistd.h$>$} header file):
    \begin{itemize}
    \item  The \texttt{pipe} system call expects a pointer to two \texttt{int} values,
representing, respectively, the file descriptor used for reading and the file
descriptor used for writing. To avoid confusion, the class \texttt{Pipe} defines an
\texttt{enum} having values associating the indices of the array of 2-\texttt{int}s with
symbolic constants. The two file descriptors themselves are stored in a data
member \texttt{d\_fd}. Here is the initial section of the class's interface:
        \begin{verbatim}
    class Pipe
    {
        enum    RW { READ, WRITE };
        int     d_fd[2];
\end{verbatim}
    \item  The class only needs a default constructor. This constructor
calls \texttt{pipe} to create  a set of associated file descriptors used for
accessing both ends of a pipe:
        \begin{verbatim}
    Pipe::Pipe()
    {
        if (pipe(d_fd))
            throw "Pipe::Pipe(): pipe() failed";
    }
\end{verbatim}
    \item  The members \texttt{readOnly} and \texttt{readFrom} are used to configure the
pipe's reading end. The latter function is used when using redirection. It is
provided with an alternate file descriptor to be used for  reading from the
pipe. Usually this alternate file descriptor is \index{STDIN\_FILENO}\texttt{STDIN\_FILENO}, allowing
\texttt{cin} to extract information from the pipe.  The former function is merely
used to configure the reading end of the pipe. It closes the matching writing
end and returns a file descriptor that can be used to read from the pipe:
        \begin{verbatim}
    int Pipe::readOnly()
    {
        close(d_fd[WRITE]);
        return d_fd[READ];
    }
    void Pipe::readFrom(int fd)
    {
        readOnly();

        redirect(d_fd[READ], fd);
        close(d_fd[READ]);
    }
\end{verbatim}
    \item  \texttt{writeOnly} and two \texttt{writtenBy} members are available to
configure the writing end of a pipe. The former function is only used to
configure the writing end of the pipe. It closes the reading end, and
returns a file descriptor that can be used for writing to the pipe:
        \begin{verbatim}
    int Pipe::writeOnly()
    {
        close(d_fd[READ]);
        return d_fd[WRITE];
    }
    void Pipe::writtenBy(int fd)
    {
        writtenBy(&fd, 1);
    }
    void Pipe::writtenBy(int const *fd, size_t n)
    {
        writeOnly();

        for (size_t idx = 0; idx < n; idx++)
            redirect(d_fd[WRITE], fd[idx]);

        close(d_fd[WRITE]);
    }
\end{verbatim}
    For the latter member two overloaded versions are available:
        \begin{itemize}
        \item \texttt{writtenBy(int fd)} is used to configure \emph{single}
redirection, so that a specific file descriptor (usually \index{STDOUT\_FILENO}\texttt{STDOUT\_FILENO}
or \index{STDERR\_FILENO}\texttt{STDERR\_FILENO}) can be used to write to the pipe;
        \item \texttt{(writtenBy(int const $*$fd, size\_t n))} may be used
to configure \emph{multiple} redirection, providing an array argument containing
file descriptors. Information written to any of these file descriptors is
actually written to the pipe.
        \end{itemize}
    \item  The class has one private data member, \texttt{redirect}, used to set up
redirection through the \index{dup2}\texttt{dup2} system call. This function expects two file
descriptors. The first file descriptor represents a file descriptor that can
be used to access the device's information; the second file descriptor is an
alternate file descriptor that may also be used to access the device's
information. Here is \texttt{redirect}'s implementation:
        \begin{verbatim}
    void Pipe::redirect(int d_fd, int alternateFd)
    {
        if (dup2(d_fd, alternateFd) < 0)
            throw "Pipe: redirection failed";
    }
\end{verbatim}
    \end{itemize}
    Now that redirection can be configured easily using one or more \texttt{Pipe}
objects, we'll use \texttt{Fork} and \texttt{Pipe} in various example programs.

\subsection{The class `ParentSlurp'}
    \typeout{Original Yodl file: concrete/parentslurp}    The class \index{ParentSlurp}\texttt{ParentSlurp}, derived from \texttt{Fork}, starts a child process
executing a stand-alone program (like \texttt{/bin/ls}). The (standard) output of
the executed program is not shown on the screen but is read by the parent
process.

For demonstration purposes the parent process writes the lines it
receives to its standard output stream, prepending linenumbers to the
lines. It is attractive to redirect the parent's standard \emph{input} stream to
allow the parent to read the \emph{output} from the child process using its
\texttt{std::cin} \emph{input} stream. Therefore, the only pipe in the program is used
as an \emph{input} pipe for the parent, and an \emph{output} pipe for the child.

The class \texttt{ParentSlurp} has the following characteristics:
    \begin{itemize}
    \item  It is derived from \texttt{Fork}. Before starting \texttt{ParentSlurp}'s class
interface, the compiler must have read \texttt{fork.h} and \texttt{pipe.h}. The class
only uses one data member, a \texttt{Pipe} object \texttt{d\_pipe}.
    \item  As \texttt{Pipe}'s constructor already defines a pipe, and as \texttt{d\_pipe}
is automatically initialized by \texttt{ParentSlurp}'s default constructor, which
is implicitly provided, all additional members only exist for
\texttt{ParentSlurp}'s own benefit so they can be defined in the class's (implicit)
\texttt{private} section. Here is the class's interface:
        \begin{verbatim}
    class ParentSlurp: public Fork
    {
        Pipe    d_pipe;

        void childRedirections() override;
        void parentRedirections() override;
        void childProcess() override;
        void parentProcess() override;
    };
\end{verbatim}
    \item  The \texttt{childRedirections} member configures the writing end of the
pipe. So, all information written to the child's standard output stream ends
up in the pipe. The big advantage of this is that no additional streams are
needed to write to a file descriptor:
        \begin{verbatim}
    inline void ParentSlurp::childRedirections()
    {
        d_pipe.writtenBy(STDOUT_FILENO);
    }
\end{verbatim}
    \item  The \texttt{parentRedirections} member, configures the reading end of
the pipe. It does so by connecting the reading end of the pipe to the parent's
standard input file descriptor (\texttt{STDIN\_FILENO}). This allows the parent to
perform extractions from \texttt{cin}, not requiring any additional streams for
reading.
        \begin{verbatim}
    inline void ParentSlurp::parentRedirections()
    {
        d_pipe.readFrom(STDIN_FILENO);
    }
\end{verbatim}
    \item  The \texttt{childProcess} member only needs to concentrate on its own
actions. As it only needs to execute a program (writing information to its
standard output), the member can consist of  one single statement:
        \begin{verbatim}
    inline void ParentSlurp::childProcess()
    {
        execl("/bin/ls", "/bin/ls", 0);
    }
\end{verbatim}
    \item  The \texttt{parentProcess} member simply `slurps' the information
appearing at its standard input. Doing so, it actually reads the child's
output. It copies the received lines to its standard output stream prefixing
line numbers to them:
        \begin{verbatim}
    void ParentSlurp::parentProcess()
    {
        std::string     line;
        size_t    nr = 1;

        while (getline(std::cin, line))
            std::cout << nr++ << ": " << line << '\n';

        waitForChild();
    }
\end{verbatim}
    \end{itemize}
    The following program simply constructs a \texttt{ParentSlurp} object, and
calls its \texttt{fork()} member. Its output consists of a numbered list of files
in the directory where the program is started.  Note that the program also
needs the \texttt{fork.o, pipe.o} and \texttt{waitforchild.o} object files (see
earlier sources):
        \begin{verbatim}
    int main()
    {
        ParentSlurp{}.fork();
    }
    /*
        Generated Output (example only, actually obtained output may differ):

        1: a.out
        2: bitand.h
        3: bitfunctional
        4: bitnot.h
        5: daemon.cc
        6: fdinseek.cc
        7: fdinseek.h
        ...
    */
\end{verbatim}
\subsection{Communicating with multiple children}
    \typeout{Original Yodl file: concrete/children}    The next step up the ladder is the construction of a child-process
monitor. Here, the parent process is responsible for all its child processes,
but it also must read their standard output. The user enters information at
the standard input of the parent process. A simple \index{command language}\emph{command language} is
used for this:
    \begin{itemize}
    \item \texttt{start}: this starts a new child process. The parent returns the
child's ID (a number) to the user. The ID is thereupon be used to identify a
particular child process;
    \item \texttt{$<$nr$>$ text} sends ``\texttt{text}'' to the child process having ID
\texttt{$<$nr$>$};
    \item \texttt{stop $<$nr$>$} terminates the child process having ID \texttt{$<$nr$>$};
    \item \texttt{exit} terminates the parent as well as all its child processes.
    \end{itemize}
    If a child process hasn't received text for some time it will complain by
sending a message to the parent-process. Those messages are simply transmitted
to the user by copying them to the standard output stream.

A problem with programs like our monitor is that they allow
        \index{asynchronous input}\emph{asynchronous input} from multiple sources. Input may appear at the
standard input as well as at the input-sides of pipes. Also, multiple output
channels are used. To handle situations like these, the \index{select}\texttt{select} system
call was developed.

\subsubsection{The class `Selector': interface}
        \typeout{Original Yodl file: concrete/select}    The \index{select}\texttt{select} system call was developed to handle asynchronous
        \index{multiplexing}\index{I/O multiplexing}\emph{I/O multiplexing}.
    The \texttt{select} system call is used to handle, e.g., input appearing
simultaneously at a set of file descriptors.

The \texttt{select} function is rather complex, and its full discussion is
beyond the \textbf{C++} Annotations' scope.  By encapsulating \texttt{select} in a \texttt{class
Selector}, hiding its details and offering an intuitively attractive
interface, its use is simplified. The \texttt{Selector} class has these
features:
    \begin{itemize}
    \item  Efficiency. As most of \texttt{Select}'s members are very small,
most members can be implemented  inline. The class requires quite a few data
members. Most of these data members belong to types that require some system
headers to be included first:
        \begin{verbatim}
    #include <limits.h>
    #include <unistd.h>
    #include <sys/time.h>
    #include <sys/types.h>
\end{verbatim}
    \item  The class interface can now be defined. The data type \texttt{fd\_set} is a
type designed to be used by \texttt{select} and variables of this type contain the
set of file descriptors on which \texttt{select} may sense some
activity. Furthermore, \texttt{select} allows us to fire an
        \index{asynchronous alarm}\emph{asynchronous alarm}. To set the alarm time, the class \texttt{Selector}
defines a \index{timeval}\texttt{timeval} data member. Other members are used for internal
bookkeeping purposes. Here is the class \texttt{Selector}'s interface:
        \begin{verbatim}
    class Selector
    {
        fd_set          d_read;
        fd_set          d_write;
        fd_set          d_except;
        fd_set          d_ret_read;
        fd_set          d_ret_write;
        fd_set          d_ret_except;
        timeval         d_alarm;
        int             d_max;
        int             d_ret;
        int             d_readidx;
        int             d_writeidx;
        int             d_exceptidx;

        public:
            Selector();

            int exceptFd();
            int nReady();
            int readFd();
            int wait();
            int writeFd();
            void addExceptFd(int fd);
            void addReadFd(int fd);
            void addWriteFd(int fd);
            void noAlarm();
            void rmExceptFd(int fd);
            void rmReadFd(int fd);
            void rmWriteFd(int fd);
            void setAlarm(int sec, int usec = 0);

        private:
            int checkSet(int *index, fd_set &set);
            void addFd(fd_set *set, int fd);
    };
\end{verbatim}
    \end{itemize}

\subsubsection{The class `Selector': implementation}
        \typeout{Original Yodl file: concrete/selectimpl}    Selector's member functions serve the following tasks:
    \begin{itemize}
    \item \index{Selector}\texttt{Selector()}: the (default) constructor. It
clears the read, write, and execute \texttt{fd\_set} variables, and switches off the
alarm. Except for \texttt{d\_max}, the remaining data members do not require
specific initializations:
        \begin{verbatim}
    Selector::Selector()
    {
        FD_ZERO(&d_read);
        FD_ZERO(&d_write);
        FD_ZERO(&d_except);
        noAlarm();
        d_max = 0;
    }
\end{verbatim}
    \item \index{wait}\texttt{int wait()}: this member \emph{blocks} until the \emph{alarm} times
out or until activity is sensed at any of the file descriptors monitored by
the \texttt{Selector} object. It throws an exception when the \texttt{select} system
call itself fails:
        \begin{verbatim}
    int Selector::wait()
    {
        timeval t = d_alarm;

        d_ret_read = d_read;
        d_ret_write = d_write;
        d_ret_except = d_except;

        d_readidx = 0;
        d_writeidx = 0;
        d_exceptidx = 0;

        d_ret = select(d_max, &d_ret_read, &d_ret_write, &d_ret_except,
                       t.tv_sec == -1 && t.tv_usec == -1 ? 0 : &t);

        if (d_ret < 0)
            throw "Selector::wait()/select() failed";

        return d_ret;
    }
\end{verbatim}
    \item \index{nReady}\texttt{int nReady}: this member function's return value is only
defined when \texttt{wait} has returned. In that case it returns 0 for an
alarm-timeout, -1 if \texttt{select} failed, and otherwise the number of file
descriptors on which activity was sensed:
        \begin{verbatim}
    inline int Selector::nReady()
    {
        return d_ret;
    }
\end{verbatim}
    \item \index{readFd}\texttt{int readFd()}: this member function's return
value is also only defined after \texttt{wait} has returned. Its return value is
-1 if no (more) input file descriptors are available. Otherwise the next file
descriptor available for reading is returned:
        \begin{verbatim}
    inline int Selector::readFd()
    {
        return checkSet(&d_readidx, d_ret_read);
    }
\end{verbatim}
    \item \index{writeFd}\texttt{int writeFd()}: operating analogously to \texttt{readFd}, it
returns the next file descriptor to which output is written.  It uses
\texttt{d\_writeidx} and \texttt{d\_ret\_read} and is implemented analogously to
\texttt{readFd};
    \item \index{exceptFd}\texttt{int exceptFd()}: operating analogously to \texttt{readFd}, it
returns the next exception file descriptor on which activity was sensed.  It
uses \texttt{d\_except\_idx} and \texttt{d\_ret\_except} and is implemented analogously to
\texttt{readFd};
    \item \index{setAlarm}\texttt{void setAlarm(int sec, int usec = 0)}: this member
activates \texttt{Select}'s alarm facility. At least the number of seconds to wait
for the alarm to go off must be specified. It simply assigns values to
\texttt{d\_alarm}'s fields. At the next \texttt{Select::wait} call, the alarm fires
(i.e., \texttt{wait} returns with return value 0) once the configured
alarm-interval has passed:
        \begin{verbatim}
    inline void Selector::setAlarm(int sec, int usec)
    {
        d_alarm.tv_sec  = sec;
        d_alarm.tv_usec = usec;
    }
\end{verbatim}
    \item \index{noAlarm}\texttt{void noAlarm()}: this member switches off the alarm, by
simply setting the alarm interval to a very long period:
        \begin{verbatim}
    inline void Selector::noAlarm()
    {
        setAlarm(-1, -1);
    }
\end{verbatim}
    \item \index{addReadFd}\texttt{void addReadFd(int fd)}: this member adds a
file descriptor to the set of input file descriptors monitored by the
\texttt{Selector} object. The member function \texttt{wait} returns once input is
available at the indicated file descriptor:
        \begin{verbatim}
    inline void Selector::addReadFd(int fd)
    {
        addFd(&d_read, fd);
    }
\end{verbatim}
    \item \index{addWriteFd}\texttt{void addWriteFd(int fd)}: this member adds a file
descriptor to the set of output file descriptors monitored by the \texttt{Selector}
object. The member function \texttt{wait} returns once output is available at
the indicated file descriptor. Using \texttt{d\_write}, it is implemented
analogously to \texttt{addReadFd};
    \item \index{addExceptFd}\texttt{void addExceptFd(int fd)}: this member adds a file
descriptor to the set of exception file descriptors to be monitored by the
\texttt{Selector} object.  The member function \texttt{wait} returns once activity
is sensed at the indicated file descriptor. Using \texttt{d\_except}, it is
implemented analogously to \texttt{addReadFd};
    \item \index{rmReadFd}\texttt{void rmReadFd(int fd)}: this member removes a file
descriptor from the set of input file descriptors monitored by the
\texttt{Selector} object:
        \begin{verbatim}
    inline void Selector::rmReadFd(int fd)
    {
        FD_CLR(fd, &d_read);
    }
\end{verbatim}
    \item \index{rmWriteFd}\texttt{void rmWriteFd(int fd)}: this member removes a file
descriptor from the set of output file descriptors monitored by the
\texttt{Selector} object.  Using \texttt{d\_write}, it is implemented analogously to
\texttt{rmReadFd};
    \item \index{rmExceptFd}\texttt{void rmExceptFd(int fd)}: this member removes a file
descriptor from the set of exception file descriptors to be monitored by the
\texttt{Selector} object.  Using \texttt{d\_except}, it is implemented analogously to
\texttt{rmReadFd};
    \end{itemize}
    The class's remaining (two) members are support members, and should not be
used by non-member functions. Therefore, they are declared in the class's
\texttt{private} section:
    \begin{itemize}
    \item  The member \texttt{addFd} adds a file descriptor to a \texttt{fd\_set}:
        \begin{verbatim}
    void Selector::addFd(fd_set *set, int fd)
    {
        FD_SET(fd, set);
        if (fd >= d_max)
            d_max = fd + 1;
    }
\end{verbatim}
    \item  The member \texttt{checkSet} tests whether a file descriptor (\texttt{$*$index})
is found in a \texttt{fd\_set}:
        \begin{verbatim}
    int Selector::checkSet(int *index, fd_set &set)
    {
        int &idx = *index;

        while (idx < d_max && !FD_ISSET(idx, &set))
            ++idx;

        return idx == d_max ? -1 : idx++;
    }
\end{verbatim}
    \end{itemize}

\subsubsection{The class `Monitor': interface}\label{MONITOR}
        \typeout{Original Yodl file: concrete/monitor}    The \texttt{monitor} program uses a \texttt{Monitor} object doing most of the
work. The class \texttt{Monitor}'s public interface only offers a default
constructor and one member, \texttt{run}, to perform its tasks.  All other member
functions are located in the class's \texttt{private} section.

\texttt{Monitor} defines the \texttt{private} enum \texttt{Commands}, symbolically
listing the various commands its input language supports, as well as several
data members.  Among the data members are a \texttt{Selector} object and a \texttt{map}
using child order numbers as its keys and pointer to \texttt{Child} objects (see
section \ref{CHILD}) as its values. Furthermore, \texttt{Monitor} has a static array
member \texttt{s\_handler{[}{]}}, storing pointers to member functions handling user
commands.

A destructor should be implemented as well, but its implementation is left
as an exercise to the reader. Here is \texttt{Monitor}'s interface, including the
interface of the nested class \texttt{Find} that is used to create a function
object:
        \begin{verbatim}
    class Monitor
    {
        enum Commands
        {
            UNKNOWN,
            START,
            EXIT,
            STOP,
            TEXT,
            sizeofCommands
        };

        using MapIntChild = std::map<int, std::shared_ptr<Child>>;

        friend class Find;
        class Find
        {
            int     d_nr;
            public:
                Find(int nr);
                bool operator()(MapIntChild::value_type &vt) const;
        };

        Selector    d_selector;
        int         d_nr;
        MapIntChild d_child;

        static void (Monitor::*s_handler[])(int, std::string const &);
        static int s_initialize;

        public:
            enum Done
            {};

            Monitor();
            void run();

        private:
            static void killChild(MapIntChild::value_type it);
            static int initialize();

            Commands    next(int *value, std::string *line);
            void    processInput();
            void    processChild(int fd);

            void    createNewChild(int, std::string const &);
            void    exiting(int = 0, std::string const &msg = std::string{});
            void    sendChild(int value, std::string const &line);
            void    stopChild(int value, std::string const &);
            void    unknown(int, std::string const &);
    };
\end{verbatim}
Since there's only one non-class type data member, the class's constructor
is a very simple function which could be implemented inline:
        \begin{verbatim}
    inline Monitor::Monitor()
    :
        d_nr(0)
    {}
\end{verbatim}
\subsubsection{The class `Monitor': s\_handler}
        \typeout{Original Yodl file: concrete/shandler}The array
\texttt{s\_handler}, storing pointers to functions needs to be initialized as
well. This can be accomplished in several ways:
    \begin{itemize}
    \item  Since the \texttt{Commands} enumeration only specifies a fairly limited
set of commands, compile-time initialization could be considered:
        \begin{verbatim}
    void (Monitor::*Monitor::s_handler[])(int, string const &)  =
    {
        &Monitor::unknown,              // order follows enum Command's
        &Monitor::createNewChild,       // elements
        &Monitor::exiting,
        &Monitor::stopChild,
        &Monitor::sendChild,
    };
\end{verbatim}
    The advantage of this is that it's simple, not requiring any run-time
effort. The disadvantage is of course relatively complex maintenance. If for
some reason \texttt{Commands} is modified, \texttt{s\_handler} must be modified as
well. In cases like these, compile-time initialization often is
asking for trouble. There is a simple alternative though.
    \item  Looking at \texttt{Monitor}'s interface we see a static data member
\texttt{s\_initialize} and a static member function \texttt{initialize}. The static
member function handles the initialization of the \texttt{s\_handler} array. It
explicitly assigns the array's elements and any modification in ordering of
\texttt{enum Commands}' values is automatically accounted for by recompiling
\texttt{initialize}:
        \begin{verbatim}
    void (Monitor::*Monitor::s_handler[sizeofCommands])(int, string const &);

    int Monitor::initialize()
    {
        s_handler[UNKNOWN] =    &Monitor::unknown;
        s_handler[START] =      &Monitor::createNewChild;
        s_handler[EXIT] =       &Monitor::exiting;
        s_handler[STOP] =       &Monitor::stopChild;
        s_handler[TEXT] =       &Monitor::sendChild;
        return 0;
    }
\end{verbatim}
    The member \texttt{initialize} is a static member and so it can be
called to initialize \texttt{s\_initialize}, a static \texttt{int} variable. The
initialization is enforced by placing the initialization statement in the
source file of a function that is known to be executed. It could be \texttt{main},
but if we're \texttt{Monitor}'s maintainers and only have control over the library
containing \texttt{Monitor}'s code then that's not an option. In those cases the
source file containing the destructor is a \emph{very} good candidate. If a class
has only one constructor and it's \emph{not} defined inline then the
constructor's source file is a good candidate as well. In \texttt{Monitor}'s
current implementation the initialization statement is put in \texttt{run}'s source
file, reasoning that \texttt{s\_handler} is only needed when \texttt{run} is used.
    \end{itemize}

\subsubsection{The class `Monitor': the member `run'}
        \typeout{Original Yodl file: concrete/run}    \texttt{Monitor}'s core activities are performed by \texttt{run}. It
performs the following tasks:
    \begin{itemize}
    \item  Initially, the \texttt{Monitor} object only monitors its standard
input. The set of input file descriptors to which \texttt{d\_selector} listens
is initialized to \texttt{STDIN\_FILENO}.
    \item  Then, in a loop  \texttt{d\_selector}'s \texttt{wait} function is called.
If input on \texttt{cin} is available, it is processed by \texttt{processInput}.
Otherwise, the input has arrived from a child process. Information sent by
children is processed by \texttt{processChild}.
    \item  To prevent \index{zombie}\emph{zombie}\emph{s}, the child processes must catch \emph{their}
children's termination signals. This is discussed below.

As noted by Ben Simons (\texttt{ben at mrxfx dot com}) \texttt{Monitor} must not catch
the termination signals.  Instead, the process spawning child processes has
that responsibility (the underlying principle being that a parent process is
responsible for its child processes; a child process, in turn, is responsible
for its own child processes).
    \item  As stated, \texttt{run}'s source file also defines and initializes
\texttt{s\_initialize} to ensure the proper initialization of the \texttt{s\_handler}
array.
    \end{itemize}
    Here is \texttt{run}'s implementation and \texttt{s\_initialize}'s definition:
        \begin{verbatim}
    #include "monitor.ih"

    int Monitor::s_initialize = Monitor::initialize();

    void Monitor::run()
    {
        d_selector.addReadFd(STDIN_FILENO);

        while (true)
        {
            cout << "? " << flush;
            try
            {
                d_selector.wait();

                int fd;
                while ((fd = d_selector.readFd()) != -1)
                {
                    if (fd == STDIN_FILENO)
                        processInput();
                    else
                        processChild(fd);
                }
                cout << "NEXT ...\n";
            }
            catch (char const *msg)
            {
                exiting(1, msg);
            }
        }
    }
\end{verbatim}
The member function \texttt{processInput} reads the commands entered by the
user using the program's standard input stream. The member itself is rather
simple. It calls \texttt{next} to obtain the next command entered by the user, and
then calls the corresponding function using the matching element of the
\texttt{s\_handler{[}{]}} array. Here are the members \texttt{processInput} and \texttt{next}:
        \begin{verbatim}
    void Monitor::processInput()
    {
        string line;
        int    value;
        Commands cmd = next(&value, &line);
        (this->*s_handler[cmd])(value, line);
    }
\end{verbatim}
        \begin{verbatim}
    Monitor::Commands Monitor::next(int *value, string *line)
    {
        if (!getline(cin, *line))
            exiting(1, "Monitor::next(): reading cin failed");

        if (*line == "start")
            return START;

        if (*line == "exit" || *line == "quit")
        {
            *value = 0;
            return EXIT;
        }

        if (line->find("stop") == 0)
        {
            istringstream istr(line->substr(4));
            istr >> *value;
            return !istr ? UNKNOWN : STOP;
        }

        istringstream istr(line->c_str());
        istr >> *value;
        if (istr)
        {
            getline(istr, *line);
            return TEXT;
        }

        return UNKNOWN;
    }
\end{verbatim}
All other input sensed by \texttt{d\_select} is created by child
processes. Because \texttt{d\_select}'s \texttt{readFd} member returns the corresponding
input file descriptor, this descriptor can be passed to
\texttt{processChild}. Using a \index{IFdStreambuf}\texttt{IFdStreambuf} (see section \ref{IFDBUF}), its
information is read from an input stream. The communication protocol used here
is rather basic. For every line of input sent to a child, the child replies by
sending back exactly one line of text. This line is then read by
\texttt{processChild}:
        \begin{verbatim}
    void Monitor::processChild(int fd)
    {
        IFdStreambuf ifdbuf(fd);
        istream istr(&ifdbuf);
        string line;

        getline(istr, line);
        cout << d_child[fd]->pid() << ": " << line << '\n';
    }
\end{verbatim}
    The construction \texttt{d\_child{[}fd{]}-$>$pid()} used in the above source deserves
some special attention. \texttt{Monitor} defines the data member \texttt{map$<$int,
shared\_ptr$<$Child$>$$>$ d\_child}.  This map contains the child's order number
as its key, and a (shared) pointer to the \texttt{Child} object as its value. A
shared pointer is used here, rather than a \texttt{Child} object, since we want to
use the facilities offered by the map, but don't want to copy a \texttt{Child}
object time and again.

\subsubsection{The class `Monitor': example}
        \typeout{Original Yodl file: concrete/monitorexample}    Now that \texttt{run}'s implementation has been covered, we'll concentrate on
the various commands users might enter:
    \begin{itemize}
    \item  When the \texttt{start} command is issued, a new child process is started.
A new element is added to \texttt{d\_child} by the member \texttt{createNewChild}.  Next,
the \texttt{Child} object should start its activities, but the \texttt{Monitor} object
can not wait for the child process to complete its activities, as there is no
well-defined endpoint in the near future, and the user probably wants to be
able to enter more commands. Therefore, the \texttt{Child} process must run as a
\index{daemon}\emph{daemon}. So the forked process terminates immediately, but its own child
process continues to run (in the background). Consequently,
\texttt{createNewChild} calls the child's \texttt{fork} member. Although it is the
child's \texttt{fork} function that is called, it is still the monitor program
wherein that \texttt{fork} function is called. So, the \emph{monitor} program is
duplicated by \texttt{fork}. Execution then continues:
    \begin{itemize}
    \item  At the \texttt{Child}'s \texttt{parentProcess} in its parent process;
    \item  At the \texttt{Child}'s \texttt{childProcess} in its child process
    \end{itemize}
    As the \texttt{Child}'s \texttt{parentProcess} is an empty function, returning
immediately, the \texttt{Child}'s parent process effectively continues immediately
below \texttt{createNewChild}'s \texttt{cp-$>$fork()} statement.  As the child process
never returns (see section \ref{CHILD}), the code below \texttt{cp-$>$fork()} is never
executed by the \texttt{Child}'s child process. This is exactly as it should be.

In the parent process, \texttt{createNewChild}'s remaining code simply
adds the file descriptor that's available for reading information from the
child to the set of input file descriptors monitored by \texttt{d\_select}, and
uses \texttt{d\_child} to  establish the association between that
file descriptor and the  \texttt{Child} object's address:
        \begin{verbatim}
    void Monitor::createNewChild(int, string const &)
    {
        Child *cp = new Child{ ++d_nr };

        cp->fork();

        int fd = cp->readFd();

        d_selector.addReadFd(fd);
        d_child[fd].reset(cp);

        cerr << "Child " << d_nr << " started\n";
    }
\end{verbatim}
    \item  Direct communication with the child is required for the \texttt{stop $<$nr$>$}
and \texttt{$<$nr$>$ text} commands. The former command terminates child process
\texttt{$<$nr$>$}, by calling \texttt{stopChild}. This function locates the child process
having the order number using an anonymous object of the class \texttt{Find},
nested inside \texttt{Monitor}. The class \texttt{Find} simply compares the
provided \texttt{nr} with the children's order number returned by their \texttt{nr}
members:
        \begin{verbatim}
    inline Monitor::Find::Find(int nr)
    :
        d_nr(nr)
    {}
    inline bool Monitor::Find::operator()(MapIntChild::value_type &vt) const
    {
        return d_nr == vt.second->nr();
    }
\end{verbatim}
    If the child process having order number \texttt{nr} was found, its file
descriptor is removed from \texttt{d\_selector}'s set of input file
descriptors. Then the child process itself is terminated by the static member
\texttt{killChild}. The member \texttt{killChild} is declared as a \emph{static} member
function, as it is used as function argument of the \texttt{for\_each} generic
algorithm by \texttt{exiting} (see below). Here is \texttt{killChild}'s
implementation:
        \begin{verbatim}
    void Monitor::killChild(MapIntChild::value_type it)
    {
        if (kill(it.second->pid(), SIGTERM))
            cerr << "Couldn't kill process " << it.second->pid() << '\n';

        // reap defunct child process
        int status = 0;
        while( waitpid( it.second->pid(), &status, WNOHANG) > -1)
            ;
    }
\end{verbatim}
    Having terminated the specified child process, the corresponding \texttt{Child}
object is destroyed and its pointer is removed from \texttt{d\_child}:
        \begin{verbatim}
    void Monitor::stopChild(int nr, string const &)
    {
        auto it = find_if(d_child.begin(), d_child.end(), Find{ nr });

        if (it == d_child.end())
            cerr << "No child number " << nr << '\n';
        else
        {
            d_selector.rmReadFd(it->second->readFd());
            d_child.erase(it);
        }
    }
\end{verbatim}
    \item  The command \texttt{$<$nr$>$ text} sends \texttt{text} to child process \texttt{nr}
using the member function \texttt{sendChild}. This function also uses a \texttt{Find}
object to locate the child-process having order number \texttt{nr}, and simply
inserts the text into the writing end of a pipe connected to that child
process:
        \begin{verbatim}
    void Monitor::sendChild(int nr, string const &line)
    {
        auto it = find_if(d_child.begin(), d_child.end(), Find(nr));

        if (it == d_child.end())
            cerr << "No child number " << nr << '\n';
        else
        {
            OFdnStreambuf ofdn{ it->second->writeFd() };
            ostream out(&ofdn);

            out << line << '\n';
        }
    }
\end{verbatim}
    \item  When users enter \texttt{exit} or \texttt{quit} the member \texttt{exiting} is
called.  It terminates all child processes using the \index{for\_each}\texttt{for\_each} generic
algorithm (see section \ref{FOREACH}) to visit all elements of
\texttt{d\_child}. Then the program itself ends:
        \begin{verbatim}
    void Monitor::exiting(int value, string const &msg)
    {
        for_each(d_child.begin(), d_child.end(), killChild);
        if (msg.length())
            cerr << msg << '\n';
        throw value;
    }
\end{verbatim}
    \end{itemize}
    The program's \texttt{main} function is simple and needs no further comment:
        \begin{verbatim}
    int main()
    try
    {
        Monitor{}.run();
    }
    catch (int exitValue)
    {
        return exitValue;
    }
\end{verbatim}
\subsubsection{The class `Child'}\label{CHILD}
        \typeout{Original Yodl file: concrete/child}    When the \texttt{Monitor} object starts a child process, it creates an object
of the class \texttt{Child}. The \texttt{Child} class is derived from the class
\texttt{Fork}, allowing it to operate as a \index{daemon}\emph{daemon} (as discussed in the
previous section). Since \texttt{Child} is a daemon class, we know that its parent
process must be defined as an empty function.  Its \texttt{childProcess} member
has a non-empty implementation. Here are the characteristics of the class
\texttt{Child}:
    \begin{itemize}
    \item  The \texttt{Child} class has two \texttt{Pipe} data members, to handle
communications between its own child- and parent processes. As these pipes are
used by the \texttt{Child}'s child process, their names refer to the child
process. The child process reads from \texttt{d\_in}, and writes to \texttt{d\_out}. Here
is the interface of the class \texttt{Child}:
        \begin{verbatim}
    class Child: public Fork
    {
        Pipe                d_in;
        Pipe                d_out;

        int         d_parentReadFd;
        int         d_parentWriteFd;
        int         d_nr;

        public:
            Child(int nr);
            ~Child() override;
            int readFd() const;
            int writeFd() const;
            int pid() const;
            int nr() const;
        private:
            void childRedirections() override;
            void parentRedirections() override;
            void childProcess() override;
            void parentProcess() override;
    };
\end{verbatim}
    \item  The \texttt{Child}'s constructor simply stores its argument, a
child-process order number, in its own \texttt{d\_nr} data member:
        \begin{verbatim}
    inline Child::Child(int nr)
    :
        d_nr(nr)
    {}
\end{verbatim}
    \item  The \texttt{Child}'s child process obtains commands from its standard
input stream and writes its output to its standard output stream. Since the
actual communication channels are pipes, redirections must be used. The
\texttt{childRedirections} member looks like this:
        \begin{verbatim}
    void Child::childRedirections()
    {
        d_in.readFrom(STDIN_FILENO);
        d_out.writtenBy(STDOUT_FILENO);
    }
\end{verbatim}
    \item  Although the parent process performs no actions, it must configure
some redirections. Realizing that the names of the pipes indicate their
functions in the child process. So the parent \emph{writes} to \texttt{d\_in} and
\emph{reads} from \texttt{d\_out}. Here is \texttt{parentRedirections}:
        \begin{verbatim}
    void Child::parentRedirections()
    {
        d_parentReadFd = d_out.readOnly();
        d_parentWriteFd = d_in.writeOnly();
    }
\end{verbatim}
    \item  The \texttt{Child} object exists until it is destroyed by the
\texttt{Monitor}'s \texttt{stopChild} member. By allowing its creator, the \texttt{Monitor}
object, to access the parent-side ends of the pipes, the \texttt{Monitor} object
can communicate with the \texttt{Child}'s child process via those pipe-ends. The
members \texttt{readFd} and \texttt{writeFd} allow the \texttt{Monitor} object to access
these pipe-ends:
        \begin{verbatim}
    inline int Child::readFd() const
    {
        return d_parentReadFd;
    }
    inline int Child::writeFd() const
    {
        return d_parentWriteFd;
    }
\end{verbatim}
    \item  The \texttt{Child} object's child process performs two tasks:
        \begin{itemize}
        \item  It must reply to information appearing at its standard input
stream;
        \item  If no information has appeared within a certain time frame (the
implementations uses an interval of five seconds), then a message is written
to its standard output stream.
        \end{itemize}
        To implement this behavior, \texttt{childProcess} defines a local
\texttt{Selector} object, adding \texttt{STDIN\_FILENO} to its set of monitored input
file descriptors.

Then, in an endless loop, \texttt{childProcess} waits for \texttt{selector.wait()}
to return. When the alarm goes off it sends a message to its standard output
(hence, into the writing pipe). Otherwise, it echoes the messages appearing
at its standard input to its standard output. Here is the \texttt{childProcess}
member:
        \begin{verbatim}
    void Child::childProcess()
    {
        Selector    selector;
        size_t    message = 0;

        selector.addReadFd(STDIN_FILENO);
        selector.setAlarm(5);

        while (true)
        {
            try
            {
                if (!selector.wait())       // timeout
                    cout << "Child " << d_nr << ": standing by\n";
                else
                {
                    string  line;
                    getline(cin, line);
                    cout << "Child " << d_nr << ":" << ++message << ": " <<
                                                        line << '\n';
                }
            }
            catch (...)
            {
                    cout << "Child " << d_nr << ":" << ++message << ": " <<
                                "select() failed" << '\n';
            }
        }
        exit(0);
    }
\end{verbatim}
    \item  Two accessors are defined allowing the \texttt{Monitor} object to obtain
the \texttt{Child}'s process ID and its order number:
        \begin{verbatim}
    inline int Child::pid() const
    {
        return Fork::pid();
    }
    inline int Child::nr() const
    {
        return d_nr;
    }
\end{verbatim}
    \item  A \texttt{Child} process terminates when the user enters a \texttt{stop}
command. When an existing child process number was entered, the corresponding
\texttt{Child} object is removed from \texttt{Monitor}'s \texttt{d\_child} map. As a result,
its destructor is called. \texttt{Child}'s destructor calls \texttt{kill} to terminate
its child, and then waits for the child to terminate. Once its child has
terminated, the destructor has completed its work and returns, thus completing
the erasure from \texttt{d\_child}. The current implementation fails if the child
process doesn't react to the \texttt{SIGTERM} signal. In this demonstration program
this does not happen. In `real life' more elaborate killing-procedures may be
required (e.g., using \texttt{SIGKILL} in addition to \texttt{SIGTERM}). As discussed in
section \ref{CONSEXCEPTIONS} it \emph{is} important to ensure the proper
destruction. Here is the \texttt{Child}'s destructor:
        \begin{verbatim}
    Child::~Child()
    {
        if (pid())
        {
            cout << "Killing process " << pid() << "\n";
            kill(pid(), SIGTERM);
            int status;
            wait(&status);
        }
    }
\end{verbatim}
    \end{itemize}


\section{Adding binary operators to classes}
\typeout{Original Yodl file: concrete/binop}As we've seen in section \ref{OVERLOADBINARY} binary operators expecting
\texttt{const \&} arguments can be implemented using a member implementing the
operation, only offering the basic exception guarantee.
This latter function can in turn be implemented using the binary
assignment member. The following examples illustrated this approach for a
fictitious class \texttt{Binary}:
        \begin{verbatim}
    class Binary
    {
        public:
            Binary();
            Binary(int value);
                // copy and move constructors are available by default, or
                // they can be explicitly declared and implemented.

            Binary &operator+=(Binary const &other) &;    // see the text
            Binary &&operator+=(Binary const &other) &&;

        private:
            void add(Binary const &rhs);

        friend Binary operator+(Binary const &lhs, Binary const &rhs);
        friend Binary operator+(Binary &&lhs, Binary const &rhs);
    };
\end{verbatim}
Eventually, the implementation of binary operators depends on the availability
of the member implementing the basic binary operation, modifying the object
calling that member (i.e., \texttt{void Binary::add(Binary const \&)} in the
example).

Since template functions are not instantiated before they are actually used we
can call non-existing functions from template functions that are never
instantiated. If such a template function is never instantiated, nothing
happens; if it is (accidentally) instantiated, then the compiler generates an
error message, complaining about the missing function.

This allows us to implement all binary operators, movable and non-movable, as
templates. In the following subsections we develop the class template
\texttt{Binops}, prividing binary operators.  A complete implementation of a class
\texttt{Derived} illustrating how addition and insertion operators can be added to
a class is provided in the file
\texttt{annotations/yo/concrete/examples/binopclasses.cc} in the \textbf{C++} Annotations'
source archive.

\subsection{Merely using operators}
    \typeout{Original Yodl file: concrete/operators}In section \ref{OVERLOADBINARY} addition operators are implemented in terms of
a support member \texttt{add}. This is less attractive when developing function
templates, as \texttt{add} is a private member, requiring us to provide friend
declarations for all function templates so they may access the private \texttt{add}
member.

At the end of section \ref{OVERLOADBINARY} we saw that \texttt{add's} implementation
can be provided by \texttt{operator+=(Class const \&rhs) \&\&}. This operator may
thereupon be used when implementing the remaining addition operators:
        \begin{verbatim}
    inline Binary &operator+=(Binary const &rhs) &
    {
        return *this = Binary{*this} += rhs;        
    }

    Binary operator+(Binary &&lhs, Binary const &rhs)
    {
        return std::move(lhs) += rhs;
    }

    Binary operator+(Binary const &lhs, Binary const &rhs)
    {
        return Binary{lhs} += rhs;
    }
\end{verbatim}
In this implementation \texttt{add} is no longer required. The plain binary
operators are free functions, which supposedly can easily be converted to
function templates. E.g.,
        \begin{verbatim}
    template <typename Binary>
    Binary operator+(Binary const &lhs, Binary const &rhs)
    {
        return Binary{lhs} += rhs;
    }
\end{verbatim}
\subsubsection{To namespace or not to namespace?}
        \typeout{Original Yodl file: concrete/namespace}When using the function template \texttt{Binary operator+(Binary const \&lhs, Binary
const \&rhs)}, however, we may encounter a subtle and unexpected
complication. Consider the following program. When run, it displays the value
12, rather than 1:
        \begin{verbatim}
    enum Values
    {
        ZERO,
        ONE
    };
    
    template <typename Tp>
    Tp operator+(Tp const &lhs, Tp const &rhs)
    {
        return static_cast<Tp>(12);
    };
    
    int main()
    {
        cout << (ZERO + ONE);       // shows 12
    }
\end{verbatim}
This complication can be avoided by defining the operators in their own
namespace, but then all classes using the binary operator also have to be
defined in that namespace, which is not a very attractive
restriction. Fortunately, there is a better alternative: using the CRTP
(cf. section \ref{STATICPOLY}).

\subsection{The CRTP and defining operator function templates}
    \typeout{Original Yodl file: concrete/crtp}When deriving classes from a class template \texttt{Binops}, using the CRTP the
operators are defined for arguments of the class \texttt{Binops$<$Derived$>$}: a base
class receiving the derived class as its template argument. 

Thus the class \texttt{Binops} as well as the additional operators are defined,
expecting \texttt{Binops$<$Derived$>$} type of arguments:
        \begin{verbatim}
    template <class Derived>
    struct Binops
    {
        Derived &operator+=(Derived const &rhs) &;
    };

    template <typename Derived>
    Derived operator+(Binops<Derived> const &lhs, Derived const &rhs)
    {
        return Derived{static_cast<Derived const &>(lhs) } += rhs;
    }
    // analogous implementation for Binops<Derived> &&lhs
\end{verbatim}
This way, a class that derives from \texttt{Binops}, and that provides an
\texttt{operator+=} member which is bound to an rvalue reference object, suddenly
also provides all other binary addition operators:
        \begin{verbatim}
    class Derived: public Binops<Derived>
    {
        ...
        public:
            ...
            Derived &&operator+=(Derived const &rhs) &&
    };
\end{verbatim}
All, but one.... 

The operator that's not available is the compound addition operator,
bound to an lvalue reference. As its function name is identical to the one in
the class \texttt{Derived}, it is not automatically visible at the user level.

Although this problem can simply be solved by providing the class \texttt{Derived}
with a \texttt{using Binops$<$Derived$>$::operator+=} declaration, it is not a very
attractive solution, as separate using declarations have to be provided for
each binary operator that is implemented in the class \texttt{Derived}.

But a \emph{much} more attractive solution exists. A beautiful out-of-the-box
solution, completely avoiding the hidden base class operator, was proposed
by \index{Wiebe-Marten Wijnja}Wiebe-Marten Wijnja. Wiebe-Marten conjectured that \texttt{operator+=}, bound
to an lvalue reference could also very well be defined as a \emph{free}
function. In that case no inheritance is used and therefore no function hiding
occurs. Consequently, the \texttt{using} directive can be avoided. 

The implementation of this free \texttt{operator+=} function looks like this:
        \begin{verbatim}
    template <class Derived>
    Derived &operator+=(Binops<Derived> &lhs, Derived const &rhs) 
    {
        Derived tmp{ Derived{ static_cast<Derived &>(lhs) } += rhs };
        tmp.swap(static_cast<Derived &>(lhs));
        return static_cast<Derived &>(lhs);
    }
\end{verbatim}
The flexibility of this design can be further augmented once we realize that
the right-hand side operand doesn't have to be a \texttt{Derived} class
object. Consider \texttt{operator$<$$<$}: oftentimes shifts are bit-shifts, using a
\texttt{size\_t} to specify the number of bits to shift. In fact, the type of the
right-hand side operand can completely be generalized by defining a second
template type parameter, which is used to specify the right-hand side's
operand type. It's up to the \texttt{Derived} class to specify the argument type of
its \texttt{operator+=} (or any other binary compound operator), whereafter the
compiler will deduce the types of the right-hand side operands for the
remaining binary operators. Here is the final implementation of the free
\texttt{operator+=} function:
        \begin{verbatim}
    template <class Derived, typename Rhs>
    Derived &operator+=(Binops<Derived> &lhs, Rhs const &rhs) 
    {
        Derived tmp{ Derived{ static_cast<Derived &>(lhs) } += rhs };
        tmp.swap(static_cast<Derived &>(lhs));
        return static_cast<Derived &>(lhs);
    }
\end{verbatim}
\subsection{Insertion and extraction}
    \typeout{Original Yodl file: concrete/insertion}Classes also frequently define overloaded insertion and extraction
operators. Since there are no `compound insertion operators' the design shown
so far cannot be used when overloading these operators. Instead using
standardized member function signatures is advocated: \texttt{void
insert(std::ostream \&out) const} to insert an object into an \texttt{ostream} and
\texttt{void extract(std::istream \&in) const} to extract an object from an
\texttt{istream}. As these functions are only used by, respectively, the insertion
and extraction operators, they can be declared in the \texttt{Derived} class's
private interface. Instead of declaring the insertion and extraction operators
friends of the class \texttt{Derived} a single \texttt{friend Binops$<$Derived$>$} is
specified. This allows \texttt{Binops$<$Derived$>$} to define private, inline \texttt{iWrap}
and \texttt{eWrap} members, merely calling, respectively, \texttt{Derived's insert} and
\texttt{extract} members:
        \begin{verbatim}
    template <typename Derived>
    inline void Binops<Derived>::iWrap(std::ostream &out) const
    {
        static_cast<Derived const &>(*this).insert(out);
    }
\end{verbatim}
\texttt{Binops$<$Derived$>$} then declares the insertion and extraction operators as
its friends, allowing these operators to call, respectively, \texttt{iWrap} and
\texttt{eWrap}. Note that the software engineer designing the class \texttt{Derived}
only has to provide a \texttt{friend Binops$<$Derived$>$} declaration. Here is the
implementation of the overloaded insertion operator:
        \begin{verbatim}
    template <typename Derived>
    std::ostream &operator<<(std::ostream &out, Binops<Derived> const &obj)
    {
        obj.iWrap(out);
        return out;
    }
\end{verbatim}
This completes the coverage of the essentials of a class template \texttt{Binops}
potentially offering binary operators and insertion/extraction operators for
any class derived from \texttt{Binops}. Finally, as noted at the beginning of this
section, a complete implementation of a class offering addition and insertion
operators is provided in the file
\texttt{annotations/yo/concrete/examples/binopclasses.cc} in the \textbf{C++} Annotations'
source archive.

\section{Distinguishing lvalues from rvalues with operator{[}{]}()}\label{PROXY}
    \typeout{Original Yodl file: concrete/proxy}A problem with \index{operator[]}\texttt{operator{[}{]}} is that it can't distinguish between its
    \index{lvalue: distinguish from rvalue}\index{rvalue: distinguish from lvalue}
 use as an \emph{lvalue} and as an \emph{rvalue}. It is a familiar misconception to
think that
        \begin{verbatim}
    Type const &operator[](size_t index) const
\end{verbatim}
is used as \emph{rvalue} (as the object isn't modified), and
    that
        \begin{verbatim}
    Type &operator[](size_t index)
\end{verbatim}
is used as \emph{lvalue} (as the returned value can be modified).

The compiler, however, distinguishes between the two operators only by the
\texttt{const}-status of the object for which \texttt{operator{[}{]}} is called. With
\texttt{const} objects the former operator is called, with non-\texttt{const} objects
the latter is always used. It is always used, irrespective of it being used as
lvalue or rvalue.

Being able to distinguish between lvalues and rvalues can be very
useful. Consider the situation where a class supporting \texttt{operator{[}{]}} stores
data of a type that is very hard to copy. With data like that reference
counting (e.g., using \texttt{shared\_ptr}s) is probably used to prevent needless
copying.

As long as \texttt{operator{[}{]}} is used as rvalue there's no need to copy the data,
but the information \emph{must} be copied if it is used as lvalue.

The \index{Proxy Design Pattern}\emph{Proxy Design Pattern} (cf. \index{Gamma, E.}\emph{Gamma et al.} (1995)) can
be used to distinguish between lvalues and rvalues. With the Proxy Design
Pattern an object of another class (the Proxy class) is used to act as a
\emph{stand in} for the `real thing'. The proxy class offers functionality that
cannot be offered by the data themselves, like distinguishing between its use
as lvalue or rvalue. A proxy class can be used in many situations where access
to the real data cannot or should not be directly provided. In this regard
\emph{iterator} types are examples of proxy classes as they create a layer
between the real data and the software using the data. Proxy classes could
also dereference pointers in a class storing its data by pointers.

In this section we concentrate on the distinction between using \texttt{operator{[}{]}}
as lvalue and rvalue. Let's assume we have a class \texttt{Lines} storing lines
from a file. Its constructor expects the name of a stream from which the
lines are read and it offers a non-const \texttt{operator{[}{]}} that can be used as
lvalue or rvalue (the \texttt{const} version of \texttt{operator{[}{]}} is omitted as it
causes no confusion because it is always used as rvalue):
        \begin{verbatim}
    class Lines
    {
        std::vector<std::string> d_line;

        public:
            Lines(std::istream &in);
            std::string &operator[](size_t idx);
    };
\end{verbatim}
To distinguish between lvalues and rvalues we must find distinguishing
characteristics of lvalues and rvalues that we can exploit. Such
distinguishing characteristics are \texttt{operator=} (which is always used as
lvalue) and the conversion operator (which is always used as rvalue). Rather
than having \texttt{operator{[}{]}} return a \texttt{string \&} we can let it return a
\texttt{Proxy} object that is able to distinguish between its use as lvalue
and rvalue.

The class \texttt{Proxy} thus needs \texttt{operator=(string const \&other)} (acting as
lvalue) and \texttt{operator std::string const \&() const} (acting as rvalue). Do we
need more operators? The \texttt{std::string} class also offers \texttt{operator+=}, so
we should probably implement that operator as well. Plain characters can also
be assigned to \texttt{string} objects (even using their numeric values). As
\texttt{string} objects cannot be \emph{constructed} from plain characters
\emph{promotion} cannot be used with \texttt{operator=(string const \&other)} if the
right-hand side argument is a character. Implementing \texttt{operator=(char
value)} could therefore also be considered. These additional operators are
left out of the current implementation but `real life' proxy classes should
consider implementing these additional operators as well. Another subtlety is
  \index{Proxy: stream insertion and extraction}
that \texttt{Proxy}'s \texttt{operator std::string const \&() const} is not used
when using \texttt{ostream}'s insertion operator or \texttt{istream}'s extraction
operator as these operators are implemented as templates not recognizing our
\texttt{Proxy} class type. So when stream insertion and extraction is required (it
probably is) then \texttt{Proxy} must be given its own overloaded insertion and
extraction operator. Here is an implementation of the overloaded insertion
operator inserting the object for which \texttt{Proxy} is a stand-in:
        \begin{verbatim}
inline std::ostream &operator<<(std::ostream &out, Lines::Proxy const &proxy)
{
    return out << static_cast<std::string const &>(proxy);
}
\end{verbatim}
There's no need for any code (except \texttt{Lines}) to create or copy \texttt{Proxy}
objects. \texttt{Proxy}'s constructor should therefore be made private, and
\texttt{Proxy} can declare \texttt{Lines} to be its friend. In fact, \texttt{Proxy} is
intimately related to \texttt{Lines} and can be defined as a nested class. In the
revised \texttt{Lines} class \texttt{operator{[}{]}} no longer returns a \texttt{string} but
instead a \texttt{Proxy} is returned. Here is the revised \texttt{Lines} class,
including its nested \texttt{Proxy} class:
        \begin{verbatim}
    class Lines
    {
        std::vector<std::string> d_line;

        public:
            class Proxy;
            Proxy operator[](size_t idx);
            class Proxy
            {
                friend Proxy Lines::operator[](size_t idx);
                std::string &d_str;
                Proxy(std::string &str);
                public:
                    std::string &operator=(std::string const &rhs);
                    operator std::string const &() const;
            };
            Lines(std::istream &in);
    };
\end{verbatim}
\texttt{Proxy}'s members are very lightweight and can usually be implemented
inline:
        \begin{verbatim}
    inline Lines::Proxy::Proxy(std::string &str)
    :
        d_str(str)
    {}
    inline std::string &Lines::Proxy::operator=(std::string const &rhs)
    {
        return d_str = rhs;
    }
    inline Lines::Proxy::operator std::string const &() const
    {
        return d_str;
    }
\end{verbatim}
The member \texttt{Lines::operator{[}{]}} can also be implemented inline: it merely
returns a \texttt{Proxy} object initialized with the \texttt{string} associated with
index \texttt{idx}.

Now that the class \texttt{Proxy} has been developed it can be used in a
program. Here is an example using the \texttt{Proxy} object as lvalue or rvalue. On
the surface \texttt{Lines} objects won't behave differently from \texttt{Lines} objects
using the original implementation, but by adding an identifying \texttt{cout}
statement to \texttt{Proxy}'s members it can be shown that \texttt{operator{[}{]}} behaves
differently when used as lvalue or as rvalue:
        \begin{verbatim}
    int main()
    {
        ifstream in("lines.cc");
        Lines lines(in);

        string s = lines[0];        // rvalue use
        lines[0] = s;               // lvalue use
        cout << lines[0] << '\n';   // rvalue use
        lines[0] = "hello world";   // lvalue use
        cout << lines[0] << '\n';   // rvalue use
    }
\end{verbatim}
\section{Implementing a `reverse\_iterator'}\label{CONCRETEITER}
\typeout{Original Yodl file: concrete/iterators}In section \ref{RANDOMIT} the construction of iterators and
reverse iterators was discussed. In that section the iterator was constructed
as an inner class in a class derived from a vector of pointers to strings.

An object of this nested iterator class handles the dereferencing of the
pointers stored in the vector. This allowed us to sort the \emph{strings}
pointed to by the vector's elements rather than the \emph{pointers}.

A drawback of this is that the class implementing the iterator is closely
tied to the derived class as the iterator class was implemented as a nested
class. What if we would like to provide any class derived from a container
class storing pointers with an iterator handling pointer-dereferencing?

In this section a variant of the earlier (nested class) approach is
discussed. Here the iterator class is defined as a class template,
    \index{iterator: as class template}
    not only parameterizing the data type to which the container's elements
point but also the container's iterator type itself. Once again, we
concentrate on developing a \index{RandomIterator}\emph{RandomIterator} as it is the most complex
iterator type.

Our class is named \texttt{RandomPtrIterator}, indicating that it is a random
iterator operating on pointer values. The class template defines three
template type parameters:
    \begin{itemize}
    \item  The first parameter specifies the derived class type
(\texttt{Class}). Like before, \texttt{RandomPtrIterator}'s
constructor is private. Therefore \texttt{friend} declarations are needed to
allow client classes to construct \texttt{RandomPtrIterators}.  However, a
\texttt{friend class Class} cannot be used as template parameter types cannot be
    \index{friend: using a template parameter}
used in \texttt{friend class ...} declarations. But this is a minor problem as not
every member of the client class needs to construct iterators. In fact, only
\texttt{Class}'s \texttt{begin} and \texttt{end} members must construct
iterators. Using the template's first parameter, friend declarations can be
specified for the client's \texttt{begin} and \texttt{end} members.

\item  The second template parameter parameterizes the container's iterator
type (\texttt{BaseIterator});

\item  The third template parameter indicates the data type to which the
pointers point (\texttt{Type}).
    \end{itemize}

\texttt{RandomPtrIterator} has one private data member, a
\texttt{BaseIterator}. Here is the class interface and the constructor's
implementation:
        \begin{verbatim}
    #include <iterator>
    #include <compare>

    template <typename Class, typename BaseIterator, typename Type>
    struct RandomPtrIterator;

    #define PtrIterator RandomPtrIterator<Class, BaseIterator, Type>
    #define PtrIteratorValue RandomPtrIterator<Class, BaseIterator, value_type>

    template <typename Class, typename BaseIterator, typename Type>
    bool operator==(PtrIterator const &lhs, PtrIterator const &rhs);

    template <typename Class, typename BaseIterator, typename Type>
    auto operator<=>(PtrIterator const &lhs, PtrIterator const &rhs);

    template <typename Class, typename BaseIterator, typename Type>
    int operator-(PtrIterator const &lhs, PtrIterator const &rhs);

    template <typename Class, typename BaseIterator, typename Type>
    struct RandomPtrIterator
    {
        using iterator_category = std::random_access_iterator_tag;
        using difference_type   = std::ptrdiff_t;
        using value_type        = Type;
        using pointer           = value_type *;
        using reference         = value_type &;


        friend PtrIterator Class::begin();
        friend PtrIterator Class::end();

        friend bool operator==<>(RandomPtrIterator const &lhs,
                                 RandomPtrIterator const &rhs);
        friend auto operator<=><>(RandomPtrIterator const &lhs,
                                  RandomPtrIterator const &rhs);
        friend int operator-<>(RandomPtrIterator const &lhs,
                               RandomPtrIterator const &rhs);
        private:
            BaseIterator d_current;

        public:
            int operator-(RandomPtrIterator const &rhs) const;
            RandomPtrIterator operator+(int step) const;
            value_type &operator*() const;
            RandomPtrIterator &operator--();
            RandomPtrIterator operator--(int);
            RandomPtrIterator &operator++();
            RandomPtrIterator operator++(int);
            RandomPtrIterator operator-(int step) const;
            RandomPtrIterator &operator-=(int step);
            RandomPtrIterator &operator+=(int step);
            value_type *operator->() const;

        private:
            RandomPtrIterator(BaseIterator const &current);
    };

    template <typename Class, typename BaseIterator, typename value_type>
    PtrIteratorValue::RandomPtrIterator(BaseIterator const &current)
    :
        d_current(current)
    {}
\end{verbatim}
    Looking at its \texttt{friend} declarations, we see that the members \texttt{begin}
and \texttt{end} of a class \texttt{Class}, returning a \texttt{RandomPtrIterator} object for
the types \texttt{Class, BaseIterator} and \texttt{Type} are granted access to
\texttt{RandomPtrIterator}'s private constructor.  That is exactly what we
want. The \texttt{Class}'s \texttt{begin} and \texttt{end} members are declared as \emph{bound
friends}.

All \texttt{RandomPtrIterator}'s remaining members are public. Since
\texttt{RandomPtrIterator} is just a generalization of the nested class
\texttt{iterator} developed in section \ref{RANDOMIT}, re-implementing the required
member functions is easy and only requires us to change \texttt{iterator} into
\texttt{RandomPtrIterator} and to change \texttt{std::string} into \texttt{Type}. For
example, \texttt{operator$<$}, defined in the class \texttt{iterator} as
        
    is now implemented as:
        \begin{verbatim}
    template <typename Class, typename BaseIterator, typename Type>
    inline auto operator<=>(PtrIterator const &lhs, PtrIterator const &rhs)
    {
        return **lhs.d_current <=> **rhs.d_current;
    }
\end{verbatim}
    Some additional examples: \texttt{operator$*$}, defined in the class
\texttt{iterator} as
        \begin{verbatim}
inline std::string &StringPtr::iterator::operator*() const
{
    return **d_current;
}
\end{verbatim}
    is now implemented as:
        \begin{verbatim}
    template <typename Class, typename BaseIterator, typename value_type>
    value_type &PtrIteratorValue::operator*() const
    {
        return **d_current;
    }
\end{verbatim}
    The pre- and postfix increment operators are now implemented as:
        \begin{verbatim}
    template <typename Class, typename BaseIterator, typename value_type>
    PtrIteratorValue &PtrIteratorValue::operator++()
    {
        ++d_current;
        return *this;
    }
    template <typename Class, typename BaseIterator, typename value_type>
    PtrIteratorValue PtrIteratorValue::operator++(int)
    {
        return RandomPtrIterator(d_current++);
    }
\end{verbatim}
    Remaining members can be implemented accordingly, their actual
implementations are left as exercises to the reader (or can be obtained from
the \texttt{cplusplus.yo.zip} archive, of course).

Re-implementing the class \texttt{StringPtr} developed in section \ref{RANDOMIT}
is not difficult either. Apart from including the header file defining the
class template \texttt{RandomPtrIterator}, it only requires a single modification.
Its \texttt{iterator} using-declaration must now be associated with a
\texttt{RandomPtrIterator}. Here is the full class interface and the class's inline
member definitions:
        \begin{verbatim}
    #ifndef INCLUDED_STRINGPTR_H_
    #define INCLUDED_STRINGPTR_H_

    #include <vector>
    #include <string>
    #include "iterator.h"

    class StringPtr: public std::vector<std::string *>
    {
        public:
            using iterator =
                    RandomPtrIterator
                    <
                        StringPtr,
                        std::vector<std::string *>::iterator,
                        std::string
                    >;

            using reverse_iterator = std::reverse_iterator<iterator>;

            iterator begin();
            iterator end();
            reverse_iterator rbegin();
            reverse_iterator rend();
    };

    inline StringPtr::iterator StringPtr::begin()
    {
        return iterator(this->std::vector<std::string *>::begin() );
    }
    inline StringPtr::iterator StringPtr::end()
    {
        return iterator(this->std::vector<std::string *>::end());
    }
    inline StringPtr::reverse_iterator StringPtr::rbegin()
    {
        return reverse_iterator(end());
    }
    inline StringPtr::reverse_iterator StringPtr::rend()
    {
        return reverse_iterator(begin());
    }
    #endif
\end{verbatim}
Including \texttt{StringPtr}'s modified header file into the program given in
section \ref{REVERSEIT} results in a program behaving identically to its
earlier version. In this case \texttt{StringPtr::begin} and \texttt{StringPtr::end}
return iterator objects constructed from a template definition.

\section{Using `bisonc++' and `flexc++'}\label{BisonAndFlex}
\typeout{Original Yodl file: concrete/bisonflex}    The example discussed below digs into the peculiarities of using
\index{parser}parser- and \index{scanner}scanner generators generating \textbf{C++} sources. Once the
input for a program exceeds a certain level of complexity, it becomes
attractive to use scanner- and parser-generators generating the code which
does the actual input recognition.

The examples in this and subsequent sections assume that the reader knows how
to use the
    \index{scanner generator}scanner generator \index{flex}\texttt{flex} and the \index{parser generator}parser generator \index{bison}\texttt{bison}. Both
\texttt{bison} and \texttt{flex} are well documented elsewhere. The original
predecessors of \texttt{bison} and \texttt{flex}, called \index{yacc}\texttt{yacc} and \index{lex}\texttt{lex} are
described in several books, e.g. in
    \index{http://www.oreilly.com/catalog/lex}
 O'Reilly's book \texttt{`lex \& yacc'}\footnote{http://www.oreilly.com/catalog/lex}.

Scanner- and parser generators are also available as free software. Both
\texttt{bison} and \texttt{flex} are usually part of software distributions or they can
be obtained from
    \index{ftp::/prep.ai.mit.edu/pub/non-gnu}
    \texttt{ftp://prep.ai.mit.edu/pub/non-gnu}. \texttt{Flex} creates a \texttt{C++} class
when \index{%option c++}\texttt{\%option c++} is specified.

For parser generators the program \index{bison}\texttt{bison} is available. In the early 90's
\emph{Alain Coetmeur} (\texttt{coetmeur@icdc.fr}\footnote{mailto:coetmeur@icdc.fr}) created a
\textbf{C++} variant (\index{bison++}\texttt{bison++}) creating a parser class. Although the
\texttt{bison++} program produces code that can be used in \textbf{C++} programs it also
shows many characteristics that are more suggestive of a \textbf{C} context than a
\textbf{C++} context. In January 2005 I rewrote parts of Alain's \texttt{bison++}
program, resulting in the original version of the program
        \index{bisonc++}
    \textbf{bisonc++}. Then, in May 2005 a complete rewrite of the \texttt{bisonc++}
parser generator was completed (version number 0.98). Current versions of
\texttt{bisonc++} can be downloaded from
    \texttt{https://fbb-git.gitlab.io/bisoncpp/}. Binary versions for various
architectures are available as, e.g., \texttt{Debian}\footnote{http://www.debian.org}
package (including \texttt{bisonc++}'s documentation).

\texttt{Bisonc++} creates a cleaner parser class than \texttt{bison++}. In particular,
it derives the parser class from a base-class, containing the parser's token-
and type-definitions as well as all member functions which should not be
(re)defined by the programmer. As a result of this approach, the generated
parser class is very small, declaring only members that are actually defined
by the programmer (as well as some other members, generated by \texttt{bisonc++}
itself, implementing the parser's \index{parse()}\texttt{parse()} member). One member that is
\emph{not} implemented by default is \texttt{lex}, producing the next lexical
token. When the directive \texttt{\%scanner} (see section \ref{BISONDEF}) is used,
\texttt{bisonc++} produces a standard implementation for this member; otherwise it
must be implemented by the programmer.

In early 2012 the program
    \index{flexc++}
    \textbf{flexc++} \texttt{http://flexcpp.org/} reached its initial release. Like
\texttt{bisonc++} it is part of the \texttt{Debian linux
distribution}\footnote{http://www.debian.org}.

Jean-Paul van Oosten (\mbox{jp@jpvanoosten.nl}\texttt{$<$jp@jpvanoosten.nl$>$}) and Richard Berendsen
(\mbox{richardberendsen@xs4all.nl}\texttt{$<$richardberendsen@xs4all.nl$>$}) started the \texttt{flexc++} project in 2008
and the final program was completed by Jean-Paul and me between 2010 and 2012.

These sections of the \textbf{C++} Annotations focus on \texttt{bisonc++} as our
 \index{parser generator}\emph{parser generator} and \texttt{flexc++} as our lexical scanner
generator. Previous releases of the \textbf{C++} Annotations were using \texttt{flex} as the
scanner generator.

Using \texttt{flexc++} and \texttt{bisonc++} \texttt{class}-based scanners and parsers are
generated. The advantage of this approach is that the interface to the scanner
and the parser tends to become cleaner than without using \texttt{class}
interfaces. Furthermore, classes allow us to get rid of most if not all global
variables, making it easy to use multiple parsers in one program.

Below two example programs are developed. The first example only uses
\texttt{flexc++}. The generated scanner monitors the production of a file from
several parts. That example focuses on the lexical scanner and on switching
files while churning through the information. The second example uses both
\texttt{flexc++} and \texttt{bisonc++} to generate a scanner and a parser transforming
standard arithmetic expressions to their postfix notations, commonly used in
code generated by compilers and in \texttt{HP}-calculators.  In the second example
the emphasis is mainly on \texttt{bisonc++} and on composing a scanner object
inside a generated parser.

\subsection{Using `flexc++' to create a scanner}\label{Flexcpp}
    \typeout{Original Yodl file: concrete/usingflex}The lexical scanner developed in this section is used to monitor the
production of a file from several subfiles. The setup is as follows: the
input-language defines \texttt{\#include} directives, followed by a text
string specifying the file (path) which should be included at the location of
the \texttt{\#include}.

In order to avoid complexities irrelevant to the current example, the format
of the \texttt{\#include} statement is restricted to the form \texttt{\#include
$<$filepath$>$}.  The file specified between the angle brackets should be
available at the location indicated by \texttt{filepath}. If the file is not
available, the program terminates after issuing an error message.

The program is started with one or two filename arguments. If the program is
started with just one filename argument, the output is written to the
standard output stream \texttt{cout}. Otherwise, the output is written to
the stream whose name is given as the program's second argument.

The program defines a maximum \index{nesting depth}nesting depth. Once this maximum is exceeded,
the program terminates after issuing an error message. In that case, the
filename stack indicating where which file was included is printed.

An additional feature of the program is that (standard \textbf{C++}) comment-lines
are ignored. Include-directives in comment-lines are also ignored.

The program is created in five major steps:
    \begin{itemize}
    \item  First, the file \texttt{lexer} is constructed, containing the
input-language specifications.
    \item  From the specifications in \texttt{lexer} the requirements for the
\texttt{class Scanner} evolve. The \texttt{Scanner} class derives from the base class
\index{ScannerBase}\texttt{ScannerBase} generated by \index{flexc++}\texttt{flexc++}.
    \item  Next, \texttt{main} is constructed. A \texttt{Scanner} object is created
inspecting the command-line arguments. If successful, the scanner's member
\texttt{lex} is called to produce the program's output.
    \item  Now that  the global setup of the program has been specified,
the member functions of the various classes are implemented.
    \item  Finally, the program is compiled and linked.
    \end{itemize}

\subsubsection{The derived class `Scanner'}
        \typeout{Original Yodl file: concrete/lexer}    The function matching the \index{regular expression}regular expression rules (\texttt{lex}) is a
member of the class \index{scanner}\texttt{Scanner}. Since \texttt{Scanner} is derived from
\texttt{ScannerBase}, it has access to all of \texttt{ScannerBase}'s protected members
that execute the lexical scanner's regular expression matching algorithm.

Looking at the regular expressions themselves, notice that we need rules
to recognize comment, \index{\#include}\texttt{\#include} directives, and all remaining characters.
This all is fairly standard practice. When an \texttt{\#include} directive is
sensed, the directive is parsed by the scanner. This too is common
practice. Our lexical scanner performs the following tasks:
    \begin{itemize}
    \item  As usual, \index{preprocessor directive}preprocessor directives are not
analyzed by a parser, but by the lexical scanner;
    \item  The scanner uses a \index{mini scanner}mini scanner to extract the filename from the
directive, throwing a exception if this fails;
    \item  If the filename could be extracted, processing switches to the next
stream, controlling for a maximum nesting depth.
    \item  Once the end of the current file has been reached processing
automatically returns to the previous file, restoring the previous file name
and line number. The scanner returns 0 if all files have been processed.
    \end{itemize}

\subsubsection{The lexical scanner specification file}
        \typeout{Original Yodl file: concrete/lexerspec}    The \index{lexical scanner specification file}lexical scanner specification file is organized comparably to the
one used for \texttt{flex} in \textbf{C} contexts. However, in \textbf{C++} contexts,
\texttt{flexc++} creates a class \texttt{Scanner}, rather than just a scanner function.

Flexc++'s specification file consists of two sections:
    \begin{itemize}
    \item  The specification file's first section is \texttt{flexc++}'s
        \index{symbol area}\emph{symbol area}, used to define symbols, like a \index{mini scanner}mini scanner, or
\index{options}\emph{options}. The following options are suggested:
        \begin{itemize}
        \item  \index{%debug}\texttt{\%debug}: includes \emph{debugging}
            \index{flexc++: debugging}
        code into the code generated by \texttt{flexc++}. Calling the member
function
            \index{setDebug}
    \texttt{setDebug(true)} activates this debugging code at run-time. When
activated, information about the matching process is written to the
standard output stream. The execution of debug code is suppressed after
calling the member function \texttt{setDebug(false)}.
        \item  \index{%filenames}\texttt{\%filenames}: defines the base-name of the class header files
generated by \texttt{flexc++}. By default the class name (itself using the default
\texttt{Scanner}) is used.
        \end{itemize}
    Here is the specification files' symbol area:
            \begin{verbatim}
%filenames scanner
%debug
%max-depth 3

%x      comment
%x      include
\end{verbatim}
    \item  The specification file's second section is a \emph{rules section} in
which the regular expressions and their associated actions are defined.
    In the example developed here,  the lexer should
copy information from the standard input stream (\texttt{std::cin}) to the
standard output stream (\texttt{std::cout}). For this  the predefined macro
\index{ECHO}\texttt{ECHO} can be used.  Here are the rules:
            \begin{verbatim}
%%
    // The comment-rules: comment is ignored.
"//".*                  // ignore eoln comment
"/*"                    begin(StartCondition__::comment);
<comment>{
    .|\n                // ignore all characters in std C comment
    "*/"                begin(StartCondition__::INITIAL);
}

    // File switching: #include <filepath>
#include[ \t]+"<"      begin(StartCondition__::include);
<include>{
    [^ \t>]+            d_nextSource = matched();
    ">"[ \t]*\n         switchSource();
    .|\n                throw runtime_error("Invalid include statement");
}

    // The default rule: echo anything else to std::cout
.|\n                    echo();
\end{verbatim}
    \end{itemize}

\subsubsection{Implementing `Scanner'}
        \typeout{Original Yodl file: concrete/scanner}    The \texttt{class Scanner} is generated once by \index{flexc++}\textbf{flexc++}. This class has
access to several members defined by its base class \texttt{ScannerBase}. Some of
these members have public access rights and can be used by code external to
the class \texttt{Scanner}. These members are extensively documented in the
\textbf{flexc++}(1) man-page, and the reader is referred to this man-page for
further information.

Our scanner performs the following tasks:
    \begin{itemize}
    \item  it matches regular expressions, ignoring comment, and writing the
matched text to the standard output stream;
    \item  it switches to other files, and returns to the previous file once a
file has completely been processed, ending the lexical scan once the end of
the first input file has been reached.
    \end{itemize}

The \texttt{\#include} statements in the input allow the scanner to distill the
name of the file where the scanning process must continue. This file name is
stored in a local variable \texttt{d\_nextSource} and a member \texttt{stackSource}
handles the switch to the next source. Nothing else is required. Pushing and
popping input files is handled by the scanner's members \texttt{pushStream} and
\texttt{popStream}, provided by \texttt{flexc++}. \texttt{Scanner}'s interface, therefore,
only needs one additional function declaration: \texttt{switchSource}.

Switching streams is handled as follows: once the scanner has extracted a
filename from an \texttt{\#include} directive, a switch to another file is realized
by \texttt{switchSource}.  This member calls \texttt{pushStream}, defined by
\texttt{flexc++}, to stack the current input stream and to switch to the stream
whose name is stored in \texttt{d\_nextSource}. This also ends the \texttt{include}
mini-scanner, so to return the scanner to its default scanning mode
\texttt{begin(StartCondition\_\_::INITIAL)} is called. Here is its source:
        \begin{verbatim}
#include "scanner.ih"

void Scanner::switchSource()
{
    pushStream(d_nextSource);
    begin(StartCondition__::INITIAL);
}
\end{verbatim}
    The member \texttt{pushStream}, defined by \texttt{flexc++}, handles all necessary
checks, throwing an exception if the file could not be opened or if too many
files are stacked.

The member performing the lexical scan is defined by \texttt{flexc++} in
\texttt{Scanner::lex}, and this member can be called by code to process the tokens
returned by the scanner.

\subsubsection{Using a `Scanner' object}
        \typeout{Original Yodl file: concrete/scanmain}    The program using our \texttt{Scanner} is very simple. It expects a filename
indicating where to start the scanning process.

The program first checks the number of arguments. If at least one argument was
given, then that argument is passed to \texttt{Scanner}'s constructor, together
with a second argument \texttt{"-"}, indicating that the output should go to the
standard output stream.

If the program receives more than one argument debug output, extensively
documenting the lexical scanner's actions, is written to the standard output
stream as well.

Next the \texttt{Scanner}'s \texttt{lex} member is called. If anything fails, a
\texttt{std::exception} is thrown, which is caught by \texttt{main}'s try-block's catch
clause. Here is the program's source:
        \begin{verbatim}
#include "lexer.ih"

int main(int argc, char **argv)
try
{
    if (argc == 1)
    {
        cerr << "Filename argument required\n";
        return 1;
    }

    Scanner scanner(argv[1], "-");

    scanner.setDebug(argc > 2);

    return scanner.lex();
}
catch (exception const &exc)
{
    cerr << exc.what() << '\n';
    return 1;
}
\end{verbatim}
\subsubsection{Building the program}\label{BUILDFLEX}
        \typeout{Original Yodl file: concrete/scancompile}    The final program is constructed in two steps. These steps are given for a
\index{Unix}Unix system, on which \index{flexc++}\texttt{flexc++} and the \index{GNU}GNU \textbf{C++} compiler \index{g++}\texttt{g++}
have been installed:
    \begin{itemize}
    \item  First, the lexical scanner's source is created using \texttt{flexc++}. For
this the following command can be given:
        \begin{verbatim}
    flexc++ lexer
\end{verbatim}
\item  Next, all sources are compiled and linked:
        \begin{verbatim}
    g++ -Wall *.cc
\end{verbatim}
\end{itemize}
    \texttt{Flexc++} can be downloaded from
    \index{https://fbb-git.gitlab.io/flexcpp/}
    \texttt{https://fbb-git.gitlab.io/flexcpp/}, 
        and requires the \index{bobcat}\texttt{bobcat} library, which can be downloaded from
    \texttt{http://fbb-git.gitlab.io/bobcat/}.

\subsection{Using `bisonc++' and `flexc++'}\label{BISONFLEX}
    \typeout{Original Yodl file: concrete/usingbison}Once an \index{input language}input language exceeds a certain level of complexity, a \index{parser}\emph{parser}
is often used to control the complexity of the language. In this case, a
\index{parser generator}\emph{parser generator} can be used to generate the code verifying the input's
grammatical correctness.  The lexical scanner (preferably composed into the
parser) provides chunks of the input, called \index{token}\emph{tokens}. The parser
then processes the series of tokens generated by the lexical scanner.

Starting point when developing programs that use both parsers and scanners is
the \index{grammar}grammar. The grammar defines a \emph{set of tokens} that can be returned
by the lexical scanner (called the \index{scanner}\emph{scanner} below).

Finally, auxiliary code is provided to `fill in the blanks': the \index{actions}actions
performed by the parser and by the scanner are not normally specified
literally in the grammar rules or lexical regular expressions, but
should be implemented in \emph{member functions}, called from  the parser's
rules or which are associated with the scanner's regular expressions.

In the previous section we've seen an example of a \textbf{C++} class generated by
\index{flexc++}\texttt{flexc++}. In the current section we concentrate on the parser. The parser
can be generated from a grammar specification file, processed by the program
\index{bisonc++}\texttt{bisonc++}. The grammar specification file required by \texttt{bisonc++} is
similar to the file processed by \index{bison}\texttt{bison} (or \index{bison++}\texttt{bison++}, \texttt{bisonc++}'s
predecessor, written in the early nineties by
    \index{Coetmeur, A.} \emph{Alain Coetmeur}).

In this section a program is developed converting \emph{infix expressions},
where binary operators are written between their operands, to \emph{postfix
expressions}, where operators are written behind their operands. Also, the
unary operator \texttt{-} is converted from its prefix notation to a postfix form.
The unary \texttt{+} operator is ignored as it requires no further actions. In
essence our little calculator is a micro compiler, transforming numeric
expressions into assembly-like instructions.

Our calculator recognizes a rather basic set of operators:
multiplication, addition, parentheses, and the unary minus. We'll
distinguish real numbers from integers, to illustrate a subtlety in
bison-like grammar specifications. That's all. The purpose of this section is,
after all, to illustrate the construction of a \textbf{C++} program that uses both
a parser and a lexical scanner, rather than to construct a full-fledged
calculator.

In the coming sections we'll develop the grammar specification for
\texttt{bisonc++}. Then, the regular expressions for the scanner are
specified. Following that, the final program is constructed.

\subsubsection{The `bisonc++' specification file}
        \typeout{Original Yodl file: concrete/bison}The \index{grammar specification file}grammar specification file required by \index{bisonc++}\texttt{bisonc++} is comparable to
the specification file required by \index{bison}\texttt{bison}. Differences are related to the
class nature of the resulting parser. Our calculator distinguishes real
numbers from integers, and supports a basic set of arithmetic operators.

\texttt{Bisonc++} should be used as follows:
    \begin{itemize}
    \item  As usual, a grammar is  defined. With \texttt{bisonc++} this is no
        different, and \texttt{bisonc++} grammar definitions are for all practical
        purposes identical to \texttt{bison}'s grammar definitions.
    \item  Having specified the grammar and (usually) some declarations
        \texttt{bisonc++} can generate files defining the parser class and
        the implementation of the member function \texttt{parse}.
    \item  All class members (except those that are required for the proper
        functioning of the member \texttt{parse}) must be
        separately implemented.  Of course, they should also be
        declared in the parser class's header.  At the very least the member
        \index{lex}\texttt{lex} must be implemented. This member is called by \texttt{parse} to
        obtain the next available token.  However, \texttt{bisonc++} offers a
        facility providing a standard implementation of the function
        \texttt{lex}. The member function
            \index{error}\texttt{error(char const $*$msg)}
       is given a simple default implementation that may be modified by the
        programmer. The member function \texttt{error} is called when \texttt{parse}
        detects (syntactic) errors.
    \item  The parser can now be used in a program. A very simple example would
        be:
    \begin{verbatim}
int main()
{
    Parser parser;
    return parser.parse();
}
\end{verbatim}
\end{itemize}

The \texttt{bisonc++} \index{bisonc++: grammar file} specification file has two
sections:
    \begin{itemize}
    \item  The \emph{declaration section}. In this section bison's tokens, and the
        priority rules for the operators are declared. However, \texttt{bisonc++}
        also supports several new declarations.  These new declarations are
        important and are discussed below.
    \item  The \emph{rules section}. The \index{grammatical rules}grammatical rules define the
        grammar. This section is identical to the one required by \texttt{bison},
        albeit that some members that were available in \texttt{bison} and
        \texttt{bison++} are obsolete in \texttt{bisonc++}, while other members can be
        used in a wider context.  For example, \textbf{ACCEPT} and \textbf{ABORT} can be
        called from any member called from the parser's action blocks to
        terminate the parsing process.
    \end{itemize}
 Readers familiar with \texttt{bison} may note that there is no
    \index{header section}\emph{header section} anymore. Header sections are used by bison to provide
for the necessary declarations allowing the compiler to compile the \textbf{C}
function generated by \texttt{bison}. In \textbf{C++} declarations are part of or
already used by class definitions. Therefore, a parser generator generating a
\textbf{C++} class and some of its member functions does not require a header
section anymore.

\paragraph{The declaration section}\label{BISONDEF}
        \typeout{Original Yodl file: concrete/definition}    The \index{declaration section}declaration section contains several sets of declarations, among
which definitions of all the tokens used in the grammar and the priorities and
associativities of the mathematical operators. Moreover, several new and
important specifications can be used here as well. Those relevant to our
current example and only available in \texttt{bisonc++} are discussed here. The
reader is referred to \texttt{bisonc++}'s man-page for a full description.
    \begin{itemize}
    \item  \index{%baseclass-preinclude}\textbf{\%baseclass-preinclude} \texttt{header}\ \\ 
          Use \texttt{header} as the pathname to the file pre-included in the
           parser's base-class header.  This declaration is useful in
           situations where the base class header file refers to types which
           might not yet be known. E.g., with \index{%union}\texttt{\%union} a \texttt{std::string $*$}
           field might be used. Since the class \texttt{std::string} might not yet
           be known to the compiler once it processes the base class header
           file we need a way to inform the compiler about these classes and
           types. The suggested procedure is to use a pre-include header file
           declaring the required types. By default \texttt{header} is
           surrounded by double quotes (using, e.g., \texttt{\#include "header"}).
           When the argument is surrounded by angle brackets \texttt{\#include
           $<$header$>$} is included. In the latter case, quotes might be
           required to escape interpretation by the shell (e.g., using \texttt{-H
           '$<$header$>$'}).
    \item  \index{%filenames}\textbf{\%filenames} \texttt{header} \ \\ 
           Defines the generic name of all generated files, unless overridden
            by specific names. By default the generated files use the
           class-name as the generic file name.
    \item  \index{%scanner}\textbf{\%scanner} \texttt{header}\ \\ 
           Use \texttt{header} as the pathname to the file pre-included in the
            parser's class header. This file should define a class
            \texttt{Scanner}, offering a member \texttt{int lex()} producing the next
            token from the input stream to be analyzed by the parser generated
            by \texttt{bisonc++}. When this option is used the parser's member
            \texttt{int lex()} is predefined as (assuming the default parser class
            name \texttt{Parser} is used):
            \begin{verbatim}
inline int Parser::lex()
{
    return d_scanner.lex();
}
\end{verbatim}
and an object \texttt{Scanner d\_scanner} is composed into the
            parser. The \texttt{d\_scanner} object is constructed by its
            default constructor. If another constructor is required, the
            parser class may be provided with an appropriate (overloaded)
            parser constructor after having constructed the default parser
            class header file using \texttt{bisonc++}.  By default \texttt{header} is
            surrounded by double quotes (using, e.g., \texttt{\#include
            "header"}).  When the argument is surrounded by angle brackets
            \texttt{\#include $<$header$>$} is included.
    \item  \index{%stype}\textbf{\%stype} \texttt{typename} \ \\ 
           The type of the semantic value of tokens.  The specification
            \texttt{typename} should be the name of an unstructured type (e.g.,
            \texttt{size\_t}). By default it is \texttt{int}. See \texttt{YYSTYPE} in
            \texttt{bison}.  It should not be used if a \texttt{\%union} specification is
            used.  Within the parser class, this type may be used as
            \texttt{STYPE}.
    \item  \index{%union}\textbf{\%union} \texttt{union-definition} \ \\ 
           Acts identically to the \texttt{bison} declaration.  As with \texttt{bison}
            this generates a union for the parser's semantic type.  The union
            type is named \texttt{STYPE}. If no \texttt{\%union} is declared, a simple
            stack-type may be defined using the \texttt{\%stype} declaration. If no
            \texttt{\%stype} declaration is used, the default stacktype (\texttt{int}) is
            used.
    \end{itemize}
    An example of a \texttt{\%union} declaration is:
        \begin{verbatim}
    %union
    {
        int     i;
        double  d;
    };
\end{verbatim}
In pre-C++11 code a \index{union}union cannot contain objects as its fields, as
constructors cannot be called when a union is created.  This means that
    \index{string: as union member} a \texttt{string} cannot be a member of the
union. A \texttt{string $*$}, however, \emph{is} a possible union member.  It might also
be possible to use \emph{unrestricted unions} (cf. section \ref{UNIONS}), having
class type objects as fields.

As an aside: the scanner does not have to know about such a union. It
can simply pass its scanned text to the parser through its \index{matched}\texttt{matched} member
function. For example using a statement like
        \begin{verbatim}
    $$.i = A2x(d_scanner.matched());
\end{verbatim}
matched text is converted to a value of an appropriate type.

Tokens and non-terminals can be associated with union fields. This is
strongly advised, as it prevents type mismatches, since the compiler may then
check for type correctness. At the same time, the bison specific
variables \texttt{\$\$}, \texttt{\$1}, \texttt{\$2}, etc. may be used, rather than the full field
specification (like \texttt{\$\$.i}).  A non-terminal or a token may be associated
with a union field using the
    \texttt{$<$fieldname$>$} specification. E.g.,
        \begin{verbatim}
    %token <i> INT          // token association (deprecated, see below)
           <d> DOUBLE
    %type  <i> intExpr      // non-terminal association
\end{verbatim}
In the example developed here, both the tokens and the non-terminals can
be associated with a union field. However, as noted before, the scanner does
not have to know about all this. In our opinion, it is cleaner to let the
scanner do just one thing: scan texts. The \emph{parser}, knowing what the input
is all about, may then convert strings like \texttt{"123"} to an integer
value. Consequently, the association of a union field and a token is
discouraged. Below, while describing the grammar's rules, this is further
illustrated.

In the \texttt{\%union} discussion the \index{%token}\texttt{\%token} and \index{%type}\texttt{\%type} specifications
should be noted. They are used to specify the tokens (terminal symbols) that
can be returned by the scanner, and to specify the return types of
non-terminals.  Apart from \texttt{\%token} the token declarators \index{%left}\texttt{\%left},
\index{%right}\texttt{\%right}, and \index{%nonassoc}\texttt{\%nonassoc} can be used to specify the associativity of
operators. The tokens mentioned at these indicators are interpreted as tokens
indicating operators, associating in the indicated direction. The precedence
of operators is defined by their order: the first specification has the lowest
priority. To overrule a certain precedence in a certain context \index{%prec}\texttt{\%prec} can
be used. As all this is standard \texttt{bisonc++} practice, it isn't further
elaborated here. The documentation provided with \texttt{bisonc++}'s distribution
should be consulted for further reference.

Here is the specification of the calculator's declaration section:
        \begin{verbatim}
%filenames parser
%scanner ../scanner/scanner.h

%union {
    int i;
    double d;
};

%token  INT DOUBLE

%type   <i> intExpr
%type   <d> doubleExpr

%left   '+'
%left   '*'
%right  UnaryMinus
\end{verbatim}
    In the declaration section \texttt{\%type} specifiers are used, associating the
\texttt{intExpr} rule's value (see the next section) to the \texttt{i}-field of the
semantic-value union, and associating \texttt{doubleExpr}'s value to the
\texttt{d}-field. This approach, admittedly, is rather complex, as expression rules
must be included for each of the supported union types. Alternatives are
definitely possible, and involve the use of \emph{polymorphic semantic
values}, covered in detail in the 
    \texttt{Bisonc++ user guide}\footnote{http://fbb-git.gitlab.io/bisoncpp/manual/bisonc++.html}.

\paragraph{The grammar rules}
        \typeout{Original Yodl file: concrete/rules}    The rules and actions of the grammar are specified as usual. The grammar
for our little calculator is given below. There are quite a few rules, but
they illustrate various features offered by \texttt{bisonc++}. In particular, note
that no action block requires more than a single line of code. This keeps the
grammar simple, and therefore enhances its readability and
understandability. Even the rule defining the parser's proper termination (the
empty line in the \texttt{line} rule) uses a single member function called
\texttt{done}. The implementation of that function is simple, but it is worth while
noting that it calls \textbf{Parser::ACCEPT}, showing that \textbf{ACCEPT} can be called
indirectly from a production rule's action block. Here are the grammar's
production rules:
        \begin{verbatim}
    lines:
        lines
        line
    |
        line
    ;

    line:
        intExpr
        '\n'
        {
            display($1);
        }
    |
        doubleExpr
        '\n'
        {
            display($1);
        }
    |
        '\n'
        {
            done();
        }
    |
        error
        '\n'
        {
            reset();
        }
    ;

    intExpr:
        intExpr '*' intExpr
        {
            $$ = exec('*', $1, $3);
        }
    |
        intExpr '+' intExpr
        {
            $$ = exec('+', $1, $3);
        }
    |
        '(' intExpr ')'
        {

            $$ = $2;
        }
    |
        '-' intExpr         %prec UnaryMinus
        {
            $$ = neg($2);
        }
    |
        INT
        {
            $$ = convert<int>();
        }
    ;

    doubleExpr:
        doubleExpr '*' doubleExpr
        {
            $$ = exec('*', $1, $3);
        }
    |
        doubleExpr '*' intExpr
        {
            $$ = exec('*', $1, d($3));
        }
    |
        intExpr '*' doubleExpr
        {
            $$ = exec('*', d($1), $3);
        }
    |
        doubleExpr '+' doubleExpr
        {
            $$ = exec('+', $1, $3);
        }
    |
        doubleExpr '+' intExpr
        {
            $$ = exec('+', $1, d($3));
        }
    |
        intExpr '+' doubleExpr
        {
            $$ = exec('+', d($1), $3);
        }
    |
        '(' doubleExpr ')'
        {
            $$ = $2;
        }
    |
        '-' doubleExpr         %prec UnaryMinus
        {

            $$ = neg($2);
        }
    |
        DOUBLE
        {
            $$ = convert<double>();
        }
    ;
\end{verbatim}
    This grammar is used to implement a simple calculator in which integer and
real values can be negated, added, and multiplied and in which standard
priority rules can be overruled by parentheses. The grammar shows the use of
typed nonterminal symbols: \texttt{doubleExpr} is linked to real (double) values,
\texttt{intExpr} is linked to integer values. Precedence and type association is
defined in the parser's definition section.

\paragraph{The Parser's header file}
        \typeout{Original Yodl file: concrete/parserh}Several class members called from the grammar are defined as member
templates. \texttt{Bisonc++} generates multiple files, among which the file
defining the parser's class. Functions called from the production rule's
action blocks are usually member functions of the parser. These member
functions must be declared and defined. Once \texttt{bisonc++} has generated the
header file defining the parser's class, that header file isn't automatically
rewritten, allowing the programmer to add new members to the parser class
whenever required. Here is `\texttt{parser.h}' as used in our little calculator:
        \begin{verbatim}
#ifndef Parser_h_included
#define Parser_h_included

#include <iostream>
#include <sstream>
#include <bobcat/a2x>

#include "parserbase.h"
#include "../scanner/scanner.h"

#undef Parser
class Parser: public ParserBase
{
    std::ostringstream d_rpn;
    // $insert scannerobject
    Scanner d_scanner;

    public:
        int parse();

    private:
        template <typename Type>
        Type exec(char c, Type left, Type right);

        template <typename Type>
        Type neg(Type op);

        template <typename Type>
        Type convert();

        void display(int x);
        void display(double x);
        void done() const;
        void reset();
        void error(char const *msg);
        int lex();
        void print();

        static double d(int i);

    // support functions for parse():

        void executeAction(int d_ruleNr);
        void errorRecovery();
        int lookup(bool recovery);
        void nextToken();
        void print__();
};

inline double Parser::d(int i)
{
    return i;
}

template <typename Type>
Type Parser::exec(char c, Type left, Type right)
{
    d_rpn << " " << c << " ";
    return c == '*' ? left * right : left + right;
}

template <typename Type>
Type Parser::neg(Type op)
{
    d_rpn << " n ";
    return -op;
}

template <typename Type>
Type Parser::convert()
{
    Type ret = FBB::A2x(d_scanner.matched());
    d_rpn << " " << ret << " ";
    return ret;
}

inline void Parser::error(char const *msg)
{
    std::cerr << msg << '\n';
}

inline int Parser::lex()
{
    return d_scanner.lex();
}

inline void Parser::print()
{}

#endif
\end{verbatim}
\subsubsection{The `flexc++' specification file}
        \typeout{Original Yodl file: concrete/bisonflexspec}    The flex-specification file used by the calculator is simple: blanks are
ignored, single characters are returned, and numeric values are returned as
either \texttt{Parser::INT} or \texttt{Parser::DOUBLE} tokens.

The \texttt{flexc++} directive \texttt{\%interactive} is provided since the
calculator is a program actively interacting with its human user.

Here is the complete \texttt{flexc++} specification file:
        \begin{verbatim}
%interactive
%filenames scanner

%%

[ \t]                       // ignored

[0-9]+                      return Parser::INT;

"."[0-9]+                   |
[0-9]+"."[0-9]*             return Parser::DOUBLE;

.|\n                        return matched()[0];
\end{verbatim}
\subsubsection{Building the program}
        \typeout{Original Yodl file: concrete/codegeneration}The calculator is built using \texttt{bisonc++} and \texttt{flexc++}.  Here is the
implementation of the calculator's \texttt{main} function:
        \begin{verbatim}
#include "parser/parser.h"

using namespace std;

int main()
{
    Parser parser;

    cout << "Enter (nested) expressions containing ints, doubles, *, + and "
            "unary -\n"
            "operators. Enter an empty line to stop.\n";

    return parser.parse();
}
\end{verbatim}
The parser's files \texttt{parse.cc} and \texttt{parserbase.h} are generated by the
command:
        \begin{verbatim}
    bisonc++ grammar
\end{verbatim}
The file \texttt{parser.h} is created only once, to allow the developer to add
members to the \texttt{Parser} class occe the need for them arises.

The program \index{flexc++}\texttt{flexc++} is used to create a lexical scanner:
        \begin{verbatim}
    flexc++ lexer
\end{verbatim}
On \index{Unix}Unix systems a command like
        \begin{verbatim}
    g++ -Wall -o calc *.cc -lbobcat -s
\end{verbatim}
can be used to compile and link the source of the main program and the
sources produced by the scanner and parser generators. The example uses the
\texttt{A2x} class, which is part of the \index{bobcat}\texttt{bobcat} library (cf. section
\ref{BUILDFLEX}) (the bobcat library is available on systems offering either
\texttt{bisonc++} or \texttt{flexc++}). \texttt{Bisonc++} can be downloaded from

\index{http://fbb-git.gitlab.io/bisoncpp/}
    \texttt{http://fbb-git.gitlab.io/bisoncpp/}.

\cleardoublepage\phantomsection\printindex
\end{document}
