C++ S: The Guide S

c-s--guide-2nd

C-s-The--Guide

C%2B%2B%20s_%20The%20%20Guide%2C%20David%20Vandevoorde%2C%20Nicolai%20M.%20Josuttis%2C%20Douglas%20Gregor%2C%20(

User Manual:

Open the PDF directly: View PDF .
Page Count: 2606

Download
Open PDF In Browser	View PDF

C++ Templates
The Complete Guide
Second Edition

David Vandevoorde
Nicolai M. Josuttis
Douglas Gregor

Boston • Columbus • Indianapolis • New York • San Francisco • Amsterdam • Cape
Town Dubai • London • Madrid • Milan • Munich • Paris • Montreal • Toronto •
Delhi • Mexico City São Paulo • Sydney • Hong Kong • Seoul • Singapore • Taipei •
Tokyo

Many of the designations used by manufacturers and sellers to distinguish their
products are claimed as trademarks. Where those designations appear in this book,
and the publisher was aware of a trademark claim, the designations have been
printed with initial capital letters or in all capitals.
The authors and publisher have taken care in the preparation of this book, but make
no expressed or implied warranty of any kind and assume no responsibility for errors
or omissions. No liability is assumed for incidental or consequential damages in
connection with or arising out of the use of the information or programs contained
herein.
For information about buying this title in bulk quantities, or for special sales
opportunities (which may include electronic versions; custom cover designs; and
content particular to your business, training goals, marketing focus, or branding
interests), please contact our corporate sales department at
corpsales@pearsoned.com or (800) 382-3419.
For government sales inquiries, please contact
governmentsales@pearsoned.com.
For questions about sales outside the U.S., please contact intlcs@pearson.com.
Visit us on the Web: informit.com/aw
Library of Congress Catalog Number: 2017946531
Copyright © 2018 Pearson Education, Inc.
This book was typeset by Nicolai M. Josuttis using the LATEX document processing
system. All rights reserved. Printed in the United States of America. This publication
is protected by copyright, and permission must be obtained from the publisher prior
to any prohibited reproduction, storage in a retrieval system, or transmission in any
form or by any means, electronic, mechanical, photocopying, recording, or likewise.
For information regarding permissions, request forms and the appropriate contacts
within the Pearson Education Global Rights & Permissions Department, please visit
www.pearsoned.com/permissions/.
ISBN-13: 978-0-321-71412-1
ISBN-10: 0-321-71412-1
1 17

To Alessandra & Cassandra
—David
To those who care for people and mankind
—Nico
To Amy, Tessa & Molly
—Doug

Contents
Preface
Acknowledgments for the Second Edition
Acknowledgments for the First Edition
About This Book
What You Should Know Before Reading This Book
Overall Structure of the Book
How to Read This Book
Some Remarks About Programming Style
The C++11, C++14, and C++17 Standards
Example Code and Additional Information
Feedback
Part I: The Basics
1 Function Templates
1.1 A First Look at Function Templates
1.1.1 Defining the Template
1.1.2 Using the Template
1.1.3 Two-Phase Translation
1.2 Template Argument Deduction
1.3 Multiple Template Parameters
1.3.1 Template Parameters for Return Types
1.3.2 Deducing the Return Type
1.3.3 Return Type as Common Type
1.4 Default Template Arguments
1.5 Overloading Function Templates

1.6 But, Shouldn’t We …?
1.6.1 Pass by Value or by Reference?
1.6.2 Why Not inline?
1.6.3 Why Not constexpr?
1.7 Summary
2 Class Templates
2.1 Implementation of Class Template Stack
2.1.1 Declaration of Class Templates
2.1.2 Implementation of Member Functions
2.2 Use of Class Template Stack
2.3 Partial Usage of Class Templates
2.3.1 Concepts
2.4 Friends
2.5 Specializations of Class Templates
2.6 Partial Specialization
2.7 Default Class Template Arguments
2.8 Type Aliases
2.9 Class Template Argument Deduction
2.10 Templatized Aggregates
2.11 Summary
3 Nontype Template Parameters
3.1 Nontype Class Template Parameters
3.2 Nontype Function Template Parameters
3.3 Restrictions for Nontype Template Parameters
3.4 Template Parameter Type auto
3.5 Summary
4 Variadic Templates
4.1 Variadic Templates
4.1.1 Variadic Templates by Example
4.1.2 Overloading Variadic and Nonvariadic Templates
4.1.3 Operator sizeof…
4.2 Fold Expressions
4.3 Application of Variadic Templates
4.4 Variadic Class Templates and Variadic Expressions

4.4.1 Variadic Expressions
4.4.2 Variadic Indices
4.4.3 Variadic Class Templates
4.4.4 Variadic Deduction Guides
4.4.5 Variadic Base Classes and using
4.5 Summary
5 Tricky Basics
5.1 Keyword typename
5.2 Zero Initialization
5.3 Using this->
5.4 Templates for Raw Arrays and String Literals
5.5 Member Templates
5.5.1 The .template Construct
5.5.2 Generic Lambdas and Member Templates
5.6 Variable Templates
5.7 Template Template Parameters
5.8 Summary
6 Move Semantics and enable_if<>
6.1 Perfect Forwarding
6.2 Special Member Function Templates
6.3 Disable Templates with enable_if<>
6.4 Using enable_if<>
6.5 Using Concepts to Simplify enable_if<> Expressions
6.6 Summary
7 By Value or by Reference?
7.1 Passing by Value
7.2 Passing by Reference
7.2.1 Passing by Constant Reference
7.2.2 Passing by Nonconstant Reference
7.2.3 Passing by Forwarding Reference
7.3 Using std::ref() and std::cref()
7.4 Dealing with String Literals and Raw Arrays
7.4.1 Special Implementations for String Literals and Raw Arrays
7.5 Dealing with Return Values

7.6 Recommended Template Parameter Declarations
7.7 Summary
8 Compile-Time Programming
8.1 Template Metaprogramming
8.2 Computing with constexpr
8.3 Execution Path Selection with Partial Specialization
8.4 SFINAE (Substitution Failure Is Not An Error)
8.4.1 Expression SFINAE with decltype
8.5 Compile-Time if
8.6 Summary
9 Using Templates in Practice
9.1 The Inclusion Model
9.1.1 Linker Errors
9.1.2 Templates in Header Files
9.2 Templates and inline
9.3 Precompiled Headers
9.4 Decoding the Error Novel
9.5 Afternotes
9.6 Summary
10 Basic Template Terminology
10.1 “Class Template” or “Template Class”?
10.2 Substitution, Instantiation, and Specialization
10.3 Declarations versus Definitions
10.3.1 Complete versus Incomplete Types
10.4 The One-Definition Rule
10.5 Template Arguments versus Template Parameters
10.6 Summary
11 Generic Libraries
11.1 Callables
11.1.1 Supporting Function Objects
11.1.2 Dealing with Member Functions and Additional Arguments
11.1.3 Wrapping Function Calls
11.2 Other Utilities to Implement Generic Libraries

11.3
11.4
11.5
11.6
11.7

11.2.1 Type Traits
11.2.2 std::addressof()
11.2.3 std::declval()
Perfect Forwarding Temporaries
References as Template Parameters
Defer Evaluations
Things to Consider When Writing Generic Libraries
Summary

Part II: Templates in Depth
12 Fundamentals in Depth
12.1 Parameterized Declarations
12.1.1 Virtual Member Functions
12.1.2 Linkage of Templates
12.1.3 Primary Templates
12.2 Template Parameters
12.2.1 Type Parameters
12.2.2 Nontype Parameters
12.2.3 Template Template Parameters
12.2.4 Template Parameter Packs
12.2.5 Default Template Arguments
12.3 Template Arguments
12.3.1 Function Template Arguments
12.3.2 Type Arguments
12.3.3 Nontype Arguments
12.3.4 Template Template Arguments
12.3.5 Equivalence
12.4 Variadic Templates
12.4.1 Pack Expansions
12.4.2 Where Can Pack Expansions Occur?
12.4.3 Function Parameter Packs
12.4.4 Multiple and Nested Pack Expansions
12.4.5 Zero-Length Pack Expansions
12.4.6 Fold Expressions
12.5 Friends

12.5.1 Friend Classes of Class Templates
12.5.2 Friend Functions of Class Templates
12.5.3 Friend Templates
12.6 Afternotes
13 Names in Templates
13.1 Name Taxonomy
13.2 Looking Up Names
13.2.1 Argument-Dependent Lookup
13.2.2 Argument-Dependent Lookup of Friend Declarations
13.2.3 Injected Class Names
13.2.4 Current Instantiations
13.3 Parsing Templates
13.3.1 Context Sensitivity in Nontemplates
13.3.2 Dependent Names of Types
13.3.3 Dependent Names of Templates
13.3.4 Dependent Names in Using Declarations
13.3.5 ADL and Explicit Template Arguments
13.3.6 Dependent Expressions
13.3.7 Compiler Errors
13.4 Inheritance and Class Templates
13.4.1 Nondependent Base Classes
13.4.2 Dependent Base Classes
13.5 Afternotes
14 Instantiation
14.1 On-Demand Instantiation
14.2 Lazy Instantiation
14.2.1 Partial and Full Instantiation
14.2.2 Instantiated Components
14.3 The C++ Instantiation Model
14.3.1 Two-Phase Lookup
14.3.2 Points of Instantiation
14.3.3 The Inclusion Model
14.4 Implementation Schemes
14.4.1 Greedy Instantiation
14.4.2 Queried Instantiation

14.5

14.6
14.7
14.8

14.4.3 Iterated Instantiation
Explicit Instantiation
14.5.1 Manual Instantiation
14.5.2 Explicit Instantiation Declarations
Compile-Time if Statements
In the Standard Library
Afternotes

15 Template Argument Deduction
15.1 The Deduction Process
15.2 Deduced Contexts
15.3 Special Deduction Situations
15.4 Initializer Lists
15.5 Parameter Packs
15.5.1 Literal Operator Templates
15.6 Rvalue References
15.6.1 Reference Collapsing Rules
15.6.2 Forwarding References
15.6.3 Perfect Forwarding
15.6.4 Deduction Surprises
15.7 SFINAE (Substitution Failure Is Not An Error)
15.7.1 Immediate Context
15.8 Limitations of Deduction
15.8.1 Allowable Argument Conversions
15.8.2 Class Template Arguments
15.8.3 Default Call Arguments
15.8.4 Exception Specifications
15.9 Explicit Function Template Arguments
15.10 Deduction from Initializers and Expressions
15.10.1 The auto Type Specifier
15.10.2 Expressing the Type of an Expression with decltype
15.10.3 decltype(auto)
15.10.4 Special Situations for auto Deduction
15.10.5 Structured Bindings
15.10.6 Generic Lambdas
15.11 Alias Templates

15.12 Class Template Argument Deduction
15.12.1 Deduction Guides
15.12.2 Implicit Deduction Guides
15.12.3 Other Subtleties
15.13 Afternotes
16 Specialization and Overloading
16.1 When “Generic Code” Doesn’t Quite Cut It
16.1.1 Transparent Customization
16.1.2 Semantic Transparency
16.2 Overloading Function Templates
16.2.1 Signatures
16.2.2 Partial Ordering of Overloaded Function Templates
16.2.3 Formal Ordering Rules
16.2.4 Templates and Nontemplates
16.2.5 Variadic Function Templates
16.3 Explicit Specialization
16.3.1 Full Class Template Specialization
16.3.2 Full Function Template Specialization
16.3.3 Full Variable Template Specialization
16.3.4 Full Member Specialization
16.4 Partial Class Template Specialization
16.5 Partial Variable Template Specialization
16.6 Afternotes
17 Future Directions
17.1 Relaxed typename Rules
17.2 Generalized Nontype Template Parameters
17.3 Partial Specialization of Function Templates
17.4 Named Template Arguments
17.5 Overloaded Class Templates
17.6 Deduction for Nonfinal Pack Expansions
17.7 Regularization of void
17.8 Type Checking for Templates
17.9 Reflective Metaprogramming
17.10 Pack Facilities
17.11 Modules

Part III: Templates and Design
18 The Polymorphic Power of Templates
18.1 Dynamic Polymorphism
18.2 Static Polymorphism
18.3 Dynamic versus Static Polymorphism
18.4 Using Concepts
18.5 New Forms of Design Patterns
18.6 Generic Programming
18.7 Afternotes
19 Implementing Traits
19.1 An Example: Accumulating a Sequence
19.1.1 Fixed Traits
19.1.2 Value Traits
19.1.3 Parameterized Traits
19.2 Traits versus Policies and Policy Classes
19.2.1 Traits and Policies: What’s the Difference?
19.2.2 Member Templates versus Template Template Parameters
19.2.3 Combining Multiple Policies and/or Traits
19.2.4 Accumulation with General Iterators
19.3 Type Functions
19.3.1 Element Types
19.3.2 Transformation Traits
19.3.3 Predicate Traits
19.3.4 Result Type Traits
19.4 SFINAE-Based Traits
19.4.1 SFINAE Out Function Overloads
19.4.2 SFINAE Out Partial Specializations
19.4.3 Using Generic Lambdas for SFINAE
19.4.4 SFINAE-Friendly Traits
19.5 IsConvertibleT
19.6 Detecting Members
19.6.1 Detecting Member Types
19.6.2 Detecting Arbitrary Member Types
19.6.3 Detecting Nontype Members
19.6.4 Using Generic Lambdas to Detect Members

19.7 Other Traits Techniques
19.7.1 If-Then-Else
19.7.2 Detecting Nonthrowing Operations
19.7.3 Traits Convenience
19.8 Type Classification
19.8.1 Determining Fundamental Types
19.8.2 Determining Compound Types
19.8.3 Identifying Function Types
19.8.4 Determining Class Types
19.8.5 Determining Enumeration Types
19.9 Policy Traits
19.9.1 Read-Only Parameter Types
19.10 In the Standard Library
19.11 Afternotes
20 Overloading on Type Properties
20.1 Algorithm Specialization
20.2 Tag Dispatching
20.3 Enabling/Disabling Function Templates
20.3.1 Providing Multiple Specializations
20.3.2 Where Does the EnableIf Go?
20.3.3 Compile-Time if
20.3.4 Concepts
20.4 Class Specialization
20.4.1 Enabling/Disabling Class Templates
20.4.2 Tag Dispatching for Class Templates
20.5 Instantiation-Safe Templates
20.6 In the Standard Library
20.7 Afternotes
21 Templates and Inheritance
21.1 The Empty Base Class Optimization (EBCO)
21.1.1 Layout Principles
21.1.2 Members as Base Classes
21.2 The Curiously Recurring Template Pattern (CRTP)
21.2.1 The Barton-Nackman Trick
21.2.2 Operator Implementations

21.2.3 Facades
21.3 Mixins
21.3.1 Curious Mixins
21.3.2 Parameterized Virtuality
21.4 Named Template Arguments
21.5 Afternotes
22 Bridging Static and Dynamic Polymorphism
22.1 Function Objects, Pointers, and std::function<>
22.2 Generalized Function Pointers
22.3 Bridge Interface
22.4 Type Erasure
22.5 Optional Bridging
22.6 Performance Considerations
22.7 Afternotes
23 Metaprogramming
23.1 The State of Modern C++ Metaprogramming
23.1.1 Value Metaprogramming
23.1.2 Type Metaprogramming
23.1.3 Hybrid Metaprogramming
23.1.4 Hybrid Metaprogramming for Unit Types
23.2 The Dimensions of Reflective Metaprogramming
23.3 The Cost of Recursive Instantiation
23.3.1 Tracking All Instantiations
23.4 Computational Completeness
23.5 Recursive Instantiation versus Recursive Template Arguments
23.6 Enumeration Values versus Static Constants
23.7 Afternotes
24 Typelists
24.1 Anatomy of a Typelist
24.2 Typelist Algorithms
24.2.1 Indexing
24.2.2 Finding the Best Match
24.2.3 Appending to a Typelist
24.2.4 Reversing a Typelist

24.3
24.4
24.5
24.6

24.2.5 Transforming a Typelist
24.2.6 Accumulating Typelists
24.2.7 Insertion Sort
Nontype Typelists
24.3.1 Deducible Nontype Parameters
Optimizing Algorithms with Pack Expansions
Cons-style Typelists
Afternotes

25 Tuples
25.1 Basic Tuple Design
25.1.1 Storage
25.1.2 Construction
25.2 Basic Tuple Operations
25.2.1 Comparison
25.2.2 Output
25.3 Tuple Algorithms
25.3.1 Tuples as Typelists
25.3.2 Adding to and Removing from a Tuple
25.3.3 Reversing a Tuple
25.3.4 Index Lists
25.3.5 Reversal with Index Lists
25.3.6 Shuffle and Select
25.4 Expanding Tuples
25.5 Optimizing Tuple
25.5.1 Tuples and the EBCO
25.5.2 Constant-time get()
25.6 Tuple Subscript
25.7 Afternotes
26 Discriminated Unions
26.1 Storage
26.2 Design
26.3 Value Query and Extraction
26.4 Element Initialization, Assignment and Destruction
26.4.1 Initialization
26.4.2 Destruction

26.4.3 Assignment
26.5 Visitors
26.5.1 Visit Result Type
26.5.2 Common Result Type
26.6 Variant Initialization and Assignment
26.7 Afternotes
27 Expression Templates
27.1 Temporaries and Split Loops
27.2 Encoding Expressions in Template Arguments
27.2.1 Operands of the Expression Templates
27.2.2 The Array Type
27.2.3 The Operators
27.2.4 Review
27.2.5 Expression Templates Assignments
27.3 Performance and Limitations of Expression Templates
27.4 Afternotes
28 Debugging Templates
28.1 Shallow Instantiation
28.2 Static Assertions
28.3 Archetypes
28.4 Tracers
28.5 Oracles
28.6 Afternotes
Appendixes
A The One-Definition Rule
A.1 Translation Units
A.2 Declarations and Definitions
A.3 The One-Definition Rule in Detail
A.3.1 One-per-Program Constraints
A.3.2 One-per-Translation Unit Constraints
A.3.3 Cross-Translation Unit Equivalence Constraints
B Value Categories

B.1 Traditional Lvalues and Rvalues
B.1.1 Lvalue-to-Rvalue Conversions
B.2 Value Categories Since C++11
B.2.1 Temporary Materialization
B.3 Checking Value Categories with decltype
B.4 Reference Types
C Overload Resolution
C.1 When Does Overload Resolution Kick In?
C.2 Simplified Overload Resolution
C.2.1 The Implied Argument for Member Functions
C.2.2 Refining the Perfect Match
C.3 Overloading Details
C.3.1 Prefer Nontemplates or More Specialized Templates
C.3.2 Conversion Sequences
C.3.3 Pointer Conversions
C.3.4 Initializer Lists
C.3.5 Functors and Surrogate Functions
C.3.6 Other Overloading Contexts
D Standard Type Utilities
D.1 Using Type Traits
D.1.1 std::integral_constant and std::bool_constant
D.1.2 Things You Should Know When Using Traits
D.2 Primary and Composite Type Categories
D.2.1 Testing for the Primary Type Category
D.2.2 Test for Composite Type Categories
D.3 Type Properties and Operations
D.3.1 Other Type Properties
D.3.2 Test for Specific Operations
D.3.3 Relationships Between Types
D.4 Type Construction
D.5 Other Traits
D.6 Combining Type Traits
D.7 Other Utilities
E Concepts

E.1 Using Concepts
E.2 Defining Concepts
E.3 Overloading on Constraints
E.3.1 Constraint Subsumption
E.3.2 Constraints and Tag Dispatching
E.4 Concept Tips
E.4.1 Testing Concepts
E.4.2 Concept Granularity
E.4.3 Binary Compatibility
Bibliography
Forums
Books and Web Sites
Glossary
Index

Preface
The notion of templates in C++ is over 30 years old. C++ templates were already
documented in 1990 in “The Annotated C++ Reference Manual” (ARM; see
[EllisStroustrupARM]), and they had been described before then in more specialized
publications. However, well over a decade later, we found a dearth of literature that
concentrates on the fundamental concepts and advanced techniques of this
fascinating, complex, and powerful C++ feature. With the first edition of this book,
we wanted to address this issue and decided to write the book about templates (with
perhaps a slight lack of humility).
Much has changed in C++ since that first edition was published in late 2002. New
iterations of the C++ standard have added new features, and continued innovation in
the C++ community has uncovered new template-based programming techniques.
The second edition of this book therefore retains the same goals as the first edition,
but for “Modern C++.”
We approached the task of writing this book with different backgrounds and with
different intentions. David (aka “Daveed”), an experienced compiler implementer
and active participant of the C++ Standard Committee working groups that evolve
the core language, was interested in a precise and detailed description of all the
power (and problems) of templates. Nico, an “ordinary” application programmer and
member of the C++ Standard Committee Library Working Group, was interested in
understanding all the techniques of templates in a way that he could use and benefit
from them. Doug, a template library developer turned compiler implementer and
language designer, was interested in collecting, categorizing, and evaluating the
myriad techniques used to build template libraries. In addition, we all wanted to
share this knowledge with you, the reader, and the whole community to help to avoid
further misunderstanding, confusion, or apprehension.
As a consequence, you will see both conceptual introductions with day-to-day
examples and detailed descriptions of the exact behavior of templates. Starting from
the basic principles of templates and working up to the “art of template
programming,” you will discover (or rediscover) techniques such as static
polymorphism, type traits, metaprogramming, and expression templates. You will
also gain a deeper understanding of the C++ standard library, in which almost all
code involves templates.

We learned a lot and we had much fun while writing this book. We hope you will
have the same experience while reading it. Enjoy!

Acknowledgments for the Second Edition
Writing a book is hard. Maintaining a book is even harder. It took us more than five
years—spread over the past decade—to come up with this second edition, and it
couldn’t have been done without the support and patience of a lot of people.
First, we’d like to thank everyone in the C++ community and on the C++
standardization committee. In addition to all the work to add new language and
library features, they spent many, many hours explaining and discussing their work
with us, and they did so with patience and enthusiasm.
Part of this community also includes the programmers who gave feedback for
errors and possible improvement for the first edition over the past 15 years. There
are simply too many to list them all, but you know who you are and we’re truly
grateful to you for taking the time to write up your thoughts and observations. Please
accept our apologies if our answers were sometimes less than prompt.
We’d also like to thank everyone who reviewed drafts of this book and provided
us with valuable feedback and clarifications. These reviews brought the book to a
significantly higher level of quality, and it again proved that good things need the
input of many “wise guys.” For this reason, huge thanks to Steve Dewhurst, Howard
Hinnant, Mikael Kilpel¨ainen, Dietmar Kühl, Daniel Krügler, Nevin Lieber, Andreas
Neiser, Eric Niebler, Richard Smith, Andrew Sutton, Hubert Tong, and Ville
Voutilainen.
Of course, thanks to all the people who supported us from AddisonWesley/Pearson. These days, you can no longer take professional support for book
authors for granted. But they were patient, nagged us when appropriate, and were of
great help when knowledge and professionalism were necessary. So, many thanks to
Peter Gordon, Kim Boedigheimer, Greg Doench, Julie Nahil, Dana Wilson, and
Carol Lallier.
A special thanks goes to the LaTeX community for a great text system and to
Frank Mittelbach for solving our LATEX issues (it was almost always our fault).

David’s Acknowledgments for the Second Edition
This second edition was a long time in the waiting, and as we put the finishing

touches to it, I am grateful for the people in my life who made it possible despite
many obligations vying for attention. First, I’m indebted to my wife (Karina) and
daughters (Alessandra and Cassandra), for agreeing to let me take significant time
out of the “family schedule” to complete this edition, particularly in the last year of
work. My parents have always shown interest in my goals, and whenever I visit
them, they do not forget this particular project.
Clearly, this is a technical book, and its contents reflect knowledge and experience
about a programming topic. However, that is not enough to pull off completing this
kind of work. I’m therefore extremely grateful to Nico for having taken upon himself
the “management” and “production” aspects of this edition (in addition to all of his
technical contributions). If this book is useful to you and you run into Nico some
day, be sure to tell him thanks for keeping us all going. I’m also thankful to Doug for
having agreed to come on board several years ago and to keep going even as
demands on his own schedule made for tough going.
Many programmers in our C++ community have shared nuggets of insight over
the years, and I am grateful to all of them. However, I owe special thanks to Richard
Smith, who has been efficiently answering my e-mails with arcane technical issues
for years now. In the same vein, thanks to my colleagues John Spicer, Mike Miller,
and Mike Herrick, for sharing their knowledge and creating an encouraging work
environment that allows us to learn ever more.

Nico’s Acknowledgments for the Second Edition
First, I want to thank the two hard-core experts, David and Doug, because, as an
application programmer and library expert, I asked so many silly questions and
learned so much. I now feel like becoming a core expert (only until the next issue, of
course). It was fun, guys.
All my other thanks go to Jutta Eckstein. Jutta has the wonderful ability to force
and support people in their ideals, ideas, and goals. While most people experience
this only occasionally when meeting her or working with her in our IT industry, I
have the honor to benefit from her in my day-to-day life. After all these years, I still
hope this will last forever.

Doug’s Acknowledgments for the Second Edition
My heartfelt thanks go to my wonderful and supportive wife, Amy, and our two little
girls, Molly and Tessa. Their love and companionship bring me daily joy and the
confidence to tackle the greatest challenges in life and work. I’d also like to thank

my parents, who instilled in me a great love of learning and encouraged me
throughout these years.
It was a pleasure to work with both David and Nico, who are so different in
personality yet complement each other so well. David brings a great clarity to
technical writing, honing in on descriptions that are precise and illuminating. Nico,
beyond his exceptional organizational skills that kept two coauthors from wandering
off into the weeds, brings a unique ability to take apart a complex technical
discussion and make it simpler, more accessible, and far, far clearer.

Acknowledgments for the First Edition
This book presents ideas, concepts, solutions, and examples from many sources.
We’d like to thank all the people and companies who helped and supported us during
the past few years.
First, we’d like to thank all the reviewers and everyone else who gave us their
opinion on early manuscripts. These people endow the book with a quality it would
never have had without their input. The reviewers for this book were Kyle Blaney,
Thomas Gschwind, Dennis Mancl, Patrick Mc Killen, and Jan Christiaan van
Winkel. Special thanks to Dietmar Kühl, who meticulously reviewed and edited the
whole book. His feedback was an incredible contribution to the quality of this book.
We’d also like to thank all the people and companies who gave us the opportunity
to test our examples on different platforms with different compilers. Many thanks to
the Edison Design Group for their great compiler and their support. It was a big help
during the standardization process and the writing of this book. Many thanks also go
to all the developers of the free GNU and egcs compilers (Jason Merrill was
especially responsive) and to Microsoft for an evaluation version of Visual C++
(Jonathan Caves, Herb Sutter, and Jason Shirk were our contacts there).
Much of the existing “C++ wisdom” was collectively created by the online C++
community. Most of it comes from the moderated Usenet groups
comp.lang.c++.moderated and comp.std.c++. We are therefore
especially indebted to the active moderators of those groups, who keep the
discussions useful and constructive. We also much appreciate all those who over the
years have taken the time to describe and explain their ideas for us all to share.
The Addison-Wesley team did another great job. We are most indebted to Debbie
Lafferty (our editor) for her gentle prodding, good advice, and relentless hard work
in support of this book. Thanks also go to Tyrrell Albaugh, Bunny Ames, Melanie
Buck, Jacquelyn Doucette, Chanda Leary-Coutu, Catherine Ohala, and Marty
Rabinowitz. We’re grateful as well to Marina Lang, who first sponsored this book
within Addison-Wesley. Susan Winer contributed an early round of editing that
helped shape our later work.

Nico’s Acknowledgments for the First Edition

My first personal thanks go with a lot of kisses to my family: Ulli, Lucas, Anica, and
Frederic supported this book with a lot of patience, consideration, and
encouragement.
In addition, I want to thank David. His expertise turned out to be incredible, but
his patience was even better (sometimes I ask really silly questions). It is a lot of fun
to work with him.

David’s Acknowledgments for the First Edition
My wife, Karina, has been instrumental in this book coming to a conclusion, and I
am immensely grateful for the role that she plays in my life. Writing “in your spare
time” quickly becomes erratic when many other activities vie for your schedule.
Karina helped me to manage that schedule, taught me to say “no” in order to make
the time needed to make regular progress in the writing process, and above all was
amazingly supportive of this project. I thank God every day for her friendship and
love.
I’m also tremendously grateful to have been able to work with Nico. Besides his
directly visible contributions to the text, his experience and discipline moved us from
my pitiful doodling to a well-organized production.
John “Mr. Template” Spicer and Steve “Mr. Overload” Adamczyk are wonderful
friends and colleagues, but in my opinion they are (together) also the ultimate
authority regarding the core C++ language. They clarified many of the trickier issues
described in this book, and should you find an error in the description of a C++
language element, it is almost certainly attributable to my failing to consult with
them.
Finally, I want to express my appreciation to those who were supportive of this
project without necessarily contributing to it directly (the power of cheer cannot be
understated). First, my parents: Their love for me and their encouragement made all
the difference. And then there are the numerous friends inquiring: “How is the book
going?” They, too, were a source of encouragement: Michael Beckmann, Brett and
Julie Beene, Jarran Carr, Simon Chang, Ho and Sarah Cho, Christophe De Dinechin,
Ewa Deelman, Neil Eberle, Sassan Hazeghi, Vikram Kumar, Jim and Lindsay Long,
R.J. Morgan, Mike Puritano, Ragu Raghavendra, Jim and Phuong Sharp, Gregg
Vaughn, and John Wiegley.

About This Book
The first edition of this book was published almost 15 years ago. We had set out to
write the definitive guide to C++ templates, with the expectation that it would be
useful to practicing C++ programmers. That project was successful: It’s been
tremendously gratifying to hear from readers who found our material helpful, to see
our book time and again being recommended as a work of reference, and to be
universally well reviewed.
That first edition has aged well, with most material remaining entirely relevant to
the modern C++ programmer, but there is no denying that the evolution of the
language—culminating in the “Modern C++” standards, C++11, C++14, and C++17
—has raised the need for a revision of the material in the first edition.
So with this second edition, our high-level goal has remained unchanged: to
provide the definitive guide to C++ templates, including both a solid reference and
an accessible tutorial. This time, however, we work with the “Modern C++”
language, which is a significantly bigger beast (still!) than the language available at
the time of the prior edition.
We’re also acutely aware that C++ programming resources have changed (for the
better) since the first edition was published. For example, several books have
appeared that develop specific template-based applications in great depth. More
important, far more information about C++ templates and template-based techniques
is easily available online, as are examples of advanced uses of these techniques. So
in this edition, we have decided to emphasize a breadth of techniques that can be
used in a variety of applications.
Some of the techniques we presented in the first edition have become obsolete
because the C++ language now offers more direct ways of achieving the same
effects. Those techniques have been dropped (or relegated to minor notes), and
instead you’ll find new techniques that show the state-ofthe-art uses of the new
language.
We’ve now lived over 20 years with C++ templates, but the C++ programmers’
community still regularly finds new fundamental insights into the way they can fit in
our software development needs. Our goal with this book is to share that knowledge
but also to fully equip the reader to develop new understanding and, perhaps,
discover the next major C++ technique.

What You Should Know Before Reading This Book
To get the most from this book, you should already know C++. We describe the
details of a particular language feature, not the fundamentals of the language itself.
You should be familiar with the concepts of classes and inheritance, and you should
be able to write C++ programs using components such as IOstreams and containers
from the C++ standard library. You should also be familiar with the basic features of
“Modern C++”, such as auto, decltype, move semantics, and lambdas.
Nevertheless, we review more subtle issues as the need arises, even when such issues
aren’t directly related to templates. This ensures that the text is accessible to experts
and intermediate programmers alike.
We deal primarily with the C++ language revisions standardized in 2011, 2014,
and 2017. However, at the time of this writing, the ink is barely dry on the C++17
revision, and we expect that most of our readers will not be intimately familiar with
its details. All revisions had a significant impact on the behavior and usage of
templates. We therefore provide short introductions to those new features that have
the greatest bearing on our subject matter. However, our goal is neither to introduce
the modern C++ standards nor to provide an exhaustive description of the changes
from the prior versions of this standard ([C++98] and [C++03]). Instead, we focus
on templates as designed and used in C++, using the modern C++ standards
([C++11], [C++14], and [C++17]) as our basis, and we occasionally call out cases
where the modern C++ standards enable or encourage different techniques than the
prior standards.

Overall Structure of the Book
Our goal is to provide the information necessary to start using templates and benefit
from their power, as well as to provide information that will enable experienced
programmers to push the limits of the state-of-the-art. To achieve this, we decided to
organize our text in parts:
• Part I introduces the basic concepts underlying templates. It is written in a tutorial
style.
• Part II presents the language details and is a handy reference to template-related
constructs.
• Part III explains fundamental design and coding techniques supported by C++
templates. They range from near-trivial ideas to sophisticated idioms.
Each of these parts consists of several chapters. In addition, we provide a few

appendixes that cover material not exclusively related to templates (e.g., an overview
of overload resolution in C++). An additional appendix covers concepts, which is a
fundamental extension to templates that has been included in the draft for a future
standard (C++20, presumably).
The chapters of Part I are meant to be read in sequence. For example, Chapter 3
builds on the material covered in Chapter 2. In the other parts, however, the
connection between chapters is considerably looser. Cross references will help
readers jump through the different topics.
Last, we provide a rather complete index that encourages additional ways to read
this book out of sequence.

How to Read This Book
If you are a C++ programmer who wants to learn or review the concepts of
templates, carefully read Part I, The Basics. Even if you’re quite familiar with
templates already, it may help to skim through this part quickly to familiarize
yourself with the style and terminology that we use. This part also covers some of
the logistical aspects of organizing your source code when it contains templates.
Depending on your preferred learning method, you may decide to absorb the many
details of templates in Part II, or instead you could read about practical coding
techniques in Part III (and refer back to Part II for the more subtle language issues).
The latter approach is probably particularly useful if you bought this book with
concrete day-to-day challenges in mind.
The appendixes contain much useful information that is often referred to in the
main text. We have also tried to make them interesting in their own right.
In our experience, the best way to learn something new is to look at examples.
Therefore, you’ll find a lot of examples throughout the book. Some are just a few
lines of code illustrating an abstract concept, whereas others are complete programs
that provide a concrete application of the material. The latter kind of examples will
be introduced by a C++ comment describing the file containing the program code.
You can find these files at the Web site of this book at
http://www.tmplbook.com.

Some Remarks About Programming Style
C++ programmers use different programming styles, and so do we: The usual
questions about where to put whitespace, delimiters (braces, parentheses), and so

forth came up. We tried to be consistent in general, although we occasionally make
concessions to the topic at hand. For example, in tutorial sections, we may prefer
generous use of whitespace and concrete names to help visualize code, whereas in
more advanced discussions, a more compact style could be more appropriate.
We do want to draw your attention to one slightly uncommon decision regarding
the declaration of types, parameters, and variables. Clearly, several styles are
possible:
void
void
void
void

foo
foo
foo
foo

(const int &x);
(const int& x);
(int const &x);
(int const& x);

Although it is a bit less common, we decided to use the order int const rather
than const int for “constant integer.” We have two reasons for using this order.
First, it provides for an easier answer to the question, “What is constant?” It’s always
what is in front of the const qualifier. Indeed, although
const int N = 100;

is equivalent to
int const N = 100;

there is no equivalent form for
Click here to view code image
int* const bookmark;
value pointed to can

// the pointer cannot change, but the

that would place the const qualifier before the pointer operator *. In this example,
it is the pointer itself that is constant, not the int to which it points.
Our second reason has to do with a syntactical substitution principle that is very
common when dealing with templates. Consider the following two type declarations
using the typedef keyword:1
Click here to view code image
typedef char* CHARS;
typedef CHARS const CPTR;

// constant pointer to chars

or using the using keyword:
Click here to view code image
using CHARS = char*;
using CPTR = CHARS const;

// constant pointer to chars

The meaning of the second declaration is preserved when we textually replace

CHARS with what it stands for:
Click here to view code image
typedef char* const CPTR;

// constant pointer to chars

or:
Click here to view code image
using CPTR = char* const; // constant pointer to chars

However, if we write const before the type it qualifies, this principle doesn’t apply.
Consider the alternative to our first two type definitions presented earlier:
Click here to view code image
typedef char* CHARS;
typedef const CHARS CPTR;

// constant pointer to chars

Textually replacing CHARS results in a type with a different meaning:
Click here to view code image
typedef const char* CPTR;

// pointer to constant chars

The same observation applies to the volatile specifier, of course.
Regarding whitespaces, we decided to put the space between the ampersand and
the parameter name:
void foo (int const& x);

By doing this, we emphasize the separation between the parameter type and the
parameter name. This is admittedly more confusing for declarations such as
char* a, b;

where, according to the rules inherited from C, a is a pointer but b is an ordinary
char. To avoid such confusion, we simply avoid declaring multiple entities in this
way.
This is primarily a book about language features. However, many techniques,
features, and helper templates now appear in the C++ standard library. To connect
these two, we therefore demonstrate template techniques by illustrating how they are
used to implement certain library components, and we use standard library utilities
to build our own more complex examples. Hence, we use not only headers such as
 and  (which contain templates but are not particularly
relevant to define other templates) but also , ,
, and  (which do provide building blocks for
more complex templates).

In addition, we provide a reference, Appendix D, about the major template utilities
provided by the C++ standard library, including a detailed description of all the
standard type traits. These are commonly used at the core of sophisticated template
programming

The C++11, C++14, and C++17 Standards
The original C++ standard was published in 1998 and subsequently amended by a
technical corrigendum in 2003, which provided minor corrections and clarifications
to the original standard. This “old C++ standard” is known as C++98 or C++03.
The C++11 standard was the first major revision of C++ driven by the ISO C++
standardization committee, bringing a wealth of new features to the language. A
number of these new features interact with templates and are described in this book,
including:
• Variadic templates
• Alias templates
• Move semantics, rvalue references, and perfect forwarding
• Standard type traits
C++14 and C++17 followed, both introducing some new language features, although
the changes brought about by these standards were not quite as dramatic as those of
C++11.2 New features interacting with templates and described in this book include
but are not limited to:
• Variable templates (C++14)
• Generic Lambdas (C++14)
• Class template argument deduction (C++17)
• Compile-time if (C++17)
• Fold expressions (C++17)
We even describe concepts (template interfaces), which are currently slated for
inclusion in the forthcoming C++20 standard.
At the time of this writing, the C++11 and C++14 standards are broadly supported
by the major compilers, and C++17 is largely supported also. Still, compilers differ
greatly in their support of the different language features. Several will compile most
of the code in this book, but a few compilers may not be able to handle some of our
examples. However, we expect that this problem will soon be resolved as
programmers everywhere demand standard support from their vendors.
Even so, the C++ programming language is likely to continue to evolve as time

passes. The experts of the C++ community (regardless of whether they participate in
the C++ Standardization Committee) are discussing various ways to improve the
language, and already several candidate improvements affect templates. Chapter 17
presents some trends in this area.

Example Code and Additional Information
You can access all example programs and find more information about this book
from its Web site, which has the following URL:
http://www.tmplbook.com

Feedback
We welcome your constructive input—both the negative and the positive. We
worked very hard to bring you what we hope you’ll find to be an excellent book.
However, at some point we had to stop writing, reviewing, and tweaking so we could
“release the product.” You may therefore find errors, inconsistencies, and
presentations that could be improved, or topics that are missing altogether. Your
feedback gives us a chance to inform all readers through the book’s Web site and to
improve any subsequent editions.
The best way to reach us is by email. You will find the email address at the Web
site of this book:
http://www.tmplbook.com

Please, be sure to check the book’s Web site for the currently known errata before
submitting reports. Many thanks.
1

Note that in C++, a type definition defines a “type alias” rather than a new type
(see Section 2.8 on page 38).
For example:
>typedef int Length; // define Length as an alias for int
int i = 42;
Length l = 88;
i = l;
// OK
l = i;
// OK

2

The committee now aims at issuing a new standard roughly every 3 years. Clearly,
that leaves less time for massive additions, but it brings the changes more quickly
to the broader programming community. The development of larger features, then,

spans time and might cover multiple standards.

Part I
The Basics
This part introduces the general concepts and language features of C++ templates. It
starts with a discussion of the general goals and concepts by showing examples of
function templates and class templates. It continues with some additional
fundamental template features such as nontype template parameters, variadic
templates, the keyword typename, and member templates. Also it discusses how to
deal with move semantics, how to declare parameters, and how to use generic code
for compile-time programming. It ends with some general hints about terminology
and regarding the use and application of templates in practice both as application
programmer and author of generic libraries.

Why Templates?
C++ requires us to declare variables, functions, and most other kinds of entities using
specific types. However, a lot of code looks the same for different types. For
example, the implementation of the algorithm quicksort looks structurally the same
for different data structures, such as arrays of ints or vectors of strings, as long as
the contained types can be compared to each other.
If your programming language doesn’t support a special language feature for this
kind of genericity, you only have bad alternatives:
1. You can implement the same behavior again and again for each type that needs
this behavior.
2. You can write general code for a common base type such as Object or void*.
3. You can use special preprocessors.
If you come from other languages, you probably have done some or all of this
before. However, each of these approaches has its drawbacks:
1. If you implement a behavior again and again, you reinvent the wheel. You make

the same mistakes, and you tend to avoid complicated but better algorithms
because they lead to even more mistakes.
2. If you write general code for a common base class, you lose the benefit of type
checking. In addition, classes may be required to be derived from special base
classes, which makes it more difficult to maintain your code.
3. If you use a special preprocessor, code is replaced by some “stupid text
replacement mechanism” that has no idea of scope and types, which might result
in strange semantic errors. Templates are a solution to this problem without these
drawbacks. They are functions or classes that are written for one or more types not
yet specified. When you use a template, you pass the types as arguments,
explicitly or implicitly. Because templates are language features, you have full
support of type checking and scope.
In today’s programs, templates are used a lot. For example, inside the C++ standard
library almost all code is template code. The library provides sort algorithms to sort
objects and values of a specified type, data structures (also called container classes)
to manage elements of a specified type, strings for which the type of a character is
parameterized, and so on. However, this is only the beginning. Templates also allow
us to parameterize behavior, to optimize code, and to parameterize information.
These applications are covered in later chapters. Let’s first start with some simple
templates.

Chapter 1
Function Templates
This chapter introduces function templates. Function templates are functions that are
parameterized so that they represent a family of functions.

1.1 A First Look at Function Templates
Function templates provide a functional behavior that can be called for different
types. In other words, a function template represents a family of functions. The
representation looks a lot like an ordinary function, except that some elements of the
function are left undetermined: These elements are parameterized. To illustrate, let’s
look at a simple example.

1.1.1 Defining the Template
The following is a function template that returns the maximum of two values:
Click here to view code image

basics/max1.hpp
template
T max (T a, T b)
{
// if b < a then yield a else yield b
return b < a ? a : b;
}

This template definition specifies a family of functions that return the maximum of
two values, which are passed as function parameters a and b.1 The type of these
parameters is left open as template parameter T. As seen in this example, template
parameters must be announced with syntax of the following form:

Click here to view code image
template< comma-separated-list-of-parameters >

In our example, the list of parameters is typename T. Note how the < and >
tokens are used as brackets; we refer to these as angle brackets. The keyword
typename introduces a type parameter. This is by far the most common kind of
template parameter in C++ programs, but other parameters are possible, and we
discuss them later (see Chapter 3).
Here, the type parameter is T. You can use any identifier as a parameter name, but
using T is the convention. The type parameter represents an arbitrary type that is
determined by the caller when the caller calls the function. You can use any type
(fundamental type, class, and so on) as long as it provides the operations that the
template uses. In this case, type T has to support operator < because a and b are
compared using this operator. Perhaps less obvious from the definition of max() is
that values of type T must also be copyable in order to be returned.2
For historical reasons, you can also use the keyword class instead of
typename to define a type parameter. The keyword typename came relatively
late in the evolution of the C++98 standard. Prior to that, the keyword class was
the only way to introduce a type parameter, and this remains a valid way to do so.
Hence, the template max() could be defined equivalently as follows:
Click here to view code image
template
T max (T a, T b)
{
return b < a ? a : b;
}

Semantically there is no difference in this context. So, even if you use class here,
any type may be used for template arguments. However, because this use of class
can be misleading (not only class types can be substituted for T), you should prefer
the use of typename in this context. However, note that unlike class type
declarations, the keyword struct cannot be used in place of typename when
declaring type parameters.

1.1.2 Using the Template
The following program shows how to use the max() function template:
Click here to view code image

basics/max1.cpp
#include "max1.hpp"
#include 
#include 
int main()
{
int i = 42;
std::cout << "max(7,i):

" << ::max(7,i) << ’\n’;

double f1 = 3.4; double f2 = -6.7;
std::cout << "max(f1,f2):
" << ::max(f1,f2) << ’\n’;
std::string s1 = "mathematics"; std::string s2 = "math";
std::cout << "max(s1,s2):
" << ::max(s1,s2) << ’\n’;
}

Inside the program, max() is called three times: once for two ints, once for two
doubles, and once for two std::strings. Each time, the maximum is
computed. As a result, the program has the following output:
Click here to view code image
max(7,i): 42
max(f1,f2): 3.4
max(s1,s2): mathematics

Note that each call of the max() template is qualified with ::. This is to ensure that
our max() template is found in the global namespace. There is also a
std::max() template in the standard library, which under some circumstances
may be called or may lead to ambiguity.3
Templates aren’t compiled into single entities that can handle any type. Instead,
different entities are generated from the template for every type for which the
template is used.4 Thus, max() is compiled for each of these three types. For
example, the first call of max()
int i = 42;
… max(7,i) …

uses the function template with int as template parameter T. Thus, it has the
semantics of calling the following code:
int max (int a, int b)
{
return b < a ? a : b;
}

The process of replacing template parameters by concrete types is called
instantiation. It results in an instance of a template.5
Note that the mere use of a function template can trigger such an instantiation
process. There is no need for the programmer to request the instantiation separately.
Similarly, the other calls of max() instantiate the max template for double and
std::string as if they were declared and implemented individually:
Click here to view code image
double max (double, double);
std::string max (std::string, std::string);

Note also that void is a valid template argument provided the resulting code is
valid. For example:
Click here to view code image
template
T foo(T*)
{
}
void* vp = nullptr;
foo(vp);
foo(void*)

// OK: deduces void

1.1.3 Two-Phase Translation
An attempt to instantiate a template for a type that doesn’t support all the operations
used within it will result in a compile-time error. For example:
Click here to view code image
std::complex c1, c2;
…
::max(c1,c2);

// doesn’t provide operator <
// ERROR at compile time

Thus, templates are “compiled” in two phases:
1. Without instantiation at definition time, the template code itself is checked for
correctness ignoring the template parameters. This includes:
– Syntax errors are discovered, such as missing semicolons.
– Using unknown names (type names, function names, …) that don’t depend on
template parameters are discovered.
– Static assertions that don’t depend on template parameters are checked.
2. At instantiation time, the template code is checked (again) to ensure that all code

is valid. That is, now especially, all parts that depend on template parameters are
double-checked.
For example:
Click here to view code image
template
void foo(T t)
{
undeclared();
// first-phase compile-time error if
undeclared() unknown
undeclared(t);
// second-phase compile-time error if
undeclared(T) unknown
static_assert(sizeof(int) > 10,
// always fails if
sizeof(int)<=10
"int too small");
static_assert(sizeof(T) > 10,
//fails if
instantiated for T with size <=10
"T too small");
}

The fact that names are checked twice is called two-phase lookup and discussed in
detail in Section 14.3.1 on page 249.
Note that some compilers don’t perform the full checks of the first phase.6 So you
might not see general problems until the template code is instantiated at least once.

Compiling and Linking
Two-phase translation leads to an important problem in the handling of templates in
practice: When a function template is used in a way that triggers its instantiation, a
compiler will (at some point) need to see that template’s definition. This breaks the
usual compile and link distinction for ordinary functions, when the declaration of a
function is sufficient to compile its use. Methods of handling this problem are
discussed in Chapter 9. For the moment, let’s take the simplest approach: Implement
each template inside a header file.

1.2 Template Argument Deduction
When we call a function template such as max() for some arguments, the template
parameters are determined by the arguments we pass. If we pass two ints to the
parameter types T, the C++ compiler has to conclude that T must be int.
However, T might only be “part” of the type. For example, if we declare max()

to use constant references:
Click here to view code image
template
T max (T const& a, T const& b)
{
return b < a ? a : b;
}

and pass int, again T is deduced as int, because the function parameters match for
int const&.
Type Conversions During Type Deduction
Note that automatic type conversions are limited during type deduction:
• When declaring call parameters by reference, even trivial conversions do not apply
to type deduction. Two arguments declared with the same template parameter T
must match exactly.
• When declaring call parameters by value, only trivial conversions that decay are
supported: Qualifications with const or volatile are ignored, references
convert to the referenced type, and raw arrays or functions convert to the
corresponding pointer type. For two arguments declared with the same template
parameter T the decayed types must match.
For example:
Click here to view code image
template
T max (T a, T b);
…
int const c = 42;
max(i, c);
// OK: T is deduced as int
max(c, c);
// OK: T is deduced as int
int& ir = i;
max(i, ir);
// OK: T is deduced as int
int arr[4];
foo(&i, arr);
// OK: T is deduced as int*

However, the following are errors:
Click here to view code image
max(4, 7.2);
std::string s;
foo("hello", s);
or std::string

// ERROR: T can be deduced as int or double
//ERROR: T can be deduced as char const[6]

There are three ways to handle such errors:
1. Cast the arguments so that they both match:
Click here to view code image
max(static_cast(4), 7.2);

// OK

2. Specify (or qualify) explicitly the type of T to prevent the compiler from
attempting type deduction:
Click here to view code image
max(4, 7.2);

// OK

3. Specify that the parameters may have different types.
Section 1.3 on page 9 will elaborate on these options. Section 7.2 on page 108 and
Chapter 15 will discuss the rules for type conversions during type deduction in
detail.
Type Deduction for Default Arguments
Note also that type deduction does not work for default call arguments. For example:
Click here to view code image
template
void f(T = "");
…
Click here to view code image
f(1);
(1)
f();

// OK: deduced T to be int, so that it calls f
// ERROR: cannot deduce T

To support this case, you also have to declare a default argument for the template
parameter, which will be discussed in Section 1.4 on page 13:
Click here to view code image
template
void f(T = "");
…
f();
// OK

1.3 Multiple Template Parameters
As we have seen so far, function templates have two distinct sets of parameters:

1. Template parameters, which are declared in angle brackets before the function
template name:
Click here to view code image
template

// T is template parameter

2. Call parameters, which are declared in parentheses after the function template
name:
Click here to view code image
T max (T a, T b)

// a and b are call parameters

You may have as many template parameters as you like. For example, you could
define the max() template for call parameters of two potentially different types:
Click here to view code image
template
T1 max (T1 a, T2 b)
{
return b < a ? a : b; }
…
auto m = ::max(4, 7.2);
// OK, but type of first argument
defines return type

It may appear desirable to be able to pass parameters of different types to the max()
template, but, as this example shows, it raises a problem. If you use one of the
parameter types as return type, the argument for the other parameter might get
converted to this type, regardless of the caller’s intention. Thus, the return type
depends on the call argument order. The maximum of 66.66 and 42 will be the
double 66.66, while the maximum of 42 and 66.66 will be the int 66.
C++ provides different ways to deal with this problem:
• Introduce a third template parameter for the return type.
• Let the compiler find out the return type.
• Declare the return type to be the “common type” of the two parameter types.
All these options are discussed next.

1.3.1 Template Parameters for Return Types
Our earlier discussion showed that template argument deduction allows us to call
function templates with syntax identical to that of calling an ordinary function: We
do not have to explicitly specify the types corresponding to the template parameters.
We also mentioned, however, that we can specify the types to use for the template

parameters explicitly:
Click here to view code image
template
T max (T a, T b);
…
::max(4, 7.2);

// instantiate T as double

In cases when there is no connection between template and call parameters and when
template parameters cannot be determined, you must specify the template argument
explicitly with the call. For example, you can introduce a third template argument
type to define the return type of a function template:
Click here to view code image
template
RT max (T1 a, T2 b);

However, template argument deduction does not take return types into account,7 and
RT does not appear in the types of the function call parameters. Therefore, RT cannot
be deduced.8
As a consequence, you have to specify the template argument list explicitly. For
example:
Click here to view code image
template
RT max (T1 a, T2 b);
…
::max(4, 7.2);
// OK, but tedious

So far, we have looked at cases in which either all or none of the function template
arguments were mentioned explicitly. Another approach is to specify only the first
arguments explicitly and to allow the deduction process to derive the rest. In general,
you must specify all the argument types up to the last argument type that cannot be
determined implicitly. Thus, if you change the order of the template parameters in
our example, the caller needs to specify only the return type:
Click here to view code image
template
RT max (T1 a, T2 b);
…
::max(4, 7.2)
//OK: return type is double, T1 and
T2 are deduced

In this example, the call to max explicitly sets RT to double, but the
parameters T1 and T2 are deduced to be int and double from the arguments.

Note that these modified versions of max() don’t lead to significant advantages.
For the one-parameter version you can already specify the parameter (and return)
type if two arguments of a different type are passed. Thus, it’s a good idea to keep it
simple and use the one-parameter version of max() (as we do in the following
sections when discussing other template issues).
See Chapter 15 for details of the deduction process.

1.3.2 Deducing the Return Type
If a return type depends on template parameters, the simplest and best approach to
deduce the return type is to let the compiler find out. Since C++14, this is possible
by simply not declaring any return type (you still have to declare the return type to
be auto):
Click here to view code image

basics/maxauto.hpp
template
auto max (T1 a, T2 b)
{
return b < a ? a : b;
}

In fact, the use of auto for the return type without a corresponding trailing return
type (which would be introduced with a -> at the end) indicates that the actual return
type must be deduced from the return statements in the function body. Of course,
deducing the return type from the function body has to be possible. Therefore, the
code must be available and multiple return statements have to match.
Before C++14, it is only possible to let the compiler determine the return type by
more or less making the implementation of the function part of its declaration. In
C++11 we can benefit from the fact that the trailing return type syntax allows us to
use the call parameters. That is, we can declare that the return type is derived from
what operator?: yields:
Click here to view code image

basics/maxdecltype.hpp
template
auto max (T1 a, T2 b) -> decltype(b
auto max (T1 a, T2 b) -> decltype(b
auto max (T1 a, T2 b) -> decltype(true?a:b);

However, in any case this definition has a significant drawback: It might happen that
the return type is a reference type, because under some conditions T might be a
reference. For this reason you should return the type decayed from T, which looks as
follows:
Click here to view code image

basics/maxdecltypedecay.hpp
#include 
template
auto max (T1 a, T2 b) -> typename std::decay::type
{ return b < a ? a : b;
}

Here, the type trait std::decay<> is used, which returns the resulting type in a
member type. It is defined by the standard library in  (see Section
D.5 on page 732). Because the member type is a type, you have to qualify the
expression with typename to access it (see Section 5.1 on page 67).
Note that an initialization of type auto always decays. This also applies to return
values when the return type is just auto. auto as a return type behaves just as in
the following code, where a is declared by the decayed type of i, int:

Click here to view code image
int i = 42;
int const& ir = i;
i auto a = ir;
int

// ir refers to
// a is declared as new object of type

1.3.3 Return Type as Common Type
Since C++11, the C++ standard library provides a means to specify choosing “the
more general type.” std::common_type<>::type yields the “common type”
of two (or more) different types passed as template arguments. For example:
Click here to view code image

basics/maxcommon.hpp
#include 
template
std::common_type_t max (T1 a, T2 b)
{
return b < a ? a : b;
}

Again, std::common_type is a type trait, defined in , which
yields a structure having a type member for the resulting type. Thus, its core usage
is as follows:
Click here to view code image
typename std::common_type::type

//since C++11

However, since C++14 you can simplify the usage of traits like this by appending _t
to the trait name and skipping typename and ::type (see Section 2.8 on page 40
for details), so that the return type definition simply becomes:
Click here to view code image
std::common_type_t
C++14

// equivalent since

The way std::common_type<> is implemented uses some tricky template
programming, which is discussed in Section 26.5.2 on page 622. Internally, it
chooses the resulting type according to the language rules of operator ?: or
specializations for specific types. Thus, both ::max(4, 7.2) and ::max(7.2,
4) yield the same value 7.2 of type double. Note that std::common_type<>

also decays. See Section D.5 on page 732 for details.

1.4 Default Template Arguments
You can also define default values for template parameters. These values are called
default template arguments and can be used with any kind of template.9 They may
even refer to previous template parameters.
For example, if you want to combine the approaches to define the return type with
the ability to have multiple parameter types (as discussed in the section before), you
can introduce a template parameter RT for the return type with the common type of
the two arguments as default. Again, we have multiple options:
1. We can use operator?: directly. However, because we have to apply
operator?: before the call parameters a and b are declared, we can only use
their types:
Click here to view code image

basics/maxdefault1.hpp
#include 
template>
RT max (T1 a, T2 b)
{
return b < a ? a : b;
}

Note again the usage of std::decay_t<> to ensure that no reference can be
returned.10
Note also that this implementation requires that we are able to call default
constructors for the passed types. There is another solution, using std::declval,
which, however, makes the declaration even more complicated. See Section 11.2.3
on page 166 for an example.
2. We can also use the std::common_type<> type trait to specify the default
value for the return type:
Click here to view code image

basics/maxdefault3.hpp
#include 

template>
RT max (T1 a, T2 b)
{
return b < a ? a : b;
}

Again, note that std::common_type<> decays so that the return value can’t
become a reference.
In all cases, as a caller, you can now use the default value for the return type:
Click here to view code image
auto a = ::max(4, 7.2);

or specify the return type after all other argument types explicitly:
Click here to view code image
auto b = ::max(7.2, 4);

However, again we have the problem that we have to specify three types to be able
to specify the return type only. Instead, we would need the ability to have the return
type as the first template parameter, while still being able to deduce it from the
argument types. In principle, it is possible to have default arguments for leading
function template parameters even if parameters without default arguments follow:
Click here to view code image
template
RT max (T1 a, T2 b)
{
return b < a ? a : b;
}

With this definition, for example, you can call:
Click here to view code image
int i; long l;
…
max(i, l);
// returns long (default argument of
template parameter for return type)
max(4, 42);
// returns int as explicitly requested

However, this approach only makes sense, if there is a “natural” default for a
template parameter. Here, we need the default argument for the template parameter
to depend from previous template parameters. In principle, this is possible as we
discuss in Section 26.5.1 on page 621, but the technique depends on type traits and

complicates the definition.
For all these reasons, the best and easiest solution is to let the compiler deduce the
return type as proposed in Section 1.3.2 on page 11.

1.5 Overloading Function Templates
Like ordinary functions, function templates can be overloaded. That is, you can have
different function definitions with the same function name so that when that name is
used in a function call, a C++ compiler must decide which one of the various
candidates to call. The rules for this decision may become rather complicated, even
without templates. In this section we discuss overloading when templates are
involved. If you are not familiar with the basic rules of overloading without
templates, please look at Appendix C, where we provide a reasonably detailed
survey of the overload resolution rules.
The following short program illustrates overloading a function template:
Click here to view code image

basics/max2.cpp
// maximum of two int values:
int max (int a,
int b)
{
return b < a ? a : b;
}
// maximum of two values of any type:
template
T max (T a, T b)
{
return b < a ? a : b;
}
int main()
{
::max(7, 42);
ints
::max(7.0, 42.0);
deduction)
::max(’a’, ’b’);
deduction)
::max<>(7, 42);
deduction)
::max(7, 42);

// calls the nontemplate for two
// calls max (by argument
//calls max (by argument
// calls max (by argument
// calls max (no argument

deduction)
::max(’a’, 42.7);
ints
}

//calls the nontemplate for two

As this example shows, a nontemplate function can coexist with a function template
that has the same name and can be instantiated with the same type. All other factors
being equal, the overload resolution process prefers the nontemplate over one
generated from the template. The first call falls under this rule:
Click here to view code image
::max(7, 42);
function perfectly

// both int values match the nontemplate

If the template can generate a function with a better match, however, then the
template is selected. This is demonstrated by the second and third calls of max():
Click here to view code image
::max(7.0, 42.0);
deduction)
::max(’a’, ’b’);
deduction)

// calls the max (by argument
//calls the max (by argument

Here, the template is a better match because no conversion from double or char
to int is required (see Section C.2 on page 682 for the rules of overload resolution).
It is also possible to specify explicitly an empty template argument list. This
syntax indicates that only templates may resolve a call, but all the template
parameters should be deduced from the call arguments:
Click here to view code image
::max<>(7, 42);

// calls max (by argument deduction)

Because automatic type conversion is not considered for deduced template
parameters but is considered for ordinary function parameters, the last call uses the
nontemplate function (while ’a’ and 42.7 both are converted to int):
Click here to view code image
::max(’a’, 42.7);
nontrivial conversions

//only the nontemplate function allows

An interesting example would be to overload the maximum template to be able to
explicitly specify the return type only:
Click here to view code image

basics/maxdefault4.hpp

template
auto max (T1 a, T2 b)
{
return b < a ? a : b;
}
template
RT max (T1 a, T2 b)
{
return b < a ? a : b;
}

Now, we can call max(), for example, as follows:
Click here to view code image
auto a = ::max(4, 7.2);
template
auto b = ::max(7.2, 4);
template

// uses first
// uses second

However, when calling:
Click here to view code image
auto c = ::max(4, 7.2);
function templates match

// ERROR: both

both templates match, which causes the overload resolution process normally to
prefer none and result in an ambiguity error. Thus, when overloading function
templates, you should ensure that only one of them matches for any call.
A useful example would be to overload the maximum template for pointers and
ordinary C-strings:
Click here to view code image

basics/max3val.cpp
#include
#include




// maximum of two values of any type:
template
T max (T a, T b)
{
return
b < a ? a : b;
}
// maximum of two pointers:

template
T* max (T* a, T* b)
{
return
*b < *a
}

? a : b;

// maximum of two C-strings:
char const* max (char
const* a,
char const* b)
{
return
std::strcmp(b,a) < 0
? a : b;
}
int
main
{
int a =
int b =
auto m1
int

()
7;
42;
= ::max(a,b);

std::string s1 =
"hey"; "
std::string s2 =
"you"; "
auto m2 = ::max(s1,s2);
std::string

// max() for two values of type

// max() for two values of type

int* p1 = &b;
int* p2 = &a;
auto m3 = ::max(p1,p2);

// max() for two pointers

char const* x = hello"; "
char const* y = "world"; "
auto m4 = ::max(x,y);

// max() for two C-strings

}

Note that in all overloads of max() we pass the arguments by value. In general, it is
a good idea not to change more than necessary when overloading function templates.
You should limit your changes to the number of parameters or to specifying template
parameters explicitly. Otherwise, unexpected effects may happen. For example, if
you implement your max() template to pass the arguments by reference and
overload it for two C-strings passed by value, you can’t use the three-argument
version to compute the maximum of three C-strings:
Click here to view code image

basics/max3ref.cpp
#include 

// maximum of two values of any type (call-by-reference)
template T const& max (T const& a, T const& b)
{
return b < a ? a : b;
}
// maximum of two C-strings (call-by-value)
char const* max (char const* a, char const* b)
{
return std::strcmp(b,a) < 0 ? a : b;
}
// maximum of three values of any type (call-by-reference)
template
T const& max (T const& a, T const& b, T const& c)
{
return max (max(a,b), c);
// error if max(a,b) uses
call-by-value
}
int main ()
{
auto m1 = ::max(7, 42, 68);
// OK
char const* s1 = "frederic";
char const* s2 = "anica";
char const* s3 = "lucas";
auto m2 = ::max(s1, s2, s3);
//run-time ERROR
}

The problem is that if you call max() for three C-strings, the statement
Click here to view code image
return max (max(a,b), c);

becomes a run-time error because for C-strings, max(a,b) creates a new,
temporary local value that is returned by reference, but that temporary value expires
as soon as the return statement is complete, leaving main() with a dangling
reference. Unfortunately, the error is quite subtle and may not manifest itself in all
cases.11
Note, in contrast, that the first call to max() in main() doesn’t suffer from the
same issue. There temporaries are created for the arguments (7, 42, and 68), but
those temporaries are created in main() where they persist until the statement is
done.
This is only one example of code that might behave differently than expected as a
result of detailed overload resolution rules. In addition, ensure that all overloaded
versions of a function are declared before the function is called. This is because the

fact that not all overloaded functions are visible when a corresponding function call
is made may matter. For example, defining a three-argument version of max()
without having seen the declaration of a special two-argument version of max() for
ints causes the two-argument template to be used by the three-argument version:
basics/max4.cpp
Click here to view code image
#include 
// maximum of two values of any type:
template
T max (T a, T b)
{
std::cout << "max() \n";
return b < a ? a : b;
}
// maximum of three values of any type:
template
T max (T a, T b, T c)
{
return max (max(a,b), c);
// uses the template version
even for ints
}
//because the following
declaration comes
// too late:
// maximum of two int values:
int max (int a,
int b)
{
std::cout << "max(int,int) \n";
return b < a ? a : b;
}
int main()
{
::max(47,11,33);
max(int,int)
}

// OOPS: uses max() instead of

We discuss details in Section 13.2 on page 217.

1.6 But, Shouldn’t We …?
Probably, even these simple function template examples might raise further
questions. Three questions are probably so common that we should discuss them
here briefly.

1.6.1 Pass by Value or by Reference?
You might wonder, why we in general declare the functions to pass the arguments by
value instead of using references. In general, passing by reference is recommended
for types other than cheap simple types (such as fundamental types or
std::string_view), because no unnecessary copies are created.
However, for a couple of reasons, passing by value in general is often better:
• The syntax is simple.
• Compilers optimize better.
• Move semantics often makes copies cheap.
• And sometimes there is no copy or move at all.
In addition, for templates, specific aspects come into play:
• A template might be used for both simple and complex types, so choosing the
approach for complex types might be counter-productive for simple types.
• As a caller you can often still decide to pass arguments by reference, using
std::ref() and std::cref() (see Section 7.3 on page 112).
• Although passing string literals or raw arrays always can become a problem,
passing them by reference often is considered to become the bigger problem. All
this will be discussed in detail in Chapter 7. For the moment inside the book we
will usually pass arguments by value unless some functionality is only possible
when using references.

1.6.2 Why Not inline?
In general, function templates don’t have to be declared with inline. Unlike
ordinary noninline functions, we can define noninline function templates in a header
file and include this header file in multiple translation units.
The only exception to this rule are full specializations of templates for specific
types, so that the resulting code is no longer generic (all template parameters are
defined). See Section 9.2 on page 140 for more details.
From a strict language definition perspective, inline only means that a

definition of a function can appear multiple times in a program. However, it is also
meant as a hint to the compiler that calls to that function should be “expanded
inline”: Doing so can produce more efficient code for certain cases, but it can also
make the code less efficient for many other cases. Nowadays, compilers usually are
better at deciding this without the hint implied by the inline keyword. However,
compilers still account for the presence of inline in that decision.

1.6.3 Why Not constexpr?
Since C++11, you can use constexpr to provide the ability to use code to
compute some values at compile time. For a lot of templates this makes sense.
For example, to be able to use the maximum function at compile time, you have to
declare it as follows:
Click here to view code image

basics/maxconstexpr.hpp
template
constexpr auto max (T1 a, T2 b)
{
return b < a ? a : b;
}

With this, you can use the maximum function template in places with compile-time
context, such as when declaring the size of a raw array:
Click here to view code image
int a[::max(sizeof(char),1000u)];

or the size of a std::array<>:
Click here to view code image
std::array arr;

Note that we pass 1000 as unsigned int to avoid warnings about comparing a
signed with an unsigned value inside the template.
Section 8.2 on page 125 will discuss other examples of using constexpr.
However, to keep our focus on the fundamentals, we usually will skip constexpr
when discussing other template features.

1.7 Summary
• Function templates define a family of functions for different template arguments.
• When you pass arguments to function parameters depending on template
parameters, function templates deduce the template parameters to be instantiated
for the corresponding parameter types.
• You can explicitly qualify the leading template parameters.
• You can define default arguments for template parameters. These may refer to
previous template parameters and be followed by parameters not having default
arguments.
• You can overload function templates.
• When overloading function templates with other function templates, you should
ensure that only one of them matches for any call.
• When you overload function templates, limit your changes to specifying template
parameters explicitly.
• Ensure the compiler sees all overloaded versions of function templates before you
call them.
1

Note that the max() template according to [StepanovNotes] intentionally returns
“b < a ? a : b” instead of “a < b ? b : a” to ensure that the function
behaves correctly even if the two values are equivalent but not equal.
2 Before C++17, type T also had to be copyable to be able to pass in arguments, but
since C++17 you can pass temporaries (rvalues, see Appendix B) even if neither a
copy nor a move constructor is valid.
3 For example, if one argument type is defined in namespace std (such as
std::string), according to the lookup rules of C++, both the global and the
max() template in std are found (see Appendix C).
4 A “one-entity-fits-all” alternative is conceivable but not used in practice (it would
be less efficient at run time). All language rules are based on the principle that
different entities are generated for different template arguments.
5 The terms instance and instantiate are used in a different context in objectoriented programming—namely, for a concrete object of a class. However,
because this book is about templates, we use this term for the “use” of templates
unless otherwise specified.
6 For example, The Visual C++ compiler in some versions (such as Visual Studio
20133 and 2015) allow undeclared names that don’t depend on template
parameters and even some syntax flaws (such as a missing semicolon).
7 Deduction can be seen as part of overload resolution—a process that is not based

on selection of return types either. The sole exception is the return type of
conversion operator members.
8 In C++, the return type also cannot be deduced from the context in which the
caller uses the call.
9 Prior to C++11, default template arguments were only permitted in class
templates, due to a historical glitch in the development of function templates.
10 Again, in C++11 you had to use typename std::decay<…>::type
instead of std::decay_t<…> (see Section 2.8 on page 40).
11 In general, a conforming compiler isn’t even permitted to reject this code.

Chapter 2
Class Templates
Similar to functions, classes can also be parameterized with one or more types.
Container classes, which are used to manage elements of a certain type, are a typical
example of this feature. By using class templates, you can implement such container
classes while the element type is still open. In this chapter we use a stack as an
example of a class template.

2.1 Implementation of Class Template Stack
As we did with function templates, we declare and define class Stack<> in a
header file as follows:
Click here to view code image

basics/stack1.hpp
#include 
#include 
template
class Stack {
private:
std::vector elems;
public:
void push(T const& elem);
void pop();
T const& top() const;
bool empty() const {
empty
return elems.empty();
}
};
template

// elements

//
//
//
//

push element
pop element
return top element
return whether the stack is

void Stack::push (T const& elem)
{
elems.push_back(elem);
// append copy of passed elem}
template
void Stack::pop ()
{
assert(!elems.empty());
elems.pop_back();
}

// remove last element

template
T const& Stack::top () const
{
assert(!elems.empty());
return elems.back();
// return copy of last element
}

As you can see, the class template is implemented by using a class template of the
C++ standard library: vector<>. As a result, we don’t have to implement memory
management, copy constructor, and assignment operator, so we can concentrate on
the interface of this class template.

2.1.1 Declaration of Class Templates
Declaring class templates is similar to declaring function templates: Before the
declaration, you have to declare one or multiple identifiers as a type parameter(s).
Again, T is usually used as an identifier:
Click here to view code image
template
class Stack {
…
};

Here again, the keyword class can be used instead of typename:
Click here to view code image
template
class Stack {
…
};

Inside the class template, T can be used just like any other type to declare members

and member functions. In this example, T is used to declare the type of the elements
as vector of Ts, to declare push() as a member function that uses a T as an
argument, and to declare top() as a function that returns a T:
Click here to view code image
template<
typename T>
class Stack {
private:
std::vector elems;
public:
void push(T const& elem);
void pop();
T const& top()
const;
bool empty() const {
empty
return elems.empty();
}
};

// elements

// push element
// pop element
// return top element
// return whether the stack is

The type of this class is Stack, with T being a template parameter. Thus, you
have to use Stack whenever you use the type of this class in a declaration
except in cases where the template arguments can be deduced. However, inside a
class template using the class name not followed by template arguments represents
the class with its template parameters as its arguments (see Section 13.2.3 on page
221 for details).
If, for example, you have to declare your own copy constructor and assignment
operator, it typically looks like this:
Click here to view code image
template
class Stack {
…
Stack (Stack const&);
Stack& operator= (Stack const&);
operator
…
};

which is formally equivalent to:
Click here to view code image
template
class Stack {

// copy constructor
// assignment

…
Stack (Stack const&);
Stack& operator= (Stack const&);
operator
…
};

// copy constructor
// assignment

but usually the  signals special handling of special template parameters, so it’s
usually better to use the first form.
However, outside the class structure you’d need:
Click here to view code image
template
bool operator== (Stack const& lhs, Stack const& rhs);

Note that in places where the name and not the type of the class is required, only
Stack may be used. This is especially the case when you specify the name of
constructors (not their arguments) and the destructor.
Note also that, unlike nontemplate classes, you can’t declare or define class
templates inside functions or block scope. In general, templates can only be defined
in global/namespace scope or inside class declarations (see Section 12.1 on page 177
for details).

2.1.2 Implementation of Member Functions
To define a member function of a class template, you have to specify that it is a
template, and you have to use the full type qualification of the class template. Thus,
the implementation of the member function push() for type Stack looks like
this:
Click here to view code image
template
void Stack::push (T const& elem)
{
elems.push_back(elem);
// append copy of passed elem
}

In this case, push_back() of the element vector is called, which appends the
element at the end of the vector.
Note that pop_back() of a vector removes the last element but doesn’t return it.
The reason for this behavior is exception safety. It is impossible to implement a
completely exception-safe version of pop() that returns the removed element (this
topic was first discussed by Tom Cargill in [CargillExceptionSafety] and is discussed

as Item 10 in [SutterExceptional]). However, ignoring this danger, we could
implement a pop() that returns the element just removed. To do this, we simply use
T to declare a local variable of the element type:
Click here to view code image
template
T Stack::pop ()
{
assert(!elems.empty());
T elem = elems.back();
elems.pop_back();
return elem;
}

// save copy of last element
// remove last element
// return copy of saved element

Because back() (which returns the last element) and pop_back() (which
removes the last element) have undefined behavior when there is no element in the
vector, we decided to check whether the stack is empty. If it is empty, we assert,
because it is a usage error to call pop() on an empty stack. This is also done in
top(), which returns but does not remove the top element, on attempts to remove a
nonexistent top element:
Click here to view code image
template
T const& Stack::top () const
{
assert(!elems.empty());
return elems.back();
// return copy of last element
}

Of course, as for any member function, you can also implement member functions of
class templates as an inline function inside the class declaration. For example:
Click here to view code image
template
class Stack {
…
void push (T const& elem) {
elems.push_back(elem);
elem
}
…
};

// append copy of passed

2.2 Use of Class Template Stack
To use an object of a class template, until C++17 you must always specify the
template arguments explicitly.1 The following example shows how to use the class
template Stack<>:
Click here to view code image

basics/stack1test.cpp
#include "stack1.hpp"
#include 
#include 
int main()
{
Stack< int>
intStack;
Stack stringStack;

// stack of ints
// stack of strings

// manipulate int stack
intStack.push(7);
std::cout << intStack.top() << ’\n’;
// manipulate string stack
stringStack.push("hello");
std::cout << stringStack.top() << ’\n’;
stringStack.pop();
}

By declaring type Stack, int is used as type T inside the class template.
Thus, intStack is created as an object that uses a vector of ints as elements and,
for all member functions that are called, code for this type is instantiated. Similarly,
by declaring and using Stack, an object that uses a vector of
strings as elements is created, and for all member functions that are called, code for
this type is instantiated.
Note that code is instantiated only for template (member) functions that are called.
For class templates, member functions are instantiated only if they are used. This, of
course, saves time and space and allows use of class templates only partially, which
we will discuss in Section 2.3 on page 29.
In this example, the default constructor, push(), and top() are instantiated for
both int and strings. However, pop() is instantiated only for strings. If a class
template has static members, these are also instantiated once for each type for which
the class template is used.

An instantiated class template’s type can be used just like any other type. You can
qualify it with const or volatile or derive array and reference types from it.
You can also use it as part of a type definition with typedef or using (see
Section 2.8 on page 38 for details about type definitions) or use it as a type
parameter when building another template type. For example:
Click here to view code image
void foo(Stack  const& s)
{
using IntStack = Stack ;
Stack
Stack< int> istack[10];
stacks
IntStack istack2[10];
10 int stacks (same type)
…
}

// parameter s is int stack
// IntStack is another name for
// istack is array of 10 int
// istack2 is also an array of

Template arguments may be any type, such as pointers to floats or even stacks of
ints:
Click here to view code image
Stack< float*>
floatPtrStack;
pointers
Stack> intStackStack;
ints

// stack of float
// stack of stack of

The only requirement is that any operation that is called is possible according to this
type.
Note that before C++11 you had to put whitespace between the two closing
template brackets:
Click here to view code image
Stack > intStackStack;
versions

// OK with all C++

If you didn’t do this, you were using operator >>, which resulted in a syntax error:
Click here to view code image
Stack> intStackStack;

// ERROR before C++11

The reason for the old behavior was that it helped the first pass of a C++ compiler to
tokenize the source code independent of the semantics of the code. However,
because the missing space was a typical bug, which required corresponding error
messages, the semantics of the code more and more had to get taken into account

anyway. So, with C++11 the rule to put a space between two closing template
brackets was removed with the “angle bracket hack” (see Section 13.3.1 on page 226
for details).

2.3 Partial Usage of Class Templates
A class template usually applies multiple operations on the template arguments it is
instantiated for (including construction and destruction). This might lead to the
impression that these template arguments have to provide all operations necessary
for all member functions of a class template. But this is not the case: Template
arguments only have to provide all necessary operations that are needed (instead of
that could be needed).
If, for example, class Stack<> would provide a member function printOn() to
print the whole stack content, which calls operator<< for each element:
Click here to view code image
template
class Stack {
…
void printOn() (std::ostream& strm) const {
for (T const& elem : elems) {
strm << elem << ’ ’;
// call << for each element
}
}
};

You can still use this class for elements that don’t have operator<< defined:
Click here to view code image
Stack> ps;
no operator<< defined
ps.push({4, 5});
ps.push({6, 7});
std::cout << ps.top().first << ’\n’;
std::cout << ps.top().second << ’\n’;

// note: std::pair<> has
// OK
// OK
// OK
// OK

Only if you call printOn() for such a stack, the code will produce an error,
because it can’t instantiate the call of operator<< for this specific element type:
Click here to view code image
ps.printOn(std::cout);
for element type

// ERROR: operator<< not supported

2.3.1 Concepts
This raises the question: How do we know which operations are required for a
template to be able to get instantiated? The term concept is often used to denote a set
of constraints that is repeatedly required in a template library. For example, the C++
standard library relies on such concepts as random access iterator and default
constructible.
Currently (i.e., as of C++17), concepts can more or less only be expressed in the
documentation (e.g., code comments). This can become a significant problem
because failures to follow constraints can lead to terrible error messages (see Section
9.4 on page 143).
For years, there have also been approaches and trials to support the definition and
validation of concepts as a language feature. However, up to C++17 no such
approach was standardized yet.
Since C++11, you can at least check for some basic constraints by using the
static_assert keyword and some predefined type traits. For example:
Click here to view code image
template
class C
{
static_assert(std::is_default_constructible::value,
"Class C requires default-constructible
elements");
…
};

Without this assertion the compilation will still fail, if the default constructor is
required. However, the error message then might contain the entire template
instantiation history from the initial cause of the instantiation down to the actual
template definition in which the error was detected (see Section 9.4 on page 143).
However, more complicated code is necessary to check, for example, objects of
type T provide a specific member function or that they can be compared using
operator <. See Section 19.6.3 on page 436 for a detailed example of such code.
See Appendix E for a detailed discussion of concepts for C++.

2.4 Friends
Instead of printing the stack contents with printOn() it is better to implement

operator<< for the stack. However, as usual operator<< has to be
implemented as nonmember function, which then could call printOn() inline:
Click here to view code image
template
class Stack {
…
void printOn() (std::ostream& strm) const {
…
}
friend std::ostream& operator<< (std::ostream& strm,
Stack const& s) {
s.printOn(strm);
return strm;
}
};

Note that this means that operator<< for class Stack<> is not a function
template, but an “ordinary” function instantiated with the class template if needed.2
However, when trying to declare the friend function and define it afterwards,
things become more complicated. In fact, we have two options:
1. We can implicitly declare a new function template, which must use a different
template parameter, such as U:
Click here to view code image
template
class Stack {
…
template
friend std::ostream& operator<< (std::ostream&, Stack
const&);
};

Neither using T again nor skipping the template parameter declaration would work
(either the inner T hides the outer T or we declare a nontemplate function in
namespace scope).
2. We can forward declare the output operator for a Stack to be a template,
which, however, means that we first have to forward declare Stack:
Click here to view code image
template
class Stack;
template
std::ostream& operator<< (std::ostream&, Stack const&);

Then, we can declare this function as friend:
Click here to view code image
template
class Stack {
…
friend std::ostream& operator<<  (std::ostream&,
Stack const&);
};

Note the  behind the “function name” operator<<. Thus, we declare a
specialization of the nonmember function template as friend. Without  we
would declare a new nontemplate function. See Section 12.5.2 on page 211 for
details.
In any case, you can still use this class for elements that don’t have operator<<
defined. Only calling operator<< for this stack results in an error:
Click here to view code image
Stack> ps;
operator<< defined
ps.push({4, 5});
ps.push({6, 7});
std::cout <<
ps.top().first << ’\n’;
std::cout <<
ps.top().second << ’\n’;
std::cout << ps << ’\n’;
supported

// std::pair<> has no
// OK
// OK
// OK
// OK
// ERROR: operator<< not
//

for element type

2.5 Specializations of Class Templates
You can specialize a class template for certain template arguments. Similar to the
overloading of function templates (see Section 1.5 on page 15), specializing class
templates allows you to optimize implementations for certain types or to fix a
misbehavior of certain types for an instantiation of the class template. However, if
you specialize a class template, you must also specialize all member functions.
Although it is possible to specialize a single member function of a class template,
once you have done so, you can no longer specialize the whole class template
instance that the specialized member belongs to.
To specialize a class template, you have to declare the class with a leading
template<> and a specification of the types for which the class template is

specialized. The types are used as a template argument and must be specified directly
following the name of the class:
Click here to view code image
template<>
class Stack {
…
};

For these specializations, any definition of a member function must be defined as an
“ordinary” member function, with each occurrence of T being replaced by the
specialized type:
Click here to view code image
void Stack::push (std::string const& elem)
{
elems.push_back(elem);
// append copy of passed elem
}

Here is a complete example of a specialization of Stack<> for type
std::string:
Click here to view code image

basics/stack2.hpp
#include
#include
#include
#include

"stack1.hpp"




template<>
class Stack {
private:
std::deque elems;
public:
void push(std::string const&);
void pop();
std::string const& top() const;
bool empty() const {
stack is empty
return elems.empty();
}
};

// elements

//
//
//
//

push element
pop element
return top element
return whether the

void Stack::push (std::string const& elem)
{

elems.push_back(elem);

// append copy of passed elem

}
void Stack::pop ()
{
assert(!elems.empty());
elems.pop_back();
// remove last element
}
std::string const& Stack::top () const
{
assert(!elems.empty());
return elems.back();
// return copy of last element
}

In this example, the specialization uses reference semantics to pass the string
argument to push(), which makes more sense for this specific type (we should
even better pass a forwarding reference, though, which is discussed in Section 6.1 on
page 91).
Another difference is to use a deque instead of a vector to manage the elements
inside the stack. Although this has no particular benefit here, it does demonstrate that
the implementation of a specialization might look very different from the
implementation of the primary template.

2.6 Partial Specialization
Class templates can be partially specialized. You can provide special
implementations for particular circumstances, but some template parameters must
still be defined by the user. For example, we can define a special implementation of
class Stack<> for pointers:
Click here to view code image

basics/stackpartspec.hpp
#include "stack1.hpp"
// partial specialization of class Stack<> for pointers:
template
class Stack {
private:
std::vector elems;
// elements
public:

void push(T*);
T* pop();
T* top() const;
bool empty() const {
empty
return elems.empty();
}
};
template
void Stack::push (T* elem)
{
elems.push_back(elem);
}
template
T* Stack::pop ()
{
assert(!elems.empty());
T* p = elems.back();
elems.pop_back();
return p;
general case)
}
template
T* Stack::top () const
{
assert(!elems.empty());
return elems.back();
}

//
//
//
//

push element
pop element
return top element
return whether the stack is

// append copy of passed elem

// remove last element
// and return it (unlike in the

// return copy of last element

With
Click here to view code image
template
class Stack {
};

we define a class template, still parameterized for T but specialized for a pointer
(Stack).
Note again that the specialization might provide a (slightly) different interface.
Here, for example, pop() returns the stored pointer, so that a user of the class
template can call delete for the removed value, when it was created with new:
Click here to view code image
Stack< int*> ptrStack;

// stack of pointers (special

implementation)
ptrStack.push(new int{42});
std::cout << *ptrStack.top() << ’\n’;
delete ptrStack.pop();

Partial Specialization with Multiple Parameters
Class templates might also specialize the relationship between multiple template
parameters. For example, for the following class template:
Click here to view code image
template

the following partial specializations are possible:
Click here to view code image
// partial specialization: both template parameters have same
type
template
class MyClass {
…
};
// partial specialization: second type is int
template
class MyClass {
…
};
// partial specialization: both template parameters are pointer
types
template
class MyClass {
…
};

The following examples show which template is used by which declaration:
Click here to view code image
MyClass<
MyClass<
MyClass<
MyClass<

int, float> mif;
float, float> mff;
float, int> mfi;
int*, float*> mp;

//
//
//
//

uses
uses
uses
uses

MyClass
MyClass
MyClass
MyClass

If more than one partial specialization matches equally well, the declaration is
ambiguous:
Click here to view code image
MyClass< int, int> m;
MyClass< int*, int*> m;

// ERROR: matches MyClass
//
and MyClass
// ERROR: matches MyClass
//
and MyClass

To resolve the second ambiguity, you could provide an additional partial
specialization for pointers of the same type:
Click here to view code image
template
class MyClass {
…
};

For details of partial specialization, see Section 16.4 on page 347.

2.7 Default Class Template Arguments
As for function templates, you can define default values for class template
parameters. For example, in class Stack<> you can define the container that is
used to manage the elements as a second template parameter, using
std::vector<> as the default value:
Click here to view code image

basics/stack3.hpp
#include 
#include 
template>
class Stack {
private:
Cont elems;
// elements
public:
void push(T const& elem);
void pop();
T const& top() const;
bool empty() const {
empty

//
//
//
//

push element
pop element
return top element
return whether the stack is

return elems.empty();
}
};
template
void Stack::push (T const& elem)
{
elems.push_back(elem);
// append copy of passed elem}
template
void Stack::pop ()
{
assert(!elems.empty());
elems.pop_back();
}

// remove last element

template
T const& Stack::top () const
{
assert(!elems.empty());
return elems.back();
// return copy of last element
}

Note that we now have two template parameters, so each definition of a member
function must be defined with these two parameters:
Click here to view code image
template
void Stack::push (T const& elem)
{
elems.push_back(elem);
// append copy of passed elem
}

You can use this stack the same way it was used before. Thus, if you pass a first and
only argument as an element type, a vector is used to manage the elements of this
type:
Click here to view code image
template>
class Stack {
private:
Cont elems;
// elements
…
};

In addition, you could specify the container for the elements when you declare a

Stack object in your program:
Click here to view code image

basics/stack3test.cpp
#include "stack3.hpp"
#include 
#include 
int main()
{
// stack of ints:
Stack< int> intStack;
// stack of doubles using a std::deque<> to manage the elements
Stack< double,std::deque< double>> dblStack;
// manipulate int stack
intStack.push(7);
std::cout << intStack.top() << ’\n’;
intStack.pop();
// manipulate double stack
dblStack.push(42.42);
std::cout << dblStack.top() << ’\n’;
dblStack.pop();
}

With
Click here to view code image
Stack< double,std::deque< double>>

you declare a stack for doubles that uses a std::deque<> to manage the
elements internally.

2.8 Type Aliases
You can make using a class template more convenient by defining a new name for
the whole type.
Typedefs and Alias Declarations

To simply define a new name for a complete type, there are two ways to do it:
1. By using the keyword typedef:
Click here to view code image
typedef Stack
typedef Stack IntStack;
void foo (IntStack const& s);
IntStack istack[10];
stacks of ints

// typedef
// s is stack ofints
// istack is array of 10

We call this declaration a typedef3 and the resulting name is called a typedef-name.
2. By using the keyword using (since C++11):
Click here to view code image
using IntStack = Stack ;
void foo (IntStack const& s);
IntStack istack[10];
stacks of ints

// alias declaration
// s is stack of ints
// istack is array of 10

Introduced by [DosReisMarcusAliasTemplates], this is called an alias declaration.
Note that in both cases we define a new name for an existing type rather than a new
type. Thus, after the typedef
Click here to view code image
typedef Stack  IntStack;

or
Click here to view code image
using IntStack = Stack ;

IntStack and Stack are two interchangeable notations for the same type.
As a common term for both alternatives to define a new name for an existing type,
we use the term type alias declaration. The new name is a type alias then.
Because it is more readable (always having the defined type name on the left side
of the =, for the remainder of this book, we prefer the alias declaration syntax when
declaring an type alias.
Alias Templates
Unlike a typedef, an alias declaration can be templated to provide a convenient
name for a family of types. This is also available since C++11 and is called an alias
template.4
The following alias template DequeStack, parameterized over the element type T,

expands to a Stack that stores its elements in a std::deque:
Click here to view code image
template
using DequeStack = Stack>;

Thus, both class templates and alias templates can be used as a parameterized type.
But again, an alias template simply gives a new name to an existing type, which can
still be used. Both DequeStack and Stack> represent the same type.
Note again that, in general, templates can only be declared and defined in
global/namespace scope or inside class declarations.
Alias Templates for Member Types
Alias templates are especially helpful to define shortcuts for types that are members
of class templates. After
Click here to view code image
struct C {
typedef … iterator;
…
};

or:
Click here to view code image
struct MyType {
using iterator = …;
…
};

a definition such as
Click here to view code image
template
using MyTypeIterator = typename MyType::iterator;

allows the use of
Click here to view code image
MyTypeIterator< int> pos;

instead of the following:5
Click here to view code image

typename MyType::iterator pos;

Type Traits Suffix_t
Since C++14, the standard library uses this technique to define shortcuts for all type
traits in the standard library that yield a type. For example, to be able to write
Click here to view code image
std::add_const_t

// since C++14

instead of
Click here to view code image
typename std::add_const::type

// since C++11

the standard library defines:
Click here to view code image
namespace std {
template using add_const_t = typename
add_const::type;
}

2.9 Class Template Argument Deduction
Until C++17, you always had to pass all template parameter types to class templates
(unless they have default values). Since C++17, the constraint that you always have
to specify the template arguments explicitly was relaxed. Instead, you can skip to
define the templates arguments explicitly, if the constructor is able to deduce all
template parameters (that don’t have a default value),
For example, in all previous code examples, you can use a copy constructor
without specifying the template arguments:
Click here to view code image
Stack< int> intStack1;
Stack< int> intStack2 = intStack1;
Stack intStack3 = intStack1;

// stack of strings
// OK in all versions
// OK since C++17

By providing constructors that pass some initial arguments, you can support
deduction of the element type of a stack. For example, we could provide a stack that
can be initialized by a single element:
Click here to view code image

template
class Stack {
private:
std::vector elems;
public:
Stack () = default;
Stack (T const& elem)
element
: elems({elem}) {
}
…
};

// elements

// initialize stack with one

This allows you to declare a stack as follows:
Click here to view code image
Stack intStack = 0;
C++17

// Stack deduced since

By initializing the stack with the integer 0, the template parameter T is deduced to be
int, so that a Stack is instantiated.
Note the following:
• Due to the definition of the int constructor, you have to request the default
constructors to be available with its default behavior, because the default
constructor is available only if no other constructor is defined:
Stack() = default;

• The argument elem is passed to elems with braces around to initialize the vector
elems with an initializer list with elem as the only argument:
: elems({elem})

There is no constructor for a vector that is able to take a single parameter as initial
element directly.6
Note that, unlike for function templates, class template arguments may not be
deduced only partially (by explicitly specifying only some of the template
arguments). See Section 15.12 on page 314 for details.
Class Template Arguments Deduction with String Literals
In principle, you can even initialize the stack with a string literal:
Click here to view code image
Stack stringStack = "bottom"; // Stack deduced
since C++17

But this causes a lot of trouble: In general, when passing arguments of a template
type T by reference, the parameter doesn’t decay, which is the term for the
mechanism to convert a raw array type to the corresponding raw pointer type. This
means that we really initialize a
Stack< char const[7]>

and use type char const[7] wherever T is used. For example, we may not push
a string of different size, because it has a different type. For a detailed discussion see
Section 7.4 on page 115.
However, when passing arguments of a template type T by value, the parameter
decays, which is the term for the mechanism to convert a raw array type to the
corresponding raw pointer type. That is, the call parameter T of the constructor is
deduced to be char const* so that the whole class is deduced to be a
Stack.
For this reason, it might be worthwhile to declare the constructor so that the
argument is passed by value:
Click here to view code image
template
class Stack {
private:
std::vector elems;
public:
Stack (T elem)
element by value
: elems({elem}) {
arg deduction
}
…
};

// elements
// initialize stack with one
//

to decay on class tmpl

With this, the following initialization works fine:
Click here to view code image
Stack stringStack = "bottom"; // Stack deduced
since C++17

In this case, however, we should better move the temporary elem into the stack to
avoid unnecessarily copying it:
Click here to view code image
template
class Stack {
private:

std::vector elems;
// elements
public:
Stack (T elem)
// initialize stack with one
element by value
: elems({std::move(elem)}) {
}
…
};

Deduction Guides
Instead of declaring the constructor to be called by value, there is a different
solution: Because handling raw pointers in containers is a source of trouble, we
should disable automatically deducing raw character pointers for container classes.
You can define specific deduction guides to provide additional or fix existing class
template argument deductions. For example, you can define that whenever a string
literal or C string is passed, the stack is instantiated for std::string:
Click here to view code image
Stack( char const*) -> Stack;

This guide has to appear in the same scope (namespace) as the class definition.
Usually, it follows the class definition. We call the type following the -> the guided
type of the deduction guide.
Now, the declaration with
Click here to view code image
Stack stringStack{"bottom"};
deduced since C++17

// OK: Stack

deduces the stack to be a Stack. However, the following still
doesn’t work:
Click here to view code image
Stack stringStack = "bottom"; // Stack deduced, but
still not valid

We deduce std::string so that we instantiate a Stack:
Click here to view code image
class Stack {
private:
std::vector elems;
public:
Stack (std::string const& elem)

// elements
// initialize stack

with one element
: elems({elem}) {
}
…
};

However, by language rules, you can’t copy initialize (initialize using =) an object
by passing a string literal to a constructor expecting a std::string. So you have
to initialize the stack as follows:
Click here to view code image
Stack stringStack{"bottom"}; // Stack deduced and
valid

Note that, if in doubt, class template argument deduction copies. After declaring
stringStack as Stack the following initializations declare
the same type (thus, calling the copy constructor) instead of initializing a stack by
elements that are string stacks:
Click here to view code image
Stack stack2{stringStack};
Stack stack3(stringStack);
Stack stack4 = {stringStack};

// Stack deduced
// Stack deduced
// Stack deduced

See Section 15.12 on page 313 for more details about class template argument
deduction.

2.10 Templatized Aggregates
Aggregate classes (classes/structs with no user-provided, explicit, or inherited
constructors, no private or protected nonstatic data members, no virtual functions,
and no virtual, private, or protected base classes) can also be templates. For example:
Click here to view code image
template
struct ValueWithComment {
T value;
std::string comment;
};

defines an aggregate parameterized for the type of the value val it holds. You can
declare objects as for any other class template and still use it as aggregate:
Click here to view code image

ValueWithComment< int> vc;
vc.value = 42;
vc.comment = "initial value";

Since C++17, you can even define deduction guides for aggregate class templates:
Click here to view code image
ValueWithComment(
char const*, char const*)
-> ValueWithComment;
ValueWithComment vc2 = {"hello", "initial value"};

Without the deduction guide, the initialization would not be possible, because
ValueWithComment has no constructor to perform the deduction against.
The standard library class std::array<> is also an aggregate, parameterized
for both the element type and the size. The C++17 standard library also defines a
deduction guide for it, which we discuss in Section 4.4.4 on page 64.

2.11 Summary
• A class template is a class that is implemented with one or more type parameters
left open.
• To use a class template, you pass the open types as template arguments. The class
template is then instantiated (and compiled) for these types.
• For class templates, only those member functions that are called are instantiated.
• You can specialize class templates for certain types.
• You can partially specialize class templates for certain types.
• Since C++17, class template arguments can automatically be deduced from
constructors.
• You can define aggregate class templates.
• Call parameters of a template type decay if declared to be called by value.
• Templates can only be declared and defined in global/namespace scope or inside
class declarations.
1

C++17 introduced class argument template deduction, which allows skipping
template arguments if they can be derived from the constructor. This will be
discussed in Section 2.9 on page 40.
2 It is a templated entity, see Section 12.1 on page 181.
3 Using the word typedef instead of “type definition” in intentional. The keyword
typedef was originally meant to suggest “type definition.” However, in C++,

“type definition” really means something else (e.g., the definition of a class or
enumeration type). Instead, a typedef should just be thought of as an alternative
name (an “alias”) for an existing type, which can be done by a typedef.
4 Alias templates are sometimes (incorrectly) referred to as typedef templates
because they fulfill the same role that a typedef would if it could be made into a
template.
5 The typename is necessary here because the member is a type. See Section 5.1
on page 67 for details.
6 Even worse, there is a vector constructor taking one integral argument as initial
size, so that for a stack with the initial value 5, the vector would get an initial size
of five elements when : elems(elem) is used.

Chapter 3
Nontype Template Parameters
For function and class templates, template parameters don’t have to be types. They
can also be ordinary values. As with templates using type parameters, you define
code for which a certain detail remains open until the code is used. However, the
detail that is open is a value instead of a type. When using such a template, you have
to specify this value explicitly. The resulting code then gets instantiated. This chapter
illustrates this feature for a new version of the stack class template. In addition, we
show an example of nontype function template parameters and discuss some
restrictions to this technique.

3.1 Nontype Class Template Parameters
In contrast to the sample implementations of a stack in previous chapters, you can
also implement a stack by using a fixed-size array for the elements. An advantage of
this method is that the memory management overhead, whether performed by you or
by a standard container, is avoided. However, determining the best size for such a
stack can be challenging. The smaller the size you specify, the more likely it is that
the stack will get full. The larger the size you specify, the more likely it is that
memory will be reserved unnecessarily. A good solution is to let the user of the stack
specify the size of the array as the maximum size needed for stack elements.
To do this, define the size as a template parameter:
Click here to view code image

basics/stacknontype.hpp
#include 
#include 
template
class Stack {
private:

std::array elems;
std::size_t numElems;
public:
Stack();
void push(T const& elem);
void pop();
T const& top() const;
bool empty() const {
empty
return numElems == 0;
}
std::size_t size() const {
elements
return numElems;
}
};

// elements
// current number of elements
// constructor
// push element
// pop element
// return top element
//return whether the stack is

//return current number of

template
Stack::Stack ()
: numElems(0)
//start with no elements
{
// nothing else to do
}
template
void Stack::push (T const& elem)
{
assert(numElems < Maxsize);
elems[numElems] = elem;
// append element
++numElems;
// increment number of elements
}
template
void Stack::pop ()
{
assert(!elems.empty());
--numElems;
// decrement number of elements
}
template
T const& Stack::top () const
{
assert(!elems.empty());
return elems[numElems-1]; // return last element
}

The new second template parameter, Maxsize, is of type int. It specifies the size

of the internal array of stack elements:
Click here to view code image
template
class Stack {
private:
std::array elems; // elements
…
};

In addition, it is used in push() to check whether the stack is full:
Click here to view code image
template
void Stack::push (T const& elem)
{
assert(numElems < Maxsize);
elems[numElems] = elem;
// append element
++numElems;
// increment number of elements
}

To use this class template you have to specify both the element type and the
maximum size:
Click here to view code image

basics/stacknontype.cpp
#include "stacknontype.hpp"
#include 
#include 
int main()
{
Stack
int20Stack;
ints
Stack
int40Stack;
ints
Stack stringStack;
strings

// stack of up to 20
// stack of up to 40
// stack of up to 40

// manipulate stack of up to 20 ints
int20Stack.push(7);
std::cout << int20Stack.top() << ’\n’;
int20Stack.pop();
// manipulate stack of up to 40 strings
stringStack.push("hello");

std::cout << stringStack.top() << ’\n’;
stringStack.pop();
}

Note that each template instantiation is its own type. Thus, int20Stack and
int40Stack are two different types, and no implicit or explicit type conversion
between them is defined. Thus, one cannot be used instead of the other, and you
cannot assign one to the other.
Again, default arguments for the template parameters can be specified:
Click here to view code image
template
class Stack {
…
};

However, from a perspective of good design, this may not be appropriate in this
example. Default arguments should be intuitively correct. But neither type int nor a
maximum size of 100 seems intuitive for a general stack type. Thus, it is better when
the programmer has to specify both values explicitly so that these two attributes are
always documented during a declaration.

3.2 Nontype Function Template Parameters
You can also define nontype parameters for function templates. For example, the
following function template defines a group of functions for which a certain value
can be added:
Click here to view code image

basics/addvalue.hpp
template
T addValue (T x)
{
return x + Val;
}

These kinds of functions can be useful if functions or operations are used as
parameters. For example, if you use the C++ standard library you can pass an
instantiation of this function template to add a value to each element of a collection:
Click here to view code image

std::transform (source.begin(), source.end(),
of source
dest.begin(),
destination
addValue<5,int>);

//start and end
//start of
// operation

The last argument instantiates the function template addValue<>() to add 5 to a
passed int value. The resulting function is called for each element in the source
collection source, while it is translated into the destination collection dest.
Note that you have to specify the argument int for the template parameter T of
addValue<>(). Deduction only works for immediate calls and
std::transform() need a complete type to deduce the type of its fourth
parameter. There is no support to substitute/deduce only some template parameters
and the see, what could fit, and deduce the remaining parameters.
Again, you can also specify that a template parameter is deduced from the
previous parameter. For example, to derive the return type from the passed nontype:
Click here to view code image
template
T foo();

or to ensure that the passed value has the same type as the passed type:
Click here to view code image
template
T bar();

3.3 Restrictions for Nontype Template Parameters
Note that nontype template parameters carry some restrictions. In general, they can
be only constant integral values (including enumerations), pointers to
objects/functions/members, lvalue references to objects or functions, or
std::nullptr_t (the type of nullptr).
Floating-point numbers and class-type objects are not allowed as nontype template
parameters:
Click here to view code image
template
not
double process (double v)
parameters
{
return v * VAT;

// ERROR: floating-point values are
//

allowed as template

}
template
not
class MyClass {
parameters
…
};

// ERROR: class-type objects are
//

allowed as template

When passing template arguments to pointers or references, the objects must not be
string literals, temporaries, or data members and other subobjects. Because these
restrictions were relaxed with each and every C++ version before C++17, additional
constraints apply:
• In C++11, the objects also had to have external linkage.
• In C++14, the objects also had to have external or internal linkage.
Thus, the following is not possible:
Click here to view code image
template
class MyClass {
…
};
MyClass<"hello"> x;

//ERROR: string literal "hello" not allowed

However there are workarounds (again depending on the C++ version):
Click here to view code image
extern char const s03[] = "hi";
char const s11[] = "hi";
int main()
{
Message m03;
Message m11;
static char const s17[] = "hi";
Message m17;
}

// external linkage
// internal linkage

//
//
//
//

OK
OK
no
OK

(all versions)
since C++11
linkage
since C++17

In all three cases a constant character array is initialized by "hello" and this object
is used as a template parameter declared with char const*. This is valid in all
C++ versions if the object has external linkage (s03), in C++11 and C++14 also if it
has internal linkage (s11), and since C++17 if it has no linkage at all.
See Section 12.3.3 on page 194 for a detailed discussion and Section 17.2 on page
354 for a discussion of possible future changes in this area.

Avoiding Invalid Expressions
Arguments for nontype template parameters might be any compile-time expressions.
For example:
Click here to view code image
template
class C;
…
C c;

However, note that if operator> is used in the expression, you have to put the
whole expression into parentheses so that the nested > ends the argument list:
Click here to view code image
C<42, sizeof(int) > 4> c;
argument list
C<42, (sizeof(int) > 4)> c;

// ERROR: first > ends the template
// OK

3.4 Template Parameter Type auto
Since C++17, you can define a nontype template parameter to generically accept any
type that is allowed for a nontype parameter. Using this feature, we can provide an
even more generic stack class with fixed size:
Click here to view code image

basics/stackauto.hpp
#include 
#include 
template
class Stack {
public:
using size_type = decltype(Maxsize);
private:
std::array elems; // elements
size_type numElems;
// current number of elements
public:
Stack();
// constructor
void push(T const& elem);
// push element
void pop();
// pop element
T const& top() const;
// return top element
bool empty() const {
//return whether the stack is

empty
return numElems == 0;
}
size_type size() const {
elements
return numElems;
}
};

//return current number of

// constructor
template
Stack::Stack ()
: numElems(0)
//start with no elements
{
// nothing else to do
}
template
void Stack::push (T const& elem)
{
assert(numElems < Maxsize);
elems[numElems] = elem;
// append element
++numElems;
// increment number of elements
}
template
void Stack::pop ()
{
assert(!elems.empty());
--numElems;
// decrement number of elements
}
template
T const& Stack::top () const
{
assert(!elems.empty());
return elems[numElems-1]; // return last element
}

By defining
Click here to view code image
template
class Stack {
…
};

by using the placeholder type auto, you define Maxsize to be a value of a type

not specified yet. It might be any type that is allowed to be a nontype template
parameter type.
Internally you can use both the value:
Click here to view code image
std::array elems;

// elements

and its type:
Click here to view code image
using size_type = decltype(Maxsize);

which is then, for example, used as return type of the size() member function:
Click here to view code image
size_type size() const {
elements
return numElems;
}

//return current number of

Since C++14, you could also just use auto here as return type to let the compiler
find out the return type:
Click here to view code image
auto size() const {
return numElems;
}

//return current number of elements

With this class declaration the type of the number of elements is defined by the type
used for the number of elements, when using a stack:
Click here to view code image

basics/stackauto.cpp
#include 
#include 
#include "stackauto.hpp"
int main()
{
Stack
int20Stack;
Stack stringStack;
strings

// stack of up to 20 ints
// stack of up to 40

// manipulate stack of up to 20 ints
int20Stack.push(7);
std::cout << int20Stack.top() << ’\n’;

auto size1 = int20Stack.size();
// manipulate stack of up to 40 strings
stringStack.push("hello");
std::cout << stringStack.top() << ’\n’;
auto size2 = stringStack.size();
if (!std::is_same_v) {
std::cout << "size types differ" << ’\n’;
}
}

With
Click here to view code image
Stack int20Stack;

// stack of up to 20 ints

the internal size type is unsigned int, because 20u is passed.
With
Click here to view code image
Stack stringStack;
strings

// stack of up to 40

the internal size type is int, because 40 is passed.
size() for the two stacks will have different return types, so that after
Click here to view code image
auto size1 = int20Stack.size();
…
auto size2 = stringStack.size();

the types of size1 and size2 differ. By using the standard type trait
std::is_same (see Section D.3.3 on page 726) and decltype, we can check
that:
Click here to view code image
if (!std::is_same::value) {
std::cout << "size types differ" << ’\n’;
}

Thus, the output will be:
size types differ

Since C++17, for traits returning values, you can also use the suffix _v and skip
::value (see Section 5.6 on page 83 for details):

Click here to view code image
if (!std::is_same_v) {
std::cout << "size types differ" << ’\n’;
}

Note that other constraints on the type of nontype template parameters remain in
effect. Especially, the restrictions about possible types for nontype template
arguments discussed in Section 3.3 on page 49 still apply. For example:
Click here to view code image
Stack sd;
argument

// ERROR: Floating-point nontype

And, because you can also pass strings as constant arrays (since C++17 even static
locally declared; see Section 3.3 on page 49), the following is possible:
basics/message.cpp
Click here to view code image
#include 
template
// take value of any possible nontype
parameter (since C++17)
class Message {
public:
void print() {
std::cout << T << ’\n’;
}
};
int main()
{
Message<42> msg1;
msg1.print();
value

// initialize with int 42 and print that

static char const s[] = "hello";
Message msg2;
// initialize with char const[6] "hello"
msg2.print();
// and print that value
}

Note also that even template is possible, which allows
instantiation of N as a reference:
Click here to view code image
template

class C {
…
};
int i;
C<(i)> x;

// N is int&

See Section 15.10.1 on page 296 for details.

3.5 Summary
• Templates can have template parameters that are values rather than types.
• You cannot use floating-point numbers or class-type objects as arguments for
nontype template parameters. For pointers/references to string literals, temporaries,
and subobjects, restrictions apply.
• Using auto enables templates to have nontype template parameters that are values
of generic types.

Chapter 4
Variadic Templates
Since C++11, templates can have parameters that accept a variable number of
template arguments. This feature allows the use of templates in places where you
have to pass an arbitrary number of arguments of arbitrary types. A typical
application is to pass an arbitrary number of parameters of arbitrary type through a
class or framework. Another application is to provide generic code to process any
number of parameters of any type.

4.1 Variadic Templates
Template parameters can be defined to accept an unbounded number of template
arguments. Templates with this ability are called variadic templates.

4.1.1 Variadic Templates by Example
For example, you can use the following code to call print() for a variable number
of arguments of different types:
Click here to view code image

basics/varprint1.hpp
#include 
void print ()
{
}
template
void print (T firstArg, Types… args)
{
std::cout << firstArg << ’\n’; //print first argument

print(args…);
arguments
}

// call print() for remaining

If one or more arguments are passed, the function template is used, which by
specifying the first argument separately allows printing of the first argument before
recursively calling print() for the remaining arguments. These remaining
arguments named args are a function parameter pack:
Click here to view code image
void print (T firstArg, Types… args)

using different “Types” specified by a template parameter pack:
Click here to view code image
template

To end the recursion, the nontemplate overload of print() is provided, which is
issued when the parameter pack is empty.
For example, a call such as
Click here to view code image
std::string s("world");
print (7.5, "hello", s);

would output the following:
Click here to view code image
7.5
hello
world

The reason is that the call first expands to
Click here to view code image
print (7.5, "hello", s);

with
• firstArg having the value 7.5 so that type T is a double and
• args being a variadic template argument having the values "hello" of type
char const* and "world" of type std::string.
After printing 7.5 as firstArg, it calls print() again for the remaining
arguments, which then expands to:
Click here to view code image

print ("hello", s);

with
• firstArg having the value "hello" so that type T is a char const* here
and
• args being a variadic template argument having the value of type
std::string.
After printing "hello" as firstArg, it calls print() again for the remaining
arguments, which then expands to:
Click here to view code image
print (s);

with
• firstArg having the value "world" so that type T is a std::string now
and
• args being an empty variadic template argument having no value.
Thus, after printing "world" as firstArg, we calls print() with no
arguments, which results in calling the nontemplate overload of print() doing
nothing.

4.1.2 Overloading Variadic and Nonvariadic Templates
Note that you can also implement the example above as follows:
Click here to view code image

basics/varprint2.hpp
#include 
template
void print (T arg)
{
std::cout << arg << ’\n’;
}

//print passed argument

template
void print (T firstArg, Types… args)
{
print(firstArg);
// call print() for the first
argument
print(args…);
// call print() for remaining

arguments
}

That is, if two function templates only differ by a trailing parameter pack, the
function template without the trailing parameter pack is preferred.1 Section C.3.1 on
page 688 explains the more general overload resolution rule that applies here.

4.1.3 Operator sizeof…
C++11 also introduced a new form of the sizeof operator for variadic templates:
sizeof…. It expands to the number of elements a parameter pack contains. Thus,
Click here to view code image
template
void print (T firstArg, Types… args)
{
std::cout << sizeof…(Types) << ’\n’;
remaining types
std::cout << sizeof…(args) << ’\n’;
remaining args
…
}

//print number of
//print number of

twice prints the number of remaining arguments after the first argument passed to
print(). As you can see, you can call sizeof… for both template parameter
packs and function parameter packs.
This might lead us to think we can skip the function for the end of the recursion by
not calling it in case there are no more arguments:
Click here to view code image
template
void print (T firstArg, Types… args)
{
std::cout << firstArg << ’\n’;
if (sizeof…(args) > 0) {
//error if sizeof…(args)==0
print(args…);
// and no print() for no
arguments declared
}
}

However, this approach doesn’t work because in general both branches of all if
statements in function templates are instantiated. Whether the instantiated code is
useful is a run-time decision, while the instantiation of the call is a compile-time

decision. For this reason, if you call the print() function template for one (last)
argument, the statement with the call of print(args…) still is instantiated for no
argument, and if there is no function print() for no arguments provided, this is an
error.
However, note that since C++17, a compile-time if is available, which achieves
what was expected here with a slightly different syntax. This will be discussed in
Section 8.5 on page 134.

4.2 Fold Expressions
Since C++17, there is a feature to compute the result of using a binary operator over
all the arguments of a parameter pack (with an optional initial value).
For example, the following function returns the sum of all passed arguments:
Click here to view code image
template
auto foldSum (T… s) {
return (… + s);
// ((s1 + s2) + s3) …
}

If the parameter pack is empty, the expression is usually ill-formed (with the
exception that for operator && the value is true, for operator || the value is
false, and for the comma operator the value for an empty parameter pack is
void()).
Table 4.1 lists the possible fold expressions.
Fold Expression

Evaluation

( … op pack )

((( pack1 op pack2 ) op pack3 ) … op packN )

( pack op … )

( pack1 op ( … ( packN-1 op packN )))

( init op … op pack )

((( init op pack1 ) op pack2 ) … op packN )

( pack op … op init )

( pack1 op ( … ( packN op init )))

Table 4.1. Fold Expressions (since C++17)
You can use almost all binary operators for fold expressions (see Section 12.4.6
on page 208 for details). For example, you can use a fold expression to traverse a
path in a binary tree using operator ->*:

Click here to view code image

basics/foldtraverse.cpp
// define binary tree structure and traverse helpers:
struct Node {
int value;
Node* left;
Node* right;
Node(int i=0) : value(i), left(nullptr), right(nullptr) {
}
…
};
auto left = &Node::left;
auto right = &Node::right;
// traverse tree, using fold expression:
template
Node* traverse (T np, TP… paths) {
return (np ->* … ->* paths); // np ->* paths1 ->* paths2 …
}
int main()
{
// init binary tree structure:
Node* root = new Node{0};
root->left = new Node{1};
root->left->right = new Node{2};
…
// traverse binary tree:
Node* node = traverse(root, left, right);
…
}

Here,
(np ->* … ->* paths)

uses a fold expression to traverse the variadic elements of paths from np.
With such a fold expression using an initializer, we might think about simplifying
the variadic template to print all arguments, introduced above:
Click here to view code image
template
void print (Types const&… args)
{
(std::cout << … << args) << ’\n’;

}

However, note that in this case no whitespace separates all the elements from the
parameter pack. To do that, you need an additional class template, which ensures that
any output of any argument is extended by a space:
basics/addspace.hpp
Click here to view code image
template
class AddSpace
{
private:
T const& ref;
// refer to argument passed in
constructor
public:
AddSpace(T const& r): ref(r) {
}
friend std::ostream& operator<< (std::ostream& os,
AddSpace s) {
return os << s.ref <<’’;
// output passed argument and a
space
}
};
template
void print (Args… args) {
( std::cout << … << AddSpace(args) ) << ’\n’;
}

Note that the expression AddSpace(args) uses class template argument
deduction (see Section 2.9 on page 40) to have the effect of AddSpace
(args), which for each argument creates an AddSpace object that refers to the
passed argument and adds a space when it is used in output expressions.
See Section 12.4.6 on page 207 for details about fold expressions.

4.3 Application of Variadic Templates
Variadic templates play an important role when implementing generic libraries, such
as the C++ standard library.
One typical application is the forwarding of a variadic number of arguments of
arbitrary type. For example, we use this feature when:

• Passing arguments to the constructor of a new heap object owned by a shared
pointer:
Click here to view code image
// create shared pointer to complex initialized by 4.2
and 7.7:
auto sp = std::make_shared>(4.2, 7.7);

• Passing arguments to a thread, which is started by the library:
Click here to view code image
std::thread t (foo, 42, "hello");
in a separate thread

//call foo(42,"hello")

• Passing arguments to the constructor of a new element pushed into a vector:
Click here to view code image
std::vector v;
…
v.emplace("Tim", "Jovi", 1962);
initialized by three arguments

//insert a Customer

Usually, the arguments are “perfectly forwarded” with move semantics (see Section
6.1 on page 91), so that the corresponding declarations are, for example:
Click here to view code image
namespace std {
template shared_ptr
make_shared(Args&&… args);
class thread {
public:
template
explicit thread(F&& f, Args&&… args);
…
};
template>
class vector {
public:
template reference emplace_back(Args&&…
args);
…
};
}

Note also that the same rules apply to variadic function template parameters as for
ordinary parameters. For example, if passed by value, arguments are copied and

decay (e.g., arrays become pointers), while if passed by reference, parameters refer
to the original parameter and don’t decay:
Click here to view code image
// args are copies with decayed types:
template void foo (Args… args);
// args are nondecayed references to passed objects:
template void bar (Args const&… args);

4.4 Variadic Class Templates and Variadic Expressions
Besides the examples above, parameter packs can appear in additional places,
including, for example, expressions, class templates, using declarations, and even
deduction guides. Section 12.4.2 on page 202 has a complete list.

4.4.1 Variadic Expressions
You can do more than just forward all the parameters. You can compute with them,
which means to compute with all the parameters in a parameter pack.
For example, the following function doubles each parameter of the parameter pack
args and passes each doubled argument to print():
Click here to view code image
template
void printDoubled (T const&… args)
{
print (args + args…);
}

If, for example, you call
Click here to view code image
printDoubled(7.5, std::string("hello"), std::complex
(4,2));

the function has the following effect (except for any constructor side effects):
Click here to view code image
print(7.5 + 7.5,
std::string("hello") + std::string("hello"),
std::complex(4,2) + std::complex(4,2);

If you just want to add 1 to each argument, note that the dots from the ellipsis may

not directly follow a numeric literal:
Click here to view code image
template
void addOne (T const&… args)
{
print (args + 1…);
// ERROR: 1… is a literal with too many
decimal points
print (args + 1 …);
// OK
print ((args + 1)…); // OK
}

Compile-time expressions can include template parameter packs in the same way.
For example, the following function template returns whether the types of all the
arguments are the same:
Click here to view code image
template
constexpr bool isHomogeneous (T1, TN…)
{
return (std::is_same::value && …);
}

// since C++17

This is an application of fold expressions (see Section 4.2 on page 58): For
Click here to view code image
isHomogeneous(43, -1, "hello")

the expression for the return value expands to
Click here to view code image
std::is_same::value && std::is_same::value

and yields false, while
Click here to view code image
isHomogeneous("hello", "", "world", "!")

yields true because all passed arguments are deduced to be char const* (note
that the argument types decay because the call arguments are passed by value).

4.4.2 Variadic Indices
As another example, the following function uses a variadic list of indices to access

the corresponding element of the passed first argument:
Click here to view code image
template
void printElems (C const& coll, Idx… idx)
{
print (coll[idx]…);
}

That is, when calling
Click here to view code image
std::vector coll = {"good", "times", "say", "bye"};
printElems(coll,2,0,3);

the effect is to call
Click here to view code image
print (coll[2], coll[0], coll[3]);

You can also declare nontype template parameters to be parameter packs. For
example:
Click here to view code image
template
void printIdx (C const& coll)
{
print(coll[Idx]…);
}

allows you to call
Click here to view code image
std::vector coll = {"good", "times", "say", "bye"};
printIdx<2,0,3>(coll);

which has the same effect as the previous example.

4.4.3 Variadic Class Templates
Variadic templates can also be class templates. An important example is a class
where an arbitrary number of template parameters specify the types of corresponding
members:
Click here to view code image
template

class Tuple;
Tuple t;
string, and character

// t can hold integer,

This will be discussed in Chapter 25.
Another example is to be able to specify the possible types objects can have:
Click here to view code image
template
class Variant;

Variant v;
// v can hold integer,
string, or character
This will be discussed in Chapter 26.
You can also define a class that as a type represents a list of indices:
Click here to view code image
// type for arbitrary number of indices:
template
struct Indices {
};

This can be used to define a function that calls print() for the elements of a
std::array or std::tuple using the compile-time access with get<>() for
the given indices:
Click here to view code image
template
void printByIdx(T t, Indices)
{
print(std::get(t)…);
}

This template can be used as follows:
Click here to view code image
std::array arr = {"Hello", "my", "new", "!",
"World"}; printByIdx(arr, Indices<0, 4, 3>());

or as follows:
Click here to view code image
auto t = std::make_tuple(12, "monkeys", 2.0);
printByIdx(t, Indices<0, 1, 2>());

This is a first step towards meta-programming, which will be discussed in Section

8.1 on page 123 and Chapter 23.

4.4.4 Variadic Deduction Guides
Even deduction guides (see Section 2.9 on page 42) can be variadic. For example,
the C++ standard library defines the following deduction guide for std::arrays:
Click here to view code image
namespace std {
template array(T, U…)
-> array && …), T>,
(1 + sizeof…(U))>;
}

An initialization such as
std::array a{42,45,77};

deduces T in the guide to the type of the element, and the various U… types to the
types of the subsequent elements. The total number of elements is therefore 1 +
sizeof…(U):
Click here to view code image
std::array a{42,45,77};

The std::enable_if<> expression for the first array parameter is a fold
expression that (as introduced as isHomogeneous() in Section 4.4.1 on page 62)
expands to:
Click here to view code image
is_same_v && is_same_v && is_same_v …

If the result is not true (i.e., not all the element types are the same), the deduction
guide is discarded and the overall deduction fails. This way, the standard library
ensures that all elements must have the same type for the deduction guide to succeed.

4.4.5 Variadic Base Classes and using
Finally, consider the following example:
Click here to view code image

basics/varusing.cpp

#include 
#include 
class Customer
{
private:
std::string name;
public:
Customer(std::string const& n) : name(n) { }
std::string getName() const { return name; }
};
struct CustomerEq {
bool operator() (Customer const& c1, Customer const& c2)
const {
return c1.getName() == c2.getName();
}
};
struct CustomerHash {
std::size_t operator() (Customer const& c) const {
return std::hash()(c.getName());
}
};
// define class that combines operator() for variadic base
classes:
template
struct Overloader : Bases…
{
using Bases::operator()…; // OK since C++17
};
int main()
{
// combine hasher and equality for customers in one type:
using CustomerOP = Overloader;
std::unordered_set coll1;
std::unordered_set coll2;
…
}

Here, we first define a class Customer and independent function objects to hash
and compare Customer objects. With
Click here to view code image

template
struct Overloader : Bases…
{
using Bases::operator()…;
};

// OK since C++17

we can define a class derived from a variadic number of base classes that brings in
the operator() declarations from each of those base classes. With
Click here to view code image
using CustomerOP = Overloader;

we use this feature to derive CustomerOP from CustomerHash and
CustomerEq and enable both implementations of operator() in the derived
class.
See Section 26.4 on page 611 for another application of this technique.

4.5 Summary
• By using parameter packs, templates can be defined for an arbitrary number of
template parameters of arbitrary type.
• To process the parameters, you need recursion and/or a matching nonvariadic
function.
• Operator sizeof… yields the number of arguments provided for a parameter pack.
• A typical application of variadic templates is forwarding an arbitrary number of
arguments of arbitrary type.
• By using fold expressions, you can apply operators to all arguments of a parameter
pack.
1 Initially, in C++11 and C++14 this was an ambiguity, which was fixed later (see
[CoreIssue1395]), but all compilers handle it this way in all versions.

Chapter 5
Tricky Basics
This chapter covers some further basic aspects of templates that are relevant to the
practical use of templates: an additional use of the typename keyword, defining
member functions and nested classes as templates, template template parameters,
zero initialization, and some details about using string literals as arguments for
function templates. These aspects can be tricky at times, but every day-to-day
programmer should have heard of them.

5.1 Keyword typename
The keyword typename was introduced during the standardization of C++ to
clarify that an identifier inside a template is a type. Consider the following example:
Click here to view code image
template
class MyClass {
public:
…
void foo() {
typename T::SubType* ptr;
}
};

Here, the second typename is used to clarify that SubType is a type defined
within class T. Thus, ptr is a pointer to the type T::SubType.
Without typename, SubType would be assumed to be a nontype member (e.g.,
a static data member or an enumerator constant). As a result, the expression
T::SubType* ptr

would be a multiplication of the static SubType member of class T with ptr,
which is not an error, because for some instantiations of MyClass<> this could be
valid code.

In general, typename has to be used whenever a name that depends on a
template parameter is a type. This is discussed in detail in Section 13.3.2 on page
228.
One application of typename is the declaration to iterators of standard containers
in generic code:
Click here to view code image

basics/printcoll.hpp
#include 
// print elements of an STL container
template
void printcoll (T const& coll)
{
typename T::const_iterator pos; // iterator to iterate over
coll
typename T::const_iterator end(coll.end()); // end position
for (pos=coll.begin(); pos!=end; ++pos) {
std::cout << *pos << ’ ’;
}
std::cout << ’\n’;
}

In this function template, the call parameter is an standard container of type T. To
iterate over all elements of the container, the iterator type of the container is used,
which is declared as type const_iterator inside each standard container class:
Click here to view code image
class stlcontainer {
public:
using iterator = …;
using const_iterator = …;
…
};

// iterator for read/write access
// iterator for read access

Thus, to access type const_iterator of template type T, you have to qualify it
with a leading typename:
Click here to view code image
typename T::const_iterator pos;

See Section 13.3.2 on page 228 for more details about the need for typename until
C++17. Note that C++20 will probably remove the need for typename in many
common cases (see Section 17.1 on page 354 for details).

5.2 Zero Initialization
For fundamental types such as int, double, or pointer types, there is no default
constructor that initializes them with a useful default value. Instead, any
noninitialized local variable has an undefined value:
Click here to view code image
void foo()
{
int x;
int* ptr;
}

// x has undefined value
// ptr points to anywhere (instead of nowhere)

Now if you write templates and want to have variables of a template type initialized
by a default value, you have the problem that a simple definition doesn’t do this for
built-in types:
Click here to view code image
template
void foo()
{
T x;
// x has undefined value if T is built-in type
}

For this reason, it is possible to call explicitly a default constructor for built-in types
that initializes them with zero (or false for bool or nullptr for pointers). As a
consequence, you can ensure proper initialization even for built-in types by writing
the following:
Click here to view code image
template
void foo()
{
T x{};
// x is zero (or false) if T is a built-in type
}

This way of initialization is called value initialization, which means to either call a
provided constructor or zero initialize an object. This even works if the constructor is
explicit.
Before C++11, the syntax to ensure proper initialization was
Click here to view code image
T x = T();

// x is zero (or false) if T is a built-in type

Prior to C++17, this mechanism (which is still supported) only worked if the

constructor selected for the copy-initialization is not explicit. In C++17,
mandatory copy elision avoids that limitation and either syntax can work, but the
braced initialized notation can use an initializer-list constructor1 if no default
constructor is available.
To ensure that a member of a class template, for which the type is parameterized,
gets initialized, you can define a default constructor that uses a braced initializer to
initialize the member:
Click here to view code image
template
class MyClass {
private:
T x;
public:
MyClass() : x{} {
built-in types
}
…
};

// ensures that x is initialized even for

The pre-C++11 syntax
Click here to view code image
MyClass() : x() {
built-in types
}

//ensures that x is initialized even for

also still works.
Since C++11, you can also provide a default initialization for a nonstatic member,
so that the following is also possible:
Click here to view code image
template
class MyClass {
private:
T x{};
specified
…
};

// zero-initialize x unless otherwise

However, note that default arguments cannot use that syntax. For example,
Click here to view code image
template
void foo(T p{}) {
…

//ERROR

}

Instead, we have to write:
Click here to view code image
template
void foo(T p = T{}) {
…
}

//OK (must use T() before C++11)

5.3 Using this->
For class templates with base classes that depend on template parameters, using a
name x by itself is not always equivalent to this->x, even though a member x is
inherited. For example:
Click here to view code image
template
class Base {
public:
void bar();
};
template
class Derived : Base {
public:
void foo() {
bar(); // calls external bar() or error
}
};

In this example, for resolving the symbol bar inside foo(), bar() defined in
Base is never considered. Therefore, either you have an error, or another bar()
(such as a global bar()) is called.
We discuss this issue in Section 13.4.2 on page 237 in detail. For the moment, as a
rule of thumb, we recommend that you always qualify any symbol that is declared in
a base that is somehow dependent on a template parameter with this-> or
Base::.

5.4 Templates for Raw Arrays and String Literals
When passing raw arrays or string literals to templates, some care has to be taken.

First, if the template parameters are declared as references, the arguments don’t
decay. That is, a passed argument of "hello" has type char const[6]. This
can become a problem if raw arrays or string arguments of different length are
passed because the types differ. Only when passing the argument by value, the types
decay, so that string literals are converted to type char const*. This is discussed
in detail in Chapter 7.
Note that you can also provide templates that specifically deal with raw arrays or
string literals. For example:
Click here to view code image

basics/lessarray.hpp
template bool less (T(&a)[N], T(&b)[M])
{
for (int i = 0; i() is instantiated with T being int, N being 3, and M being 5.
You can also use this template for string literals:
Click here to view code image
std::cout << less("ab","abc") << ’\n’;

In this case, less<>() is instantiated with T being char const, N being 3 and M
being 4.
If you only want to provide a function template for string literals (and other char
arrays), you can do this as follows:
Click here to view code image

basics/lessstring.hpp
template

bool less (char const(&a)[N], char const(&b)[M])
{
for (int i = 0; i
template
struct MyClass;

// primary template

template
struct MyClass
// partial specialization for arrays
of known bounds
{
static void print() { std::cout << "print() for T[" << SZ <<
"]\n"; }
};
template
struct MyClass
// partial spec. for references to
arrays of known bounds
{
static void print() { std::cout << "print() for T(&)[" << SZ <<
"]\n"; }
};
template
struct MyClass
// partial specialization for arrays
of unknown bounds
{
static void print() { std::cout << "print() for T[]\n"; }
};
template
struct MyClass
arrays of unknown bounds

// partial spec. for references to

{
static void print() { std::cout << "print() for T(&)[]\n"; }
};
template
struct MyClass
// partial specialization for pointers
{
static void print() { std::cout << "print() for T*\n"; }
};

Here, the class template MyClass<> is specialized for various types: arrays of
known and unknown bound, references to arrays of known and unknown bounds,
and pointers. Each case is different and can occur when using arrays:
Click here to view code image

basics/arrays.cpp
#include "arrays.hpp"
template
void foo(int a1[7], int a2[],
// pointers by language rules
int (&a3)[42],
// reference to array of known
bound
int (&x0)[],
// reference to array of unknown
bound
T1 x1,
// passing by value decays
T2& x2, T3&& x3)
// passing by reference
{
MyClass::print();
// uses MyClass
MyClass::print();
// uses MyClass
MyClass::print();
// uses MyClass
MyClass::print();
// uses MyClass
MyClass::print();
// uses MyClass
MyClass::print();
// uses MyClass
MyClass::print();
// uses MyClass
}
int main()
{
int a[42];
MyClass::print();
extern int x[];
MyClass::print();
foo(a, a, a, x, x, x, x);
}

// uses MyClass
// forward declare array
// uses MyClass

int x[] = {0, 8, 15};
array

// define forward-declared

Note that a call parameter declared as an array (with or without length) by language
rules really has a pointer type. Note also that templates for arrays of unknown
bounds can be used for an incomplete type such as
extern int i[];

And when this is passed by reference, it becomes a int(&)[], which can also be
used as a template parameter.2
See Section 19.3.1 on page 401 for another example using the different array types
in generic code.

5.5 Member Templates
Class members can also be templates. This is possible for both nested classes and
member functions. The application and advantage of this ability can again be
demonstrated with the Stack<> class template. Normally you can assign stacks to
each other only when they have the same type, which implies that the elements have
the same type. However, you can’t assign a stack with elements of any other type,
even if there is an implicit type conversion for the element types defined:
Click here to view code image
Stack intStack1, intStack2;
Stack floatStack;
…
intStack1 = intStack2;
floatStack = intStack1;
different types

// stacks for ints
// stack for floats
// OK: stacks have same type
// ERROR: stacks have

The default assignment operator requires that both sides of the assignment operator
have the same type, which is not the case if stacks have different element types.
By defining an assignment operator as a template, however, you can enable the
assignment of stacks with elements for which an appropriate type conversion is
defined. To do this you have to declare Stack<> as follows:
Click here to view code image

basics/stack5decl.hpp
template

class Stack {
private:
std::deque elems;
public:
void push(T const&);
void pop();
T const& top() const;
bool empty() const {
empty
return elems.empty();
}

// elements

//
//
//
//

push element
pop element
return top element
return whether the stack is

// assign stack of elements of type T2
template
Stack& operator= (Stack const&);
};

The following two changes have been made:
1. We added a declaration of an assignment operator for stacks of elements of
another type T2.
2. The stack now uses a std::deque<> as an internal container for the elements.
Again, this is a consequence of the implementation of the new assignment
operator.
The implementation of the new assignment operator looks like this:3
Click here to view code image

basics/stack5assign.hpp
template
template
Stack& Stack::operator= (Stack const& op2)
{
Stack tmp(op2);
// create a copy of the
assigned stack
elems.clear();
// remove existing elements
while (!tmp.empty()) {
// copy all elements
elems.push_front(tmp.top());
tmp.pop();
}
return *this;
}

First let’s look at the syntax to define a member template. Inside the template with

template parameter T, an inner template with template parameter T2 is defined:
Click here to view code image
template
template
…

Inside the member function, you may expect simply to access all necessary data for
the assigned stack op2. However, this stack has a different type (if you instantiate a
class template for two different argument types, you get two different class types), so
you are restricted to using the public interface. It follows that the only way to access
the elements is by calling top(). However, each element has to become a top
element, then. Thus, a copy of op2 must first be made, so that the elements are taken
from that copy by calling pop(). Because top() returns the last element pushed
onto the stack, we might prefer to use a container that supports the insertion of
elements at the other end of the collection. For this reason, we use a
std::deque<>, which provides push_front() to put an element on the other
side of the collection.
To get access to all the members of op2 you can declare that all other stack
instances are friends:
Click here to view code image

basics/stack6decl.hpp
template
class Stack {
private:
std::deque elems;
public:
void push(T const&);
void pop();
T const& top() const;
bool empty() const {
empty
return elems.empty();
}

// elements
//
//
//
//

push element
pop element
return top element
return whether the stack is

// assign stack of elements of type T2
template
Stack& operator= (Stack const&);
// to get access to private members of Stack for any type
T2:
template friend class Stack;
};

As you can see, because the name of the template parameter is not used, you can
omit it:
Click here to view code image
template friend class Stack;

Now, the following implementation of the template assignment operator is possible:
Click here to view code image

basics/stack6assign.hpp
template
template
Stack& Stack::operator= (Stack const& op2)
{
elems.clear();
// remove existing
elements
elems.insert(elems.begin(),
// insert at the
beginning
op2.elems.begin(),
// all elements from
op2
op2.elems.end());
return *this;
}

Whatever your implementation is, having this member template, you can now assign
a stack of ints to a stack of floats:
Click here to view code image
Stack intStack;
Stack floatStack;
…
floatStack = intStack;

// stack for ints
// stack for floats
// OK: stacks have different types,
//
but int converts to float

Of course, this assignment does not change the type of the stack and its elements.
After the assignment, the elements of the floatStack are still floats and
therefore top() still returns a float.
It may appear that this function would disable type checking such that you could
assign a stack with elements of any type, but this is not the case. The necessary type
checking occurs when the element of the (copy of the) source stack is moved to the
destination stack:
elems.push_front(tmp.top());

If, for example, a stack of strings gets assigned to a stack of floats, the
compilation of this line results in an error message stating that the string returned by
tmp.top() cannot be passed as an argument to elems.push_front() (the
message varies depending on the compiler, but this is the gist of what is meant):
Click here to view code image
Stack stringStack;
Stack floatStack;
…
floatStack = stringStack;
convert to float

// stack of strings
// stack of floats
// ERROR: std::string doesn’t

Again, you could change the implementation to parameterize the internal container
type:
Click here to view code image

basics/stack7decl.hpp
template>
class Stack {
private:
Cont elems;
// elements
public:
void push(T const&);
void pop();
T const& top() const;
bool empty() const {
empty
return elems.empty();
}

//
//
//
//

push element
pop element
return top element
return whether the stack is

// assign stack of elements of type T2
template
Stack& operator= (Stack const&);
// to get access to private members of Stack for any type
T2:
template friend class Stack;
};

Then the template assignment operator is implemented like this:
Click here to view code image

basics/stack7assign.hpp

template
template
Stack&
Stack::operator= (Stack
{
elems.clear();
elements
elems.insert(elems.begin(),
beginning
op2.elems.begin(),
op2
op2.elems.end());
return *this;
}

const& op2)
// remove existing
// insert at the
// all elements from

Remember, for class templates, only those member functions that are called are
instantiated. Thus, if you avoid assigning a stack with elements of a different type,
you could even use a vector as an internal container:
Click here to view code image
// stack for ints using a vector as an internal container
Stack> vStack;
…
vStack.push(42); vStack.push(7);
std::cout << vStack.top() << ’\n’;

Because the assignment operator template isn’t necessary, no error message of a
missing member function push_front() occurs and the program is fine.
For the complete implementation of the last example, see all the files with a name
that starts with stack7 in the subdirectory basics.
Specialization of Member Function Templates
Member function templates can also be partially or fully specialized. For example,
for the following class:
Click here to view code image

basics/boolstring.hpp
class BoolString {
private:
std::string value;
public:
BoolString (std::string const& s)
: value(s) {

}
template
T get() const {
// get value (converted to T)
return value;
}
};

you can provide a full specialization for the member function template as follows:
Click here to view code image

basics/boolstringgetbool.hpp
// full specialization for BoolString::getValue<>() for bool
template<>
inline bool BoolString::get() const {
return value == "true" || value == "1" || value == "on";
}

Note that you don’t need and also can’t declare the specializations; you only define
them. Because it is a full specialization and it is in a header file you have to declare it
with inline to avoid errors if the definition is included by different translation
units.
You can use class and the full specialization as follows:
Click here to view code image
std::cout << std::boolalpha;
BoolString s1("hello");
std::cout << s1.get() << ’\n’;
std::cout << s1.get() << ’\n’;
BoolString s2("on");
std::cout << s2.get() << ’\n’;

//prints hello
//prints false
//prints true

Special Member Function Templates
Template member functions can be used wherever special member functions allow
copying or moving objects. Similar to assignment operators as defined above, they
can also be constructors. However, note that template constructors or template
assignment operators don’t replace predefined constructors or assignment operators.
Member templates don’t count as the special member functions that copy or move
objects. In this example, for assignments of stacks of the same type, the default
assignment operator is still called.
This effect can be good and bad:

• It can happen that a template constructor or assignment operator is a better match
than the predefined copy/move constructor or assignment operator, although a
template version is provided for initialization of other types only. See Section 6.2
on page 95 for details.
• It is not easy to “templify” a copy/move constructor, for example, to be able to
constrain its existence. See Section 6.4 on page 102 for details.

5.5.1 The .template Construct
Sometimes, it is necessary to explicitly qualify template arguments when calling a
member template. In that case, you have to use the template keyword to ensure
that a < is the beginning of the template argument list. Consider the following
example using the standard bitset type:
Click here to view code image
template
void printBitset (std::bitset const& bs) {
std::cout << bs.template to_string,
std::allocator>();
}

For the bitset bs we call the member function template to_string(), while
explicitly specifying the string type details. Without that extra use of .template,
the compiler does not know that the less-than token (<) that follows is not really
less-than but the beginning of a template argument list. Note that this is a problem
only if the construct before the period depends on a template parameter. In our
example, the parameter bs depends on the template parameter N.
The .template notation (and similar notations such as ->template and
::template) should be used only inside templates and only if they follow
something that depends on a template parameter. See Section 13.3.3 on page 230 for
details.

5.5.2 Generic Lambdas and Member Templates
Note that generic lambdas, introduced with C++14, are shortcuts for member
templates. A simple lambda computing the “sum” of two arguments of arbitrary
types:
Click here to view code image

[] (auto x, auto y) {
return x + y;
}

is a shortcut for a default-constructed object of the following class:
Click here to view code image
class SomeCompilerSpecificName {
public:
SomeCompilerSpecificName(); // constructor only callable by
compiler
template
auto operator() (T1 x, T2 y) const {
return x + y;
}
};

See Section 15.10.6 on page 309 for details.

5.6 Variable Templates
Since C++14, variables also can be parameterized by a specific type. Such a thing is
called a variable template.4
For example, you can use the following code to define the value of ˇ while still not
defining the type of the value:
Click here to view code image
template
constexpr T pi{3.1415926535897932385};

Note that, as for all templates, this declaration may not occur inside functions or
block scope.
To use a variable template, you have to specify its type. For example, the
following code uses two different variables of the scope where pi<> is declared:
Click here to view code image
std::cout << pi << ’\n’;
std::cout << pi << ’\n’;

You can also declare variable templates that are used in different translation units:
Click here to view code image
//== header.hpp:
template T val{};

// zero initialized value

//== translation unit 1:
#include "header.hpp"
int main()
{
val = 42;
print();
}
//== translation unit 2:
#include "header.hpp"
void print()
{
std::cout << val << ’\n’; // OK: prints 42
}

Variable templates can also have default template arguments:
Click here to view code image
template
constexpr T pi = T{3.1415926535897932385};

You can use the default or any other type:
Click here to view code image
std::cout << pi<> << ’\n’;
std::cout << pi << ’\n’;

//outputs a long double
//outputs a float

However, note that you always have to specify the angle brackets. Just using pi is
an error:
Click here to view code image
std::cout << pi << ’\n’;

//ERROR

Variable templates can also be parameterized by nontype parameters, which also
may be used to parameterize the initializer. For example:
Click here to view code image
#include 
#include 
template
std::array arr{};
zero-initialized
template
constexpr decltype(N) dval = N;
passed value

// array with N elements,

// type of dval depends on

int main()
{
std::cout << dval<’c’> << ’\n’;
// N has value ’c’
of type char
arr<10>[0] = 42;
// sets first
element of global arr
for (std::size_t i=0; i.size(); ++i) {
// uses
values set in arr
std::cout << arr<10>[i] << ’\n’;
}
}

Again, note that even when the initialization of and iteration over arr happens in
different translation units the same variable std::array arr of
global scope is still used.
Variable Templates for Data Members
A useful application of variable templates is to define variables that represent
members of class templates. For example, if a class template is defined as follows:
Click here to view code image
template
class MyClass {
public:
static constexpr int max = 1000;
};

which allows you to define different values for different specializations of
MyClass<>, then you can define
Click here to view code image
template
int myMax = MyClass::max;

so that application programmers can just write
Click here to view code image
auto i = myMax;

instead of
Click here to view code image
auto i = MyClass::max;

This means, for a standard class such as

Click here to view code image
namespace std {
template class numeric_limits {
public:
…
static constexpr bool is_signed = false;
…
};
}

you can define
Click here to view code image
template
constexpr bool isSigned = std::numeric_limits::is_signed;

to be able to write
isSigned

instead of
Click here to view code image
std::numeric_limits::is_signed

Type Traits Suffix _v
Since C++17, the standard library uses the technique of variable templates to define
shortcuts for all type traits in the standard library that yield a (Boolean) value. For
example, to be able to write
Click here to view code image
std::is_const_v

// since C++17

instead of
Click here to view code image
std::is_const::value

//since C++11

the standard library defines
Click here to view code image
namespace std {
template constexpr bool is_const_v =
is_const::value;
}

5.7 Template Template Parameters
It can be useful to allow a template parameter itself to be a class template. Again, our
stack class template can be used as an example.
To use a different internal container for stacks, the application programmer has to
specify the element type twice. Thus, to specify the type of the internal container,
you have to pass the type of the container and the type of its elements again:
Click here to view code image
Stack> vStack;
a vector

// integer stack that uses

Using template template parameters allows you to declare the Stack class template
by specifying the type of the container without respecifying the type of its elements:
Click here to view code image
Stack vStack;
uses a vector

// integer stack that

To do this, you must specify the second template parameter as a template template
parameter. In principle, this looks as follows:5
Click here to view code image

basics/stack8decl.hpp
template class Cont = std::deque>
class Stack {
private:
Cont elems;
// elements
public:
void push(T const&);
void pop();
T const& top() const;
bool empty() const {
empty
return elems.empty();
}
…
};

//
//
//
//

push element
pop element
return top element
return whether the stack is

The difference is that the second template parameter is declared as being a class
template:

Click here to view code image
template class Cont

The default value has changed from std::deque to std::deque. This
parameter has to be a class template, which is instantiated for the type that is passed
as the first template parameter:
Cont elems;

This use of the first template parameter for the instantiation of the second template
parameter is particular to this example. In general, you can instantiate a template
template parameter with any type inside a class template.
As usual, instead of typename you could use the keyword class for template
parameters. Before C++11, Cont could only be substituted by the name of a class
template.
Click here to view code image
template class Cont = std::deque>
class Stack {
//OK
…
};

Since C++11, we can also substitute Cont with the name of an alias template, but it
wasn’t until C++17 that a corresponding change was made to permit the use of the
keyword typename instead of class to declare a template template parameter:
Click here to view code image
template typename Cont = std::deque>
class Stack {
//ERROR before
C++17
…
};

Those two variants mean exactly the same thing: Using class instead of
typename does not prevent us from specifying an alias template as the argument
corresponding to the Cont parameter.
Because the template parameter of the template template parameter is not used, it
is customary to omit its name (unless it provides useful documentation):
Click here to view code image
template class Cont = std::deque>
class Stack {

…
};

Member functions must be modified accordingly. Thus, you have to specify the
second template parameter as the template template parameter. The same applies to
the implementation of the member function. The push() member function, for
example, is implemented as follows:
Click here to view code image
template class Cont>
void Stack::push (T const& elem)
{
elems.push_back(elem);
// append copy of passed elem
}

Note that while template template parameters are placeholders for class or alias
templates, there is no corresponding placeholder for function or variable templates.
Template Template Argument Matching
If you try to use the new version of Stack, you may get an error message saying
that the default value std::deque is not compatible with the template template
parameter Cont. The problem is that prior to C++17 a template template argument
had to be a template with parameters that exactly match the parameters of the
template template parameter it substitutes, with some exceptions related to variadic
template parameters (see Section 12.3.4 on page 197). Default template arguments of
template template arguments were not considered, so that a match couldn’t be
achieved by leaving out arguments that have default values (in C++17, default
arguments are considered).
The pre-C++17 problem in this example is that the std::deque template of the
standard library has more than one parameter: The second parameter (which
describes an allocator) has a default value, but prior to C++17 this was not
considered when matching std::deque to the Cont parameter.
There is a workaround, however. We can rewrite the class declaration so that the
Cont parameter expects containers with two template parameters:
Click here to view code image
template>
class Cont = std::deque>
class Stack {
private:

Cont elems;
…

// elements

};

Again, we could omit Alloc because it is not used.
The final version of our Stack template (including member templates for
assignments of stacks of different element types) now looks as follows:
Click here to view code image

basics/stack9.hpp
#include 
#include 
#include 
template>
class Cont = std::deque>
class Stack {
private:
Cont elems;
// elements
public:
void push(T const&);
void pop();
T const& top() const;
bool empty() const {
empty
return elems.empty();
}

//
//
//
//

push element
pop element
return top element
return whether the stack is

// assign stack of elements of type T2
template
>class Cont2>
Stack& operator= (Stack const&);
// to get access to private members of any Stack with
elements of type T2:
templateclass>
friend class Stack;
};
template class Cont>
void Stack::push (T const& elem)
{

elems.push_back(elem);

// append copy of passed elem

}
template class Cont>
void Stack::pop ()
{
assert(!elems.empty());
elems.pop_back();
// remove last element
}
template class Cont>
T const& Stack::top () const
{
assert(!elems.empty());
return elems.back();
// return copy of last element
}
template class Cont>
template class Cont2>
Stack&
Stack::operator= (Stack const& op2)
{
elems.clear();
// remove existing
elements
elems.insert(elems.begin(),
// insert at the
beginning
op2.elems.begin(),
// all elements from
op2
op2.elems.end());
return *this;
}

Note again that to get access to all the members of op2 we declare that all other
stack instances are friends (omitting the names of the template parameters):
Click here to view code image
templateclass>
friend class Stack;

Still, not all standard container templates can be used for Cont parameter. For
example, std::array will not work because it includes a nontype template
parameter for the array length that has no match in our template template parameter
declaration.
The following program uses all features of this final version:
Click here to view code image

basics/stack9test.cpp
#include "stack9.hpp"
#include 
#include 
int main()
{
Stack
iStack;
Stack fStack;

// stack of ints
// stack of floats

// manipulate int stack
iStack.push(1);
iStack.push(2);
std::cout << "iStack.top(): " << iStack.top() << ’\n’;
// manipulate float stack:
fStack.push(3.3);
std::cout << "fStack.top(): " << fStack.top() << ’\n’;
// assign stack of different type and manipulate again
fStack = iStack;
fStack.push(4.4);
std::cout << "fStack.top(): " << fStack.top() << ’\n’;
// stack for doubless using a vector as an internal container
Stack vStack;
vStack.push(5.5);
vStack.push(6.6);
std::cout << "vStack.top(): " << vStack.top() << ’\n’;
vStack = fStack;
std::cout << "vStack: ";
while (! vStack.empty()) {
std::cout << vStack.top() << ’ ’;
vStack.pop();
}
std::cout << ’\n’;
}

The program has the following output:
Click here to view code image
iStack.top():
fStack.top():
fStack.top():
vStack.top():
vStack: 4.4 2

2
3.3
4.4
6.6
1

For further discussion and examples of template template parameters, see Section
12.2.3 on page 187, Section 12.3.4 on page 197, and Section 19.2.2 on page 398.

5.8 Summary
• To access a type name that depends on a template parameter, you have to qualify
the name with a leading typename.
• To access members of bases classes that depend on template parameters, you have
to qualify the access by this-> or their class name.
• Nested classes and member functions can also be templates. One application is the
ability to implement generic operations with internal type conversions.
• Template versions of constructors or assignment operators don’t replace predefined
constructors or assignment operators.
• By using braced initialization or explicitly calling a default constructor, you can
ensure that variables and members of templates are initialized with a default value
even if they are instantiated with a built-in type.
• You can provide specific templates for raw arrays, which can also be applicable to
string literals.
• When passing raw arrays or string literals, arguments decay (perform an array-topointer conversion) during argument deduction if and only if the parameter is not a
reference.
• You can define variable templates (since C++14).
• You can also use class templates as template parameters, as template template
parameters.
• Template template arguments must usually match their parameters exactly.
1

That is, a constructor with a parameter of type
std::initializer_list, for some type X.
2 Parameters of type X (&)[]—for some arbitrary type X—have become valid
only in C++17, through the resolution of Core issue 393. However, many
compilers accepted such parameters in earlier versions of the language.
3 This is a basic implementation to demonstrate the template features. Issues like
proper exception handling are certainly missing.
4 Yes, we have very similar terms for very different things: A variable template is a
variable that is a template (variable is a noun here). A variadic template is a
template for a variadic number of template parameters (variadic is an adjective
here).
5 Before C++17, there is an issue with this version that we explain in a minute.

However, this affects only the default value std::deque. Thus, we can
illustrate the general features of template template parameters with this default
value before we discuss how to deal with it before C++17.

Chapter 6
Move Semantics and enable_if<>
One of the most prominent features C++11 introduced was move semantics. You can
use it to optimize copying and assignments by moving (“stealing”) internal resources
from a source object to a destination object instead of copying those contents. This
can be done provided the source no longer needs its internal value or state (because it
is about to be discarded).
Move semantics has a significant influence on the design of templates, and special
rules were introduced to support move semantics in generic code. This chapter
introduces these features.

6.1 Perfect Forwarding
Suppose you want to write generic code that forwards the basic property of passed
arguments:
• Modifyable objects should be forwarded so that they still can be modified.
• Constant objects should be forwarded as read-only objects.
• Movable objects (objects we can “steal” from because they are about to expire)
should be forwarded as movable objects.
To achieve this functionality without templates, we have to program all three cases.
For example, to forward a call of f() to a corresponding function g():
Click here to view code image

basics/move1.cpp
#include 
#include 
class X {
…
};

void g (X&) {
std::cout << "g() for variable\n";
}
void g (X const&) {
std::cout << "g() for constant\n";
}
void g (X&&) {
std::cout << "g() for movable object\n";
}
// let f() forward argument val
void f (X& val) {
g(val);
// val is
}
void f (X const& val) {
g(val);
// val is
}
void f (X&& val) {
g(std::move(val)); // val is
std::move() to call g(X&&)
}
int main()
{
X v;
X const c;

to g():
non-const lvalue => calls g(X&)

const lvalue => calls g(X const&)

non-const lvalue => needs

// create variable
// create constant

f(v);
//
calls g(X&)
f(c);
//
=> calls g(X const&)
f(X());
//
g(X&&)
f(std::move(v)); //
calls g(X&&)
}

f() for nonconstant object calls f(X&) =>
f() for constant object calls f(X const&)
f() for temporary calls f(X&&) => calls
f() for movable variable calls f(X&&) =>

Here, we see three different implementations of f() forwarding its argument to
g():
Click here to view code image
void f (X& val) {
g(val);
// val is non-const lvalue => calls g(X&)
}
void f (X const& val) {
g(val);
// val is const lvalue => calls g(X
const&)

}
void f (X&& val) {
g(std::move(val)); // val is non-const lvalue => needs
std::move() to call g(X&&)
}

Note that the code for movable objects (via an rvalue reference) differs from the
other code: It needs a std::move() because according to language rules, move
semantics is not passed through.1 Although val in the third f() is declared as
rvalue reference its value category when used as expression is a nonconstant lvalue
(see Appendix B) and behaves as val in the first f(). Without the move(),
g(X&) for nonconstant lvalues instead of g(&&) would be called.
If we want to combine all three cases in generic code, we have a problem:
Click here to view code image
template
void f (T val) {
g(T);
}

works for the first two cases, but not for the (third) case where movable objects are
passed.
C++11 for this reason introduces special rules for perfect forwarding parameters.
The idiomatic code pattern to achieve this is as follows:
Click here to view code image
template
void f (T&& val) {
g(std::forward(val));
}

// perfect forward val to g()

Note that std::move() has no template parameter and “triggers” move semantics
for the passed argument, while std::forward<>() “forwards” potential move
semantic depending on a passed template argument.
Don’t assume that T&& for a template parameter T behaves as X&& for a specific
type X. Different rules apply! However, syntactically they look identical:
• X&& for a specific type X declares a parameter to be an rvalue reference. It can only
be bound to a movable object (a prvalue, such as a temporary object, and an
xvalue, such as an object passed with std::move(); see Appendix B for
details). It is always mutable and you can always “steal” its value.2
• T&& for a template parameter T declares a forwarding reference (also called
universal reference).3 It can be bound to a mutable, immutable (i.e., const), or
movable object. Inside the function definition, the parameter may be mutable,

immutable, or refer to a value you can “steal” the internals from.
Note that T must really be the name of a template parameter. Depending on a
template parameter is not sufficient. For a template parameter T, a declaration such
as typename T::iterator&& is just an rvalue reference, not a forwarding
reference.
So, the whole program to perfect forward arguments will look as follows:
Click here to view code image

basics/move2.cpp
#include 
#include 
class X {
…
};
void g (X&) {
std::cout << "g() for variable\n";
}
void g (X const&) {
std::cout << "g() for constant\n";
}
void g (X&&) {
std::cout << "g() for movable object\n";
}
// let f() perfect forward argument val to g():
template
void f (T&& val) {
g(std::forward(val));
// call the right g() for any passed
argument val
}
int main()
{
X v;
X const c;
f(v);
g(X&)
f(c);
calls g(X const&)
f(X());
g(X&&)
f(std::move(v));

// create variable
// create constant
// f() for variable calls f(X&) => calls
// f() for constant calls f(X const&) =>
// f() for temporary calls f(X&&) => calls
// f() for move-enabled variable calls f(X&&)

=> calls g(X&&)
}

Of course, perfect forwarding can also be used with variadic templates (see Section
4.3 on page 60 for some examples). See Section 15.6.3 on page 280 for details of
perfect forwarding.

6.2 Special Member Function Templates
Member function templates can also be used as special member functions, including
as a constructor, which, however, might lead to surprising behavior.
Consider the following example:
Click here to view code image

basics/specialmemtmpl1.cpp
#include 
#include 
#include 
class Person
{
private:
std::string name;
public:
// constructor for passed initial name:
explicit Person(std::string const& n) : name(n) {
std::cout << "copying string-CONSTR for ’" << name <<
"’\n";
}
explicit Person(std::string&& n) : name(std::move(n)) {
std::cout << "moving string-CONSTR for ’" << name <<
"’\n";
}
// copy and move constructor:
Person (Person const& p) : name(p.name) {
std::cout << "COPY-CONSTR Person ’" << name << "’\n";
}
Person (Person&& p) : name(std::move(p.name)) {
std::cout << "MOVE-CONSTR Person ’" << name << "’\n";
}
};
int main()

{
std::string s = "sname";
Person p1(s);
copying string-CONSTR
Person p2("tmp");
moving string-CONSTR
Person p3(p1);
Person p4(std::move(p1));
}

// init with string object => calls
// init with string literal => calls
// copy Person => calls COPY-CONSTR
// move Person => calls MOVE-CONST

Here, we have a class Person with a string member name for which we provide
initializing constructors. To support move semantics, we overload the constructor
taking a std::string:
• We provide a version for string object the caller still needs, for which name is
initialized by a copy of the passed argument:
Click here to view code image
Person(std::string const& n) : name(n) {
std::cout << "copying string-CONSTR for ’" << name << "’\n";
}

• We provide a version for movable string object, for which we call std::move()
to “steal” the value from:
Click here to view code image
Person(std::string&& n) : name(std::move(n)) {
std::cout << "moving string-CONSTR for ’" << name << "’\n";
}

As expected, the first is called for passed string objects that are in use (lvalues),
while the latter is called for movable objects (rvalues):
Click here to view code image
std::string s = "sname";
Person p1(s);
copying string-CONSTR
Person p2("tmp");
moving string-CONSTR

// init with string object => calls
// init with string literal => calls

Besides these constructors, the example has specific implementations for the copy
and move constructor to see when a Person as a whole is copied/moved:
Click here to view code image
Person p3(p1);
Person p4(std::move(p1));

// copy Person => calls COPY-CONSTR
// move Person => calls MOVE-CONSTR

Now let’s replace the two string constructors with one generic constructor perfect
forwarding the passed argument to the member name:
Click here to view code image

basics/specialmemtmpl2.hpp
#include 
#include 
#include 
class Person
{
private:
std::string name;
public:
// generic constructor for passed initial name:
template
explicit Person(STR&& n) : name(std::forward(n)) {
std::cout << "TMPL-CONSTR for ’" << name << "’\n";
}
// copy and move constructor:
Person (Person const& p) : name(p.name) {
std::cout << "COPY-CONSTR Person ’" << name << "’\n";
}
Person (Person&& p) : name(std::move(p.name)) {
std::cout << "MOVE-CONSTR Person ’" << name << "’\n";
}
};

Construction with passed string works fine, as expected:
Click here to view code image
std::string s = "sname";
Person p1(s);
TMPL-CONSTR
Person p2("tmp");
TMPL-CONSTR

// init with string object => calls
//init with string literal => calls

Note how the construction of p2 does not create a temporary string in this case: The
parameter STR is deduced to be of type char const[4]. Applying
std::forward to the pointer parameter of the constructor has not much of
an effect, and the name member is thus constructed from a null-terminated string.
But when we attempt to call the copy constructor, we get an error:
Click here to view code image

Person p3(p1);

// ERROR

while initializing a new Person by a movable object still works fine:
Click here to view code image
Person p4(std::move(p1));
CONST

// OK: move Person => calls MOVE-

Note that also copying a constant Person works fine:
Click here to view code image
Person const p2c("ctmp");
literal
Person p3c(p2c);
COPY-CONSTR

//init constant object with string
// OK: copy constant Person => calls

The problem is that, according to the overload resolution rules of C++ (see Section
16.2.4 on page 333), for a nonconstant lvalue Person p the member template
Click here to view code image
template
Person(STR&& n)

is a better match than the (usually predefined) copy constructor:
Click here to view code image
Person (Person const& p)

STR is just substituted with Person&, while for the copy constructor a conversion
to const is necessary.
You might think about solving this by also providing a nonconstant copy
constructor:
Person (Person& p)

However, that is only a partial solution because for objects of a derived class, the
member template is still a better match. What you really want is to disable the
member template for the case that the passed argument is a Person or an
expression that can be converted to a Person. This can be done by using
std::enable_if<>, which is introduced in the next section.

6.3 Disable Templates with enable_if<>
Since C++11, the C++ standard library provides a helper template
std::enable_if<> to ignore function templates under certain compile-time

conditions.
For example, if a function template foo<>() is defined as follows:
Click here to view code image
template
typename std::enable_if<(sizeof(T) > 4)>::type
foo() {
}

this definition of foo<>() is ignored if sizeof(T) > 4 yields false.4 If
sizeof(T) > 4 yields true, the function template instance expands to
void foo() {
}

That is, std::enable_if<> is a type trait that evaluates a given compile-time
expression passed as its (first) template argument and behaves as follows:
• If the expression yields true, its type member type yields a type:
– The type is void if no second template argument is passed.
– Otherwise, the type is the second template argument type.
• If the expression yields false, the member type is not defined. Due to a
template feature called SFINAE (substitution failure is not an error), which is
introduced later (see Section 8.4 on page 129), this has the effect that the function
template with the enable_if expression is ignored.
As for all type traits yielding a type since C++14, there is a corresponding alias
template std::enable_if_t<>, which allows you to skip typename and
::type (see Section 2.8 on page 40 for details). Thus, since C++14 you can write
Click here to view code image
template
std::enable_if_t<(sizeof(T) > 4)>
foo() {
}

If a second argument is passed to enable_if<> or enable_if_t<>:
Click here to view code image
template
std::enable_if_t<(sizeof(T) > 4), T>
foo() {
return T();
}

the enable_if construct expands to this second argument if the expression yields

true. So, if MyType is the concrete type passed or deduced as T, whose size is
larger than 4, the effect is
MyType foo();

Note that having the enable_if expression in the middle of a declaration is pretty
clumsy. For this reason, the common way to use std::enable_if<> is to use an
additional function template argument with a default value:
Click here to view code image
template 4)>>
void foo() {
}

which expands to
Click here to view code image
template
void foo() {
}

if sizeof(T) > 4.
If that is still too clumsy, and you want to make the requirement/constraint more
explicit, you can define your own name for it using an alias template:5
Click here to view code image
template
using EnableIfSizeGreater4 = std::enable_if_t<(sizeof(T) > 4)>;
template>
void foo() {
}

See Section 20.3 on page 469 for a discussion of how std::enable_if is
implemented.

6.4 Using enable_if<>
We can use enable_if<> to solve our problem with the constructor template
introduced in Section 6.2 on page 95.
The problem we have to solve is to disable the declaration of the template

constructor
Click here to view code image
template
Person(STR&& n);

if the passed argument STR has the right type (i.e., is a std::string or a type
convertible to std::string).
For this, we use another standard type trait,
std::is_convertible. With C++17, the corresponding
declaration looks as follows:
Click here to view code image
template>>
Person(STR&& n);

If type STR is convertible to type std::string, the whole declaration expands to
Click here to view code image
template
Person(STR&& n);

If type STR is not convertible to type std::string, the whole function template
is ignored.6
Again, we can define our own name for the constraint by using an alias template:
Click here to view code image
template
using EnableIfString = std::enable_if_t<
std::is_convertible_v>;
…
template>
Person(STR&& n);

Thus, the whole class Person should look as follows:
Click here to view code image

basics/specialmemtmpl3.hpp
#include
#include
#include
#include






template
using EnableIfString = std::enable_if_t<
std::is_convertible_v>;
class Person
{
private:
std::string name;
public:
// generic constructor for passed initial name:
template>
explicit Person(STR&& n)
: name(std::forward(n)) {
std::cout << "TMPL-CONSTR for ’" << name << "’\n";
}
// copy and move constructor:
Person (Person const& p) : name(p.name) {
std::cout << "COPY-CONSTR Person ’" << name << "’\n";
}
Person (Person&& p) : name(std::move(p.name)) {
std::cout << "MOVE-CONSTR Person ’" << name << "’\n";
}
};

Now, all calls behave as expected:
Click here to view code image

basics/specialmemtmpl3.cpp
#include "specialmemtmpl3.hpp"
int main()
{
std::string s = "sname";
Person p1(s);
TMPL-CONSTR
Person p2("tmp");
TMPL-CONSTR
Person p3(p1);
Person p4(std::move(p1));
}

// init with string object => calls
// init with string literal => calls
// OK => calls COPY-CONSTR
// OK => calls MOVE-CONST

Note again that in C++14, we have to declare the alias template as follows, because
the _v version is not defined for type traits that yield a value:
Click here to view code image

template
using EnableIfString = std::enable_if_t<
std::is_convertible::value>;

And in C++11, we have to declare the special member template as follows, because
as written the _t version is not defined for type traits that yield a type:
Click here to view code image
template
using EnableIfString
= typename std::enable_if::value
>::type;

But that’s all hidden now in the definition of EnableIfString<>.
Note also that there is an alternative to using std::is_convertible<>
because it requires that the types are implicitly convertible. By using
std::is_constructible<>, we also allow explicit conversions to be used for
the initialization. However, the order of the arguments is the opposite is this case:
Click here to view code image
template
using EnableIfString = std::enable_if_t<
std::is_constructible_v>;

See Section D.3.2 on page 719 for details about std::is_constructible<>
and Section D.3.3 on page 727 for details about std::is_convertible<>. See
Section D.6 on page 734 for details and examples to apply enable_if<> on
variadic templates.
Disabling Special Member Functions
Note that normally we can’t use enable_if<> to disable the predefined
copy/move constructors and/or assignment operators. The reason is that member
function templates never count as special member functions and are ignored when,
for example, a copy constructor is needed. Thus, with this declaration:
Click here to view code image
class C {
public:
template
C (T const&) {
std::cout << "tmpl copy constructor\n";

}
…
};

the predefined copy constructor is still used, when a copy of a C is requested:
Click here to view code image
C x;
C y{x}; // still uses the predefined copy constructor (not the
member template)

(There is really no way to use the member template because there is no way to
specify or deduce its template parameter T.)
Deleting the predefined copy constructor is no solution, because then the trial to
copy a C results in an error.
There is a tricky solution, though:7 We can declare a copy constructor for const
volatile arguments and mark it “deleted” (i.e., define it with = delete). Doing
so prevents another copy constructor from being implicitly declared. With that in
place, we can define a constructor template that will be preferred over the (deleted)
copy constructor for nonvolatile types:
Click here to view code image
class C
{
public:
…
// user-define the predefined copy constructor as deleted
// (with conversion to volatile to enable better matches)
C(C const volatile&) = delete;
// implement copy constructor template with better match:
template
C (T const&) {
std::cout << "tmpl copy constructor\n";
}
…
};

Now the template constructors are used even for “normal” copying:
Click here to view code image
C x;
C y{x};

// uses the member template

In such a template constructor we can then apply additional constraints with
enable_if<>. For example, to prevent being able to copy objects of a class

template C<> if the template parameter is an integral type, we can implement the
following:
Click here to view code image
template
class C
{
public:
…
// user-define the predefined copy constructor as deleted
// (with conversion to volatile to enable better matches)
C(C const volatile&) = delete;
// if T is no integral type, provide copy constructor
template with better match:
template::value>>
C (C const&) {
…
}
…
};

6.5 Using Concepts to Simplify enable_if<> Expressions
Even when using alias templates, the enable_if syntax is pretty clumsy, because
it uses a work-around: To get the desired effect, we add an additional template
parameter and “abuse” that parameter to provide a specific requirement for the
function template to be available at all. Code like this is hard to read and makes the
rest of the function template hard to understand.
In principle, we just need a language feature that allows us to formulate
requirements or constraints for a function in a way that causes the function to be
ignored if the requirements/constraints are not met.
This is an application of the long-awaited language feature concepts, which allows
us to formulate requirements/conditions for templates with its own simple syntax.
Unfortunately, although long discussed, concepts still did not become part of the
C++17 standard. Some compilers provide experimental support for such a feature,
however, and concepts will likely become part of the next standard after C++17.
With concepts, as their use is proposed, we simply have to write the following:
Click here to view code image
template

requires std::is_convertible_v
Person(STR&& n) : name(std::forward(n)) {
…
}

We can even specify the requirement as a general concept
Click here to view code image
template
concept ConvertibleToString =
std::is_convertible_v;

and formulate this concept as a requirement:
Click here to view code image
template
requires ConvertibleToString
Person(STR&& n) : name(std::forward(n)) {
…
}

This also can be formulated as follows:
Click here to view code image
template
Person(STR&& n) : name(std::forward(n)) {
…
}

See Appendix E for a detailed discussion of concepts for C++.

6.6 Summary
• In templates, you can “perfectly” forward parameters by declaring them as
forwarding references (declared with a type formed with the name of a template
parameter followed by &&) and using std::forward<>() in the forwarded
call.
• When using perfect forwarding member function templates, they might match
better than the predefined special member function to copy or move objects.
• With std::enable_if<>, you can disable a function template when a compiletime condition is false (the template is then ignored once that condition has been
determined).
• By using std::enable_if<> you can avoid problems when constructor
templates or assignment operator templates that can be called for single arguments

are a better match than implicitly generated special member functions.
• You can templify (and apply enable_if<>) to special member functions by
deleting the predefined special member functions for const volatile.
• Concepts will allow us to use a more intuitive syntax for requirements on function
templates.
1 The fact that move semantics is not automatically passed through is intentional
and important. If it weren’t, we would lose the value of a movable object the first
time we use it in a function.
2 A type like X const&& is valid but provides no common semantics in practice
because “stealing” the internal representation of a movable object requires
modifying that object. It might be used, though, to force passing only temporaries
or objects marked with std::move() without being able to modify them.
3 The term universal reference was coined by Scott Meyers as a common term that
could result in either an “lvalue reference” or an “rvalue reference.” Because
“universal” was, well, too universal, the C++17 standard introduced the term
forwarding reference, because the major reason to use such a reference is to
forward objects. However, note that it does not automatically forward. The term
does not describe what it is but what it is typically used for.
4 Don’t forget to place the condition into parentheses, because otherwise the > in
the condition would end the template argument list.
5 Thanks to Stephen C. Dewhurst for pointing that out.
6 If you wonder why we don’t instead check whether STR is “not convertible to
Person,” beware: We are defining a function that might allow us to convert a
string to a Person. So the constructor has to know whether it is enabled, which
depends on whether it is convertible, which depends on whether it is enabled, and
so on. Never use enable_if in places that impact the condition used by
enable_if. This is a logical error that compilers do not necessarily detect.
7 Thanks to Peter Dimov for pointing out this technique.

Chapter 7
By Value or by Reference?
Since the beginning, C++ has provided call-by-value and call-by-reference, and it is
not always easy to decide which one to choose: Usually calling by reference is
cheaper for nontrivial objects but more complicated. C++11 added move semantics
to the mix, which means that we now have different ways to pass by reference:1
1. X const& (constant lvalue reference):
The parameter refers to the passed object, without the ability to modify it.
2. X& (nonconstant lvalue reference):
The parameter refers to the passed object, with the ability to modify it.
3. X&& (rvalue reference):
The parameter refers to the passed object, with move semantics, meaning that you
can modify or “steal” the value.
Deciding how to declare parameters with known concrete types is complicated
enough. In templates, types are not known, and therefore it becomes even harder to
decide which passing mechanism is appropriate.
Nevertheless, in Section 1.6.1 on page 20 we did recommend passing parameters
in function templates by value unless there are good reasons, such as the following:
• Copying is not possible.2
• Parameters are used to return data.
• Templates just forward the parameters to somewhere else by keeping all the
properties of the original arguments.
• There are significant performance improvements.
This chapter discusses the different approaches to declare parameters in templates,
motivating the general recommendation to pass by value, and providing arguments
for the reasons not to do so. It also discusses the tricky problems you run into when
dealing with string literals and other raw arrays.
When reading this chapter, it is helpful to be familiar with the terminology of
value categories (lvalue, rvalue, prvalue, xvalue, etc.), which is explained in
Appendix B.

7.1 Passing by Value
When passing arguments by value, each argument must in principle be copied. Thus,
each parameter becomes a copy of the passed argument. For classes, the object
created as a copy generally is initialized by the copy constructor.
Calling a copy constructor can become expensive. However, there are various way
to avoid expensive copying even when passing parameters by value: In fact,
compilers might optimize away copy operations copying objects and can become
cheap even for complex objects by using move semantics.
For example, let’s look at a simple function template implemented so that the
argument is passed by value:
Click here to view code image
template
void printV (T arg) {
…
}

When calling this function template for an integer, the resulting code is
Click here to view code image
void printV (int arg) {
…
}

Parameter arg becomes a copy of any passed argument, whether it is an object or a
literal or a value returned by a function.
If we define a std::string and call our function template for it:
std::string s = "hi";
printV(s);

the template parameter T is instantiated as std::string so that we get
Click here to view code image
void printV (std::string arg)
{
…
}

Again, when passing the string, arg becomes a copy of s. This time the copy is
created by the copy constructor of the string class, which is a potentially expensive
operation, because in principle this copy operation creates a full or “deep” copy so
that the copy internally allocates its own memory to hold the value.3

However, the potential copy constructor is not always called. Consider the
following:
Click here to view code image
std::string returnString();
std::string s = "hi";
printV(s);
printV(std::string("hi"));
not, move constructor)
printV(returnString());
(if not, move constructor)
printV(std::move(s));

//copy constructor
//copying usually optimized away (if
// copying usually optimized away
// move constructor

In the first call we pass an lvalue, which means that the copy constructor is used.
However, in the second and third calls, when directly calling the function template
for prvalues (temporary objects created on the fly or returned by another function;
see Appendix B), compilers usually optimize passing the argument so that no
copying constructor is called at all. Note that since C++17, this optimization is
required. Before C++17, a compiler that doesn’t optimize the copying away, must at
least have to try to use move semantics, which usually makes copying cheap. In the
last call, when passing an xvalue (an existing nonconstant object with
std::move()), we force to call the move constructor by signaling that we no
longer need the value of s.
Thus, calling an implementation of printV() that declares the parameter to be
passed by value usually is only expensive if we pass an lvalue (an object we created
before and typically still use afterwards, as we didn’t use std::move() to pass it).
Unfortunately, this is a pretty common case. One reason is that it is pretty common
to create objects early to pass them later (after some modifications) to other
functions.
Passing by Value Decays
There is another property of passing by value we have to mention: When passing
arguments to a parameter by value, the type decays. This means that raw arrays get
converted to pointers and that qualifiers such as const and volatile are
removed (just like using the value as initializer for an object declared with auto):4
Click here to view code image
template
void printV (T arg) {
…
}

Click here to view code image
std::string const c = "hi";
printV(c);
// c decays so that arg has type
std::string
printV("hi");
type char const*
int arr[4];
printV(arr);
type char const*

//decays to pointer so that arg has

// decays to pointer so that arg has

Thus, when passing the string literal "hi", its type char const[3] decays to
char const* so that this is the deduced type of T. Thus, the template is
instantiated as follows:
Click here to view code image
void printV (char const* arg)
{
…
}

This behavior is derived from C and has its benefits and drawbacks. Often it
simplifies the handling of passed string literals, but the drawback is that inside
printV() we can’t distinguish between passing a pointer to a single element and
passing a raw array. For this reason, we will discuss how to deal with string literals
and other raw arrays in Section 7.4 on page 115.

7.2 Passing by Reference
Now let’s discuss the different flavors of passing by reference. In all cases, no copy
gets created (because the parameter just refers to the passed argument). Also, passing
the argument never decays. However, sometimes passing is not possible, and if
passing is possible, there are cases in which the resulting type of the parameter may
cause problems.

7.2.1 Passing by Constant Reference
To avoid any (unnecessary) copying, when passing nontemporary objects, we can
use constant references. For example:
Click here to view code image

template
void printR (T const& arg) {
…
}

With this declaration, passing an object never creates a copy (whether it’s cheap or
not):
Click here to view code image
std::string returnString();
std::string s = "hi";
printR(s);
printR(std::string("hi"));
printR(returnString());
printR(std::move(s));

//
//
//
//

no
no
no
no

copy
copy
copy
copy

Even an int is passed by reference, which is a bit counterproductive but shouldn’t
matter that much. Thus:
Click here to view code image
int i = 42;
printR(i);
copying i

// passes reference instead of just

results in printR() being instantiated as:
Click here to view code image
void printR(int const& arg) {
…
}

Under the hood, passing an argument by reference is implemented by passing the
address of the argument. Addresses are encoded compactly, and therefore
transferring an address from the caller to the callee is efficient in itself. However,
passing an address can create uncertainties for the compiler when it compiles the
caller’s code: What is the callee doing with that address? In theory, the callee can
change all the values that are “reachable” through that address. That means, that the
compiler has to assume that all the values it may have cached (usually, in machine
registers) are invalid after the call. Reloading all those values can be quite expensive.
You may be thinking that we are passing by constant reference: Cannot the compiler
deduce from that that no change can happen? Unfortunately, that is not the case
because the caller may modify the referenced object through its own, non-const
reference.5
This bad news is moderated by inlining: If the compiler can expand the call inline,
it can reason about the caller and the callee together and in many cases “see” that the

address is not used for anything but passing the underlying value. Function templates
are often very short and therefore likely candidates for inline expansion. However, if
a template encapsulates a more complex algorithm, inlining is less likely to happen.
Passing by Reference Does Not Decay
When passing arguments to parameters by reference, they do not decay. This means
that raw arrays are not converted to pointers and that qualifiers such as const and
volatile are not removed. However, because the call parameter is declared as T
const&, the template parameter T itself is not deduced as const. For example:
Click here to view code image
template
void printR (T const& arg) {
…
}
std::string const c = "hi";
printR(c);
// T deduced as std::string, arg is
std::string const&
printR("hi");
const(&)[3]
int arr[4];
printR(arr);
const(&)[4]

// T deduced as char[3], arg is char

// T deduced as int[4], arg is int

Thus, local objects declared with type T in printR() are not constant.

7.2.2 Passing by Nonconstant Reference
When you want to return values through passed arguments (i.e., when you want to
use out or inout parameters), you have to use nonconstant references (unless you
prefer to pass them via pointers). Again, this means that when passing the arguments,
no copy gets created. The parameters of the called function template just get direct
access to the passed argument.
Consider the following:
Click here to view code image
template
void outR (T& arg) {
…
}

Note that calling outR() for a temporary (prvalue) or an existing object passed
with std::move() (xvalue) usually is not allowed:
Click here to view code image
std::string returnString();
std::string s = "hi";
outR(s);
//OK: T deduced as std::string, arg is
std::string&
outR(std::string("hi")); //ERROR: not allowed to pass a
temporary (prvalue)
outR(returnString());
// ERROR: not allowed to pass a
temporary (prvalue)
outR(std::move(s));
// ERROR: not allowed to pass an
xvalue

You can pass raw arrays of nonconstant types, which again don’t decay:
Click here to view code image
int arr[4];
outR(arr);
int(&)[4]

// OK: T deduced as int[4], arg is

Thus, you can modify elements and, for example, deal with the size of the array. For
example:
Click here to view code image
template
void outR (T& arg) {
if (std::is_array::value) {
std::cout << "got array of " << std::extent::value << "
elems\n";
}
…
}

However, templates are a bit tricky here. If you pass a const argument, the
deduction might result in arg becoming a declaration of a constant reference, which
means that passing an rvalue is suddenly allowed, where an lvalue is expected:
Click here to view code image
std::string const c = "hi";
outR(c);
//
outR(returnConstString()); //
returns const string
outR(std::move(c));
//
6
const
outR("hi");
//

OK: T deduced as std::string const
OK: same if returnConstString()
OK: T deduced as std::string
OK: T deduced as char const[3]

Of course, any attempt to modify the passed argument inside the function template is
an error in such cases. Passing a const object is possible in the call expression
itself, but when the function is fully instantiated (which may happen later in the
compilation process) any attempt to modify the value will trigger an error (which,
however, might happen deep inside the called template; see Section 9.4 on page
143).
If you want to disable passing constant objects to nonconstant references, you can
do the following:
• Use a static assertion to trigger a compile-time error:
Click here to view code image
template
void outR (T& arg) {
static_assert(!std::is_const::value,
"out parameter of foo(T&) is const");
…
}

• Disable the template for this case either by using std::enable_if<> (see
Section 6.3 on page 98):
Click here to view code image
template::value>
void outR (T& arg) {
…
}

or concepts once they are supported (see Section 6.5 on page 103 and Appendix
E):
Click here to view code image
template
requires !std::is_const_v
void outR (T& arg) {
…
}

7.2.3 Passing by Forwarding Reference
One reason to use call-by-reference is to be able to perfect forward a parameter (see
Section 6.1 on page 91). But remember that when a forwarding reference is used,
which is defined as an rvalue reference of a template parameter, special rules apply.

Consider the following:
Click here to view code image
template
void passR (T&& arg) {
reference
…
}

// arg declared as forwarding

You can pass everything to a forwarding reference and, as usual when passing by
reference, no copy gets created:
Click here to view code image
std::string s = "hi";
passR(s);
the type of arg)
passR(std::string("hi"));
is std::string&&
passR(returnString());
is std::string&&
passR(std::move(s));
is std::string&&
passR(arr);
the type of arg)

// OK: T deduced as std::string& (also
// OK: T deduced as std::string, arg
// OK: T deduced as std::string, arg
// OK: T deduced as std::string, arg
// OK: T deduced as int(&)[4] (also

However, the special rules for type deduction may result in some surprises:
Click here to view code image
std::string const c = "hi";
passR(c);
//OK: T deduced as std::string const&
passR("hi");
//OK: T deduced as char const(&)[3]
(also the type of arg)
int arr[4];
passR("hi");
//OK: T deduced as int (&)[4] (also
the type of arg)

In each of these cases, inside passR() the parameter arg has a type that “knows”
whether we passed an rvalue (to use move semantics) or a constant/nonconstant
lvalue. This is the only way to pass an argument, such that it can be used to
distinguish behavior for all of these three cases.
This gives the impression that declaring a parameter as a forwarding reference is
almost perfect. But beware, there is no free lunch.
For example, this is the only case where the template parameter T implicitly can
become a reference type. As a consequence, it might become an error to use T to
declare a local object without initialization:
Click here to view code image

template
void passR(T&& arg) { // arg is a forwarding reference
T x;
// for passed lvalues, x is a reference, which
requires an initializer
…
}
foo(42); // OK: T deduced as int
int i;
foo(i);
// ERROR: T deduced as int&, which makes the
declaration of x in passR() invalid

See Section 15.6.2 on page 279 for further details about how you can deal with this
situation.

7.3 Using std::ref() and std::cref()
Since C++11, you can let the caller decide, for a function template argument,
whether to pass it by value or by reference. When a template is declared to take
arguments by value, the caller can use std::cref() and std::ref(), declared
in header file , to pass the argument by reference. For example:
Click here to view code image
template
void printT (T arg) {
…
}
std::string s = "hello";
printT(s);
printT(std::cref(s));

//pass s by reference
// pass s “as if by reference”

However, note that std::cref() does not change the handling of parameters in
templates. Instead, it uses a trick: It wraps the passed argument s by an object that
acts like a reference. In fact, it creates an object of type
std::reference_wrapper<> referring to the original argument and passes
this object by value. The wrapper more or less supports only one operation: an
implicit type conversion back to the original type, yielding the original object.7 So,
whenever you have a valid operator for the passed object, you can use the reference
wrapper instead. For example:
Click here to view code image

basics/cref.cpp
#include 
#include 
#include 

// for std::cref()

void printString(std::string const& s)
{
std::cout << s << ’\n’;
}
template
void printT (T arg)
{
printString(arg);
std::string
}

// might convert arg back to

int main()
{
std::string s = "hello";
printT(s);
// print s passed by value
printT(std::cref(s));
// print s passed “as if by reference”
}

The last call passes by value an object of type
std::reference_wrapper to the parameter arg, which
then passes and therefore converts it back to its underlying type std::string.
Note that the compiler has to know that an implicit conversion back to the original
type is necessary. For this reason, std::ref() and std::cref() usually work
fine only if you pass objects through generic code. For example, directly trying to
output the passed object of the generic type T will fail because there is no output
operator defined for std::reference_wrapper<>:
Click here to view code image
template
void printV (T arg) {
std::cout << arg << ’\n’;
}
…
std::string s = "hello";
printV(s);
//OK
printV(std::cref(s));
// ERROR: no operator << for reference
wrapper defined

Also, the following fails because you can’t compare a reference wrapper with a

char const* or std::string:
Click here to view code image
template
bool isless(T1 arg1, T2 arg2)
{
return arg1 < arg2;
}
…
std::string s = "hello";
if (isless(std::cref(s) < "world")) …
if (isless(std::cref(s) < std::string("world"))) …

//ERROR
//ERROR

It also doesn’t help to give arg1 and arg2 a common type T:
Click here to view code image
template
bool isless(T arg1, T arg2)
{
return arg1 < arg2;
}

because then the compiler gets conflicting types when trying to deduce T for arg1
and arg2.
Thus, the effect of class std::reference_wrapper<> is to be able to use a
reference as a “first class object,” which you can copy and therefore pass by value to
function templates. You can also use it in classes, for example, to hold references to
objects in containers. But you always finally need a conversion back to the
underlying type.

7.4 Dealing with String Literals and Raw Arrays
So far, we have seen the different effects for templates parameters when using string
literals and raw arrays:
• Call-by-value decays so that they become pointers to the element type.
• Any form of call-by-reference does not decay so that the arguments become
references that still refer to arrays.
Both can be good and bad. When decaying arrays to pointers, you lose the ability to
distinguish between handling pointers to elements from handling passed arrays. On
the other hand, when dealing with parameters where string literals may be passed,
not decaying can become a problem, because string literals of different size have
different types. For example:

Click here to view code image
template
void foo (T const& arg1, T const& arg2)
{
…
}
foo("hi", "guy");

//ERROR

Here, foo("hi","guy") fails to compile, because "hi" has type char
const[3], while "guy" has type char const[4], but the template requires
them to have the same type T. Only if the string literals were to have the same length
would such code compile. For this reason, it is strongly recommended to use string
literals of different lengths in test cases.
By declaring the function template foo() to pass the argument by value the call
is possible:
Click here to view code image
template
void foo (T arg1, T arg2)
{
…
}
foo("hi", "guy");

//compiles, but …

But, that doesn’t mean that all problems are gone. Even worse, compile-time
problems may have become run-time problems. Consider the following code, where
we compare the passed argument using operator==:
Click here to view code image
template
void foo (T arg1, T arg2)
{
if (arg1 == arg2) { //OOPS: compares addresses of passed
arrays
…
}
}
foo("hi", "guy");

//compiles, but …

As written, you have to know that you should interpret the passed character pointers
as strings. But that’s probably the case anyway, because the template also has to deal
with arguments coming from string literals that have been decayed already (e.g., by

coming from another function called by value or being assigned to an object declared
with auto).
Nevertheless, in many cases decaying is helpful, especially for checking whether
two objects (both passed as arguments or one passed as argument and the other
expecting the argument) have or convert to the same type. One typical usage is
perfect forwarding. But if you want to use perfect forwarding, you have to declare
the parameters as forwarding references. In those cases, you might explicitly decay
the arguments using the type trait std::decay<>(). See the story of
std::make_pair() in Section 7.6 on page 120 for a concrete example.
Note that other type traits sometimes also implicitly decay, such as
std::common_type<>, which yields the common type of two passed argument
types (see Section 1.3.3 on page 12 and Section D.5 on page 732).

7.4.1 Special Implementations for String Literals and Raw
Arrays
You might have to distinguish your implementation according to whether a pointer
or an array was passed. This, of course, requires that a passed array wasn’t decayed
yet.
To distinguish these cases, you have to detect whether arrays are passed.
Basically, there are two options:
• You can declare template parameters so that they are only valid for arrays:
Click here to view code image
template
void foo(T (&arg1)[L1], T (&arg2)[L2])
{
T* pa = arg1; // decay arg1
T* pb = arg2; // decay arg2
if (compareArrays(pa, L1, pb, L2)) {
…
}
}

Here, arg1 and arg2 have to be raw arrays of the same element type T but with
different sizes L1 and L2. However, note that you might need multiple
implementations to support the various forms of raw arrays (see Section 5.4 on
page 71).
• You can use type traits to detect whether an array (or a pointer) was passed:
Click here to view code image

template>>
void foo (T&& arg1, T&& arg2)
{
…
}

Due to these special handling, often the best way to deal with arrays in different
ways is simply to use different function names. Even better, of course, is to ensure
that the caller of a template uses std::vector or std::array. But as long as
string literals are raw arrays, we always have to take them into account.

7.5 Dealing with Return Values
For return values, you can also decide between returning by value or by reference.
However, returning references is potentially a source of trouble, because you refer to
something that is out of your control. There are a few cases where returning
references is common programming practice:
• Returning elements of containers or strings (e.g., by operator[] or front())
• Granting write access to class members
• Returning objects for chained calls (operator<< and operator>> for streams
and operator= for class objects in general)
In addition, it is common to grant read access to members by returning const
references.
Note that all these cases may cause trouble if used improperly. For example:
Click here to view code image
std::string* s = new std::string("whatever");
auto& c = (*s)[0];
delete s;
std::cout << c;
//run-time ERROR

Here, we obtained a reference to an element of a string, but by the time we use that
reference, the underlying string no longer exists (i.e., we created a dangling
reference), and we have undefined behavior. This example is somewhat contrived
(the experienced programmer is likely to notice the problem right away), but things
easily become less obvious. For example:
Click here to view code image
auto s = std::make_shared("whatever");
auto& c = (*s)[0];
s.reset();

std::cout << c;

//run-time ERROR

We should therefore ensure that function templates return their result by value.
However, as discussed in this chapter, using a template parameter T is no guarantee
that it is not a reference, because T might sometimes implicitly be deduced as a
reference:
Click here to view code image
template
T retR(T&& p)
// p is a forwarding reference
{
return T{…};
// OOPS: returns by reference when called for
lvalues
}

Even when T is a template parameter deduced from a call-by-value call, it might
become a reference type when explicitly specifying the template parameter to be a
reference:
Click here to view code image
template
T retV(T p)
//Note: T might become a reference
{
return T{…}; // OOPS: returns a reference if T is a reference
}
int x;
retV(x);

// retT() instantiated for T as int&

To be safe, you have two options:
• Use the type trait std::remove_reference<> (see Section D.4 on page 729)
to convert type T to a nonreference:
Click here to view code image
template
typename std::remove_reference::type retV(T p)
{
return T{…}; // always returns by value
}

Other traits, such as std::decay<> (see Section D.4 on page 731), may also be
useful here because they also implicitly remove references.
• Let the compiler deduce the return type by just declaring the return type to be
auto (since C++14; see Section 1.3.2 on page 11), because auto always decays:
Click here to view code image

template
auto retV(T p) // by-value return type deduced by compiler
{
return T{…}; // always returns by value
}

7.6 Recommended Template Parameter Declarations
As we learned in the previous sections, we have very different ways to declare
parameters that depend on template parameters:
• Declare to pass the arguments by value:
This approach is simple, it decays string literals and raw arrays, but it doesn’t
provide the best performance for large objects. Still the caller can decide to pass by
reference using std::cref() and std::ref(), but the caller must be careful
that doing so is valid.
• Declare to pass the arguments by-reference:
This approach often provides better performance for somewhat large objects,
especially when passing
– existing objects (lvalues) to lvalue references,
– temporary objects (prvalues) or objects marked as movable (xvalue) to rvalue
references,
– or both to forwarding references.
Because in all these cases the arguments don’t decay, you may need special care
when passing string literals and other raw arrays. For forwarding references, you
also have to beware that with this approach template parameters implicitly can
deduce to reference types.
General Recommendations
With these options in mind, for function templates we recommend the following:
1. By default, declare parameters to be passed by value. This is simple and usually
works even with string literals. The performance is fine for small arguments and
for temporary or movable objects. The caller can sometimes use std::ref()
and std::cref() when passing existing large objects (lvalues) to avoid
expensive copying.
2. If there are good reasons, do otherwise:
– If you need an out or inout parameter, which returns a new object or allows to
modify an argument to/for the caller, pass the argument as a nonconstant reference
(unless you prefer to pass it via a pointer). However, you might consider disabling

accidentally accepting const objects as discussed in Section 7.2.2 on page 110.
– If a template is provided to forward an argument, use perfect forwarding. That is,
declare parameters to be forwarding references and use std::forward<>()
where appropriate. Consider using std::decay<> or
std::common_type<> to “harmonize” the different types of string literals and
raw arrays.
– If performance is key and it is expected that copying arguments is expensive, use
constant references. This, of course, does not apply if you need a local copy
anyway.
3. If you know better, don’t follow these recommendations. However, do not make
intuitive assumptions about performance. Even experts fail if they try. Instead:
Measure!
Don’t Be Over-Generic
Note that, in practice, function templates often are not for arbitrary types of
arguments. Instead, some constraints apply. For example, you may know that only
vectors of some type are passed. In this case, it is better not to declare such a
function too generically, because, as discussed, surprising side effects may occur.
Instead, use the following declaration:
Click here to view code image
template
void printVector (std::vector const& v)
{
…
}

With this declaration of parameter v in printVector(), we can be sure that the
passed T can’t become a reference because vectors can’t use references as element
types. Also, it is pretty clear that passing a vector by value almost always can
become expensive because the copy constructor of std::vector<> creates a
copy of the elements. For this reason, it is probably never useful to declare such a
vector parameter to be passed by value. If we declare parameter v just as having type
T deciding, between call-by-value and call-by-reference becomes less obvious.

The std::make_pair() Example
std::make_pair<>() is a good example to demonstrate the pitfalls of deciding
a parameter passing mechanism. It is a convenience function template in the C++

standard library to create std::pair<> objects using type deduction. Its
declaration changed through different versions of the C++ standard:
• In the first C++ standard, C++98, make_pair<>() was declared inside
namespace std to use call-by-reference to avoid unnecessary copying:
Click here to view code image
template
pair make_pair (T1 const& a, T2 const& b)
{
return pair(a,b);
}

This, however, almost immediately caused significant problems when using pairs
of string literals or raw arrays of different size.8
• As a consequence, with C++03 the function definition was changed to use call-byvalue:
Click here to view code image
template
pair make_pair (T1 a, T2 b)
{
return pair(a,b);
}

As you can read in the rationale for the issue resolution, “it appeared that this was
a much smaller change to the standard than the other two suggestions, and any
efficiency concerns were more than offset by the advantages of the solution.”
• However, with C++11, make_pair() had to support move semantics, so that the
arguments had to become forwarding references. For this reason, the definition
changed roughly again as follows:
Click here to view code image
template
constexpr pair::type, typename
decay::type>
make_pair (T1&& a, T2&& b)
{
return pair::type,
typename decay::type>(forward(a),
forward(b));
}

The complete implementation is even more complex: To support std::ref()
and std::cref(), the function also unwraps instances of
std::reference_wrapper into real references.

The C++ standard library now perfectly forwards passed arguments in many places
in similar way, often combined with using std::decay<>.

7.7 Summary
• When testing templates, use string literals of different length.
• Template parameters passed by value decay, while passing them by reference does
not decay.
• The type trait std::decay<> allows you to decay parameters in templates
passed by reference.
• In some cases std::cref() and std::ref() allow you to pass arguments by
reference when function templates declare them to be passed by value.
• Passing template parameters by value is simple but may not result in the best
performance.
• Pass parameters to function templates by value unless there are good reasons to do
otherwise.
• Ensure that return values are usually passed by value (which might mean that a
template parameter can’t be specified directly as a return type).
• Always measure performance when it is important. Do not rely on intuition; it’s
probably wrong.
1 A constant rvalue reference X const&& is also possible but there is no
established semantic meaning for it.
2 Note that since C++17 you can pass temporary entities (rvalues) by value even if
no copy or move constructor is available (see Section B.2.1 on page 676). So,
since C++17 the additional constraint is that copying for lvalues is not possible.
3 The implementation of the string class might itself have some optimizations to
make copying cheaper. One is the small string optimization (SSO), using some
memory directly inside the object to hold the value without allocating memory as
long as the value is not too long. Another is the copy-on-write optimization, which
creates a copy using the same memory as the source as long as neither source nor
the copy is modified. However, the copy-on-write optimization has significant
drawbacks in multithreaded code. For this reason, it is forbidden for standard
strings since C++11.
4 The term decay comes from C, and also applies to the type conversion from a
function to a function pointer (see Section 11.1.1 on page 159).
5 The use of const_cast is another, more explicit, way to modify the referenced
object.

6

When passing std::move(c), std::move() first converts c to
std::string const&&, which then has the effect that T is deduced as
std::string const.
7 You can also call get() on a reference wrapper and use it as function object.
8 See C++ library issue 181 [LibIssue181] for details.

Chapter 8
Compile-Time Programming
C++ has always included some simple ways to compute values at compile time.
Templates considerably increased the possibilities in this area, and further evolution
of the language has only added to this toolbox.
In the simple case, you can decide whether or not to use certain or to choose
between different template code. But the compiler even can compute the outcome of
control flow at compile time, provided all necessary input is available.
In fact, C++ has multiple features to support compile-time programming:
• Since before C++98, templates have provided the ability to compute at compile
time, including using loops and execution path selection. (However, some consider
this an “abuse” of template features, e.g., because it requires nonintuitive syntax.)
• With partial specialization we can choose at compile time between different class
template implementations depending on specific constraints or requirements.
• With the SFINAE principle, we can allow selection between different function
template implementations for different types or different constraints.
• In C++11 and C++14, compile-time computing became increasingly better
supported with the constexpr feature using “intuitive” execution path selection
and, since C++14, most statement kinds (including for loops, switch
statements, etc.).
• C++17 introduced a “compile-time if” to discard statements depending on
compile-time conditions or constraints. It works even outside of templates.
This chapter introduces these features with a special focus on the role and context of
templates.

8.1 Template Metaprogramming
Templates are instantiated at compile time (in contrast to dynamic languages, where
genericity is handled at run time). It turns out that some of the features of C++
templates can be combined with the instantiation process to produce a sort of

primitive recursive “programming language” within the C++ language itself.1 For
this reason, templates can be used to “compute a program.” Chapter 23 will cover the
whole story and all features, but here is a short example of what is possible.
The following code finds out at compile time whether a given number is a prime
number:
Click here to view code image

basics/isprime.hpp
template // p: number to check, d:
current divisor
struct DoIsPrime {
static constexpr bool value = (p%d != 0) && DoIsPrime::value;
};
template
// end recursion if divisor is
2
struct DoIsPrime {
static constexpr bool value = (p%2 != 0);
};
template
// primary template
struct IsPrime {
// start recursion with divisor from p/2:
static constexpr bool value = DoIsPrime::value;
};
// special cases (to avoid
instantiation):
template<>
struct IsPrime<0> { static
template<>
struct IsPrime<1> { static
template<>
struct IsPrime<2> { static
template<>
struct IsPrime<3> { static

endless recursion with template

constexpr bool value = false; };
constexpr bool value = false; };
constexpr bool value = true; };
constexpr bool value = true; };

The IsPrime<> template returns in member value whether the passed template
parameter p is a prime number. To achieve this, it instantiates DoIsPrime<>,
which recursively expands to an expression checking for each divisor d between
p/2 and 2 whether the divisor divides p without remainder.
For example, the expression

IsPrime<9>::value

expands to
DoIsPrime<9,4>::value

which expands to
Click here to view code image
9%4!=0 && DoIsPrime<9,3>::value

which expands to
Click here to view code image
9%4!=0 && 9%3!=0 && DoIsPrime<9,2>::value

which expands to
Click here to view code image
9%4!=0 && 9%3!=0 && 9%2!=0

which evaluates to false, because 9%3 is 0.
As this chain of instantiations demonstrates:
• We use recursive expansions of DoIsPrime<> to iterate over all divisors from
p/2 down to 2 to find out whether any of these divisors divide the given integer
exactly (i.e., without remainder).
• The partial specialization of DoIsPrime<> for d equal to 2 serves as the criterion
to end the recursion.
Note that all this is done at compile time. That is,
IsPrime<9>::value

expands to false at compile time.
The template syntax is arguably clumsy, but code similar to this has been valid
since C++98 (and earlier) and has proven useful for quite a few libraries.2
See Chapter 23 for details.

8.2 Computing with constexpr
C++11 introduced a new feature, constexpr, that greatly simplifies various forms
of compile-time computation. In particular, given proper input, a constexpr
function can be evaluated at compile time. While in C++11 constexpr functions
were introduced with stringent limitations (e.g., each constexpr function
definition was essentially limited to consist of a return statement), most of these

restrictions were removed with C++14. Of course, successfully evaluating a
constexpr function still requires that all computational steps be possible and valid
at compile time: Currently, that excludes things like heap allocation or throwing
exceptions.
Our example to test whether a number is a prime number could be implemented as
follows in C++11:
Click here to view code image

basics/isprime11.hpp
constexpr bool
doIsPrime (unsigned p, unsigned d) // p: number to check, d:
current divisor
{
return d!=2 ? (p%d!=0) && doIsPrime(p,d-1) // check this and
smaller divisors
: (p%2!=0);
// end recursion if
divisor is 2
}
constexpr bool isPrime (unsigned p)
{
return p < 4 ? !(p<2)
: doIsPrime(p,p/2);
divisor from p/2
}

// handle special cases
// start recursion with

Due to the limitation of having only one statement, we can only use the conditional
operator as a selection mechanism, and we still need recursion to iterate over the
elements. But the syntax is ordinary C++ function code, making it more accessible
than our first version relying on template instantiation.
With C++14, constexpr functions can make use of most control structures
available in general C++ code. So, instead of writing unwieldy template code or
somewhat arcane one-liners, we can now just use a plain for loop:
Click here to view code image

basics/isprime14.hpp
constexpr bool isPrime (unsigned int p)
{
for (unsigned int d=2; d<=p/2; ++d) {
if (p % d == 0) {
return false; // found divisor without remainder

}
}
return p > 1;

// no divisor without remainder found

}

With both the C++11 and C++14 versions of our constexpr isPrime()
implementations, we can simply call
isPrime(9)

to find out whether 9 is a prime number. Note that it can do so at compile time, but it
need not necessarily do so. In a context that requires a compile-time value (e.g., an
array length or a nontype template argument), the compiler will attempt to evaluate a
call to a constexpr function at compile time and issue an error if that is not
possible (since a constant must be produced in the end). In other contexts, the
compiler may or may not attempt the evaluation at compile time3 but if such an
evaluation fails, no error is issued and the call is left as a run-time call instead.
For example:
Click here to view code image
constexpr bool b1 = isPrime(9);

// evaluated at compile time

will compute the value at compile time. The same is true with
Click here to view code image
const bool b2 = isPrime(9);
if in namespace scope

// evaluated at compile time

provided b2 is defined globally or in a namespace. At block scope, the compiler can
decide whether to compute it at compile or run time.4 This, for example, is also the
case here:
Click here to view code image
bool fiftySevenIsPrime() {
return isPrime(57);
running time
}

// evaluated at compile or

the compiler may or may not evaluate the call to isPrime at compile time.
On the other hand:
Click here to view code image
int x;
…
std::cout << isPrime(x);

// evaluated at run time

will generate code that computes at run time whether x is a prime number.

8.3 Execution Path Selection with Partial Specialization
An interesting application of a compile-time test such as isPrime() is to use
partial specialization to select at compile time between different implementations.
For example, we can choose between different implementations depending on
whether a template argument is a prime number:
Click here to view code image
// primary helper template:
template
struct Helper;
// implementation if SZ is not a prime number:
template
struct Helper
{
…
};
// implementation if SZ is a prime number:
template
struct Helper
{
…
};
template
long foo (std::array const& coll)
{
Helper h;
// implementation depends on whether array has
prime number as size
…
}

Here, depending on whether the size of the std::array<> argument is a prime
number, we use two different implementations of class Helper<>. This kind of
application of partial specialization is broadly applicable to select among different
implementations of a function template depending on properties of the arguments it’s
being invoked for.

Above, we used two partial specializations to implement the two possible
alternatives. Instead, we can also use the primary template for one of the alternatives
(the default) case and partial specializations for any other special case:
Click here to view code image
// primary helper template (used if no specialization fits):
template
struct Helper
{
…
};
// special implementation if SZ is a prime number:
template
struct Helper
{
…
};

Because function templates do not support partial specialization, you have to use
other mechanisms to change function implementation based on certain constraints.
Our options include the following:
• Use classes with static functions,
• Use std::enable_if, introduced in Section 6.3 on page 98,
• Use the SFINAE feature, which is introduced next, or
• Use the compile-time if feature, available since C++17, which is introduced
below in Section 8.5 on page 135.
Chapter 20 discusses techniques for selecting a function implementation based on
constraints.

8.4 SFINAE (Substitution Failure Is Not An Error)
In C++ it is pretty common to overload functions to account for various argument
types. When a compiler sees a call to an overloaded function, it must therefore
consider each candidate separately, evaluating the arguments of the call and picking
the candidate that matches best (see also Appendix C for some details about this
process).
In cases where the set of candidates for a call includes function templates, the
compiler first has to determine what template arguments should be used for that
candidate, then substitute those arguments in the function parameter list and in its

return type, and then evaluate how well it matches (just like an ordinary function).
However, the substitution process could run into problems: It could produce
constructs that make no sense. Rather than deciding that such meaningless
substitutions lead to errors, the language rules instead say that candidates with such
substitution problems are simply ignored.
We call this principle SFINAE (pronounced like sfee-nay), which stands for
“substitution failure is not an error.”
Note that the substitution process described here is distinct from the on-demand
instantiation process (see Section 2.2 on page 27): The substitution may be done
even for potential instantiations that are not needed (so the compiler can evaluate
whether indeed they are unneeded). It is a substitution of the constructs appearing
directly in the declaration of the function (but not its body).
Consider the following example:
Click here to view code image

basics/len1.hpp
// number of elements in a raw array:
template
std::size_t len (T(&)[N])
{
return N;
}
// number of elements for a type having size_type:
template
typename T::size_type len (T const& t)
{
return t.size();
}

Here, we define two function templates len() taking one generic argument:5
1. The first function template declares the parameter as T(&)[N], which means that
the parameter has to be an array of N elements of type T.
2. The second function template declares the parameter simply as T, which places no
constraints on the parameter but returns type T::size_type, which requires
that the passed argument type has a corresponding member size_type.
When passing a raw array or string literals, only the function template for raw arrays
matches:
Click here to view code image

int a[10];
std::cout << len(a);
std::cout << len("tmp");

// OK: only len() for array matches
//OK: only len() for array matches

According to its signature, the second function template also matches when
substituting (respectively) int[10] and char const[4] for T, but those
substitutions lead to potential errors in the return type T::size_type. The second
template is therefore ignored for these calls.
When passing a std::vector<>, only the second function template matches:
Click here to view code image
std::vector v;
std::cout << len(v);
size_type matches

// OK: only len() for a type with

When passing a raw pointer, neither of the templates match (without a failure). As a
result, the compiler will complain that no matching len() function is found:
Click here to view code image
int* p;
std::cout << len(p);
found

// ERROR: no matching len() function

Note that this differs from passing an object of a type having a size_type
member, but no size() member function, as is, for example, the case for
std::allocator<>:
Click here to view code image
std::allocator x;
std::cout << len(x);
// ERROR: len() function found, but can’t
size()

When passing an object of such a type, the compiler finds the second function
template as matching function template. So instead of an error that no matching
len() function is found, this will result in a compile-time error that calling
size() for a std::allocator is invalid. This time, the second function
template is not ignored.
Ignoring a candidate when substituting its return type is meaningless can cause the
compiler to select another candidate whose parameters are a worse match. For
example:
Click here to view code image

basics/len2.hpp

// number of elements in a raw array:
template
std::size_t len (T(&)[N])
{
return N;
}
// number of elements for a type having size_type:
template
typename T::size_type len (T const& t)
{
return t.size();
}
// fallback for all other types:
std::size_t len (…)
{
return 0;
}

Here, we also provide a general len() function that always matches but has the
worst match (match with ellipsis (…) in overload resolution (see Section C.2 on page
682).
So, for raw arrays and vectors, we have two matches where the specific match is
the better match. For pointers, only the fallback matches so that the compiler no
longer complains about a missing len() for this call.6 But for the allocator, the
second and third function templates match, with the second function template as the
better match. So, still, this results in an error that no size() member function can
be called:
Click here to view code image
int a[10];
std::cout << len(a);
std::cout << len("tmp");
std::vector v;
std::cout << len(v);
size_type is best match
int* p;
std::cout << len(p);
std::allocator x;
std::cout << len(x);
best,

// OK: len() for array is best match
//OK: len() for array is best match

// OK: len() for a type with

// OK: only fallback len() matches

// ERROR: 2nd len() function matches

//

but can’t call size() for

x

See Section 15.7 on page 284 for more details about SFINAE and Section 19.4 on
page 416 about some applications of SFINAE.
SFINAE and Overload Resolution
Over time, the SFINAE principle has become so important and so prevalent among
template designers that the abbreviation has become a verb. We say “we SFINAE out
a function” if we mean to apply the SFINAE mechanism to ensure that function
templates are ignored for certain constraints by instrumenting the template code to
result in invalid code for these constraints. And whenever you read in the C++
standard that a function template “shall not participate in overload resolution
unless…” it means that SFINAE is used to “SFINAE out” that function template for
certain cases.
For example, class std::thread declares a constructor:
Click here to view code image
namespace std {
class thread {
public:
…
template
explicit thread(F&& f, Args&&… args);
…
};
}

with the following remark:
Remarks: This constructor shall not participate in overload resolution if
decay_t is the same type as std::thread.
This means that the template constructor is ignored if it is called with a
std::thread as first and only argument. The reason is that otherwise a member
template like this sometimes might better match than any predefined copy or move
constructor (see Section 6.2 on page 95 and Section 16.2.4 on page 333 for details).
By SFINAE’ing out the constructor template when called for a thread, we ensure that
the predefined copy or move constructor is always used when a thread gets
constructed from another thread.7
Applying this technique on a case-by-case basis can be unwieldy. Fortunately, the
standard library provides tools to disable templates more easily. The best-known

such feature is std::enable_if<>, which was introduced in Section 6.3 on page
98. It allows us to disable a template just by replacing a type with a construct
containing the condition to disable it.
As a consequence, the real declaration of std::thread typically is as follows:
Click here to view code image
namespace std {
class thread {
public:
…
template,
thread>>>
explicit thread(F&& f, Args&&… args);
…
};
}

See Section 20.3 on page 469 for details about how std::enable_if<> is
implemented, using partial specialization and SFINAE.

8.4.1 Expression SFINAE with decltype
It’s not always easy to find out and formulate the right expression to SFINAE out
function templates for certain conditions.
Suppose, for example, that we want to ensure that the function template len() is
ignored for arguments of a type that has a size_type member but not a size()
member function. Without any form of requirements for a size() member function
in the function declaration, the function template is selected and its ultimate
instantiation then results in an error:
Click here to view code image
template
typename T::size_type len (T const& t)
{
return t.size();
}
std::allocator x;
std::cout << len(x) << ’\n’;
x has no size()

//ERROR: len() selected, but

There is a common pattern or idiom to deal with such a situation:

• Specify the return type with the trailing return type syntax (use auto at the front
and -> before the return type at the end).
• Define the return type using decltype and the comma operator.
• Formulate all expressions that must be valid at the beginning of the comma
operator (converted to void in case the comma operator is overloaded).
• Define an object of the real return type at the end of the comma operator.
For example:
Click here to view code image
template
auto len (T const& t) -> decltype( (void)(t.size()),
T::size_type() )
{
return t.size();
}

Here the return type is given by
Click here to view code image
decltype( (void)(t.size)(), T::size_type() )

The operand of the decltype construct is a comma-separated list of expressions,
so that the last expression T::size_type() yields a value of the desired return
type (which decltype uses to convert into the return type). Before the (last)
comma, we have the expressions that must be valid, which in this case is just
t.size(). The cast of the expression to void is to avoid the possibility of a userdefined comma operator overloaded for the type of the expressions.
Note that the argument of decltype is an unevaluated operand, which means
that you, for example, can create “dummy objects” without calling constructors,
which is discussed in Section 11.2.3 on page 166.

8.5 Compile-Time if
Partial specialization, SFINAE, and std::enable_if allow us to enable or
disable templates as a whole. C++17 additionally introduces a compile-time if
statement that allows is to enable or disable specific statements based on compiletime conditions. With the syntax if constexpr(… ), the compiler uses a
compile-time expression to decide whether to apply the then part or the else part (if
any).
As a first example, consider the variadic function template print() introduced

in Section 4.1.1 on page 55. It prints its arguments (of arbitrary types) using
recursion. Instead of providing a separate function to end the recursion, the constexpr
if feature allows us to decide locally whether to continue the recursion:8
Click here to view code image
template
void print (T const& firstArg, Types const&… args)
{
std::cout << firstArg << ’\n’;
if constexpr(sizeof…(args) > 0) {
print(args…);
//code only available if sizeof…(args)>0
(since C++17)
}
}

Here, if print() is called for one argument only, args becomes an empty
parameter pack so that sizeof…(args) becomes 0. As a result, the recursive call
of print() becomes a discarded statement, for which the code is not instantiated.
Thus, a corresponding function is not required to exist and the recursion ends.
The fact that the code is not instantiated means that only the first translation phase
(the definition time) is performed, which checks for correct syntax and names that
don’t depend on template parameters (see Section 1.1.3 on page 6). For example:
Click here to view code image
template
void foo(T t)
{
if constexpr(std::is_integral_v) {
if (t > 0) {
foo(t-1);
// OK
}
}
else {
undeclared(t);
// error if not declared and not
discarded (i.e. T is not integral)
undeclared();
// error if not declared (even if
discarded)
static_assert(false, "no integral");
// always asserts
(even if discarded)
static_assert(!std::is_integral_v, "no
integral");
//OK
}
}

Note that if constexpr can be used in any function, not only in templates. We
only need a compile-time expression that yields a Boolean value. For example:

Click here to view code image
int main()
{
if constexpr(std::numeric_limits::is_signed {
foo(42);
// OK
}
else {
undeclared(42);
// error if
undeclared() not declared
static_assert(false, "unsigned");
// always asserts
(even if discarded)
static_assert(!std::numeric_limits::is_signed,
"char is unsigned");
//OK
}
}

With this feature, we can, for example, use our isPrime() compile-time function,
introduced in Section 8.2 on page 125, to perform additional code if a given size is
not a prime number:
Click here to view code image
template
void foo (std::array const& coll)
{
if constexpr(!isPrime(SZ)) {
…
//special additional handling if the passed array has
no prime number as size
}
…
}

See Section 14.6 on page 263 for further details.

8.6 Summary
• Templates provide the ability to compute at compile time (using recursion to iterate
and partial specialization or operator ?: for selections).
• With constexpr functions, we can replace most compile-time computations with
“ordinary functions” that are callable in compile-time contexts.
• With partial specialization, we can choose between different implementations of
class templates based on certain compile-time constraints.
• Templates are used only if needed and substitutions in function template
declarations do not result in invalid code. This principle is called SFINAE

(substitution failure is not an error).
• SFINAE can be used to provide function templates only for certain types and/or
constraints.
• Since C++17, a compile-time if allows us to enable or discard statements
according to compile-time conditions (even outside templates).
1

In fact, it was Erwin Unruh who first found it out by presenting a program
computing prime numbers at compile time. See Section 23.7 on page 545 for
details.
2 Before C++11, it was common to declare the value members as enumerator
constants instead of static data members to avoid the need to have an out-of-class
definition of the static data member (see Section 23.6 on page 543 for details). For
example:
Click here to view code image
enum { value = (p%d != 0) && DoIsPrime::value };
3

At the time of writing this book in 2012"fn">4 Theoretically, even with
constexpr, the compiler can decide to compute the initial value of b at run
time.
5 We don’t name this function size() because we want to avoid a naming conflict
with the C++ standard library, which defines a standard function template
std::size() since C++17.
6 In practice, such a fallback function would usually provide a more useful default,
throw an exception, or contain a static assertion to result in a useful error message.
7 Since the copy constructor for class thread is deleted, this also ensures that
copying is forbidden.
8 Although the code reads if constexpr, the feature is called constexpr if,
because it is the “constexpr” form of if (and for historical reasons).

Chapter 9
Using Templates in Practice
Template code is a little different from ordinary code. In some ways templates lie
somewhere between macros and ordinary (nontemplate) declarations. Although this
may be an oversimplification, it has consequences not only for the way we write
algorithms and data structures using templates but also for the day-to-day logistics of
expressing and analyzing programs involving templates.
In this chapter we address some of these practicalities without necessarily delving
into the technical details that underlie them. Many of these details are explored in
Chapter 14. To keep the discussion simple, we assume that our C++ compilation
systems consist of fairly traditional compilers and linkers (C++ systems that don’t
fall in this category are rare).

9.1 The Inclusion Model
There are several ways to organize template source code. This section presents the
most popular approach: the inclusion model.

9.1.1 Linker Errors
Most C and C++ programmers organize their nontemplate code largely as follows:
• Classes and other types are entirely placed in header files. Typically, this is a file
with a .hpp (or .H, .h, .hh, .hxx) filename extension.
• For global (noninline) variables and (noninline) functions, only a declaration is put
in a header file, and the definition goes into a file compiled as its own translation
unit. Such a CPP file typically is a file with a .cpp (or .C, .c, .cc, or .cxx)
filename extension.
This works well: It makes the needed type definition easily available throughout the
program and avoids duplicate definition errors on variables and functions from the

linker.
With these conventions in mind, a common error about which beginning template
programmers complain is illustrated by the following (erroneous) little program. As
usual for “ordinary code,” we declare the template in a header file:
Click here to view code image

basics/myfirst.hpp
#ifndef MYFIRST_HPP
#define MYFIRST_HPP
// declaration of template
template
void printTypeof (T const&);
#endif

//MYFIRST_HPP

printTypeof() is the declaration of a simple auxiliary function that prints some
type information. The implementation of the function is placed in a CPP file:
Click here to view code image

basics/myfirst.cpp
#include 
#include 
#include "myfirst.hpp"
// implementation/definition of template
template
void printTypeof (T const& x)
{
std::cout << typeid(x).name() << ’\n’;
}

The example uses the typeid operator to print a string that describes the type of
the expression passed to it. It returns an lvalue of the static type
std::type_info, which provides a member function name() that shows the
types of some expressions. The C++ standard doesn’t actually say that name()
must return something meaningful, but on good C++ implementations, you should
get a string that gives a good description of the type of the expression passed to
typeid.1
Finally, we use the template in another CPP file, into which our template
declaration is #included:

Click here to view code image

basics/myfirstmain.cpp
#include "myfirst.hpp"
// use of the template
int main()
{
double ice = 3.0;
printTypeof(ice);
double
}

// call function template for type

A C++ compiler will most likely accept this program without any problems, but the
linker will probably report an error, implying that there is no definition of the
function printTypeof().
The reason for this error is that the definition of the function template
printTypeof() has not been instantiated. In order for a template to be
instantiated, the compiler must know which definition should be instantiated and for
what template arguments it should be instantiated. Unfortunately, in the previous
example, these two pieces of information are in files that are compiled separately.
Therefore, when our compiler sees the call to printTypeof() but has no
definition in sight to instantiate this function for double, it just assumes that such a
definition is provided elsewhere and creates a reference (for the linker to resolve) to
that definition. On the other hand, when the compiler processes the file
myfirst.cpp, it has no indication at that point that it must instantiate the template
definition it contains for specific arguments.

9.1.2 Templates in Header Files
The common solution to the previous problem is to use the same approach that we
would take with macros or with inline functions: We include the definitions of a
template in the header file that declares that template.
That is, instead of providing a file myfirst.cpp, we rewrite myfirst.hpp
so that it contains all template declarations and template definitions:
Click here to view code image

basics/myfirst2.hpp
#ifndef MYFIRST_HPP

#define MYFIRST_HPP
#include 
#include 
// declaration of template
template
void printTypeof (T const&);
// implementation/definition of template
template
void printTypeof (T const& x)
{
std::cout << typeid(x).name() << ’\n’; }
#endif

//MYFIRST_HPP

This way of organizing templates is called the inclusion model. With this in place,
you should find that our program now correctly compiles, links, and executes.
There are a few observations we can make at this point. The most notable is that
this approach has considerably increased the cost of including the header file
myfirst.hpp. In this example, the cost is not the result of the size of the template
definition itself but the result of the fact that we must also include the headers used
by the definition of our template—in this case  and .
You may find that this amounts to tens of thousands of lines of code because headers
like  contain many template definitions of their own.
This is a real problem in practice because it considerably increases the time
needed by the compiler to compile significant programs. We will therefore examine
some possible ways to approach this problem, including precompiled headers (see
Section 9.3 on page 141) and the use of explicit template instantiation (see Section
14.5 on page 260).
Despite this build-time issue, we do recommend following this inclusion model to
organize your templates when possible until a better mechanism becomes available.
At the time of writing this book in 2017, such a mechanism is in the works: modules,
which is introduced in Section 17.11 on page 366. They are a language mechanism
that allows the programmer to more logically organize code in such a way that a
compiler can separately compile all declarations and then efficiently and selectively
import the processed declarations whenever needed.
Another (more subtle) observation about the inclusion approach is that noninline
function templates are distinct from inline functions and macros in an important way:
They are not expanded at the call site. Instead, when they are instantiated, they create
a new copy of a function. Because this is an automatic process, a compiler could end

up creating two copies in two different files, and some linkers could issue errors
when they find two distinct definitions for the same function. In theory, this should
not be a concern of ours: It is a problem for the C++ compilation system to
accommodate. In practice, things work well most of the time, and we don’t need to
deal with this issue at all. For large projects that create their own library of code,
however, problems occasionally show up. A discussion of instantiation schemes in
Chapter 14 and a close study of the documentation that came with the C++
translation system (compiler) should help address these problems.
Finally, we need to point out that what applies to the ordinary function template in
our example also applies to member functions and static data members of class
templates, as well as to member function templates.

9.2 Templates and inline
Declaring functions to be inline is a common tool to improve the running time of
programs. The inline specifier was meant to be a hint for the implementation that
inline substitution of the function body at the point of call is preferred over the usual
function call mechanism.
However, an implementation may ignore the hint. Hence, the only guaranteed
effect of inline is to allow a function definition to appear multiple times in a
program (usually because it appears in a header file that is included in multiple
places).
Like inline functions, function templates can be defined in multiple translation
units. This is usually achieved by placing the definition in a header file that is
included by multiple CPP files.
This doesn’t mean, however, that function templates use inline substitutions by
default. It is entirely up to the compiler whether and when inline substitution of a
function template body at the point of call is preferred over the usual function call
mechanism. Perhaps surprisingly, compilers are often better than programmers at
estimating whether inlining a call would lead to a net performance improvement. As
a result, the precise policy of a compiler with respect to inline varies from
compiler to compiler, and even depends on the options selected for a specific
compilation.
Nevertheless, with appropriate performance monitoring tools, a programmer may
have better information than a compiler and may therefore wish to override compiler
decisions (e.g., when tuning software for particular platforms, such as mobiles
phones, or particular inputs). Sometimes this is only possible with compiler-specific
attributes such as noinline or always_inline.

It’s worth pointing out at this point that full specializations of function templates
act like ordinary functions in this regard: Their definition can appear only once
unless they’re defined inline (see Section 16.3 on page 338). See also Appendix
A for a broader, detailed overview of this topic.

9.3 Precompiled Headers
Even without templates, C++ header files can become very large and therefore take a
long time to compile. Templates add to this tendency, and the outcry of waiting
programmers has in many cases driven vendors to implement a scheme usually
known as precompiled headers (PCH). This scheme operates outside the scope of
the standard and relies on vendor-specific options. Although we leave the details on
how to create and use precompiled header files to the documentation of the various
C++ compilation systems that have this feature, it is useful to gain some
understanding of how it works.
When a compiler translates a file, it does so starting from the beginning of the file
and working through to the end. As it processes each token from the file (which may
come from #included files), it adapts its internal state, including such things as
adding entries to a table of symbols so they may be looked up later. While doing so,
the compiler may also generate code in object files.
The precompiled header scheme relies on the fact that code can be organized in
such a manner that many files start with the same lines of code. Let’s assume for the
sake of argument that every file to be compiled starts with the same N lines of code.
We could compile these N lines and save the complete state of the compiler at that
point in a precompiled header. Then, for every file in our program, we could reload
the saved state and start compilation at line N+1. At this point it is worthwhile to
note that reloading the saved state is an operation that can be orders of magnitude
faster than actually compiling the first N lines. However, saving the state in the first
place is typically more expensive than just compiling the N lines. The increase in
cost varies roughly from 20 to 200 percent.
#include 

The key to making effective use of precompiled headers is to ensure that—as
much as possible— files start with a maximum number of common lines of code. In
practice this means the files must start with the same #include directives, which
(as mentioned earlier) consume a substantial portion of our build time. Hence, it can
be very advantageous to pay attention to the order in which headers are included. For
example, the following two files:

#include 
#include 
…

and
#include 
#include 
…

inhibit the use of precompiled headers because there is no common initial state in the
sources.
Some programmers decide that it is better to #include some extra unnecessary
headers than to pass on an opportunity to accelerate the translation of a file using a
precompiled header. This decision can considerably ease the management of the
inclusion policy. For example, it is usually relatively straightforward to create a
header file named std.hpp that includes all the standard headers:2
#include
#include
#include
#include
#include
…







This file can then be precompiled, and every program file that makes use of the
standard library can then simply be started as follows:
#include "std.hpp"
…

Normally this would take a while to compile, but given a system with sufficient
memory, the pre-compiled header scheme allows it to be processed significantly
faster than almost any single standard header would require without precompilation.
The standard headers are particularly convenient in this way because they rarely
change, and hence the precompiled header for our std.hpp file can be built once.
Otherwise, precompiled headers are typically part of the dependency configuration
of a project (e.g., they are updated as needed by the popular make tool or an
integrated development environment’s (IDE) project build tool).
One attractive approach to manage precompiled headers is to create layers of
precompiled headers that go from the most widely used and stable headers (e.g., our
std.hpp header) to headers that aren’t expected to change all the time and
therefore are still worth precompiling. However, if headers are under heavy
development, creating precompiled headers for them can take more time than what is
saved by reusing them. A key concept to this approach is that a precompiled header

for a more stable layer can be reused to improve the precompilation time of a less
stable header. For example, suppose that in addition to our std.hpp header (which
we have precompiled), we also define a core.hpp header that includes additional
facilities that are specific to our project but nonetheless achieve a certain level of
stability:
#include "std.hpp"
#include "core_data.hpp
#include "core_algos.hpp"
…

Because this file starts with #include "std.hpp", the compiler can load the
associated precom-piled header and continue with the next line without recompiling
all the standard headers. When the file is completely processed, a new precompiled
header can be produced. Applications can then use #include "core.hpp" to
provide access quickly to large amounts of functionality because the compiler can
load the latter precompiled header.

9.4 Decoding the Error Novel
Ordinary compilation errors are normally quite succinct and to the point. For
example, when a compiler says “class X has no member ’fun’,” it usually
isn’t too hard to figure out what is wrong in our code (e.g., we might have mistyped
run as fun). Not so with templates. Let’s look at some examples.
Simple Type Mismatch
Consider the following relatively simple example using the C++ standard library:
Click here to view code image

basics/errornovel1.cpp
#include 
#include 

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Author                          : David Vandevoorde & Nicolai M. Josuttis & Douglas Gregor
Create Date                     : 2017:09:16 16:18:52+00:00
Producer                        : calibre 3.7.0 [https://calibre-ebook.com]
Title                           : C++ Templates: The Complete Guide
Description                     : 
Subject                         : 
Creator                         : David Vandevoorde, Nicolai M. Josuttis, Douglas Gregor
Publisher                       : Pearson Education
Date                            : 2017:09:15 00:00:00+03:00
Language                        : en
Identifier Scheme               : isbn
Identifier                      : 9780134778747, B075MJNCCH
Metadata Date                   : 2017:09:16 19:18:52.972000+03:00
ISBN                            : 9780134778747
Isbn                            : 9780134778747
Timestamp                       : 2017:09:16 19:15:29.047000+03:00
Title sort                      : C++ Templates: The Complete Guide
Author sort                     : Vandevoorde, David
Page Count                      : 2606