Contents

Introduction

Igor's C++ Grimoire aims to be a reasonably complete reference to C++11, C++14, and C++17

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 , and 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 . A few non-standard (but commonly supported) features are described, and these are identified with

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

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
• Keywords are often shown like this; virtual
• If a particular part of the syntax is being highlighted or referred to, it is shown like this; class colour {…}
• 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 written in plain ASCII text and any one program is implemented as one or more text files

Whitespace

Whitespace (' ', TAB, and NEWLINE) must be used to separate type/variable/function names and reserved keywords. It is generally not required between names/keywords and syntactic elements and operators such as ( or ->. It is significant within string literals. Some operators are composed of multiple characters such as +=. Adding whitespace to these (ie, + =) would result in a syntax error. 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;-

• 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 to a function with C++ linkage as an argument 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' 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 that refers to the environment (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 seperately 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

[[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 namespaces 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 label

• A name is an lvalue expression

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
• 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). See also this point. Floating point type representation is defined by the IEEE-754 standard
• 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
• 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 example, 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 References of type T&&

• Class Templates constructor arguments

  • These rules are the same as those used for function agument 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"
• 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
• 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 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
• 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
• A variable name starts with a character a-z, A-Z, or '_', and consists of these plus 0-9
• All names (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 variable name length, though other parts of the tool chain are likely to
• 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

Zero Initialisation

If an object of type T is declared static or thread_local then it is zero initialised

• If T is a scalar type then it is initialised with a value derived by converting an integer literal value of zero to a type T
• If T is a (possibly const/volatile) non-union class then each non-static member and each base class is zero initialised with any padding bytes being filled with binary zero
• If the object is an array then each element of the array is zero initialised
• If T is a reference type then no zero initialisation takes place
• Following zero initialisation, further initialisation may take place as described below

Default Initialisation

If an object of type T is defined with no explicit initialiser at all, for example T a; then default initialisation takes place

• If T is a (possibly const/volatile) class then if it defines a user-provided default constructor, it is called. 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 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) then value initialisation takes place

• If T is a (possibly const/volatile) 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 (possibly const/volatile) class 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 also 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

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(arguments);

This 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)

Here describes the effects of direct initialisation on particular types

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

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 the initialisation T a{arguments};

If the type defines one or more constructors, then this forms Direct List Initialisation. This behaves like a function call (which is what it is; a function call to a constructor). 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). If an initializer_list constructor is defined then this will usually be selected in preference to other constructors

Here describes the effects of direct list initialisation on particular types

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 the initialisation T a = {arguments};

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

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

• 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};

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 allocated raw memory. The initialisation is applied to the returned memory pointer after new completes

• 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

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 initalised 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

Aliasing

NOTE: All the following examples use pointers. However, exactly the same rules and procedures can be applied to references as well

Aliasing is the process of accessing an object via multiple means (not to be confused with type aliasing which is quite different). For example;-

Here, the variable a can be accessed directly or via the alias b. There is an implicit assumption that the object's value will be the same regardless of whether it is accessed directly or via the alias, and that if the value is modified (by either means), its new value will become immediately available directly and via any and all alias'

There are a number of rules that dictate which types of expression (the alias) may be used to access a particular type of value. It is important that these rules are strictly followed (hence the often-quoted term strict aliasing rules, although this is not an officially used term) because the compiler will make assumptions based on them and if the rules are broken then undefined behaviour shall result and the compiler is likely to generate incorrect code, especially with more aggressive optimisation levels

The aliasing rules

A pointer b may alias a pointer a if;-

• It is of the same type;-

  int a{}; int* b = &a; // This is a legal alias
  int fn(int* c, int* d) { // It must be assumed that 'c' and 'd' may refer to the same object }

• It is a const and/or volatile of the same type;-

  int* a{}; const int* b = &a; // This is a legal alias
  int fn(int* c, const int* d) { // It must be assumed that 'c' and 'd' may refer to the same object }

• It the two types are similar. That is;-

  • They are the same type
  • They are both pointers and the referenced types are similar
  • They are both pointers to members of the same class, and the types of the pointed-to members are similar and the referenced types are similar
  • They are both arrays of the same size or both arrays of unknown bounds, and the array element types are similar

• It is a signed or unsigned version of the same type;-

  int a{}; auto b = std::reinterpret_cast<unsigned int*>(&a); // This is a legal alias
  int fn(int* c, unsigned int* d) { // It must be assumed that 'c' and 'd' may refer to the same object }

• It is a const and/or volatile of a signed or unsigned version of the same type;-

  int a{}; auto b = std::reinterpret_cast<volatile unsigned int*>(&a); // This is a legal alias
  int fn(int* c, volatile unsigned int* d) { // It must be assumed that 'c' and 'd' may refer to the same object }

• It is a char, unsigned char (but not signed char) or  std::byte;-

  int a{}; auto b = std::reinterpret_cast<char*>(&a); // This is a legal alias
  int fn(int* c, char* d) { // It must be assumed that 'c' and 'd' may refer to the same object }

  Being able to legally alias any type with char* is necessary for functions like memcpy() to work. It also allows any type to be handled in sizeof(char) parts, which is often necessary for functions such as serialisation, network traffic handling, etc

  In theory, there is no reason why an int8_t or uint8_t type must be based on a char type. In reality, all current implementations that define int8_t and uint8_t define them as type aliases of char. Because of this, it is also possible to alias any other type with int8_t* or uint8_t*. If an implementation did not follow this convention then quite a lot of code would probably break

• It is a (possibly const and/or volatile) base class of the other type;-

  class X { int m; }; class Y : public X { int n; }; X a{}; volatile Y* b = &a; // This is a legal alias
  int fn(X* c, volatile Y* d) { // It must be assumed that 'c' and 'd' may refer to the same object }

• If a pointer a is a struct, class or union type and includes one of the above types among its elements or non-static data members (including, recursively, an element or non-static data member of a sub-struct/class or contained union), then a pointer b may alias such a member by employing the appropriate rule shown above

  class X { int m; }; X a{}; int* b = &a->m; // This is a legal alias
  void fn(X* c, int* d) { // It must be assumed that 'c->m' and 'd' may refer to the same object }

• A pointer to a standard layout structure may be safely cast to the type of its first member, and visa-versa. This works because the first member of any structure is aligned with the very start of the structure (there are no intervening padding bytes)

  class Y { int m; float n; }; Y a{}; int* b = reinterpret_cast<int*>(&a); // This is safe

• Similarly, a pointer may be safely cast between union members consisting of standard layout structures with common initial types, though clearly it's possible to easily get into trouble!

  union Z { X u; // Using the definitions of 'X' and 'Y' from above Y v; }; Z a{}; X* b = &a.u; Y* c = reinterpret_cast<Y*>(b); // This is safe, though somewhat unwise int d = c->m; // d == a.u.m

  The above is only safe up to the point of accessing the start of the structures that match each other. In this example, only the first member matches both structures

• Aliasing effects which optimisations may be performed by a compiler. For example;-

  int fn1(int* a, int* b) { *a = 1; *b = 2; return *a; }

  It may seem obvious that a compiler could optimise the above function to return the literal 1. However, it can't because a and b may refer to the same object, rendering such an assumption dangerous and potentially wrong; instead, the compiler must abandon an otherwise useful optimisation. This problem can be addressed by specifying restrict, if it's available

• In contrast, given;-

  int fn2(int* a, float* b) { *a = 1; *b = 2.0; return *a; }

  …the compiler can assume that a and b do not refer to the same object, because to do so would be counter to the aliasing rules (it is not legal to alias an int* with a float*) and would lead to undefined behaviour. It is therefore possible to optimise the function and return the literal 1; the aliasing rules allow the compiler and optimiser to make certain assumptions and therefore generate better code

• The aliasing rules can be deliberately subverted; for example, the above function could be called as;-

  int c{}; int d = fn2(&c, std::reinterpret_cast<float*>(&c);

  The above may even execute 'correctly' (as expected). However, as already explained, it represents undefined behaviour. If the size of a float is not the same as the size of an int then it is also likely to lead to memory corruption. See also Punning

Punning

Punning is the technique of forcing an otherwise illegal object alias to be used. In general use, this is (for obvious reasons) not a good thing to do as it deliberately circumvents the type system and can easily lead to undefined behaviour

However, there are cases where it is necessary; low-level driver interfaces to hardware, some low-level network operations, etc

The only safe method to employ in forcing such an operation is to use memcpy() to copy the raw bit pattern from one variable (of a particular type) to another (of another type). In all cases, the following conditions must be met, otherwise undefined behaviour will result;-

• The two objects must be of the same size
• The two objects must be POD types

Note that in any event, the resulting value (the one copied-to) may or may not hold a value representation that makes sense

• Using memcpy() may seem excessively expensive, but many implementations will identify such use and actually optimise-away the actual function call
• Do not use other methods such as writing to a union member of one type and then reading some other member of another type; such a technique will result in undefined behaviour

Pointers

A pointer type is specified by the syntax T* varname (a pointer to type T). A pointer holds an address. The address of an object is derived with the & (address-of) operator. A pointer is dereferenced (that is, access is gained to the object being pointed-to) by using the * (dereference) operator

A pointer may refer to any object that has identity; that is, an object that resides at a specific address

• The smallest unit a pointer can refer to is a char
• A pointer to any valid object is guaranteed to compare with nullptr as not equal
• Two pointers of the same type that are both set to nullptr will compare as being equal. This is not guaranteed if the pointers are of different types
• Arithmetic with pointers is possible with the operators +, -, ++ and -- supported. Given a pointer of type T* Adding 1 to a pointer shall increment its address by sizeof(T). So, incrementing a pointer to an array shall make it refer to the next element in the array. Similarly, subtracting 1 shall refer to the previous array element
• Adding/subtracting an integer from a pointer shall modify the pointer by sizeof(T) times the integer value
• To modify the value of a pointer in steps other than sizeof(T) then consider using uintptr_t
• Subtracting one pointer from another is only defined if the two pointers refer to elements within the same array, and the result is the (inclusive) integer number of elements in the sequence - 1
• Adding one pointer to another pointer makes no sense and is not allowed
• A pointer to a definite type may be assigned to a void*, except that a pointer to a function or an object member cannot be directly assigned to void* (these require an explicit cast)
• Pointers never throw exceptions during initialisation or assignment
• A const pointer may be assigned to a non-const pointer, but not the other way round
• A pointer to a non-const object may be assigned to a pointer to a const object, but not the other way round (unless explicitly cast)
• A void* may be assigned to another void*
• A void* must be explicitly cast to a pointer of a definite type in order to dereference it
• A void* may be compared with another pointer for (in)equality but pointer arithmetic is not allowed as the object size is unknown
• The 'range-for' for (int x : v) clause does not work for pointers because the range is unknown. It does work for arrays of a known size though
• The common 'C' macro definition of NULL as (void*)0 often results in illegal code in C++ because is not possible to assign a void* to a definite type without an explicit cast (as in int* a = NULL;)
• See also std::addressof()

Pointers to pointers

A pointer may point to another pointer. Such a type is specified by the syntax T** varname (a pointer to a pointer to type T)

• Referring to an array's name implicitly yields a pointer. For example, given int a[3], the expression a shall yield a type of int* that shall refer to the first element
• Given int a[3], the expression &a shall yield a type int (*)[]
• Given for (int x = 0; v[x]; ++x) { use(v[x]); } and for (char* x = v; *p; ++p) { use(*p); }, there is no reason why one version should perform any better than the other. In fact, most compilers will generate identical code
• As shown for the standard pointers examples, volatile can also be specified instead of, or in addition to const

• Pointer indirection may be extended beyond two levels;-

  int a{42}; int* b = &a; int** c = &b; int*** d = &c; int**** e = &d; // ...etc... int f = ****e; // f == 42
• An implementation should support at least 256 levels of indirection

nullptr

nullptr is a literal that represents a null pointer

• nullptr is of type std::nullptr_t and will implicitly convert to, and can be assign to, any pointer type
• nullptr cannot be implicitly cast to an integral type, so an expression such as if (a == nullptr) {...} is clearer than alternatives because it implies that a must be a pointer type
• nullptr will almost certainly have the numeric value zero but this is not actually guaranteed

restrict

restrict is not a standard C++ keyword, but it is supported as an extension by several implementations. As such, if it is supported, it will actually be named __restrict or __restrict__

• __restrict__ is purely an optimisation option; it serves no other purpose and code written that uses it should behave identically to code that is not (assuming it is used correctly!)

• It may be applied to pointer and reference types, and it hints to the compiler that the particular pointer/reference is the only one used in the current scope that refers to a particular set of data; no other pointers/references are used by the current scope that refer to the same object. For example;-

  void fn(char* __restrict__ a, char* __restrict__ b) { for (auto x = 0; x < 10; ++x) { a[x] = 42; b[x] = 83; } }

  In this example, the arguments a and b are both marked as __restrict__. This indicates a promise (to the compiler) that a is guaranteed to be the only reference to the data that it refers to (ie, no other pointers (in this case b) will ever refer to the same area of memory that a can), and similarly for b. This allows the compiler to make certain assumptions, which in this case will almost certainly mean reducing the loop within the function to two calls to memset (which is typically optimised for the platform to perform such an operation very efficiently)

• There is no need to apply __restrict__ to pointers of different types because the implementation will assume that such pointers will never overlap anyway (because of C++'s aliasing rules). For example, if b in the above example were defined as a float type then __restrict__ would have no effect; the assumptions that can be made as a result of it would be made anyway
• __restrict__ may be applied to references. For example, int& __restrict__ c
• To specify __restrict__ for the this pointer of a member function, use void T::fn() __restrict__
• It is up to the writer to ensure that __restrict__ is applied appropriately; there are no safeguards for specifying it unjustifiably. If it is used incorrectly then the results are undefined because the assumptions that the compiler will make will be wrong, with a high probably of incorrectly generated code
• The above warning being noted, __restrict__ can provide the compiler with very real optimisation opportunities

Arrays

• The first element of an array is numbered 0 (zero)
• Run-time bounds checking is not guaranteed and if (usually optionally) supported, can be rather expensive
• Creating a pointer to one-past the end of an array is guaranteed to work (though obviously it should never be read from or written to)
• Creating a pointer to a position before the start of an array or two-or-more past the end of an array is undefined
• Given for (int x = 0; v[x]; ++x) { use(v[x]); } and for (char* x = v; *p; ++p) { use(*p); }, there is no reason why one version should perform any better than the other. In fact, most compilers will generate identical code
• The size of an array at definition must be a constant or a constant expression. If a (run-time) variable size is required then use std::vector
• The use of the name of an array on its own (with no indices) implicitly converts to a pointer to its first element, at the cost of loosing the array's size information
• Beware of defining alias' for arrays; doing so hides the fact that the type is an array. Therefore, if the type is allocated with new then the subsequent delete must actually be a delete[], which may not be obvious. Another issue is the non-intuitive syntax used to manipulate such types. Notwithstanding this, here is an example of how an array alias can be used
• There is no copy operator for arrays and no means of directly initialising an array from another array or from a pointer to an array
• Arrays cannot be passed by value (unless they are wrapped up in a struct/class); only by reference. See Array Arguments
• Specifying the array size in a function argument (eg, void calc(int arg[10]) {…}) is no safeguard against passing too-small or too-large an array; because the array shall be passed by reference, the specified size shall probably be ignored by the compiler
• Specifying the second and subsequent sizes for a multi-dimensional array in a function argument (eg, void calc(int arg[][10]) {…}) is necessary if the function is to access the array as a multi-dimensional array; the function must know the second and subsequent dimension(s) in order to calculate the indexing. This is still no guard against passing an array of different dimensions though
• The direct use of arrays in an interface is strongly discouraged; use higher-level types such as std::vector, std::array, std::map or std::string instead
• some big advantages of using std::array over plain C-type arrays is that the former is a 'proper' object which provides useful operators, it can be manipulated and passed around more easily, and (critically) will not revert to a pointer type when referred to my name only
• The major disadvantage of using std::array over a plain C-type array is that the compiler cannot automatically deduce the length of the array from the number of initialisers given; its size must be explicitly stated along with the initialiser list; ie, array<T, 3> a{1, 2, 3}; will work whereas array<T> a{1, 2, 3}; will not
• Note that std::array is defined such that it embeds an array inside it, meaning that it will still be stack-based if defined appropriately. In contrast, std::vector and std::string are only handles to heap-based storage
• See also Array Arguments