Contents

Introduction

Igor's C++ Grimoire aims to be a reasonably complete reference to C++11, C++14 and C++17. C++20 additions are a work in progress; what there is is limited and subject to change (in particular, the section on Coroutines is likely to change significantly in the future). There are also some C++20 specific cross-references that will not resolve at present

Many sources have been used to compile it, but the major ones, and some of particular note are as follows. The C++ Programming Language 4th Ed, by Bjarne Stroustrup. Effective C++ 3rd Ed, and Effective Modern C++ 1st Ed, November 2014, both by Scott Meyers. On-line resources include ISO C++ FAQ, cppreference.com, CppCon and many others

The original intention was to just present the facts; the syntax, some examples, and a thorough description of the language with the aim of being as complete and unambiguous as possible whilst keeping the fluff to a minimum. As time has marched on, considerable 'other stuff' has been added particularly in the area of advice on avoiding common (and sometimes obscure) pitfalls, particular techniques, and general advice that should make life easier, Notable exceptions to the original ethos of only the facts are the Templates and Meta-Programming sections which almost entirely describe the application of technique rather than syntax, and the Design Considerations section which is mostly made-up of (often other people's) rambling thoughts and ideas

The standard library is not described in any detail. Exceptions are the Concurrency support (which is almost entirely implemented by standard library components), and some basic components and/or particular types/functions that are referred to by other items. These are all described in the Standard Techniques section and the sections that follow it. Be aware though, that most of this latter section provides only cursory descriptions, and those descriptions that are more complete may not be absolutely comprehensive

This document is intended as a reference; not a tutorial. As such, early sections often refer to concepts that are not introduced until later; hopefully the extensive cross-referencing will help in this respect

Specific points in the main text may also be highlighted with one of the above symbols as appropriate

Items that only relate to a specific C++ version are identified with , , etc, as appropriate. Whilst no attempt is made to document versions earlier than C++11, there is the odd item that is specific to C++98/03. These are identified with

Features that apply in all versions upto and including a particular version are identified with , , , etc

Features that have been introduced or modified in a particular version and retained in all subsequent versions are identified with , , , etc, though in the case of (indicating a change since C++98/03), only major features are identified this way

A few non-standard (but commonly supported) features are described, and these are identified with

Any points that are incomplete, seemingly inconsistent or based on ambiguous source material are marked with . Hovering over these markers should display further details

• Code snippets are shown like this; int a = fn();
• Individual code elements are shown like this; a (or sometimes like this if there is a likelihood that it would get lost/confused within the surrounding text; a)
• Reserved words are often shown like this; virtual int fn();
• If a particular part of the syntax is being highlighted or referred to, it is shown like this; class colour {…}. Operators may also be highlighted this way
• Any optional parts of the syntax (or parts that may not be applicable in all cases) are indicated like this; short int a;
• Pseudocode or syntax which may represent a number of forms is shown like this; while(condition) {…}

All but the most trivial of code examples have been compiled, run, and shown to work. However, they typically omit the required header file inclusions, and may require some using declarations where components from the std namespace have not been qualified (which is often the case)

References within this document may be textual links or may be shown as just tiny links like (which should pop-up a destination hint if hovered over). Many links refer to very specific items, paragraphs or examples appropriate to the context of the referrer

If you spot any errors, inconsistencies, or think something has been missed out or is incomplete or ambiguous then please let me know; no-matter how trivial the issue may seem. You can email me at igorknockknock.org.uk (note that this will not cut-and-paste correctly - that's deliberate. Also, take care spelling 'knockknock'!)

You are free to make copies of this document for your own use. You may not publicly republish it. Distribution within an organisation may only be in its original, unmodified form. You may not charge for it

Code Structure

• C++ is generally written in plain (7 bit) ASCII text (though an implementation may also support extended identifiers)
• String literals may contain Unicode characters
• Any one program is implemented as one or more text files

Whitespace

• Whitespace (one or more of the characters ' ' (space), TAB, and/or NEWLINE, in any sequence) must be used to separate type/variable/function names and reserved words. It is generally optional between names/reserved words and syntactic elements and operators such as ( or ->
• Some operators are composed of multiple characters such as +=. Adding whitespace to these (eg, + =) will result in a syntax error
• Whitespace is significant within string literals
• All but the last line of a multi-line macro definition must be terminated with a \ continuation character
• Other than these points and the occasional special case, whitespace may be freely used (or not) as required

Trigraphs

A trigraph is a series of three characters which represent a single other character. The full collection of supported trigraphs are;-

• Trigraphs were first introduced into C to address the problem that some keyboard layouts and some character sets (in particular ISO-646) do not support all the characters of the C (and by extension, C++) syntax
• Trigraph sequences are searched for, and replaced with their single-character equivalents by the pre-processor before any other parsing takes place
• A trigraph sequence may occur anywhere within the C++ source text; the search-and-replace process takes no regard of the context. Therefore, a trigraph sequence may occur within a pre-processor directive, a comment, a character or string literal, etc
• Trigraphs are now largely anachronistic and their use is strongly discouraged. Some pre-processors will not even parse them without a special option being specified. Some pre-processors will parse them but issue a warning
• Support for trigraphs has been removed

Digraphs

A digraph is a series of two characters which represent a single other character. The full collection of supported digraphs are;-

• Digraphs were introduced as a simplified alternative to the most common five trigraphs
• The pre-processor performs the substitution of digraphs in the same way as for trigraphs
• Unlike trigraphs, a digraph may not be used as part of another token. That is, a digraph sequence embedded within a pre-processor directive, a comment, a character or string literal, etc shall not be substituted. This makes them marginally safer
• The digraph sequence %:%: is (specially) treated as a single token (##) and not as two separate # tokens
• Most pre-processors will honour and substitute digraph sequences but their use is strongly discouraged

Source Files

Apart from the maintainability and management improvements that come from dividing a program into multiple files, the technique improves modularity, enhances logical structure, and allows separation of interfaces from implementation

The text files are generally divided into two groups; implementation files and interface (header) files. Implementation files will typically include one or more header files, and header files may (and often do) also include other header files. This distinction is rendered a little fuzzy in practice because it is common for header files to define implementation in the form of inline functions, template definitions, etc

A compiler shall typically deal with each implementation file in turn. It will first invoke the preprocessor to create a translation unit. It is to this that the C++ language rules are applied. The translation unit is compiled into object code. All the individual object code parts are then passed to a linker to form the final executable code

• By convention, implementation files have the filename extension .cpp and header files have the filename extension .h. Other options in use are .cxx, .cc, .hh, .hpp, etc
• Although the #include directive may be used almost anywhere, it is not wise to use it anywhere other than at the top of a file and from within the global namespace. A possible exception is from within a namespace when dealing with old code. Including implementation files into other implementation files is extremely bad practice
• Because each implementation file is dealt with individually, each must define and include all that it needs in order to be analysed and compiled in isolation
• A translation unit that relies on a definition in some other translation unit is said to have external linkage
• A name that is not accessible from other translation units is said to have internal linkage
• To be correct, all non-local declarations and definitions must be identical across all translation units; if two translation units had a different idea of a particular class structure, for example, then the resulting program would almost certainly be incorrect
• The way to ensure consistency between translation units is to define common header files and include them into any other files that make use of the definitions defined within them
• A header file must (should!) never contain any function or object definitions (ie, anything that will directly consume memory at run-time), any unnamed namespaces or any using-directives. If a header file included a function or object definition, then that object would risk being instantiated multiple times which would either cause a subsequent linker failure or would cause the program to malfunction at run time
• Exceptions to this are the definition of inline functions, template definitions, constants and constant expressions, either stand-alone or as class methods. Also, despite being definitions, struct and class types are also acceptable in header files

• Where multiple header files are used that include each other, repeated inclusion of the same header can occur. Apart from wasting compilation time, this can cause problems with multiple definitions of the same thing(s). To protect against this, use something like this (see also pre-processor);-

  // My header file (my_header.h) #ifndef MY_HEADER_H #define MY_HEADER_H (1) // Body of header file #endif // def MY_HEADER_H
• A compiler is free to remove from the final object/executable any functions that are not actually used, with the exception of virtual functions
• The physical structure of the program, as defined by its collection of files, is not necessarily (and quite often is not) the same as its logical structure. For example, the logical structure of a namespace or class could be divided across multiple files

Template Code Organisation

There are some special considerations when dealing with templates. In particular, there are two rules with regard to template compilation;-

• A template must be defined (not just declared) in any translation unit it is used in, though it need not be instantiated prior to use
• A template must be declared before it is used, but may be defined afterwards (within the same translation unit)

Probably the most common code organisation approach is to include the same template definition into all translation units and rely on the compiler to optimise-away all duplicate specialisations; the "include everywhere" technique;-

One problem with this approach is that it tends to (unintentionally) encourage undesirable dependencies to grow between the user-code and the template definition

This problem can be mitigated by taking the approach of "include template definitions later (after they are used)". This can be achieved by dividing the template into a declaration .h file, and a definition .cpp file, and then arranging the translation unit thus;-

This minimises the changes of the template definition having some unanticipated and detrimental effect on the user code, but makes the reverse risk greater

• The linkage rules for a template are those of the generated specialisations/instantiations
• Non-inline, non-template functions and static members must have a unique definition in exactly one translation unit within the whole executable. Such members can be a cause of linkage problems if defined within a class template that is used by several translation units
• Because templates tend to include more data in their .h files than their non-template equivalents, changes in a template can lead to considerable recompilation of many translation units, especially if the "include everywhere" technique is employed
• One technique for minimising such dependencies is to add a non-template wrapper (function) around the template. Such a function can reside in a separate translation unit and it may even be possible to restrict the exposure of the template to the single .cpp file where the wrapper is defined
• Manual/explicit instantiation can also be employed as an alternative to "include everywhere" technique by limiting instantiation to a single translation unit. This avoids generating multiple instantiations in the first place

Standard Headers

An implementation may be "hosted" or "free-standing"; the former includes all the standard library headers by default. The latter does not, but must support at least the header files highlighted (eg, <cstddef>) as a minimum

Everything defined in these headers is in the std namespace, so the definitions within them must be explicitly qualified or appropriate using-declarations and/or a using-directive must be used to bring them into scope

• The C Library is based on C99

  The C Library is based on C11 with the 2012 technical corrections applied, except it does not include stdatomic.h, stdnoreturn.h or threads.h as these features are provided by other library components

• An implementation may treat standard headers specially by providing some optimisation of their use. It is even possible that the header files do not actually exist at all as files, but just as a compiler's internal representation. Such optimisation should be transparent to the user's code though

'C' Functions

To access an external 'C' function from C++, use the following;-

A group declaration may also be made in order to create a linkage block;-

Assuming the above is within a header file, it is more common to see it written as follows; to avoid errors when processed by a C compiler;-

• The "C" identifier indicates a linkage convention, not a language. Hence, the same syntax may also be used when a 'C' function needs to call a C++ function, or to access external code written in other languages such as assembler or Fortran; the "C" identifier remains the same
• A function specified as extern "C" still obeys the C++ type-checking and argument conversion rules, and not the weaker plain 'C' rules
• Despite the extern syntax, any variables declared within an extern "C" {…} linkage block must themselves still be declared extern in order to be declarations rather than definitions
• If a function is declared as extern "C", the linkage specifier effects not only the function name, but also all of its arguments
• As a result, it is not possible (unless a particular compiler and environment allows it) to (say) pass a pointer argument to a function with C++ linkage to a function with plain 'C' linkage. The reverse is also true
• The C++ versions of the standard 'C' headers already include appropriate extern "C" specifiers
• Any variables passed to or from a 'C' function must (of course) comply with the rules of the 'C' (or other foreign) language. Therefore, any function arguments (or indeed any shared global variables) are restricted to POD types

Inline Assembler

Assembler code may be embedded into C++ source code with the asm statement;-

• asm is not guaranteed to be supported by an implementation
• If it is supported then because of the nature of what it does, the exact details of what string means, its format and how it interfaces with the surrounding C++ code is highly platform-specific
• Although string is usually a '\0'-terminated ('C'-style) string literal, a particular implementation may define it otherwise

main()

The entry point of any C++ program is the function main(). It's prototype is the same as for plain 'C'. In fact, two prototypes are supported. A program must specify only one of them;-

Where;-

• argc indicates the number of parameters being passed via the argv array. This is always ≥ 1
• argv is an array of string pointers to '\0'-terminated strings. Generally, the first parameter (argv[0]) is the name of the application (as specified on the command line). There may be zero or more additional parameters that are (of course) application-specific
• The list of arguments is zero terminated, so argv[argc] is always nullptr
• The form of main() with the third argument envp[] is non-standard but quite widely supported. The envp[] argument is an array of string pointers, arranged in the same way as the argv[] argument. It refers to the environment (table of variables) that the program is running in and can be used in the same way as the POSIX extern char** environ reference
• The normal function return requirements of main() are relaxed; there is no absolute requirement for main() to return a value. Reaching the end of main() without returning a value implies success. Convention is that if a value is returned, zero indicates 'success', and any other value indicates an application/platform-specific error code
• main() must be defined globally, outside of any namespace

Program Termination

A program shall terminate if any of the following occurs;-

• If main() returns
• If there is a call to exit(int rtn_code). This represents normal termination, and destructors for all global and static objects (but not local) shall be called. Any open 'C' file streams shall be flushed and closed. Temporary files shall be deleted (ref. tmpfile()). The value passed to exit() is analogous to the return value from main(). Calling exit() from within a destructor may cause an infinite loop
• If there is a call to abort(). This indicates abnormal termination. No destructors are called
• If an exception is thrown but not caught
• By violating noexcept. See also unexpected() and set_unexpected()
• If there is a call to quick_exit(). This is the same as exit() and also represents normal termination, but no destructors are called

In any implementation, there are probably other ways of terminating a program such as division by zero, illegal memory access, etc

The plain 'C' (and C++) standard library function std::atexit() may be used to register a function that should be executed on normal program termination. For example;-

• The function at_quick_exit() performs the same job as atexit() but for calls to quick_exit()
• An object constructed before a call of atexit(f) will have its destructor called after f() is invoked. An object constructed after a call of atexit(f) will have its destructor called before f() is invoked (ie, destruction in the reverse order of construction is maintained)
• exit(), abort(), quick_exit(), atexit(), and at_quick_exit() are defined in <cstdlib>
• Abnormal termination can also result in an implicit call to std::terminate()

Pre-Processor

There are a number of pre-processor directives. Parsing these can (and likely does) result in code modification or compiler parameter modification. Only after all pre-processor directives are parsed is the compiler presented with the resulting code

• The preprocessor has no concept of a type; it deals only with numeric literals and strings (any surrounding "…" are part of the string as far as the preprocessor is concerned)
• It can perform some basic arithmetic (eg, +, -, * and /), logical (eg, &&, ||), bitwise (eg, &, |) and comparative (eg, ==, <) operations
• It does not understand what a C++ variable, type or function is; specifying any of these within a pre-processor directive shall be treated as an arbitrary string without specific meaning

All pre-processor directives start with the character #. Here is a list of them;-

Pre-Defined Macros

The compiler defines a number of macros which may be used within code. Some of these are very useful, especially for debugging

Some other macros are conditionally defined by the implementation;-

Comments

Comments are defined as follows. There are two forms; the traditional 'C' comments which start with /* and end with */. Such comments may extend for as many lines as required. There is also the C++ comment style. This allows single-line comments only, starts with // and ends with the end-of-line character

• The /* */ comment style cannot be nested within itself; doing so will result in a compilation error
• The // comment style can be nested inside itself (on a single line) or within a /* */ style comment

Reserved Words

Here is a complete list of reserved keywords;-

In addition, the keyword export is reserved but currently not used. It was originally intended to facilitate template definition/declaration separation, but the idea failed

The following contextual keywords are defined;-

Attributes

Attributes provide a means of tagging certain names, types, functions, etc as having particular features. The following standard attributes are defined (there are also several non-standard attributes in common use);-

• Atributes do not affect the type system and they do not change the meaning of a program. They are instructions to the compiler to enable or disable certain features. The compiler may issue appropriate warnings based on the existence (or absence) of a perticular attribute
• A compiler will not issue an error for any attributes it doesn't recognise (though it may issue a warning).   Implementations often exhibit this behaviour anyway
• Some attributes take arguments, such as [[deprecated("reason text")]]
• Multiple attributes may be specified separately such as [[deprecated]] [[noreturn]] or together as a comma-separated list, [[deprecated, noreturn]]
• Attributes applied to a declaration may be specified before and/or immediately after the entity's name
• Attributes applied to a non-declaration must usually be placed immediately after the entity
• An implementation may define local (non-standard) attributes. If it does then these should be defined within a unique namespace. For example, [[my_compiler::turbo_boost]]
• If several attributes from the same namespace are required, then a using directive may be used. For example, [[my_platform::turbo_boost, my_platform::flash_lights]] could also be written as [[using my_platform: turbo_boost, flash_lights]]
• Several implementation-specific methods of specifying attributes are also in common use, such as __attribute__(attr_name)

[[deprecated]]

The [[deprecated]] attribute may be used to mark a name as deprecated. The name can still be used, but such marking gives the compiler an opportunity to issue a warning of its use

There are two forms of this attribute;-

This attribute may be applied to the following;-

• Note the somewhat inconsistent placement of the [[deprecated]] attribute, depending on the target entity. The indicated placement is important
• A name declared as non-deprecated may be later redeclared deprecated but not visa-versa

[[likely]] and [[unlikely]]

The [[likely]] and [[unlikely]] attributes are used to indicate to the compiler execution paths that are more or less likely to be taken. This may allow the compiler to apply optimisations based on these directions

[[likely]] and [[unlikely]] cannot both be applied to the same label/statement

These attributes may be applied as follows. Note that this is not an exhaustive list of examples; these attributes may be applied to any label or statement other than a declaration (it may also be applied to function calls, but not function definitions)

In the following examples, [[likely]] and [[unlikely]] are interchangeable

[[maybe_unused]]

The [[maybe_unused]] attribute is used to indicate that a declaration may not be used. If a compiler would normally issue a warning for an unused entity, then this attribute will suppress it

It may be applied to the same entities as [[deprecated]] (except for namespace names and template specialisations) in the same way

[[nodiscard]]

The [[nodiscard]] attribute is used to indicate that the return value of a function holds some significance and should not be ignored by the caller. It may be applied to a function declaration, a class declaration or an enum declaration

If the caller of a function with this attribute ignores the function's return value, then the compiler should issue a warning

Similarly, if a function returns a class or enum type that has been declared with this attribute then the compiler should issue a warning. For example;-

Names

A Name refers any of the following;-

• An identifier—that is, a variable; given the variable declaration int a;, a is the variable name. A function; given the function declaration void fn(int a);, fn is the function's name
• An operator function has a name. Given the function declaration X& operator+(const X& rhs);, operator+ is a name
• Similarly for a conversion operators, for example operator int(const X& a);, and user-defined literal operators, for example operator"" _cm ();

• A template. Given;-

  template<typename T> struct X { T a; };

  X is the template's name

• A goto label

• A name is an lvalue expression

Naming Rules

• Generally, a name starts with a character a-z, A-Z, or '_', and consists of these plus 0-9

• An implementation that supports extended identifiers allows a subset of the wider Unicode character set to be used for identifier names. Such characters may be specified directly as multi-byte UTF-8 sequences, or by indicating the Unicode code-point value (\uhhhh or \Uhhhhhhhh. For example, the following three definitions are identical;-

  int ģ = 0; int \u0123 = 0; int \U00000123 = 0;
• In the case of an operator@ name, then the appropriate operator character(s) are also used
• All names (whether namespaces, types, variables, functions, etc) are case sensitive
• Non-local names starting with '_' are reserved for use by the environment and should not be used. All names starting with '_{A-Z}' or '__' are reserved
• C++ imposes no limit on name length, though other parts of the tool chain are likely to

Scope

A declaration (or a definition, if no previous declaration exists) introduces a name into a scope. Here is a list of possible scopes and details of what qualifies a name to be considered to be within each scope;-

Any name may be a type name or a non-type name. A type name is a struct, class, enum or union. A non-type name is a variable, function or an argument to a function

For the purposes of the following discussion, alias, typedef and template names do not feature (it's not possible to do so without causing an error)

• The same type name or the same non-type name may not be defined twice within the same scope. So;-

  void fn(int a) { int a; // Error: The non-type name 'a' is already defined in this scope } class b {}; enum b { one, two }; // Error: The type name 'b' is already defined in this scope

• It is possible to define a type name that is the same as a non-type name in the same scope. For example, this is legal;-

  namespace x { class a {}; // A type name void a(void); // A non-type name }

• When referring to a name that is duplicated in this way, the default is to assume use of the non-type name. To use the type version of the name, it must be qualified by preceding its use with the appropriate struct, class, enum or union. This is called an Elaborated Type Specifier. Expanding on the previous example;-

  int main() { x::a b; // Error: 'a' refers to the the function 'a', not the class class x::a c; // Ok: use of 'class a' is qualified }
• A forward declaration is a special case of an Elaborated Type Specifier

Name Hiding And Qualification

• A declaration of a type or non-type name will hide/override any same-named declaration already made in a wider scope until the (narrower) scope ends

• The same name may be defined in two different scopes. It may be necessary to disambiguate which of the names is being referred to by qualifying the reference. For example;-

  namespace x { int a; namespace z { int b; } } namespace y { int a; } using namespace x; using namespace y; int c = a; // Error: Ambiguous reference to 'a' int d = x::a; // Ok: Explicit qualification

  Qualification can be nested. Expanding on the above example;-

  int e = x::z::b;

  The qualification syntax (::) may be used to identify type or (as in the above example) non-type names.

• A hidden global name may be referred to by qualifying with ::name

Namespaces

A Namespace defines a named scope. This allows collections of logically related (type/function/object) names to be grouped together; they become members of the namespace. This notion allows the same names to exist in multiple parts of the codebase. Because they are in different scopes, the names do not interfere with each other. A namespace is declared like this;-

• Members declared within a namespace form a distinct scope; separate from members of any other namespace
• Members within a namespace may make reference to other members within the same namespace without any special syntax (they are in the same scope)
• Access to namespace members from outside the namespace may be achieved by using an explicitly qualified name; namespace-name::member-name
• Global members (not declared in any namespace) may be explicitly qualified by using ::name

• This example demonstrates the scope of namespaces and implicit/explicit name resolution;-

  // Some global declarations, outside of any namespace struct X {int y; int z;} int var = 0; void fn(X& b); namespace my_library { // Declare a type and a variable struct X {int y; int z;} int var = 0; // Declare/define a function. The type 'X' referred to here implicitly refers to the 'X' // defined just above, in the same namespace. Similarly, for the variable 'var' void fn(X& b) { b.y = var; } } namespace other_library { // Declare a type and a variable struct X {int y; int z;} int var = 0; // Declare/define a function. The type 'X' referred to here implicitly refers to the 'X' // defined just above, in the same namespace. Similarly, for the variable 'var' void fn(X& b) { b.y = var; } // Another function; The type 'X' referred to here explicitly refers to the 'X' // defined globally. Similarly, for the variable 'var' void fn2(::X& b) { b.y = ::var; } // Another function; The type 'X' referred to here explicitly refers to the 'X' // defined in the 'my_library' namespace. Similarly, for the variable 'var' void fn3(my_library::X& b) { b.y = my_library::var; } // Declare/define another function void fn4() { ::X v1; ::fn(v1); // Call global fn() my_library::X v2; my_library::fn(v2); // Call my_library::fn() X v3; fn(v3); // Call other_library::fn() } } // Call global fn() X v1{}; fn(v1); // Call my_library::fn() my_library::X v2{}; my_library::fn(v2);

• Argument-dependant lookup may be used to qualify name lookup, rather than explicit qualification with ::. For example;-

  my_library::string s; // Call fn(). This is implicitly resolved to my_library::fn() because that is the only // version of fn() that takes a my_library::X parameter my_library::X v{}; fn(v);
  • When performing such lookups, normal overload resolution is performed. This means that if a namespace member invokes a function, argument-dependant resolution will NOT prefer its own namespace over other namespaces
  • A special case is when a class member invokes a function. In this case, argument-dependant resolution will prefer other members of the same class or base classes over members of any namespaces

• Namespaces are open and may be declared in parts. This allows the namespace members to be declared in separate source files, or maybe to allow division of members for improved readability (for example, separating the private from the public interface). For example;-

  namespace my_namespace { void fn1(); } // ... namespace my_namespace { string fn2(int); }

  Namespace alias' may not be used to 'add' to a namespace in this way; the original namespace-name must be used

• Namespace members may be declared within the namespace but defined outside it by qualification. For example;-

  namespace my_namespace { // Declaration void fn(); } // Definition void my_namespace::fn() {…}

  This is an important feature; it allows the namespace to be declared in a header file and some or all of its members to be defined elsewhere

• A namespace member must be declared within the namespace before it can be defined outside it
• It is not possible to declare a new namespace member using the :: qualifier. All members must be declared within the namespace
• A class definition creates a namespace, hence the :: qualifier is used in the same way for class member qualification
• A variable defined within a namespace without an explicit initialiser shall be initialised by default in the same way as globals are
• When used in a namespace, static has the same effect as for globals
• It is legal to declare plain 'C' functions within a namespace without effecting the external linkage. This technique is used in the standard library <cstdio> header for example and is useful for including plain 'C' libraries without polluting the global namespace
• Namespace names follow the usual naming rules
• The [[deprecated]] attribute may be applied to a namespace

Nested Namespaces

Namespaces may be nested (this is used in the standard library in the chrono and rel_ops classes);-

Nested namespaces may be specified directly. For example, declaring sub_fn() from the previous example could also be written;-

• Nested namespaces are subject to the same qualification and resolution rules as other namespaces

Inline Namespaces

Any members within a namespace declared as inline will take on the scope of the including namespace. For example;-

• The main intended use of inline namespaces is, as the above example shows, to allow library implementations to cleanly support multiple versions of themselves

Unnamed (Anonymous) Namespaces

A namespace can be created without a name such as;-

• A nameless namespace is useful when the purpose is to just create a local scope to avoid clashes with other namespace members
• Immediately following a nameless namespace is an implicit using-directive so that all the namespace members are externally visible from the parent scope, and into other scopes if qualified

Namespace Hierarchies

Namespaces can include other namespaces. This can lead to naming conflicts. using-declarations, using-directives and namespace-alias' can resolve these issues and are described in the following sections

'using' Declaration

If a namespace-scoped name is used often, a synonym (a using-declaration) may be defined via the using qualifier. This eliminates the need to constantly explicitly qualify the name with ::. Rather than this;-

…it is possible to do this;-

• The effects of the using-declaration are restricted to the current scope
• The using-declaration applies to all versions of an overloaded name
• A using-declaration creates a local name. Like any other local name, this may hide other non-local declarations of the same name
• It is not possible to apply a using-declaration to an unnamed namespace member
• The using-declaration may also be used within class hierarchies
• The using keyword may also be used in other contexts; see aliases and 'using' Directive

'using' Directive

A using-directive may be used to bring into scope all members of a namespace. For example;-

• Names brought into scope with a using-directive are on an equal priority with global names in terms of name resolution
• Name clashes between members of different namespaces brought into the same scope with using-directive (or between those namespace members and globals) are only considered to be in error if the clashing name(s) are actually used
• See also aliases and 'using' Declaration

Using 'using'

Both using-declarations and using-directives may be used within other namespaces. Apart from bringing-in common external namespaces, this can be useful if a hierarchy of namespaces are being defined, such as a 'user' part and an 'implementation' part

The technique can also be used to construct local collections of other namespaces. For example;-

• Following the above, it would be possible to access any members of the external_lib1 and external_lib2 namespaces, and selected parts of the external_lib3 namespace in terms of my_library. For example, if external_lib1::fn(); were defined, it would be possible to access it with my_library::fn();
• When it comes to resolving clashes within compound namespaces, explicitly defined names and using-declarations take priority over using-directives. So if external_lib1::X were defined, then my_library::X would resolve to external_lib3::X and not external_lib1::X

• The inline qualifier may be applied to a using-directive. In the event of a name clash, this will give priority to the effected namespace. For example;-

  inline using external_lib1;

  While this may have some use in specific cases such as version control, it is not something that should be used generally

• The above example also shows that using-declarations and using-directives may be used for the same namespace. This is useful for resolving clashes; in this case, the whole of the extern_lib2 namespace is available but a reference to my_library::Z will resolve to external_lib2::Z in preference to any other declaration
• The only time the external names would have to be used would be during object declaration. For example, if a type external_lib1::Y were defined, then my_library::Y my_obj; would not work. external_lib1::Y my_obj; would have to be specified instead

Namespace Alias'

• A namespace alias may be defined. This is usually used to provide a shorter, more convenient name for a namespace, or (for example) to provide a generic name for a versioned library;-

  namespace alias = namespace-name

  For example;-

  namespace my_very_long_namespace_name { …member declarations… } // Declare an alias. After this, 'stuff' may be used where // 'my_very_long_namespace_name' would normally be required namespace stuff = my_very_long_namespace_name;

• This idea can also be applied to individual namespace members (though through a different mechanism);-

  using object = my_very_long_namespace_name::long_object_name;

Program Behaviour

Undefined Behaviour

The C++ language entertains the concept of Undefined Behaviour. Essentially, this arises from code structures, techniques and/or control paths that do not perform in a predictable way; often without any warning from the compiler

• Many things can lead to Undefined Behaviour; some obvious ones being dereferencing a null pointer, race conditions in a multi-threaded program, casting-away const on a variable and then writing to it, accessing an object beyond its lifetime, and many more

• If a program exhibits Undefined Behaviour then, essentially, anything that follows in the execution cannot be relied upon to be correct, or even to make sense. The program may crash. It may exit. It may continue to run but behave incorrectly or generate an indeterminate result. It may continue to run and operate perfectly well. It may proceed to calculate the answer to life, the universe, and everything; anything is possible. For example, the following will invoke Undefined Behaviour but is unlikely to cause a crash or provoke the program to become spontaneously self-aware. It will, however, generate an indeterminate result;-

  int a = 1; int b = --a + ++a;
• An operation that exhibits Undefined Behaviour may behave differently on different platforms and architectures. It may even behave differently when compiled on different versions of the same compiler
• There are some cases where the possibility of Undefined Behaviour can provide the compiler with optimisation possibilities; if certain behaviour should never happen (because to do so would be Undefined Behaviour), the compiler may ignore such possibilities, resulting in better code generation; example

Unspecified Behaviour

Some behaviour is left to the discretion of the implementation, though it must be handled 'correctly' by the implementation

• In many cases, Unspecified Behaviour must conform to one or more of a (typically small) selection of options. Such behaviour need not be documented by the implementation, and in many cases, is not
• It may not degenerate into undefined behaviour
• Unspecified Behaviour may or may not be consistent throughout the program
• Example: The order in which arguments to a function are evaluated is unspecified; it is at the discretion of the implementation, and may differ between calls, even to the same function
• Because Unspecified Behaviour may be inconsistent (even within the same program), code which relies on it should be avoided; it is safest to treat it similarly to undefined behaviour in this respect

Implementation-Specific & Implementation-Defined Behaviour

Some behaviour is left to the discretion of the implementation, but it should be documented by the implementation sufficiently well enough to be able to make meaningful analysis of the behaviour

• Like unspecified behaviour, degradation to undefined behaviour is not an option for the implementation
• Unlike unspecified behaviour, it must be consistent throughout the program
• Example: The size of an int type must conform to a minimum size, but it is left to the discretion of the implementation to define its actual size, which should be documented. Another example is how high-order bits of a signed integral are handled when a right-shift operation is performed on it
• Implementation Defined Behaviour is, by its very definition, non-portable

Fundamental Data Types

• Elsewhere, there are several references to Integral types. Unless specifically stated otherwise, this can be interpreted as referring to any of the 'Character', 'Integral', or 'Boolean' types in the following table, (with or without modifiers), as well as "plain" enumerations
• An arithmetic type is an Integral or any of the 'Floating Point' types in the following table
• A scalar type is one that is an arithmetic type, an enum class, a pointer, pointer-to-member, or std::nullptr_t (in each case, with or without modifiers)
• There are also several references to Built-In types. Unless specifically stated otherwise, this can be interpreted as referring to any of the types in the following table, (with or without modifiers), and arrays of any of these. void is usually excluded from such contexts
• All built-in types ( except void,  including void) are also literal types
• Although implemented as some fundamental type, an enumeration ("plain" or class) is a user-defined type
• There are a number of standard predicates that may be used to test the type properties referred to above

• A char is usually 8 bits, but this is not always the case. Regardless, sizeof(char) is ALWAYS 1. See this point for further details
• The Character types are large enough to represent at least 256 distinct values. This guarantees UTF-8 encoding capability
• There are a number of Data Models in widespread use (though an implementation is not guaranteed to follow any of these);-

  Data Model	int	long	pointer	Common Platform(s)
  LP32 or 2/4/4	16 bit	32 bit	32 bit	Win16 API
  ILP32 or 4/4/4	32 bit	32 bit	32 bit	Unix, BSD, Linux, Win32 API
  LLP64 or 4/4/8	32 bit	32 bit	64 bit	Win64 API
  LP64 or 4/8/8	32 bit	64 bit	64 bit	Unix, BSD, Linux
  ILP64 or 8/8/8	64 bit	64 bit	64 bit	Cray, Unicos

  In all of the above Data Models, long long is 64 bit

  Generally, LP32 and ILP32 are considered 32 bit systems and LLP64, LP64 and ILP64 are considered 64 bit systems though this definition is somewhat controversial

  ILP64 is not very common; defining int as 64 bit tends to cause problems with portability, and it artificially inflates data structure sizes. It is common for implementations of this model to define a specific 32 bit integer type, often called _int32, but this is outside of the C++ specification

• long double is commonly either 64 or 80 bits (though could be larger). For > 64 bits, sizeof(long double) will almost certainly be rounded-up to 96 bits (12 bytes) or (even more likely) 128 bits (16 bytes) to satisfy hardware alignment requirements; this padding cannot be used for other purposes. See also this point
• More formally, the following is guaranteed;-
  • 1 ≡ sizeof(char) ≤ sizeof(short) ≤ sizeof(int) ≤ sizeof(long) ≤ sizeof(long long)
  • 1 ≤ sizeof(bool) ≤ sizeof(long)
  • sizeof(char) ≤ sizeof(wchar_t) ≤ sizeof(long)
  • sizeof(float) ≤ sizeof(double) ≤ sizeof(long double)
  • sizeof(T) ≡ sizeof(signed T) ≡ sizeof(unsigned T) (where T is any Integral type that accepts modifiers)
• The effect of assigning too large a value to a (signed) char is undefined behaviour
• Automatic type conversion is performed between fundamental types. Most significant bits are lost when converting from a large to a small type
• char, signed char, and unsigned char are considered to be three distinct types, so you can't (say) mix pointers of each type. However, char must behave in exactly the same way as one of the other two types
• wchar_t size is implementation-specific and is large enough to hold the largest character set supported by the implementation's locale
• The header <cstdint> defines sized types (actually aliases) such as int64_t (exactly 64 bits), uint_fast16_t (the 'fastest' unsigned integer of at least 16 bits), and int_least32_t (at least 32 bits)
• Testing size assumptions within an application can be done by including <limits> and adding a compile-time test such as static_assert(sizeof(int) == 4, "int is not 32 bits");
• Min/max values can be obtained with (eg) std::numeric_limits<float>::max(). Signed representation can be checked with (eg) std::numeric_limits<char>::is_signed(). The standard header <climits> also defines a set of macros that specify minimum and maximum values for fundamental types
• Floating point type representation is defined by the IEEE-754 standard
• Although void is syntactically a fundamental type, its use is restricted to building more complex types (ie void*), and as a function argument or return type
• Fundamental types never throw exceptions during initialisation or assignment

Fundamental Type Modifiers

The following modifiers may be applied to char, short, int, long and long long types

• Unsigned types can lead to performance penalties on some platforms

Regular Types

Regular type is a loose term but generally refers to a type that;-

• Can be default constructed, and destroyed
• Can be copied, using assignment or initialisation with normal copy semantics
• Can be moved, using assignment or initialisation with normal move semantics
• Can be compared using == and !=
• Supports taking the address of it with &, and other "normally expected" behaviour. See also std::addressof()

• All built-in types except void are regular
• Regular types are often assumed/required in many cases such as when using templates, especially standard library ones
• See also Plain Old Data (POD)

Literal Types

A user-defined type can be used as a constant expression if it is sufficiently simple. 'Sufficiently simple' means the constructor must have an empty body and all members must be able to be initialised with constant expressions. Such a type is called a Literal Type

Here is an example of a literal type being used by several constant expressions;-

• A literal type may be used to define an object who's value is known at compile-time

• A standard library type predicate is_literal_type<T>::value is defined in <type_traits> that returns whether a type is a literal type or not. This may be used in exactly the same way as is_pod<T>

  is_literal_type<> is deprecated; not considered useful

• All built-in types, except void, are literal types
• All built-in types, including void, are literal types

Trivial Types

A trivial type is one that has standard copy semantics; ie, it must be trivially copyable and movable. It must also have a trivial destructor. A copy/move/destructor operation is trivial if;-

• It is default-defined (use = default if you need to define one)
• Its class has no virtual functions
• Its class has no virtual bases
• All bases are also trivial

The standard library predicate is_trivial<T> may be used to test the above rules

Standard Layout Types

A standard layout type is one that;-

• Has no virtual functions
• Has no virtual bases
• Has no members that are references
• Has the same access specifier for all non-static data members
• Has all non-static members declared in the same class (either all in the derived class or all in the same base class)
• Has no two base class objects of the same type
• Has no base that is not also standard layout

• For non-union types, have no base class sub-objects of the same type as the first non-static data member of the derived class (this is because of empty-base optimisation). This rule applies recursively throughout the class tree

  For union types, this rule extends to all members, not just the first

Basically, if a type can be expressed in plain 'C' then it is probably a standard layout

The standard library predicate is_standard_layout<T> may be used to test the above rules

Aggregate Types

An aggregate type is an array (even an array of non-aggregate types) or a class (often a struct or a union) that has the following properties;-

• No user-provided constructors (explicitly deleted or defaulted constructors are allowed)
• No inherited or explicit constructors
• No default member initialisers
• No private or protected non-static data members
• It may contain aggregate and/or non-aggregate members
• No base classes
• No private, protected or virtual base classes. Any allowed base classes may be aggregare and/or non-aggregate types
• No virtual functions

An aggregate type may be aggregate initialised

An aggregate type may be copy list initialised

Miscellaneous Types

Defined in <cstddef> (note that the types defined in the std namespace are always the same as the 'C' equivalents; both are shown below where applicable);-

Defined in <cstdint>;-

Incomplete Types

The following are considered incomplete types

• void (possibly const and/or volatile qualified)
• A class that is declared (ie, forward declared) but not defined
• An array of unknown bounds
• An array of elements that are incomplete types
• An enum from the point of declaration up until its underlying type is determined

In general terms, an incomplete type may not be used if the type's layout or size is required

In particular, a pointer to an incomplete type can be used, as long as it is not dereferenced. For example, the following is legal;-

User-defined Data Types

Declarator Operators

• With the exception of the last three examples dealing with function declarations, the above operators may also be applied to auto. eg, const auto& a = b; or auto a[] = {1, 2, 3};
• The postfix operators bind tighter than the prefix ones, so char* cheese[] is an array of char pointers. The alternative char(*cheese)[] is a pointer to an array of char
• It is this binding rule that means we have to use parentheses to define a function pointer
• Operators apply to individual names ONLY. This is why int* a, b; will result in a being an int pointer and b being an int (and not a pointer)
• See also Regular Types

Derived Types

• Derived types may be formed from any of the fundamental types or from other derived types
• A union is a type of struct which in turn is a type of class

Deferred Type Definitions

If a type is required but that type is not yet defined, a Forward Declaration may be specified. For example;-

• Types that are forward declared in this way are incomplete types until fully defined
• A type name becomes usable immediately after its name is specified; the entire type does not have to be parsed first as long as its use does not require its internal structure to be known. This allows (say) structures to contain pointers to the same type (such as in a linked list)
• A forward declaration may be used as long as its use does not imply knowledge of the type's internals
• Reference and pointer types may be defined for an incomplete type, but not objects (this would imply knowledge of the type's internals)
• This principle is extended to all types, including classes, of which struct is a type-of
• A function declaration may take an argument of an incomplete type by value, reference or pointer, but a function definition may take such as argument by reference or pointer only (by-value would imply knowledge of the type's internals)
• A Forward Declaration is a special case of an Elaborated Type Specifier

Deducing Types

There are several sets of rules for type deduction; used in a variety of scenarios;-

• Function Templates

  • An argument may be passed by value and of type T
  • An argument may be passed by reference or pointer and be of type T& or T*
  • An argument may be a Forwarding Reference of type T&&  

• Class Templates constructor arguments  

  • These rules are the same as those used for function argument type deduction

• Lambda implicit return types  

  • These use the same rules as function template by-value parameters

• decltype()   and decltype(auto) 

  • These use a separate set of rules

• Lambda capture  

  • These rules are based on those of function template by-reference and by-pointer parameters, but are not identical

• Lambda init capture  

  • These rules are the same as those used for auto objects

• auto objects  

  • These rules are based on those of function template argument type deduction, but are not identical

• Generic lambda auto parameters  

  • These rules are the same as those used for function template type deduction

• Function auto return type  

  • These rules are the same as those used for function template type deduction

Function Template Type Deduction

• Here is a complete list of function template argument constructs from which it is possible to deduce a type T or U, and a non-type argument N;-

  T

  const T

  volatile T

  T*

  T&

  T[constant-expression]

  type[N]

  class-template-name<T>

  class-template-name<N>

  U<T>

  T<N>

  T<>

  T type::*

  T T::*

  type T::*

  Function Pointer Forms;-

  T(*)(args)

  type(T::*)(args)

  T(type::*)(args)

  type(type::*)(args-TN)

  T(T::*)(args-TN)

  type(T::*)(args-TN)

  T(type::*)(args-TN)

  type(*)(args-TN)
  • type is some other type not specified in the parameter list
  • args is a parameter list that does not allow deduction
  • args-TN is a parameter list from which T and/or N may be derived from successive application of the above rules
• Implicit type conversions are not applied during template argument deduction; see how to deal with this

Type Deduction Rules

When a function template is called, two type deductions take place; one for the type T and one for the function argument(s) based on T. How this is performed depends on the function argument declaration(s) and how the function is called. Consider;-

The above could be called with;-

The form of expr and arg-type interact to deduce the type of T and the type arg-type

• If arg-type is a (non-forwarding) reference or a pointer;-

  • If expr is a reference type then ignore the reference part
  • Then pattern-match the type of expr against arg-type to determine T

  Function Decl.	Call	T	arg-type	Notes
  void fn(T& a)	int b = 3; fn(b);	int	int&
  	const int c = 3; fn(c);	const int	const int&
  	const int& d = b; fn(d);	const int	const int&
  	const int e[] = {1, 2, 3}; fn(e);	const int[3]	const int (&)[3]	#1
  	void f(int, double); fn(f);	void (int, double)	void (&)(int, double)	#2
  void fn(const T& a)	int b = 3; fn(b);	int	const int&	#3
  	const int c = 3; fn(c);	int	const int&
  	const int& d = b; fn(d);	int	const int&
  void fn(T* a)	int b = 3; fn(&b);	int	int*
  	const int* d = &b; fn(d);	const int	const int*

Note #1 Because fn() takes a reference, the array type passed to it does not decay to a pointer. This technique can be used (for example) to create a template that returns the number of elements in an array;-

Note #2 Because fn() takes a reference, the function type passed to it does not decay to a pointer

Note #3 The derived type of T is always non-const even if a const value is supplied in the call. This is because the const-ness is taken care of, and guaranteed by the function declaration itself

• T is never deduced to be a reference or pointer type

• If arg-type is a forwarding reference;-

  • If expr is an lvalue, then both T and arg-type are deduced to be lvalue references.  This is the only case in template type deduction where T becomes a reference type
  • If expr is an rvalue then the non-forwarding reference/pointer rules apply

  Function Decl.	Call	T	arg-type
  void fn(T&& a)	int b = 3; fn(b);	int&	int&
  	const int c = 3; fn(c);	const int&	const int&
  	const int& d = b; fn(d);	const int&	const int&
  	fn(83);	int	int&&

  Note b, c and d are all lvalues, but 83 is an rvalue. This distinction is maintained in the deduction of arg-type

  • For forwarding reference arguments, the type of the argument also encodes whether the supplied value was an lvalue or an rvalue; when an lvalue is supplied, T becomes a T& (lvalue reference). When an rvalue is supplied, T remains as just T (by-value). It is this distinction that determines whether the argument is an lvalue or rvalue reference within the function and is what allows std::forward to work
  • See also Reference Collapsing

• If arg-type is neither a pointer or reference (ie, it is passed-by-value);-

  • If expr is a reference type then ignore the reference part
  • Then, ignore any const or volatile attributes of expr
  • The result is T

  Function Decl.	Call	T	arg-type	Notes
  void fn(T a)	int b = 3; fn(b);	int	int
  	const int c = 3; fn(c);	int	int
  	const int& d = b; fn(d);	int	int
  	const int* const e = &b; fn(e);	const int*	const int*	#1
  	const int f[] = {1, 2, 3}; fn(f);	const int*	const int*	#2
  	void g(int, double); fn(g);	void (*)(int, double)	void (*)(int, double)	#3

  Note #1 The actual pointer e is passed by value and therefore its const-ness can be discarded. However, the referenced target value is not copied or moved. Therefore, the target's const-ness is honoured

  Note #2 An array passed by-value decays to a pointer

  Note #3 A function passed by-value decays to a pointer

• If expr is a uniform initialiser

  • ( Unlike auto type deduction) ( Like auto type deduction), template type deduction does not assume a std::initializer_list<> type when expr is a uniform initialiser enclosed in {…}. Therefore;-

  Function Decl.	Call	Result
  template<typename T> void fn(T a);	fn({1, 2, 3});	Error: The type cannot be deduced
  template<typename T> void fn(std::initializer_list<T> a);	fn({1, 2, 3});	Ok: T deduced to be an int

  • The use of auto to indicate that a function's return type should be deduced, and the use of auto argument declarations in lambda expressions use the template type deduction rules, not the auto type deduction rules; ie, {…} does not automatically imply a std::initializer_list<> type

    auto type deduction rules no longer deduce to an std::initializer_list<> anyway so this distinction is now moot

auto Object Types

auto varname = expr; deduces an object's type from its initialiser. The type may be a variable type, a const or constexpr

• auto becomes more useful the harder the actual type is to determine. For example;-

  template<class T> void f1(vector<T>& arg) { for (auto p = arg.begin(); p != arg.end(); ++p) { p = 42; } }

  …is much easier to write (and read) than;-

  template<class T> void f1(vector<T>& arg) { for (typename vector<T>::iterator p = arg.begin(); p != arg.end(); ++p) { p = 42; } }

  It is also more resilient to change; eg, changing arg to a list type would not break the above function

• auto types are deduced from their initialisers. It is therefore impossible to create an uninitialised auto variable
• Complex types such as iterator types, std::iterator_traits<I>::value_type, are much more simply expressed as auto
• auto may be combined with the declarator operators
• Non-static auto objects are not allowed as class data members
• lambda expressions have types that are only known to the compiler and so cannot be explicitly stated; auto solves this problem and therefore allows lambda expressions to be assigned to variables
• Code refactoring is often eased by using auto as types adjust themselves without having to do much
• auto is superior to other methods such as std::function
• Use auto in narrow scopes unless there is a good reason not to. In wider scopes, explicit types may be better
• The technique of using auto to deduce a type resulting from an expression or function call, ie auto a = expression; is called auto to track

• Example: auto can prevent problems resulting from lazy type specification. For example;-

  std::vector<int> a; unsigned int sz = a.size();

  The above will compile and will probably work as intended. But it may not. The type returned from a.size() is actually std::vector<int>::size_type. It is an unsigned integral, but depending on the platform, it may or may not be the same size as unsigned int; if it isn't, an implicit conversion must take place which could cause trouble. Using auto sz = a.size(); instead will ensure correct behaviour

• Example: An very nasty but subtle problem that auto can avoid;-

  std::unordered_map<std::string, int> a; // ... for (const std::pair<std::string, int>& n : a) { /* Use 'n' */ }

  This looks perfectly reasonable and will compile and run, but there is a problem. The type of the key for an unordered_map is const std::string, and not std::string. Therefore, n is the wrong type. As a result, the compiler will convert std::pair<const std::string, int> objects from the unordered_map container to std::pair<std::string, int> (the type of n). It can only achieve this by creating a temporary object on each iteration, binding n to that temporary, and then destroying the temporary at the end of each iteration; almost certainly not what was intended

  This entire problem can be solved by using auto;-

  for (const auto& n : a) { /* Use 'n' */ }

auto Type Deduction

The rules for auto type deduction are exactly as for function template type deduction, ( with one exception). With reference to the simple function template;-

…think of an auto expression as taking the form;-

Where auto takes the part of T from the template, and the deduced type of the variable a takes the part of arg-type

As with function template type deduction, there are three cases;-

• If arg-type is a (non-forwarding) reference or pointer;-

  • If expr is a reference type then ignore the reference part
  • Then pattern-match the type of expr against arg-type to determine T

  Given….	auto Decl.	Deduced Type Of a	Notes
  int b = 0; const int c = 3 const int& d = b;	auto& a = b;	int&
  	auto& a = c;	const int&
  	auto& a = d;	const int&
  	const auto& a = b;	const int&
  	const auto& a = c;	const int&
  	const auto& a = d;	const int&
  int b = 0; int* c = &b; const int* d = &b; const int* const e = &b;	auto* a = c;	int*	#1
  	auto* a = d;	const int*
  	auto* a = e;	const int*
  const int b[] = {1, 2, 3};	auto a = b;	const int*
  	auto& a = b;	const int (&)[3]
  void f(int double);	auto a = f;	void (*)(int, double)
  	auto& a = f;	void (&)(int, double)

  Note #1 The '*' is optional because it can be deduced

• If arg-type is a forwarding reference;-

  • If expr is an lvalue, then both T and arg-type are deduced to be lvalue references.  This is the only case in template type deduction where T becomes a reference type
  • If expr is an rvalue then the non-forwarding reference/pointer rules apply

  Given….	auto Decl.	Deduced Type Of a	Notes
  int b = 0;	auto&& a = b;	int&	b is an int lvalue
  const int b = 0;	auto&& a = b;	const int&	b is a const int lvalue
  	auto&& a = 22;	int&&	22 is an int rvalue

• If arg-type is neither a pointer or reference;-

  • If expr is a reference type then ignore the reference part
  • Then, ignore any const or volatile attributes of expr
  • The result is T

  Given….	auto Decl.	Deduced Type Of a	Notes
  int b = 0; const int c = 3 const int& d = b;	auto a = b;	int
  	const auto a = c;	const int
  	auto a = c;	int
  	auto a = d;	int	#1
  	decltype(auto) a = d;	const int&	#2
  	auto a = 42;	int

  Note #1 Derived type is int and not const int&. This is because of the rules concerning stripping of references from the initialiser before deducing the type

  Note #2 The decltype preserves the reference from the initialiser

  • A naked auto never deduces to be a reference; it must be manually added or decltype(auto) used

The one difference between template and auto type deduction comes about from the use of uniform initialisers (which get interpreted as std::initialiser_list constructs);-

• The use of the uniform initialiser {…} causes the deduced type to be a std::initializer_list<>. If such deduction is not possible, (for example, if the initialisers are of differing types), then an error shall result
• When a uniform initialiser is deduced, there are actually two deductions being made; the one for auto; this sees that the initialiser is of the form {…} and therefore we expect to deduce a std::initializer_list<>. Because std::initializer_list<T> is itself a template, a second deduction is made to derive T (which is what restricts the initialising values to be all of the same type)
• This deduction of std::initializer_list<> does not apply to function template type deduction
• The use of auto to indicate that a function's return type should be deduced, and the use of auto argument declarations in generic lambda expressions use the function template type deduction rules, not the auto type deduction rules; ie, {…} does not automatically imply a std::initializer_list<> type
• auto type deduction rules no longer deduce to an std::initializer_list<> anyway so this distinction is now moot

auto never deduces to a std::initialiser_list type. The above examples therefore give the following results;-

When auto Deduces The Wrong Type

auto sometimes deduces a type other than one expects. A common example is when proxy classes are being used; classes that emulate some other type. For example;-

The above problem comes about because vector defines a specialisation for bool; packing single bit bool values into words. As a result, vector<bool>::operator[]() returns a proxy class to hide this fact and to provide a clean interface to the resulting expression, with the primary intention of making vector<bool>::operator[]() look like it returns a T& in the same way as the general vector<T>::operator[]() operation does

Such a proxy class is intended to be transparent and usually only used an an rvalue. In the above case, the type std::vector<bool>::reference probably contains an internal pointer which, if a were an rvalue (say, returned from a function), would be left dangling when assigned to c. Other proxy classes include 'smart' pointers std::unique_ptr and std::shared_ptr (though these are designed to be more visible), std::bitset (similar issue to vector<boot>), and many others.

In cases such as these, options include:-

• Abandoning the use of auto and explicitly declaring the type; bool c = a[3];
• Using a cast to force the type; auto c = static_cast<bool>(a[3]);

Lambda Capture Type Deduction

There are three types of lambda capture;-

• By-reference (or pointer) This uses function template reference argument type deduction rules

• By-value This uses function template by-value argument type deduction rules except that const and volatile are retained. For example;-

  const int a = 42; auto lam = [a] { /* ... */ };

  Within the body of the lambda, the captured a value shall be const

  This is the only case in C++ where by-value assignment retains const and volatile

• Init Capture This uses the auto type deduction rules. Expanding on the previous example;-

  const int a = 42; auto lam = [a = a] { /* ... */ };

  Within the body of the lambda, the captured a value shall not be const

Normally, the difference between the way by-value and init-capture handle const (and volatile) is not important because the object that a lambda creates is const anyway. However, if the lambda is made mutable then the difference does become apparent

decltype

decltype(expr) deduces a type from an expression; that is, the declared type

• decltype() is most useful in generic programming. The following example defines a function that adds two matrices with possibly different element types. The problem that decltype() resolves here is in determining an appropriate result type;-

  template<class T, class U> auto operator+(const Matrix<T>& a, const Matrix<U>& b) −> Matrix<decltype(T{} + U{})> { Matrix<decltype(T{} + U{})> res; for (int x = 0; x != a.rows(); ++x) { for (int y = 0; y != a.cols(); ++y) { res(x, y) += a(x, y) + b(x, y); } } return res; }

  See also Functions for an example of defining a function's return type in terms of some other expression

• decltype has its own type deduction rules

• Given two functions such as;-

  string lookup1(); string& lookup2();

  …we could write wrapper functions;-

  string lookup_string_1() { return lookup1(); } string& lookup_string_2() { return lookup2(); }

  …or we can automate the process by using decltype(auto);-

  decltype(auto) lookup_string_1() { return lookup1(); } decltype(auto) lookup_string_2() { return lookup2(); }
• The use of decltype(auto) is limited in its intended scope and using it in situations other than wrappers and forwarding functions like this could lead to unexpected results
• See also this auto return example
• See also std::result_of and std::declval

decltype Type Deduction

• Applying decltype to a name (which is an lvalue expression) yields the type for that name

• Applying decltype to an lvalue expression more complex than just a name causes the type to be deduced in the same way as for a name, but then an lvalue reference is added to the result

  This distinction usually doesn't matter because an lvalue expression is almost always by-reference already; for example, given int x[50];, the expression x[42] actually behaves as if it is of type int& rather than just int, and this is supported by the fact that an operator[] function usually returns a reference. If this were not so, it would not be possible to assign to such an expression; x[42] = 3; would be illegal

  Therefore, the addition of the reference by decltype() fits the general use of most expressions and function calls

• There is a case where this implicit reference behaviour can cause a problem. Given int a = 0;, the expression decltype(a) shall yield a type of int. However, decltype((a)) is taking an expression of '(a)' which is more complex than just a name and so yields a type of int&

  This rarely matters for C++11, but for auto return deduction, it can cause real problems;-

  decltype(auto) fn() { int a = 0; return a; } // Returns an 'int' (by value) decltype(auto) fn() { int a = 0; return (a); } // Returns an 'int&' to a local stack variable
• See this example showing how decltype may be used to preserve references in auto declarations

• The most common use of decltype is probably in declaring the return type of a function template, based on the type of a supplied argument when such a return type cannot be easily derived. For example, given a container of type T, what is the type of the objects it contains?;-

  template<typename T, typename I> auto get_object(T& container, I index) -> decltype(container[index]) { return container[index]; }

Function Return Type Deduction

See function return type deduction

Literals

• The use of 'U', 'L' and 'LL' to indicate unsigned and long integers are case-insensitive, and the relative order is not important
• The use of 'E' and 'P' to indicate floating point exponent is case-insensitive
• For the decimal floating point format, the exponent is optional in some cases. If specified, it represents an integer power of 10

• For the hexadecimal floating point format, 0x is case insensitive

  The mantissa is specified as one or more hexadecimal digits. The exponent must always be specified and is expressed in decimal. The exponent represents an integer power of 2. So, 0x123.4p5 is interpreted as the hexadecimal fraction 123.4 (291.25 decimal) scaled by 2 to the power 5 (32) = 9320.0

  The L/l (long double) and F/f (float) suffixes may also be used

  This format is (clearly!) not really useful generally; it is mostly of use when specific bit patterns are required in specialist cases

• The digit separator ' (single quote) may be used to make literals easier to read. For example;-

  auto one_million = 1'000'000; auto ltuae = 0b1010'0101; auto a_hex_number = 0xabcd'1234; auto pi = 3.14159'26535'89793;
• If a bool is cast to an integral then it becomes a value of 0 or 1 (false/true respectively)
• If an integral or pointer is cast to a bool then a zero/nullptr value becomes false. Any other value is true
• The size of a literal can be tested by including <limits> and evaluating the literal thus; sizeof(123L);. The functions defined in <limits> are constexpr so incur no run-time overhead
• Literals for user-defined types can also be defined by using constant expression constructors and literal operators
• A number of standard literal suffixes are defined in the namespace std::literals

Character And String Literals

The following 'escape' (\) codes may be used in characters or strings

• Although there is no requirement to, when using Octal representation, it is best to always use multiples of 3 digits, and for hexadecimal, use multiples of 2 digits
• Octal and Hexadecimal notation may be extended to any length

• Literal char strings are implicitly concatenated at compile time. For example, "Hello" "-" "World" would define the single string "Hello-World"
• For char type, unicode characters may be specified directly as UTF-8 sequences. For example, char a[] = {u8"ģ"};
• The u'\Uxxxx' and U'\Uxxxxxxxx' representation may be used within UTF-8/16/32 strings as well as single characters. For example, u8"The official vowels in Danish are: a, e, i, o, u, \u00E6, \u00F8, \u00E5 and y."
• The meaning of the u'\Uxxxx' and U'\Uxxxxxxxx' codes is defined by ISO/IEC 10646

• A Raw string may include "real" newline characters. eg, the following two strings are equal;-

  char a[] = {"Hello\nWorld"}; char b[] = {R"(Hello World)"};
• The "(…)" deliminators of a Raw string may be modified if required (rare, but possible) by adding additional decoration immediately before the ( and after the ). For example R"***(Hello)***" is the string "Hello". The chosen decoration is arbitrary but the opening/closing must match

String Literals

• The type of a string literal is "array of the appropriate number of const characters". Therefore, in the above example, "Hello" is of type const char[6]
• The const-ness of string literals is important. Prior to C++11, it was possible to assign a string literal to a non-const pointer. This is no longer allowed in C++11 where the receiving pointer must be a const*
• A string literal is always 1 character longer than written, with an implicit NULL terminator '\0' appended to it. For example, sizeof("Hello") == 6
• String literals are statically allocated so it is safe to return one from a function
• String literals are implicitly const
• Writing to a string literal (eg, char* a = const_cast<char*>("Hip"); a[1] = 'o';) represents undefined behaviour
• An implementation may optimise string literals so that repeated strings refer to the same single instance. Therefore, take care if comparing pointers to string literals

The namespace std::literals::string_literals defines operators for defining std::string literals;-

• All the above std::string literals are implicitly treated as raw types

Type Size and Alignment

The following compile-time operators are available to determine the physical size and alignment of an object;-

• All the above operators return values as a number of bytes. A byte is the same size as a char, and although it is usually 8 bits, it may not be. The number of bits in a byte (or char) is defined by the macro CHAR_BIT, defined in <climits>
• In practice, the above operators are likely to be implemented as macros

Variable Declarations and Definitions

lvalues And rvalues

Every expression is either an lvalue or an rvalue, but not both

Object Lifetime

• 'automatic' and 'static' are traditionally referred to as 'storage classes'

Storage Classes

• Storage classes apply only to variable declarations/definitions, NOT type declarations
• In the case of a global or static variable, if the initialising expression is a constant expression then initialisation may be performed at compile-time rather than at run-time. Initialisation is deferred if the variable is declared thread_local
• The storage class effects how unspecified initialisation is performed (ie, when no explicit initialiser is specified)
• extern and static may be combined with volatile; eg - extern volatile type var
• extern and static may also be applied to function declarations/definitions, though extern is somewhat redundant in this case

volatile

The volatile modifier may be applied to any object declaration. Some examples;-

The purpose of volatile is as an instruction to the compiler not to optimise-away what may seem like redundant read/write operations. For example;-

In the above example, had p not been declared volatile then the compiler would likely optimise-away the line *p = 0; because it would "know" that it was redundant. The volatile modifier prevents such optimisation

• The volatile modifier is of most use when used to declare an object that overlays memory-mapped hardware registers. In such cases, it is often essential that every read/write operation is performed
• A more classical ('C' language) view of volatile is that it indicates that the object in question may be subject to modification by means outside of the current thread of execution. Such meaning is not appropriate for C++. The only meaning that should be inferred is that of preventing read/write optimisation
• The volatile modifier has no special meaning with regard to the memory order model. To guarantee memory ordering, use an atomic type. volatile may be applied to an atomic type to guarantee execution ordering and to prevent undesirable read/write optimisations
• Casing-away the volatile modifier and then writing to the (previously) volatile object is undefined behaviour
• At the time of writing, I cannot find a definitive answer to whether execution ordering of operations on volatile objects is guaranteed or not. The closest answer I can get to is that the compiler will guarantee the order but the underlying hardware may not

Declarations and Definitions

All variables and functions must be declared or defined before they are referenced

• Except for function definition and namespace definitions, all declarations and definitions are terminated with a ; (semi-colon)
• A declaration is also a statement
• A variable declaration that includes an initial value, or a function declaration that includes a function body is a definition
• A variable declaration that is NOT declared extern is a definition. See also Storage Classes
• use of extern with function declarations is largely redundant
• A variable or function may be declared extern and defined elsewhere in the same scope (at which point it stops being 'external')
• All the above examples are definitions (they all instantiate variables or define functions), with the exception of the very last example which is a function declaration
• See also Naming Rules
• A variable (or function) may be declared multiple times, but may only be defined once
• Variables may be declared/defined anywhere in the code that any other statement can
• Variables of a type cannot be declared until the type is fully defined (not just declared), with the exception of a pointer reference to a forward-declared type (because this does not require knowledge of the type's size)
• The following attributes may be applied to a variable declaration; [[deprecated]], [[maybe_unused]]
• Note the different ways a variable may be initialised; particularly the use of = and {…}
• A string literal such as "Hello" is always const. Therefore, any variable it is assigned to must also be const

Inline Variables

A variable may be defined as inline. For example;-

• For the inline specifier to take effect, the variable must be declared/defined with static storage duration; that it, it must be within global or namespace-scope, or a static class member
• In particular, a static global variable that is also declared inline will act as if the inline were not specified (because it is, by definition, local to the translation unit)
• An inline variable must be defined for any translation unit that refers to it, though only its declaration need be specified before its use (just like a non-inline variable)
• A non-static inline variable (ie, one with external linkage) must be declared inline in all translation units that use it. It will have the same address in all translation units

• An inline variable may be defined multiple times in multiple translation units (but only once per translation unit). This allows the variable to be defined in a header file

  If different definitions exist, spread across different translation units then the program may still link, but the result is undefined

• The behaviour of the program shall be as if only one instance of the inline variable were defined
• An inline variable may also be specified as const, volatile, etc
• inline const variables declared at namespace scope have implicit external linkage. Non-inline none-volatile const variables do not
• A variable declared as non-inline cannot also be declared as inline
• An object constexpr that is also a static class member is implicitly inline (this does not apply to namespace constexpr variables)

Constants

An object may be variable (mutable) or constant (immutable). The former is the default. The latter can be achieved with the const specifier. The general form is;-

Some examples;-

• A constant must be initialised at declaration
• A constant may be initialised with a constant or non-constant value
• A constant cannot later be modified
• Any object may be made constant
• const modifies the type of an object; it does NOT specify the way in which it is stored
• A constant is local to the module it is defined in (even if defined outside of any function); ie, it has implicit internal linkage. To make it externally available, specify extern const var = n; in the defining module
• An enumeration or constant expression may be a better alternative to a const in some cases

Aliases

A type alias generates a new name for an existing type. The new and old names are interchangeable; they are not distinctly different types. Aliases are useful to insulate the code from the underlying type details and allow for simpler modification. Not to be confused with object/variable aliasing

There are two methods of creating a type alias;-

Every storage class in the standard library defines value_type which is a synonym for the type it has been instantiated with. For example;-

• An alias is a declaration
• Naming convention for aliases is that they end with '_t'
• An alias has implicit internal linkage
• An alias of an alias cannot add any additional specifiers such as unsigned or const
• The using syntax allows partial binding of a template's parameters, whereas typedef does not. See Alias Templates
• The using keyword may also be used in other contexts; see 'using' Declaration and 'using' Directive

• Note the difference in syntax when defining an alias for a function pointer;-

  typedef void (*fn_t)(int, const double); using fn_t = void (*)(int, const double);
• using has the great advantage over typedef in that it can be made into a template
• typedef can be used within a template to create a similar result, but it must be embedded inside a class template, and the syntax and structures required to make it work can get rather ugly. See type generators for an example
• The following attributes may be applied to an alias declaration; [[deprecated]], [[maybe_unused]]

Structured Binding Declaration

Structured bindings provide a method of decomposing a complex object into individual variables. The syntax is as follows;-

• The following attributes may be applied; [[deprecated]], [[maybe_unused]]
• identifier-list is a comma-separated list of variable names, as yet undeclared/undefined within the current scope
• expression is an expression that yields an object of one of the following types; an array, struct, class or tuple
• Normal auto type deduction is performed for each of the names specified by identifier-list. If & or && is specified then reference-binding takes place in the normal way

Note: The process of constructing the variables defined by identifier-list starts with the creation of a temporary object to hold the initialising values. It is to this temporary object that the [[attributes]] const volatile applies, and not to the identifier-list variables

Array binding

The number of names specified by identifier-list must match the size of the array. Each name is then bound to each array element in-turn

struct and class binding

The struct/class must either contain only public non-static members, or no non-static members at all, but one or more bases, only one of which (which must be public) may contain non-static members, all of which must be public

The struct/class and/or its bases may contain static members

The number of names specified by identifier-list must match the number of non-static members of the struct/class. Each name is then bound to each member in-turn (in the order they are defined in the struct/class)

Expanding on this example, showing a different (and common) context;-

tuple binding

The number of names specified by identifier-list must match the size of the tuple. Each name is then bound to each tuple element in-turn (in the order they are defined in the tuple)

Further example;-

• When binding a tuple, each variable name listed in identifier-list is created to be a reference. If the initialising value for each element is an lvalue, then an lvalue reference shall be created. Otherwise, an rvalue reference shall be created

• The initialising value for tuple element N is determined as follows (where I is the initialising object);-

  • If the name get is within the scope of the initialising object (regardless of type), then it shall be assumed to be a function that can return an initialising value, and is called as I.get<N>()
  • Otherwise, a call is made to get<N>(I) (which is located via ADL only)
• This mechanism can be used to perform structured binding on a class that would otherwise be ineligible

Initialisation

In the following text, the term initialisation is synonymous with construction

Initialisation Forms

The forms of initialisation are Zero, Constant, Default, Value, Direct, Copy (or Move), List (two forms), Aggregate, and Unspecified

An object may be subject to none, one or more of the above forms

Zero Initialisation

If an object meets any of the following criteria then it is zero initialised;-

Zero initialisation is never applied to a reference type

For an object of (possibly const/volatile) type T, zero initialisation will perform the following;-

• If T is a scalar type then it is initialised with a value derived by explicit conversion of an integer literal value of zero to a type T
• If T is a non-union class then each non-static member and each base class is zero initialised with any padding bytes being filled with binary zero. All constructors are ignored
• If T is a union type then the first non-static named element is zero initialised. All remaining space in the object is filled with binary zero
• If the object is an array then each element of the array is zero initialised
• Following zero initialisation, further initialisation may take place as described below

Constant Initialisation

If a reference or object of type T is declared static or thread_local and it meets one of the following criteria then it is constant initialised;-

• A reference that is bound to a static glvalue, or to a temporary object, or to a function, and if all expressions in the binding (including any implicit type conversions) are constant expressions
• A class that is initialised via a constexpr constructor, and all arguments (including implicit type conversions) are constexpr, and whos members' constructors are also initialised with only constexpr
• An object (which may or may not be a class) that is not initialised via a constructor, and is value initialised or is initialised via (only) constexpr value(s)

• Constant initialisation is performed after () or instead of () zero initialisation
• constant initialisation will result in the same result as the respective non-constant initialisation; the principal difference being that it is guaranteed to be performed before all non-constant initialisation of the respective static or thread_local object
• In reality, constant initialisation is usually performed at compile-time
• An implementation is free to constant initialise objects that do not meet the above criteria, as long as the result is guaranteed to be equivalent to the respective non-constant initialisation
• Following constant initialisation, further initialisation may take place as described below

Default Initialisation

If an object meets any of the following criteria then it is default initialised;-

• A local (stack-based), static or thread_local or a dynamically allocated object of type T is defined with no explicit initialiser at all, for example T a; or T* a = new(T);
• A base class or non-static member is not specified in ai constructor initializer_list and that constructor is called

For an object of (possibly const/volatile) type T, default initialisation will perform the following;-

• If T is a class then a default constructor is called (selected, based on resolution of an empty argument list). If there is no such constructor, or it is inaccessible, or overload resolution fails then the program is in error
• If the object is an array then each element of the array is default initialised
• In all other cases, the object shall be left uninitialised (though zero initialisation and/or constant initialisation may have already been performed). If the object is declared const then such non-initialisation is an error condition

Value Initialisation

If an object of type T is defined with an explicit empty initialiser, for example T a{};, T a = {};, or T a(); (though this last form will be parsed as a function declaration in most cases) and it meets one of the following criteria then it is value initialised;-

The following exceptions apply;-

• If T is an aggregate type then aggregate initialisation is performed instead
• If T is a class with no default constructor but with an initializer_list constructor then that constructor is called instead

For an object of (possibly const/volatile) type T, value initialisation will perform the following;-

• If T is a class and it does not define a default constructor (being declared = default is considered 'declared'), or it defines a user-provided default constructor or it explicitly deletes its default constructor with = delete, then the object is default initialised
• If T is a class and does not define a user-provided or explicitly deleted default constructor then it is zero initialised. If T meets the default initialisation criteria and it defines a non-trivial default constructor then the object is then default initialised
• If the object is an array then each element of the array is value initialised
• In all other cases, the object is zero initialised
• See also Unspecified Initialisation

Direct Initialisation

If an object of type T is defined with a non-default (non-empty) initialiser, for example T a{args};, T a(args);, or T* a = new T{args};, and it meets one of the following criteria then it is direct initialised;-

For an object of (possibly const/volatile) type T, direct initialisation will perform the following;-

• If T is an array then the statement is in error

• If T is an array then it is aggregate initialised with the additional rules that narrowing conversions are allowed and any elements without an initialiser are vale initialised. For example;-

  struct X { explicit X(int a = 0) {} }; X b[2](X(42)); // Ok: b[0] = X(42), b[1] = X(); X c[2]{X(42)}; // Error: Initialisation of b[1] selects explicit constructor

• If T is a class-type then;-

  • If the object's initialising expression is a prvalue of the same type, ignoring any const/volatile differences (eg, T a(T(args))) then…

    … A temporary is created from the expression and this is used to copy-initialise the object. In reality, an implementation is likely to elide the creation of the temporary object. However, logically, it must still follow this procedure and as such the appropriate constructor must still be defined

    …the expression itself is used to initialise the object (rather than creating a temporary from the expression and using that to copy-initialise the object)

    For further details of the above differences, see Return Value Mechanics where a similar principle applies

  • Initialisation behaves like a function call (to a constructor). Both explicit and non-explicit constructors are considered and ADNL is employed to identify the best candidate, and (if required) implicit conversion is used to modify the argument(s) to match the constructor (unless the constructor is explicit)
• If T is not a class-type but the initialising expression is then ADNL is employed to identify the best candidate conversion functions provided by the source type
• If T is of type bool and the initialiser is a std::nullptr_t type then it is implicitly converted to false
• In all other cases, initialisation behaves like a function call (to a constructor). Both explicit and non-explicit constructors are considered and ADNL is employed to identify the best candidate, and (if required) implicit conversion is used to modify the argument(s) to match the constructor (unless the constructor is explicit)

The above is more relaxed than for copy initialisation; the latter only considers non-explicit constructors and conversion functions as valid candidates for selection, whereas direct initialisation considers all options

Copy (or Move) Initialisation

This occurs when T is a (possibly const/volatile) type and it defines a non-default constructor that may be called with the arguments specified by the initialisation T a = initialiser;

This is an initialisation and conversion operation. If the initialiser does not exactly match the object's type, then methods shall be sought to convert the initialiser to the correct type and ADNL shall be employed to determine if the initialiser can be used to construct the object

Given the initialiser X a = b;, b is converted to a type X and the result passed to a copy constructor of X (or if b is an rvalue, possibly a move constructor). Both explicit and non-explicit constructors are considered for ADNL purposes, but only non-explicit versions may be selected. In practice, the copy/move is usually optimised-away by the compiler. The effect of this behaviour when compared with direct initialisation can be seen here

The optimisation that can elide the call to the constructor is mandatory, even if invoking such a constructor would have side-effects. As a result, explicit constructors may be selected. Technically, the rule regarding not selecting explicit constructors still applies, but as the constructor is guaranteed to never be called, the rule never comes into play. See also Return Value Mechanics

List Initialisation

There are two forms of List Initialisation; Direct and Copy. These are described in the following sections. See also Lists

• Within a braced-init-list ({args}), each argument of the list is always evaluated in-turn in the order they are specified, unlike the arguments in a function call
• A braced-init-list is not an expression and therefore has no type; it cannot be be used where a specific type is needed such as decltype({1, 2, 3}). Template declarations cannot deduce the type of a braced-init-list (because there isn't one). Explicitly specifying an std::initializer_list type can circumvent such restrictions in many cases

Direct List Initialisation

This occurs when T is a (possibly const/volatile) type and it defines a non-default constructor that may be called with the arguments specified by an initialisation of one of the following forms;-

Both explicit and non-explicit constructors are considered and Argument Dependent Name Lookup is employed to identify the best candidate, and (if required) implicit conversion is used to modify the argument(s) to match the constructor (unless the constructor is explicit)

Copy List Initialisation

This occurs when T is a (possibly const/volatile) type and it defines a non-default constructor that may be called with the arguments specified by an initialisation of one of the following forms;-

This behaves similarly to direct list initialisation except that explicit constructors are considered for ADNL purposes but never used; ADNL selection of an explicit constructor is an error

List Initialisation Effects

For an object of (possibly const/volatile) type T, direct list initialisation will perform the following;-

• If T is an aggregate class and the initialiser list has a single element of the same or derived type (possibly const/volatile qualified), the object is initialised from that element (by copy initialisation for copy list initialisation, or by direct initialisation for direct list initialisation)
• If T is a character array and the initialiser list has a single element that is an appropriately-typed string literal, the array is initialised from the string literal as usual
• If T is an aggregate type, aggregate initialisation is performed
• If T is a class type with a default constructor and the braced-init-list is empty, then value initialisation is performed
• If T is a specialisation of std::initializer_list, then the T object is direct initialised or copy initialised, depending on context, [ from a prvalue of the same type initialised from the braced-init-list] [ from the braced-init-list]
• Otherwise, the constructors of T are considered, in two phases;-
  • All constructors that take std::initializer_list as the only argument, or as the first argument if the remaining arguments have default values, are examined, and matched by overload resolution against a single argument of type std::initializer_list
  • If the previous stage does not produce a match, all constructors of T participate in overload resolution against the set of arguments that consists of the elements of the braced-init-list, with the restriction that only non-narrowing conversions are allowed. For copy list initialisation, explicit constructors are considered for ADNL purposes but never used; ADNL selection of an explicit constructor is therefore an error
• If the initialisation is direct list initialisation and T is a plain or class enumeration type with fixed underlying type, the braced-init-list has only one initialiser, and the conversion from the initialiser to the enumeration's underlying type is non-narrowing, then the enumeration is initialised with the result of converting the initialiser to its underlying type
• If T is not a class type and the braced-init-list has only one element and either T isn't a reference type or is a reference type whose referenced type is same as or is a base class of the type of the element, then T is direct initialised (in the case of direct list initialisation) or copy initialised (in the case of copy list initialisation), with the restriction that that narrowing conversions are not allowed
• If T is a reference type that isn't compatible with the type of the element, a temporary of the referenced type ( or its corresponding array type of known bounds) is list initialised, and the reference is bound to that temporary. This fails if the reference is a non-const lvalue reference
• If the referenced type is an array type of unknown bound (ie, T[]), the type of the temporary is T[N], as if it is defined as T a[] {args};
• If the braced-init-list has no elements, then T is value initialised

There are some restrictions placed on the forms of implicit type conversions allowed when performing list initialisation. The following implicit conversions are not allowed;-

• Conversion from floating-point to integer types
• Any narrowing of a floating-point type to another floating point type; long double to double to float, except where the source is a constant expression and overflow does not occur
• Conversion from an integer to a floating-point type, except where the source is a constant expression and the floating-point type can represent the value exactly
• Conversion from an integer or a plain enumeration type to an integer type that cannot represent all the possible values of the source, except where the source is a constant expression and the destination type can represent the value exactly
• Conversion from a pointer or a pointer-to-member type to a bool

Aggregate Initialisation

An aggregate type is eligible for aggregate initialisation

• If an object of type T is defined with an explicit non-empty initialiser, for example T a{42, 83};, T a = {42, 83}; (but not the form T a(42, 83);) then aggregate initialisation takes place. This involves taking each of the constructor arguments in turn and copy initialising each of the member variables one-for-one with the arguments
• If an initialiser is itself enclosed within {}, for example T a{42, {83}}; then the respective member is list initialised rather than copy initialised

• For example, the declaration;-

  struct X { int m1; int m2; float m3; };

  …can be aggregate initialised with;-

  X a{42, 83, 3.14};

  This will result in m1 == 42, m2 == 83, m3 == 3.14

• Aggregate initialisation is not possible if any members of the type have default initialisers

  Given the following type with some default initialisers defined;-

  struct X { int m1 = 1; int m2; float m3 = 8.3; int m4; };

  …an aggregate initialisation of X b{42, 83} shall result in m1 == 42, m2 == 83, m3 == 8.3. The value of m4 will depend on the Unspecified Initialisation rules, and may be undefined

• Designated Initialisers Individual elements of an aggregate-initialised class/structure may be initialised by name. Expanding on the previous example, an aggregate initialisation of X b{.m1 = 42, .m2 = 83} shall yield the same result as in that example. Designated initialisers may not be mixed with non-designated initialisers; this X c{.m1 = 42, 83}; is illegal
• aggregate initialisation can also be applied to arrays. For example int a[3]{17, 42, 83};
• Aggregate initialisation is recursive; for example, X b[2]{{42, 83, 3.14}, {17, 59, 9.806}};
• If the number of initialisers is less than the number of members or array elements then the remaining members/array elements are value initialised

• An aggregate class type may contain aggregate and non-aggregate members. Aggregate initialisation of such a type is performed as follows;-

  struct R { int rm; R() : rm{3} {} // User-provided default constructor R(int a) : rm{a} {} // User-provided constructor }; struct S { R sm1; int sm2; }; // Aggregate initialise a S object. This will set;- // sm1.rm == 3 via the constructor R::R() // sm2 == 2 S a{{}, 2}; // The following will set;- // sm1.rm == 1 via the constructor R::R(int) // sm2 == 2 S b{{1}, 2};

• An aggregate class type may have one or more bases (which may or may not also be aggregate types). Aggregate initialisation of such a type is performed as follows;-

  // An aggregate base type struct X { int xm; }; // A non-aggregate base type struct Y { int ym; Y() : ym{12} {}; // User-provided default constructor Y(int a) : ym{a} {}; // User-provided constructor }; // An aggregate derived type struct Z : X, Y { int zm; }; // Aggregate initialise a Z object. This will set;- // xm == 1 // ym == 12 via the constructor Y::Y() // zm == 3 Z a{{1}, {}, 3}; // The following will set;- // xm == 1 // ym == 2 via the constructor Y::Y(int) // zm == 3 Z a{{1}, {2}, 3};

  An aggregate may have an empty base. Such a type is initialised as follows;-

  // An empty base type struct V { }; // An aggregate derived type struct W : V { int wm; }; // Aggregate initialise a B object. Note the empty {}. This // is required to skip over the (empty) base. This will set // wm == 2 W c{{}, 2};

Unspecified Initialisation

Default initialisation may be specified as an empty list. For a type X, this could be X a{};. It is also possible to omit even the default initialiser; eg, X a;

When no initialiser is specified at all like this, there are special rules concerning the initialisation;-

• If the object is statically allocated (ie, is defined with static storage class or is global) then it shall be default initialised (as if {} had been specified)
• For local (ie, stack-based) objects and objects allocated with new, the default initialisation will only be performed for user-defined types; built-in types and enumerations will not be initialised

For example;-

• The reason why global and static variables of built-in types are always initialised is because it incurs no run-time cost

  In contrast, a stack-based variable must be initialised at run-time. It is not acceptable for user-defined types not to be initialised (whether global, static or stack-based) and so they always are, despite any run-time cost. However, it may be acceptable for built-in types to not be initialised (hence, this is the default for stack-based variables)

  This reasoning allows (for example) large amounts of raw memory (say, a byte buffer) to be allocated without the overhead of forcing initialisation of all its elements

• Specifying {} will always guarantee initialisation regardless of type
• For a user-defined type, {} will call the type's default constructor if one is defined

User-Provided Constructors And Initialisation

An example of how the declaration (or not) of user-provided constructors can effect initialisation;-

The reason for the above result is as follows;-

• When X a{} is encountered, the value initialisation rules apply and (because X does not define a user-provided default constructor) a is zero initialised. Hence a.m1 is initialised to zero
• When Y b{} is encountered, the value initialisation rules also apply but because Y defines a user-provided default constructor, a is default initialised. The default initialisation rules result in no initialisation at all being performed, hence b.m2 is left uninitialised

• The {} and = {} forms are called Uniform Initialisers
• The direct list initialisation form, {}, may be used in almost  all contexts, it is safer than other forms, and its exclusive use is suggested
• Because of an error in the C++11 specification, some older compilers will not accept {} (without =) for copy construction

• The plain copy initialisation form, auto var = init_val, may be preferred when the type is auto. This is because the form '{init_val}' or '{init_val, …}' always results in a generated type of std::initializer_list<T> rather than just 'T' which is often not the intended result

  auto never deduces to a std::initialiser_list type so this is not an issue

For user-defined types, there can be differences between the behaviour of the different initialisation forms; it depends on the type's implementation

Example; given the following declarations;-

…the following definitions will invoke the indicated constructor(s)/operation(s);-

• If the type Y were replaced with the following (ie, by adding the conversion operator X());-

  class Y { public: Y(); // Default constructor 1 Y(int a); // Constructor 2 operator X(); // Conversion to X 3 };

  …then the behaviour is as the original example except for the copy initialisation forms;-

  // In principle, this definition shall call 3 and then take that // result to call 6 (or maybe 5). In practice, only the call to 3 // is likely to be made; the call to 6 (or 5) is optimised-away // // The reason for this change is because of this rule; the same // principle applies here. The original invocation was to 7 which // takes a const reference. The new invocation is to 3 because it // takes a non-const reference, which is preferred during resolution X m = y; // This definition will no longer compile owing to ambiguous // resolution between 3 (and by association, 8) and 7. That is, 3 // and 7 are equally (non-)const in the arguments they take X r = Y{3}; // Note that the following definitions do not change behaviour. This // is because they use copy list initialisation rather than // copy initialisation X k = {y}; X q = {Y{3}};

• If the conversion operator 3 is left in-place but 8 is deleted then the behaviour is as the original example except;-

  X m = y; // Calls 3 as previously // These three definitions shall call 2 and then take that result to // call 7 X p{Y{3}}; X q = {Y{3}}; X s(Y{3}); // In principle, this definition shall call 3 and then take that // result to call 6 (or maybe 5). In practice, only the call to 3 // is likely to be made; the call to 6 (or 5) is optimised-away X r = Y{3};

{} vs () in initialisers

• Mostly, initialisation using = {} is treated the same as {} (though be aware that they are not actually the same  )
• In constructor calls, {} and () have the same meaning as long as std::initializer_list arguments are not declared as constructor(s) arguments
• If {} initialisation syntax is used, and if any constructor includes a std::initializer_list argument, the compiler will favour this wherever possible, even if the result is an inferior match to some other constructor and requires implicit casting to work, or even if the result is in error because (say) it implies the use of some narrowing conversion (which {} does not allow). If usable type conversion operators are also defined, the string of conversion operations can become quite complex and (often) undesirable. Other constructors shall only be considered if there is no way at all to match the initialising values with the std::initializer_list constructor(s)
• An empty {} (eg, X a{};) always means default construction, even in the presence of any constructors taking std::initializer_list types. If there really is a need to call an std::initializer_list constructor with an empty list, then use the form X a({}); or X a{{}};
• A classic case that defines a std::initializer_list constructor is the unfortunate case of std::vector; std::vector<int> a(3, 8) (3 elements, each with a value of 8) vs std::vector<int> a{3, 8} (2 elements, with values of 3 and 8 respectively)
• Try and design your classes so that any constructors that take std::initializer_list types can't be called by accident; the situation with std::vector is generally considered a design error
• The choice between using {} and () can be particularly difficult within variadic templates. If there is a need to forward the variadic arguments on to some internal object, which syntax is most appropriate? This is a design decision. std::make_unique and std::make_shared tackle exactly this problem by using () internally and documenting this use as part of their interfaces. One way of dealing with this problem is to use tag dispatch
• Non-static class members may be initialised in-place with {} or =, but not () (the latter would likely be parsed as a function declaration)
• Uncopyable objects such as std::atomic<T> may be initialised with {} or (), but not =
• Initialisation with an empty () creates a function declaration and not an object; X a(123); (create an object), X a(); (function declaration). This happens because of the C++ rule that states an expression that can be parsed as a function declaration must be parsed as a function declaration

• There is a rare case where the (), rather than {}, notation must be used; that is to force initialisation by non-list constructor rather than list constructor (which {} also supports). For example;-

  vector<int> v1{42} // Uses list constructor initialisation; results in one element with a value of 42 vector<int> v1(42) // Uses non-list constructor initialisation; results in 42 elements, all initialised with zero vector<int> v1{42, 83} // Uses list constructor initialisation; results in two elements with a values 42 and 83 respectively vector<int> v1(42, 83) // Uses non-list constructor initialisation; results in 42 elements, all initialised with 83

  In theory, this distinction may be applied to any type, but in reality the situation shown above only manifests itself if an initializer_list constructor is defined for the type. This is because if the type has no such constructor then the distinction is not useful, or even possible, and because of the next point…

  This distinction is not always uniform though. For example, if the vector<int> in the above example were to be changed to a vector<string>;-

  vector<string> v1{42} // Results in 42 elements, all initialised with "" vector<string> v1(42) // Results in 42 elements, all initialised with ""

  The reason the {} notation in this case gives different behaviour to the first example is because there is no initialiser-list constructor for vector<string> that accepts 42 as an argument (it expects one or more strings instead). As a result, the construction resolves to the same as if () has been specified

  • The rules regarding {} being interpreted as list initialisation apply regardless of whether the 'list' initialiser is provided by simple memberwise initialisation or by an initializer_list constructor; there is no distinction between them

  • If a class defines an initializer_list constructor, it is normally preferred over a "standard" constructor in the event of an overload resolution. Using the () notation will force use of the "standard" constructor. For example;-

    struct X { X(initializer_list<int>); X(int a, int b, int c); }; // {} will always prefer the initializer_list constructor if it exists (which it does) X{1, 3, 5}; // () forces use of "standard" parameterised constructor X(1, 3, 5);
  • See also Direct Member Initialisation, function template type deduction and auto type deduction

• The {} notation can only be used as an initialiser and on the right-hand side of an assignment. For example, assuming a and b are of type X, and the function is declared as fn(X j, X k);;-

  X a = {1, 2}; // Ok: Right hand side of assignment X a += {1, 2}; // Ok: Right hand side of assignment X a = b + {1, 2}; // Error: Syntax error X a = b + X{1,2}; // Ok fn(a, {1,2}); // Ok: A function argument is considered an initialiser {a, b} = {b, a}; // Error: Syntax error
• ({…}) will resolve to the same as {}
• The {} style does not allow narrowing of initialisers. For example, it will not allow implicit casting from int to short, or implicit float to int or int to float casting (though literal integral to floating-point is allowed as long at it can be expressed exactly)

• If any constructor is defined for a type then a constructor will be used regardless of whether {} or () notation is used (though {} may invoke an initializer_list constructor). Specifically, 'raw' memberwise initialisation by a list is no longer an option

• An empty {} or () indicates the default value for the type;-

  • Numeric types are set to zero
  • Pointers are set to nullptr
  • Booleans are set to false
  • POD types are usually set to binary zero
  • For a user-defined type T, T{} invokes the default constructor. If no such constructor exists then constructors for T's individual members are invoked (ie, compiler-generated default construction)
  • Enumerations ("plain" and class) types are set to binary zero. Be aware that this may not be a valid enumerator value for the type

• Any type, built-in or user-defined, can be default-initialised with any of;-

  int var1{}; int* var2{new int{}};

  This works for arrays too. Either of the following will initialise all 42 elements to zero;-

  int var3[42]{}; int* var4{new int[42]{}};

  Note that it is not the new operation that performs the initialisation; new simply allocates raw memory. The initialisation is applied to the returned memory pointer after new completes; see Overloading new And delete for full details

• There are special rules for objects defined without explicit initialisation

• Any runtime initialisation required for global, namespace, and non-local (ie, not defined within a function) static objects within a translation unit is performed in the order that the objects are defined, prior to invoking main()
• Such run-time initialisation is only guaranteed at all if main() is executed; an important issue if writing a C++ library that shall be invoked by a plain 'C' program. Constant expressions are always safe in this respect
• The relative order of initialisation of global, namespace, and non-local static objects in different translation units is undefined. It is therefore undefined behaviour for a global to be statically initialised in terms of another global defined in some other translation unit. See also exceptions
• Local (ie, defined within a function) static objects are always initialised on the first call to the function. So if the function is never called, the object will not be constructed
• Class member initialisation always occurs in the same order as the members are declared
• If there is a need to access a global, namespace-bound or non-local static object from outside its translation unit, then move it into a function, define it as static, and have the function return a reference to it (ie, create a Singleton pattern). That way, its initialisation is guaranteed
• In a multi-threaded application, it may be prudent to call all such Singleton functions at the start (within a single-threaded environment) to prevent any race conditions caused by the initialisation
• Global objects, objects defined within a namespace, and static objects (whether in file, namespace, function or class scope) are destroyed when main() exits

• The var = value (with no {} or ()) form is a plain 'C' style and still extensively used, especially when initialising fundamental types

More complex and multi-element initialisation is achieved with an initialiser list