Storing two values in a single variable using std::pair

A very common scenario we will come across is the need to store two values together. This might be to return two values from a function, to store two elements at every index of an array, or the simple desire to establish in our code that these two values are connected in some way.

Let's introduce a new Item struct that we will use for these lessons:

1#include <string>
2using std::string;
3
4struct Item {
5  string Name;
6  int Weight;
7  int Value;
8};
9
10Item HealingPotion { "Healing Potion", 2, 10 };
11

Imagine we were trying to create an inventory system, where each slot in our inventory can contain multiple quantities of a specific item.

So, we have two closely connected values: an Item, and how many of those items we have in our inventory. We already know we could create a struct for that:

1struct InventoryItem {
2  Item* Item;
3  int Quantity;
4}
5
6InventoryItem Slot { &HealingPotion, 1000 };
7

Creating Pairs

But we can also use a more generic container. One of the most basic containers is a simple pair, available from the std namespace by including <utility>:

1#include <utility>
2
3std::pair Slot { &HealingPotion, 1000 };
4

In the above example, because we are initializing the pair at the same time we create it, we do not have to specify the type of each member in the pair.

We can provide the types we want (demonstrated below) but the compiler can just automatically deduce the types by the values we are providing for initialization.

In the above example, we create a pair that contains a pointer to an Item and an int. This form of automatic type inference is called "Class Template Argument Deduction", or CTAD.

If we do not provide the initial values, the data type we want to store cannot be inferred, so we would need to provide that information upfront.

For example, a pair that contains an Item pointer and int can be declared like this:

1#include <utility>
2
3std::pair<Item*, int> Slot;
4

CTAD is optional - we can provide both the types and initial values if we prefer:

1#include <utility>
2
3std::pair<Item*, int> Slot { &HealingPotion, 1000 };
4

The use of < and > in these examples indicates we are using a template. We will make use of templates provided by the standard library throughout this section, and we will learn how to create our own in the intermediate course.

As a final example of creating pairs, the following shows how we can create and return one from a function:

1Item HealingPotion { "Healing Potion", 2, 10 };
2
3std::pair<Item*, int> GetInventoryItem() {
4  return { &HealingPotion, 10 }
5}
6
7auto InventoryItem { GetInventoryItem() };
8

Using Pairs

The first and second members of the pair are available through the member access operator . with the keys first and second respectively.

1std::pair Slot { &HealingPotion, 1000 };
2
3// Reading Values
4Item& Item { Slot.first };
5int Quantity { Slot.second };
6
7int ItemValue { Slot.first->Value };
8int TotalValue { Slot.first->Value * Quantity };
9int TotalWeight { Slot.first->Weight * Quantity };
10
11// Writing Values
12Item ManaPotion { "Mana Potion", 1, 5 };
13Slot.first = &ManaPotion;
14Slot.second = 10;
15

Pair References and Pointers

Like with any other type, pairs can also be stored and passed around as values, references, or pointers. In the below example, we pass the pair by value, ie, we create a copy:

1using std::pair, std::cout, std::endl;
2
3void IncrementByValue(pair<Item*, int> Slot) {
4  Slot.second++;
5}
6
7int main() {
8  pair Slot { &HealingPotion, 100 };
9  IncrementByValue(Slot);
10
11  // Quantity is still 100 - we passed a copy of the Slot.
12  cout << "Quantity: " << Slot.second << endl;
13}
14

1Quantity: 100
2

Like with any other type, we can create a reference to a pair using the & operator:

1// A reference to a pair
2// The pair stores a pointer to an Item and an integer
3std::pair<Item*, int>& Slot;
4

Here, we pass a reference. Note the addition of the & in our parameter list:

1using std::pair, std::cout, std::endl;
2
3void IncrementByReference(pair<Item*, int>& Slot) {
4  Slot.second++;
5}
6
7int main() {
8  pair Slot { &HealingPotion, 100 };
9  IncrementByReference(Slot);
10
11  // Quantity is now 101 - we passed a reference to the Slot.
12  cout << "Quantity: " << Slot.second << endl;
13}
14

1Quantity: 101
2

Finally, lets see an example using a pointer. Note the addition of the * on line 3 to indicate we're expecting a pointer, the switching of the . for the -> operator on line 4, and the use of the address-of operator & on line 9.

1using std::pair, std::cout, std::endl;
2
3void IncrementByPointer(pair<Item*, int>* Slot) {
4  Slot->second++;
5}
6
7int main() {
8  pair Slot { &HealingPotion, 100 };
9  IncrementByPointer(&Slot);
10
11  // Quantity is now 101 - we passed a pointer to the Slot.
12  cout << "Quantity: " << Slot.second << endl;
13}
14

1Quantity: 101
2

The use of a pointer to a container (our pair) that itself contains a pointer (our Item) may be confusing but is not fundamentally different from what we’ve seen before.

We can get access to our Item* properties through our pair* by using the -> operator multiple times.

1using std::pair;
2
3int GetItemValue(pair<Item*, int>* Slot) {
4  return Slot->first->Value;
5}
6

As covered in our earlier lessons on pointers, we might want to ensure that a pointer is not a nullptr before trying to dereference it, to prevent exceptions:

1using std::pair;
2
3int GetItemValue(pair<Item*, int>* Slot) {
4  // Ensure the std::pair* is not a nullptr
5  if (!Slot) return 0;
6
7  // Ensure the Item* is not a nullptr
8  if (!Slot->first) return 0;
9
10  return Slot->first->Value;
11}
12

Pair Type Alias

The types of pairs can get a little verbose. As with other data structures, we can alias a pair type to a simpler, more descriptive name:

1using InventorySlot = std::pair<Item*, int>*;
2
3int GetItemValue(InventorySlot Slot) {
4  if (!Slot) return 0;
5  if (!Slot->first) return 0;
6
7  return Slot->first->Value;
8}
9

Structured Bindings with std::pair

As with classes and structs, we can use structured bindings to access the first and second elements of pairs. This allows us to use more descriptive names in our code, rather than first and second:

1using std::pair;
2
3// Using structured binding with a pair value
4void BindingExample1(pair<Item*, int> Slot) {
5  auto [item, quantity] = Slot;
6}
7
8// Using structured binding with a pair pointer
9void BindingExample2(pair<Item*, int>* Slot) {
10  auto [item, quantity] = *Slot;
11}
12

Complete Example of std::pair

Here is a more complex example, using all the techniques we covered above:

1#include <string>
2#include <utility>
3#include <iostream>
4
5using std::string, std::pair, std::cout, std::endl;
6
7struct Item {
8  std::string Name;
9  int Weight;
10  int Value;
11};
12
13using InventorySlot = std::pair<Item*, int>*;
14
15void LogSlotDetails(InventorySlot Slot) {
16  auto [item, quantity] = *Slot;
17  cout << "This slot has " << quantity
18       << " " << item->Name << "s." << endl;
19  cout << "Their weight is "
20       << quantity * item->Weight
21       << " grams." << endl;
22  cout << "They are worth "
23       << quantity * item->Value
24       << " coins." << endl;
25}
26
27int main() {
28  Item HealingPotion { "Healing Potion", 200, 5 };
29  std::pair Slot { &HealingPotion, 10 };
30  LogSlotDetails(&Slot);
31}
32

1This slot has 10 Healing Potions.
2Their weight is 2000 grams.
3They are worth 50 coins.
4