Getting our machines set up for C++ development, and introducing the fundamental building blocks of programming - variables.

Getting our computer set up so we can create and build C++ programs. Then, creating our very first application

Setting up a C++ Development Environment

An introduction to the building blocks of our software - objects, and the variables that can be associated with them.

Objects, Variables and Types

Creating variables to store and update the data that describes our objects.  We also introduce comments, allowing us to describe our code in plain language.

Creating Variables

An introduction to the different types of numbers in C++, and how we can do basic math operations on them.

Numbers

An overview of the fundamental true or false data type, how we can create them, and how we can combine them.

Booleans - `true` and `false` values

Explore how C++ programs store and manage numbers in computer memory, including integer and floating-point types, memory allocation, and overflow handling.

Types and Literals

Creating a tiny program using numbers and booleans, then adding some breakpoints so we can step through our code in a debugger.

Introduction to Debugging

Types and Variables

Discover how we can package our code into reusable functions that we can easily call.  Then, learn how we can use conditionals and loops to control the flow of our program.

An introduction to functions - reusable blocks of code that we can use to break our application into smaller pieces.

Creating and Calling Functions

An introduction to how our function calls create a call stack, and how we can navigate it in a debugger.

The Call Stack and Debugging Functions

Use booleans and if statements to make our functions and programs more dynamic, choosing different execution paths.

Conditional Logic

Learn an alternative way to write conditionals, which is often used when we want to take different paths based on a specific value

Switch Statements

Allow our functions to communicate with their caller by returning values when they complete

Function `return` Statements

Going into more depth on what is happening when a variable is used as a different type

Implicit Conversions and Narrowing Casts

Making our functions more useful and dynamic by providing them with additional values to use in their execution

Function Arguments and Parameters

Learn more about how and when we can access variables, by understanding the importance of the scope in which they exist.

Scope

Understand what function prototypes are, and learn how we can use them to let us order our code any way we want.

Forward Declarations

Learn how we can use loops to iterate over a block of code, executing it as many times as needed.

Loops

Learn how we can use the modulus operator to get the remainder of integer division, and some common use cases.

The Modulus Operator (`%`)

Put everything we've learned in this chapter to the test by creating a C++ version of the Fizz Buzz game.

Fizz Buzz

Learn how the `&&` and `||` operators are optimized with short-circuit evaluation, only evaluating expressions when necessary

Short-circuit Evaluation

Functions, Conditionals and Loops

Classes and structs are the fundamental feature of object oriented programming.  In this chapter, we will see how we can set them up, and how we can use them to create the custom types our program needs.

Learn how to define, instantiate, and utilize classes, understanding how they form the backbone of object-oriented programming.

Abstraction and Classes

A guide to encapsulation, class invariants, and controlling data access with `public` and `private` specifiers.

Encapsulation and Access Specifiers

Learn about special functions we can add to our classes, control how our objects get created and destroyed.

Constructors and Destructors

Discover the role of structs, how they differ from classes, and how to initialize them without requiring a constructor.

Structs and Aggregate Initialization

This lesson introduces operator overloading, a fundamental concept to create more intuitive and readable code by customizing operators for user-defined types

Operator Overloading

This lesson introduces Structured Binding, a handy tool for unpacking simple data structures

Structured Binding

Classes and Structs

See how we can use inheritance to organise our classes into a hierarchy, unlocking a massive range of possibilities for building more complex software

In this lesson, we explore C++ inheritance, guiding you through creating and managing class hierarchies to streamline your code

Inheritance

Learn about `protected` class members in C++, including how and when to use them in your code, especially in the context of inheritance and class design

Protected Class Members

This lesson introduces Member Initializer Lists, focusing on their advantages for performance and readability, and how to use them effectively

Member Initializer Lists

This lesson provides an in-depth exploration of using inherited methods and variables in C++, covering constructor calls, variable modification, and function shadowing

Working with Inherited Members

An introduction to working with memory, and how we represent memory locations using references and pointers

This lesson introduces references, explaining how they work, their benefits, and their role in performance and data manipulation

References

This lesson provides a thorough introduction to pointers in C++, covering their definition, usage, and the distinction between pointers and references

Pointers

Learn about the `this` pointer in C++ programming, focusing on its application in identifying callers, chaining functions, and overloading operators.

The `this` Pointer

Learn about an important consideration when returning pointers and references from functions

Dangling Pointers and References

Memory, References and Pointers

An introduction to polymorphism - the key tool that let us build more complex programs whilst keeping our code simple.

This lesson provides an in-depth look at function overloading in C++, covering its importance, implementation, and best practices

Function Overloading

Explore the concept of static casting in C++, including examples and best practices for converting data types at compile time

Static Casting

This lesson provides an introduction to virtual functions and overrides, focusing on their role in enabling runtime polymorphism

Virtual Functions and Overrides

Get to grips with downcasting in C++, including static and dynamic casts. This lesson provides clear explanations and practical examples for beginners

Downcasting

Polymorphism

Go deeper on what is happening when we build our software.  Learn how we can use the preprocessor to automatically modify our source code before it is compiled, and how the linker connects our program together.

Explore the essential concepts of C++ preprocessing, from understanding directives to implementing macros

Preprocessor Definitions

Discover how the `#include` directive helps us include library features and split our project across multiple files.

The `#include` Directive

Explore how header files and linkers streamline C++ programming, learning to organize and link our code effectively

Header Files

The Preprocessor and the Linker

Discover additional methods and techniques to keep our data and code organised.

Learn the essentials of using namespaces to organize your code and handle large projects with ease

Namespaces

Learn about Enums and how they offer an efficient way to handle predefined values in your code

Enums

This lesson introduces the `using` keyword in C++, focusing on namespaces, enums, and type aliasing

The `using` Keyword

Namespaces and Enums

Learn how to store collections of objects, and take control of how memory is managed

Explore the fundamentals of dynamic arrays with an introduction to `std::vector`

Dynamic Arrays using `std::vector`

Learn how to manage dynamic memory using unique pointers and the concept of memory ownership

Memory Ownership and Smart Pointers

Explore advanced techniques for managing object copying and resource allocation

Copy Constructors and Operators

Learn the techniques and pitfalls of manual memory management in C++

Managing Memory Manually

Arrays and Dynamic Memory

Techniques to simplify our code, making it easier to understand and maintain

This lesson covers how we can ask the compiler to infer what types we are using through the `auto` keyword

Automatic Type Deduction using `auto`

Learn the intricacies of using `const` and how to apply it in different contexts

Constants and `const`-Correctness

This lesson provides an overview of effective commenting strategies, including Javadoc style commenting for automated documentation

Effective Comments and Javadoc

This lesson introduces the concept of Style Guides and ClangFormat, focusing on how to achieve consistency in our code

Style Guides and Automatic Code Formatting

An introduction to static analysis tools, and how they can help beginners learn faster and improve code quality

Static Analysis

Explore the fundamentals of attributes, including `[[nodiscard]]`, `[[likely]]`, and `[[deprecated]]`

Attributes

Clean Code

A collection of lessons covering a variety of topics worth learning as a beginner

This lesson covers the basics of using randomness, with practical applications

Random Number Generation

Learn the basics of the chrono library and discover how to effectively manage durations, clocks, and time points

Dates, Times and Durations

A detailed guide to string formatting using C++20's `std::format()`, and C++23's `std::print()`

String Interpolation

Learn how to overload the `<<` operator, so our custom types can stream information directly to the console using `std::cout`

Overloading the `<<` Operator

This lesson introduces system calls, and how to use them to clear the terminal

System Calls and Terminal Management

This lesson introduces the fundamentals of capturing user input, using `std::cin` and `std::getline()`

User Input in the Terminal

Unravel the fundamentals of bitwise operators and bit flags in this practical lesson

Bitwise Operators and Bit Flags

Odds and Ends

This course is designed for beginners. We'll take you from the fundamentals and lay a solid foundation for creating real-world programs and learning more advanced concepts.

Become a software engineer with C++.  Starting from the basics, we guide you step by step along the way

This course teaches the fundamentals of C++ while instilling habits used by real-world developers. You'll gain practical experience with concepts that are the foundation of all modern programming.

No previous programming experience is needed - we start from the basics.

Start your Journey

We explain every line of code we're using, so you understand exactly what is happening.

Understand Every Line of Code

Everything we create is organised and implemented using modern, professional practices.

Use Professional Best Practices

We don't just explain what we're doing, but also why. This builds transferrable skills, so you can take what you've learnt and apply them to your own projects.

Focus on Transferrable Skills

No paywalls, no ads - the course is completely free with unlimited access

Free and Unrestricted Access

We break complex concepts into manageable steps, making even advanced topics feel approachable.

Step-by-Step Learning

What You'll Learn

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Professional C++

If you're already familiar with the basics of C++ and object oriented programming, you may want to skip to the advanced course.  It starts with a quick summary of everything we cover here.

Already Familiar with Programming?

Intro to C++ Programming

Swapping values using references without a temporary variable is a neat trick in C++. It's not only efficient but also demonstrates the power of references. Here's how you can do it:


```c++
#include <iostream>

void swap(int& a, int& b) {
  a = a + b;
  b = a - b;  // b is now original a
  a = a - b;  // a is now original b
}

int main() {
  int x{5};
  int y{10};

  std::cout << "Before swap: x = "
    << x << ", y = " << y << '\n';
  swap(x, y);
  std::cout << "After swap:  x = "
    << x << ", y = " << y << '\n';
}
```


```c++
//<o>
Before swap: x = 5, y = 10
After swap:  x = 10, y = 5
```


Let's break down how this works.


First, we define a `swap()` function that takes two integer references as parameters.


Then, inside `swap()`, we perform three operations:

- Add `b` to `a`, storing the result in `a`.
- Subtract the new `b` from `a`, which gives us the original value of `a`, and store it in `b`.
- Subtract the new `b` from `a`, which gives us the original value of `b`, and store it in `a`.

This method works because we're using references, so we're directly manipulating the original variables, not copies.


While this method is clever, it's worth noting that it can cause issues with overflow for very large numbers. In practice, the standard library's `std::swap()` function is often a better choice:


```c++
#include <iostream>
#include <utility>

int main() {
  int x{5};
  int y{10};

  std::cout << "Before swap: x = "
    << x << ", y = " << y << '\n';
  std::swap(x, y);
  std::cout << "After swap:  x = "
    << x << ", y = " << y << '\n';
}
```


`std::swap()` is more versatile as it works with any type, not just integers, and it handles potential edge cases more robustly.

Swapping Values Using References

Creating an array of references in C++ is not directly possible. This is because references must be initialized when they are created and cannot be reseated (made to refer to a different object) later. However, there are a few workarounds that can achieve similar functionality.


## Using `std::reference_wrapper`


The most common and recommended approach is to use `std::reference_wrapper` from the `<functional>` header. This class template wraps a reference in a copyable, assignable object:


```c++
#include <array>
#include <functional>
#include <iostream>

int main() {
  int a{1}, b{2}, c{3};

  std::array<
    std::reference_wrapper<int>, 3
  > refArray{a, b, c};

  for (auto& ref : refArray) {
    std::cout << ref << ' ';
    ref.get()++;  // Modify the original values
  }
  std::cout << '\n';

  std::cout << "a: " << a
    << ", b: " << b
    << ", c: " << c << '\n';
}
```


```c++
//<o>
1 2 3
a: 2, b: 3, c: 4
```


In this example, we create an array of `std::reference_wrapper<int>`. We can access and modify the original values through this array.


## Using Pointers


Another approach is to use an array of pointers. While not exactly the same as references, pointers can achieve similar functionality:


```c++
#include <array>
#include <iostream>

int main() {
  int a{1}, b{2}, c{3};

  std::array<int*, 3> ptrArray{&a, &b, &c};

  for (auto ptr : ptrArray) {
    std::cout << *ptr << ' ';
    (*ptr)++;
  }
  std::cout << '\n';

  std::cout << "a: " << a
    << ", b: " << b
    << ", c: " << c << '\n';
}
```


```c++
//<o>
1 2 3
a: 2, b: 3, c: 4
```


This approach uses pointers instead of references, but achieves a similar result.


Remember, while these methods allow you to create collections of references or reference-like objects, they each have their own implications for syntax and semantics. The `std::reference_wrapper` approach is generally preferred as it more closely mimics the behavior of actual references.

Creating an Array of References

Absolutely! References are a great way to achieve runtime polymorphism in C++. They allow you to work with derived class objects through base class references, enabling you to call virtual functions and get the correct derived class behavior.


Let's look at an example using our `Character` class from the lesson:


```c++
#include <iostream>
#include <string>

class Character {
 public:
  Character(const std::string& name)
  : mName{name} {}
  virtual void Attack() const {
    std::cout << mName
      << " performs a basic attack!\n";
  }
  virtual ~Character() = default;

 protected:
  std::string mName;
};

class Warrior : public Character {
 public:
  Warrior(const std::string& name)
  : Character{name} {}
  void Attack() const override {
    std::cout << mName
      << " swings a mighty sword!\n";
  }
};

class Mage : public Character {
 public:
  Mage(const std::string& name)
  : Character{name} {}
  void Attack() const override {
    std::cout << mName
      << " casts a powerful spell!\n";
  }
};

void PerformAttack(const Character& character) {
  character.Attack();
}

int main() {
  Character genericChar{"Generic"};
  Warrior warrior{"Conan"};
  Mage mage{"Gandalf"};

  PerformAttack(genericChar);
  PerformAttack(warrior);
  PerformAttack(mage);
}
```


```c++
//<o>
Generic performs a basic attack!
Conan swings a mighty sword!
Gandalf casts a powerful spell!
```


In this example:

1. We define a base `Character` class with a virtual `Attack()` method.
2. We create two derived classes, `Warrior` and `Mage`, each overriding the `Attack()` method.
3. We define a `PerformAttack()` function that takes a `const Character&` parameter.
4. In `main()`, we create instances of each class and pass them to `PerformAttack()`.

The key here is the `PerformAttack()` function. It takes a reference to a `Character`, but when we call it with a `Warrior` or `Mage`, it still calls the correct overridden `Attack()` method. This is runtime polymorphism in action!


A few important points:

- The `Attack()` method must be declared `virtual` in the base class for this to work.
- We use `const` references here as we're not modifying the objects.
- It's good practice to declare a virtual destructor in the base class when using polymorphism.

References provide a clean syntax for achieving polymorphism, as you don't need to worry about dereferencing pointers. However, remember that unlike pointers, references can't be null and can't be reassigned after initialization.

References and Runtime Polymorphism

The Observer pattern is a software design pattern where an object, called the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes. We can implement this pattern in C++ using references for a clean and efficient design.


Here's a simple implementation:


```c++
#include <iostream>
#include <string>
#include <vector>

class Observer {
 public:
  virtual void Update(
    const std::string& message) = 0;
  virtual ~Observer() = default;
};

class Subject {
 private:
  std::vector<Observer*> observers;
  std::string state;

 public:
  void Attach(Observer& observer) {
    observers.push_back(&observer);
  }

  void Detach(Observer& observer) {
    observers.erase(std::remove(
      observers.begin(),
      observers.end(),
      &observer
    ), observers.end());
  }

  void SetState(const std::string& newState) {
    state = newState;
    Notify();
  }

  void Notify() {
    for (auto observer : observers) {
      observer->Update(state);
    }
  }
};

class ConcreteObserver : public Observer {
 private:
  std::string name;

 public:
  ConcreteObserver(const std::string& observerName)
  : name{observerName} {}

  void Update(const std::string& message) override {
    std::cout << name << " received message: "
      << message << '\n';
  }
};

int main() {
  Subject subject;

  ConcreteObserver observer1{"Observer 1"};
  ConcreteObserver observer2{"Observer 2"};

  subject.Attach(observer1);
  subject.Attach(observer2);

  subject.SetState("Hello, observers!");

  subject.Detach(observer2);

  subject.SetState("Observer 2 won't see this.");
}
```


```c++
//<o>
Observer 1 received message: Hello, observers!
Observer 2 received message: Hello, observers!
Observer 1 received message: Observer 2 won't see this.
```


Let's break this down:

1. We define an `Observer` interface with a pure virtual `Update()` method.
2. The `Subject` class maintains a list of observer pointers. We use pointers here because `std::vector` can't store references directly.
3. The `Attach()` and `Detach()` methods in `Subject` take references to `Observer` objects. This provides a clean syntax for the user of the class and ensures that null observers can't be attached.
4. When `SetState()` is called, it updates the state and calls `Notify()`, which updates all observers.
5. `ConcreteObserver` is an implementation of the `Observer` interface.
6. In `main()`, we create a subject and two observers, attach the observers, set the subject's state (which notifies the observers), detach an observer, and set the state again.

Using references in the `Attach()` and `Detach()` methods provides several benefits:

- It's more intuitive: passing by reference clearly communicates that we're working with an existing object.
- It's safer: you can't pass a null reference, unlike with pointers.
- It's efficient: no need to check for null before dereferencing.

Remember, while we're using references in the interface, we're storing pointers internally. This is a common pattern when you need a mutable collection of references.

Implementing Observer Pattern with References

When it comes to function parameters, both references to const and pointers to const are commonly used for passing objects efficiently without allowing modification. However, there are some key differences in their behavior and use cases.


Let's compare them


## Syntax and Usage


In this example, we compare the two types:


```c++
#include <iostream>
#include <string>

void PrintByRef(const std::string& str) {
  std::cout << "Reference: " << str << '\n';
}

void PrintByPtr(const std::string* str) {
  if (str) {
    std::cout << "Pointer: " << *str << '\n';
  } else {
    std::cout << "Null pointer\n";
  }
}

int main() {
  std::string message{"Hello, World!"};

  PrintByRef(message);
  PrintByPtr(&message);
  PrintByPtr(nullptr);  // This is valid

  // This would be a compile-time error
  PrintByRef(nullptr); //<e>
}
```


```c++
//<o>
Reference: Hello, World!
Pointer: Hello, World!
Null pointer
```


Key differences:

1. **Nullability**: Pointers can be null, references cannot. This means you can pass `nullptr` to a function expecting a pointer, but not to one expecting a reference.
2. **Syntax**: References use more intuitive syntax (just like passing by value), while pointers require dereferencing with  when accessing the value.
3. **Optionality**: Pointers can represent optional parameters (by allowing null), while references always expect a valid object.
4. **Safety**: References are generally safer as they can't be null and don't require checking before use.

## Performance


In terms of performance, references and pointers are essentially identical. The compiler typically implements references using pointers under the hood.


## Const Correctness


Both `const T&` and `const T*` prevent modification of the pointed-to object:


```c++
#include <iostream>

void ModifyByRef(const int& x) {
  // x++;  // Compilation error
  std::cout << "Reference value: " << x << '\n';
}

void ModifyByPtr(const int* x) {
  // (*x)++;  // Compilation error
  if (x) {
    std::cout << "Pointer value: " << *x << '\n';
  }
}

int main() {
  int value{42};
  ModifyByRef(value);
  ModifyByPtr(&value);
}
```


## When to Use Each


Use references when:

- The parameter is required and will always be valid.
- You want a cleaner syntax in the function body.
- You want to prevent accidental null dereferences.

Use pointers when:

- The parameter is optional (can be null).
- You might need to change what the pointer points to.
- You're working with C-style APIs or older codebases.

In modern C++, references are often preferred for their safety and cleaner syntax, unless you specifically need the nullability or rebinding capabilities of pointers.

Reference vs Pointer to Const

Returning a reference to a local object from a function is a dangerous practice that can lead to undefined behavior. This is because local variables are destroyed when the function exits, leaving the returned reference dangling - it refers to memory that is no longer valid.


Let's look at an example to illustrate this problem:


```c++
#include <iostream>
#include <string>

std::string& CreateGreeting() {
  std::string greeting{"Hello, World!"};  //<w>
  return greeting;                        //<e>
}

int main() {
  std::string& ref = CreateGreeting();
  std::cout << "Greeting: " << ref << '\n';
}
```


This code might appear to work on some compilers or in some situations, but it's actually undefined behavior. Here's what's happening:

1. `CreateGreeting()` creates a local `std::string` object.
2. It returns a reference to this local object.
3. The function exits, and the local `greeting` object is destroyed.
4. The reference in `main()` now points to destroyed memory.
5. Attempting to use this reference leads to undefined behavior.

Some compilers might warn about this issue:


```plain text
//<oe>
warning: reference to local variable 'greeting' returned
```


The consequences of this undefined behavior can vary:

- The program might seem to work correctly (dangerous, as it masks the problem).
- It might crash.
- It might produce unexpected output.
- It might corrupt memory, leading to hard-to-debug issues elsewhere in the program.

To fix this, you have several options:


Return by value instead of by reference:


```c++
std::string CreateGreeting() {
  std::string greeting{"Hello, World!"};
  return greeting;
}
```


If you need to return a reference, ensure it's to a static or global object:


```c++
const std::string& CreateGreeting() {
  static const std::string greeting{
    "Hello, World!"
  };
  return greeting;
}
```


If the object needs to outlive the function but shouldn't be static, consider dynamic allocation (but be careful with memory management):


```c++
#include <iostream>

std::string* CreateGreeting() {
  return new std::string{"Hello, World!"};
}

int main() {
  std::string* pGreeting = CreateGreeting();
  std::cout << "Greeting: " << *pGreeting << '\n';
  // Don't forget to free the memory!
  delete pGreeting;
}
```


```c++
//<o>
Greeting: Hello, World!
```


In modern C++, option 1 (return by value) is often the best choice. The compiler can usually optimize this to be as efficient as returning a reference, without the dangers of dangling references.


Remember, when working with references, always ensure that the lifetime of the referenced object extends beyond the lifetime of the reference itself. This is especially crucial when returning references from functions.

Dangers of Returning References to Local Objects

<Excerpt>


At this point, we're hopefully familiar with calling functions, including passing arguments into our function's parameters.


However, we may have noticed, that if we modify a parameter within our function, the original variable is left unaffected:


```c++
#include <iostream>
using namespace std;

void Increment(int x){ x++; }//<h>

int main(){
  int Number{1};

  cout << "Number: " << Number;
  Increment(Number);//<h>
  cout << "\nNumber: Still " << Number;
}
```


```c++
//<o>
Number: 1
Number: Still 1
```


This is often the desired behavior, but not always.


In this lesson, we'll understand why code like this doesn't work in the way we might expect.  Then, we'll learn how to make it work.


</Excerpt>


## Pass by Value


The behavior of our previous function is a result of how arguments get passed to parameters.  When we call our functions, our arguments are _**copied**_.  


So, the integer we're modifying in our function is a copy of the original variable.  The variable within the calling function is not modified.


This behavior is called passing by value and, by default, it is what is used with all variable types in C++.  Below, we show a user-defined type, exhibiting similar behavior:


```c++
#include <iostream>
using namespace std;

class Character {
public:
  int Health{200};
};

void Combat(Character Player, Character Enemy){//<h>
  Player.Health -= 50;
  Enemy.Health -= 50;
}

int main(){
  Character Player;
  Character Enemy;
  cout << "Player: " << Player.Health;
  cout << "\nEnemy: " << Enemy.Health;
  Combat(Player, Enemy);//<h>
  cout << "\n\nPlayer: " << Player.Health;
  cout << "\nEnemy: " << Enemy.Health;
}
```


Because the `Player` and `Enemy` within our `Combat()` function are copies, the original Characters in our `main()` function are left unscathed:


```c++
//<o>
Player: 200
Enemy: 200

Player: 200
Enemy: 200
```


## Pass by Reference


The alternative to passing arguments by value is passing them by _**reference**_.  


A variable and its corresponding reference refer to the same location in our system's memory. Therefore, modifying a variable through its reference will reflect in the original variable.


To denote a reference, we append an `&` to any of our other types.  For example:

- `int&` is a reference to an `int`
- `float&` is a reference to a `float`
- `Character&` is a reference to a `Character`, a user-defined type

A variable can be implicitly converted to a reference to a variable of that same type so, to update our function's parameter to be passed by reference, we simply need to update its type using the `&` syntax:


```c++
#include <iostream>
using namespace std;

void Increment(int& x){ x++; }//<h>

int main(){
  int Number{1};

  cout << "Number: " << Number;
  Increment(Number);
  cout << "\nNumber: Now " << Number;
}
```


With that, modifications to the reference within the `Increment()` function are now reflected in our original variable in `main()`:


```c++
//<o>
Number: 1
Number: Now 2
```


We can do the same thing with our `Combat()` function, updating our `Character` types to be references, `Character&`:


```c++
#include <iostream>
using namespace std;

class Character {
public:
  int Health{200};
};

void Combat(Character& Player,//<h>
            Character& Enemy){//<h>
  Player.Health -= 50;
  Enemy.Health -= 50;
}

int main(){
  Character Player;
  Character Enemy;
  cout << "Player: " << Player.Health;
  cout << "\nEnemy: " << Enemy.Health;
  Combat(Player, Enemy);
  cout << "\n\nPlayer: " << Player.Health;
  cout << "\nEnemy: " << Enemy.Health;
}
```


```c++
//<o>
Player: 200
Enemy: 200

Player: 150
Enemy: 150
```


## Output Parameters


We've previously seen `return` statements in action.  They're the main way our functions communicate information back to their caller.


But with references, we now have another way.  The caller can pass a value to our function as a reference, our function can modify it, and then the caller can inspect it after the function ends.


```c++
#include <iostream>
using namespace std;

int Attack(bool& wasFatal) {//<h>
  wasFatal = true;
  return 50;
}

int main() {
  bool wasFatal;//<h>
  int Damage{Attack(wasFatal)};//<h>

  cout << "Inflicted " << Damage << " Damage";
  if (wasFatal) { cout << " (Fatal)"; }
}
```


```c++
//<o>
Inflicted 50 Damage (Fatal)
```


A parameter that is used for this approach is sometimes referred to as an _**output parameter**_.


Output parameters are rarely recommended.  It's difficult for our function to communicate which parameters will be used in this way, and the exact nature of the modifications that could be made.


The previous function can be written in a more friendly way by returning a new type.  The caller can understand what the function returns just by looking at that type, and can even unpack its values using structured binding:


```c++
#include <iostream>
using namespace std;

struct AttackResult {//<h>
  int Damage;//<h>
  bool wasFatal;//<h>
};//<h>

AttackResult Attack(){//<h>
  return AttackResult{50, true};
}

int main(){
  auto [Damage, wasFatal]{Attack()};//<h>

  cout << "Inflicted " << Damage << " Damage";
  if (wasFatal) { cout << " (Fatal)"; }
}
```


```c++
//<o>
Inflicted 50 Damage (Fatal)
```


But output parameters have some valid use cases, and the code we're interacting with will often use them, so we should understand the pattern.


<Error>


### Passing Literals to References


When we set our function up to receive a reference, our function expects to be called with a variable from which to create that reference.


As such, we can no longer pass a simple literal, as attempted below:


```c++
void SomeFunction(int& x){}

int main(){
  SomeFunction(5);//<e>
}
```


```c++
//<oe>
error: cannot convert argument 1 from 'int' to 'int &'
```


We cover the nuance here in more detail in the advanced course.


For now, we can note that literals are temporary values and references are meant to refer to something more permanent like a variable, so that changes can be made to that variable.


If we're not planning on changing the variable through our reference, we can bypass this error by declaring our reference as a **constant**, which we cover in the next section.


</Error>


## Reference Performance and `const`


Aside from the ability to modify parameters, passing by reference has a second, more useful property.


Copying an object has a performance cost.  Therefore, if we don't need a copy within our function, using pass-by-value may have an unnecessary performance overhead.


However, the ability to modify a reference in a way that affects variables within the calling code is generally not desirable.  For this reason, we can mark references as _**constant**_, using `const`:


```c++
#include <iostream>
using namespace std;

class Character {
public:
  int Health{200};
};

void SomeFunction(const Character& Player){//<h>
  // We can do this with a const reference:  
  cout << Player.Health;

  // But we can't do this:
  Player.Health -= 50;//<e>
}

int main(){
  Character Player;
  SomeFunction(Player);
}
```


```c++
//<oe>
error: 'Health' cannot be modified because it is being accessed through a const object
```


We can use the keyword `const` in many situations in C++, all relating to the idea of defining data that cannot be modified.  We'll see more examples later in the course.


With a `const` reference, we can read the data, but not change it.  This includes indirect modification by, for example, passing the reference off to another function that hasn't marked the parameter as `const`.


Constant references get us the performance benefits of passing by reference, whilst also letting the caller know we're not going to modify their argument.


### So How Should I Pass Arguments?


The copying cost of trivial types such as `int`, `float`, and `bool` is negligible. Creating copies of these is approximately as fast as creating references to them, so we tend to just pass these by value.


The copying cost is something we need to be more conscious of when we're dealing with objects that contain other objects.


Examples of this include user-defined types created from a class or struct that defines multiple member variables.  Strings are also an example of things we generally want to avoid copying, as a string is effectively a collection of `char` (character) objects. 


As such, when we're dealing with objects like these, passing them by `const` reference is generally preferred


To summarise, our decision process generally looks like this:

1. If we're intentionally using an output parameter: _**pass it by reference**_
2. Else if the parameter is cheap to copy: _**pass it by value**_
3. Else if the function needs to make a copy of the object anyway for its own internal logic: _**pass it by value**_
4. Else: _**pass it by constant reference**_

In real use cases, situations 2 and 4 are by far the most common.


## Creating References


The use of references goes beyond just passing data to functions.  We can use references at any time.  


Below, we simply create a reference like any other variable.  Our identifier `Ref` is bound to the `MyNumber` variable.  As such, modifications to `Ref` affect `MyNumber`: 


```c++
#include <iostream>
using namespace std;

int main(){
  int MyNumber{5};
  int& Ref{MyNumber};//<h>
  Ref++;
  cout << "Value: " << MyNumber;
}
```


```c++
//<o>
Value: 6
```


This effectively means our `main` function now has two names for the same value: we can access it through either `MyNumber` or `Ref`.  In practice, this is rarely useful, but it can help us explain two important restrictions of using references.


## Reference Restrictions


References are closely related to the concept of **memory addresses**, which we'll cover in more detail throughout this chapter.


Working with memory addresses is a common source of bugs.  References implement two restrictions that eliminate two of the main reasons for these defects:


### References Must be Initialized


When we create a reference, we must also initialize it to point to the desired memory address - usually by assigning it to a variable:


```c++
int main(){
  int MyNumber{5};
  int& Ref{MyNumber};//<h>
}
```


If we try to declare a reference without providing it with an initial value, we will get a compilation error:


```c++
int main(){
  int& Ref;//<e>
}
```


```c++
//<oe>
error: 'Ref': references must be initialized
```


### References Cannot be Reassigned


The second restriction is that a reference cannot be updated to point to a different memory address.  Once a reference is created, it will always point to the memory address it was initialized with.


In the next lesson, we'll introduce **pointers**.  These effectively work in the same way as references, but they remove these two restrictions.  This makes pointers more dangerous to work with, but also more flexible.


## References as Class Members


Finally, let's see an example of a reference within a user-defined type.  Below, our `Character` objects have a member `mSword`, which is a reference to a `Weapon`:


```c++
class Weapon {
public:
  string Name;
};

class Character {
public:
  Character(Weapon& Sword): mSword{Sword}{}//<h>
  Weapon GetWeapon(){ return mSword; }

private:
  Weapon& mSword;//<h>
};
```


When our classes contain references, the references _**must**_ be initialized within a member initializer list.


Attempting to set a reference within a constructor body is too late to satisfy the "references must be initialized" restriction.  We covered the reasons for this in more detail in our earlier lesson on <InlineLessonPromo url="intro-to-programming/member-initializer-lists" title="Member Initializer Lists" description="This lesson introduces Member Initializer Lists, focusing on their advantages for performance and readability, and how to use them effectively">member initializer lists</InlineLessonPromo>.


References within an object work the same way as they do anywhere else.  Below, we modify `PlayerWeapon` and, since our `Character` is holding that object by reference, we see the changes reflected in the `Player.GetWeapon()` return value:


```c++
#include <iostream>
using namespace std;

class Weapon {
public:
  string Name;
};

class Character {
public:
  Character(Weapon& Sword): mSword{Sword}{}
  Weapon GetWeapon(){ return mSword; }

private:
  Weapon& mSword;
};

int main(){
  Weapon PlayerWeapon{"Wooden Sword"};
  Character Player{PlayerWeapon};

  cout << Player.GetWeapon().Name << '\n';
  PlayerWeapon.Name = "Steel Sword";
  cout << Player.GetWeapon().Name;
}
```


```c++
//<o>
Wooden Sword
Steel Sword
```


<Error>


### Returning References from Functions


In the previous example, our `GetWeapon()` function is returning the weapon by value, not by reference.


Functions can return references, but we need to be careful here.  Because a reference is linked to an underlying object, we need to ensure that the object has not automatically been deleted from memory.


The following program creates a `Character` within the `GetPlayer()` function and returns a reference to it.


But when the `GetPlayer()` function ends, the `Character` is automatically deleted, breaking the reference:


```c++
#include <iostream>
using namespace std;

class Character {
public:
  string Name;
};

Character& GetPlayer(){//<w>
  Character Player{"Anna"};
  return Player;
}

int main(){
  cout << "Name: " << GetPlayer().Name;
}
```


Our program will likely output some gibberish and then crash:


```c++
//<o>
Name: P$P$^$
```


This example is technically valid so compilers will allow it.  However, most can detect something is wrong here, and will issue a warning:


```c++
//<ow>
main.cpp:11:10: warning: reference to stack memory associated with local variable 'Player' returned [-Wreturn-stack-address]
```


This scenario is typically called a "dangling reference" and is something we want to avoid.  We cover it in more detail later in this chapter.


</Error>


<Quiz title="References">


<Question>


Consider the following variable:


```c++
int SomeVariable{42};
```


What is the correct syntax for declaring a reference to `SomeVariable`?


<Answer isCorrect>
`int& Ref{SomeVariable};`


<Feedback>
Correct! The syntax `int& Ref{SomeVariable};` is used to declare a reference to an integer
</Feedback>


</Answer>


<Answer>
`int Ref&{SomeVariable};`


<Feedback>
Not quite right. The ampersand (&) should be placed directly after the type and before the variable name
</Feedback>


</Answer>


<Answer>
`&int Ref{SomeVariable};`


<Feedback>
Incorrect. The correct syntax for declaring a reference places the ampersand between the type and the variable name.
</Feedback>


</Answer>


<Answer>
`int Ref{&SomeVariable};`


<Feedback>
This isn't correct. In C++, the type comes first, followed by the ampersand and then the variable name.
</Feedback>


</Answer>


</Question>


<Question>
What is the result of modifying a variable through its reference?


<Answer>
The original variable remains unchanged.


<Feedback>
Not quite. When you modify a variable through its reference, the original variable is also changed.
</Feedback>


</Answer>


<Answer>
It creates a new copy of the variable.


<Feedback>
Incorrect. Modifying a variable through its reference directly affects the original variable, without creating a new copy.
</Feedback>


</Answer>


<Answer isCorrect>
The original variable is also modified.


<Feedback>
Correct! In C++, modifying a variable through its reference will also change the original variable.
</Feedback>


</Answer>


<Answer>
A variable cannot be modified through its reference.


<Feedback>
That's not right. Modifying a variable through its reference is a valid operation.
</Feedback>


</Answer>


</Question>


<Question>
What is the primary purpose of using references in functions?


<Answer isCorrect>
To pass data to functions more efficiently and allow for modification of the original data.


<Feedback>
Correct! Using references in functions allows for efficient data passing and direct modification of the original variables.
</Feedback>


</Answer>


<Answer>
To create new copies of variables for safe manipulation without affecting the original data.


<Feedback>
Not quite right. While creating copies is a feature of passing by value, references are used to directly modify the original data, not copies.
</Feedback>


</Answer>


<Answer>
To `return` multiple values from a function without defining a new type.


<Feedback>
While references can be used as output parameters, this is not equivalent to returning multiple values, and it is not their main purpose.
</Feedback>


</Answer>


</Question>


<Question>
What happens if you try to declare a reference without initializing it?


<Answer>
The program will compile successfully, but the reference will point to a random memory location.


<Feedback>
Not quite. In C++, a reference must be initialized when it is declared; otherwise, it leads to a compilation error.
</Feedback>


</Answer>


<Answer isCorrect>
A compilation error will occur.


<Feedback>
Correct! In C++, you must initialize a reference when you declare it; failing to do so will result in a compilation error.
</Feedback>


</Answer>


<Answer>
The reference will automatically be initialized to NULL.


<Feedback>
This isn't correct. In C++, references cannot be uninitialized or set to NULL; they must be initialized with a valid object.
</Feedback>


</Answer>


<Answer>
The reference will be automatically initialized to the most recently declared variable of the same type.


<Feedback>
That's not correct. C++ requires explicit initialization of references; they do not automatically initialize to any variable.
</Feedback>


</Answer>


</Question>


</Quiz>


## Summary


This lesson provided an introduction to the concept of references.  We covered:

- Understanding the difference between passing by value and passing by reference.
- Learning how to use the `&` symbol to create references.
- Exploring the use of references in functions, including output parameters and constant references.
- Discussing the restrictions and rules governing the use of references.
- Examining the role of references in user-defined types, such as class members.

<Preview>


### Pointers


The upcoming lesson will delve into pointers.  Pointers have many similarities to references but with some additional capabilities. We'll cover

- Understanding the basic concept of pointers and their syntax.
- Learning how to use pointers to directly access and manipulate memory.
- Differentiating between pointers and references.
- Exploring the use of pointers in functions.
- Discussing best practices and common pitfalls associated with pointer usage.

</Preview>

Merged and rewrote "Why we Need References" and "Creating References" lessons

Updated initialization syntax in some examples, and minor style improvements

3D art showing a female blacksmith character

Reference declaration

References (C++)

Passing Variables by Reference

C++ value categories and decltype demystified

{CPP}Learn how to use references for data manipulation and performance improvements

References

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Intro to C++ Programming

Questions & Answers