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:

1#include <iostream>
2using namespace std;
3
4void Increment(int x){ x++; }
5
6int main(){
7  int Number{1};
8
9  cout << "Number: " << Number;
10  Increment(Number);
11  cout << "\nNumber: Still " << Number;
12}

1Number: 1
2Number: 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.

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:

1#include <iostream>
2using namespace std;
3
4class Character {
5public:
6  int Health{200};
7};
8
9void Combat(Character Player, Character Enemy){
10  Player.Health -= 50;
11  Enemy.Health -= 50;
12}
13
14int main(){
15  Character Player;
16  Character Enemy;
17  cout << "Player: " << Player.Health;
18  cout << "\nEnemy: " << Enemy.Health;
19  Combat(Player, Enemy);
20  cout << "\n\nPlayer: " << Player.Health;
21  cout << "\nEnemy: " << Enemy.Health;
22}

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

1Player: 200
2Enemy: 200
3
4Player: 200
5Enemy: 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:

1#include <iostream>
2using namespace std;
3
4void Increment(int& x){ x++; }
5
6int main(){
7  int Number{1};
8
9  cout << "Number: " << Number;
10  Increment(Number);
11  cout << "\nNumber: Now " << Number;
12}

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

1Number: 1
2Number: Now 2

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

1#include <iostream>
2using namespace std;
3
4class Character {
5public:
6  int Health{200};
7};
8
9void Combat(Character& Player,
10            Character& Enemy){
11  Player.Health -= 50;
12  Enemy.Health -= 50;
13}
14
15int main(){
16  Character Player;
17  Character Enemy;
18  cout << "Player: " << Player.Health;
19  cout << "\nEnemy: " << Enemy.Health;
20  Combat(Player, Enemy);
21  cout << "\n\nPlayer: " << Player.Health;
22  cout << "\nEnemy: " << Enemy.Health;
23}

1Player: 200
2Enemy: 200
3
4Player: 150
5Enemy: 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.

1#include <iostream>
2using namespace std;
3
4int Attack(bool& wasFatal) {
5  wasFatal = true;
6  return 50;
7}
8
9int main() {
10  bool wasFatal;
11  int Damage{Attack(wasFatal)};
12
13  cout << "Inflicted " << Damage << " Damage";
14  if (wasFatal) { cout << " (Fatal)"; }
15}

1Inflicted 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:

1#include <iostream>
2using namespace std;
3
4struct AttackResult {
5  int Damage;
6  bool wasFatal;
7};
8
9AttackResult Attack(){
10  return AttackResult{50, true};
11}
12
13int main(){
14  auto [Damage, wasFatal]{Attack()};
15
16  cout << "Inflicted " << Damage << " Damage";
17  if (wasFatal) { cout << " (Fatal)"; }
18}

1Inflicted 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.

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:

1void SomeFunction(int& x){}
2
3int main(){
4  SomeFunction(5);
5}

1error: cannot convert argument 1
2from '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.

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:

1#include <iostream>
2using namespace std;
3
4class Character {
5public:
6  int Health{200};
7};
8
9void SomeFunction(const Character& Player){
10  // We can do this with a const reference:  
11  cout << Player.Health;
12
13  // But we can't do this:
14  Player.Health -= 50;
15}
16
17int main(){
18  Character Player;
19  SomeFunction(Player);
20}

1error: 'Health' cannot be modified because it is
2being 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 that defines multiple member variables. Strings are also an example of this, 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

Therefore, our decision process generally follows the following process:

If we're intentionally using an output parameter: pass by reference
Else if the parameter is cheap to copy: pass by value
Else if we need to modify the object in some way within our function, and don't want our changes affecting the caller: pass by value
Else: pass 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:

1#include <iostream>
2using namespace std;
3
4int main(){
5  int MyNumber{5};
6  int& Ref{MyNumber};
7  Ref++;
8  cout << "Value: " << MyNumber;
9}

1Value: 6

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 a large source of 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:

1int main(){
2  int MyNumber{5};
3  int& Ref{MyNumber};
4}

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

1int main(){
2  int& Ref;
3}

1error: '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 use similar concepts to references, but they remove these two restrictions. This makes pointers more dangerous to work with, but also more powerful.

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:

1class Weapon {
2public:
3  string Name;
4};
5
6class Character {
7public:
8  Character(Weapon& Sword): mSword(Sword){}
9  Weapon GetWeapon(){ return mSword; }
10
11private:
12  Weapon& mSword;
13};

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:

Member Initializer Lists

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

View Related Lesson

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:

1#include <iostream>
2using namespace std;
3
4class Weapon {
5public:
6  string Name;
7};
8
9class Character {
10public:
11  Character(Weapon& Sword): mSword(Sword){}
12  Weapon GetWeapon(){ return mSword; }
13
14private:
15  Weapon& mSword;
16};
17
18int main(){
19  Weapon PlayerWeapon{"Wooden Sword"};
20  Character Player{PlayerWeapon};
21
22  cout << Player.GetWeapon().Name << '\n';
23  PlayerWeapon.Name = "Steel Sword";
24  cout << Player.GetWeapon().Name;
25}

1Wooden Sword
2Steel Sword

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.

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

But when the function ends, the Character is automatically deleted, breaking the reference:

1#include <iostream>
2using namespace std;
3
4class Character {
5public:
6  string Name;
7};
8
9Character& GetPlayer(){
10  Character Player{"Anna"};
11  return Player;
12}
13
14int main(){
15  cout << "Name: " << GetPlayer().Name;
16}

Our program will likely output some gibberish and then crash:

1Name: P$P$^$

We cover this scenario and how to deal with it in more detail later in this chapter.

Test your Knowledge

References

Consider the following variable:

1int SomeVariable{42};

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

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

What is the primary purpose of using references in functions?

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

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.

References

Pass by Value

Pass by Reference

Output Parameters

Reference Performance and `const`

Creating References

Reference Restrictions

References Must be Initialized

References Cannot be Reassigned

References as Class Members

Member Initializer Lists

References

Summary

Pointers

Intro to C++ Programming

Questions & Answers

References

Pass by Value

Pass by Reference

Output Parameters

Reference Performance and const

Creating References

Reference Restrictions

References Must be Initialized

References Cannot be Reassigned

References as Class Members

Member Initializer Lists

References

Summary

Pointers

Questions & Answers

Reference Performance and `const`