Implementing Ranges for Custom Types

In the previous lesson, we introduced how types that implement appropriate begin() and end() methods can be considered ranges and therefore become compatible with range-based techniques.

Often, we’d like to give our custom, user-defined types this capability too. For example, we might have a Party type that contains a collection of Player objects.

We’d like to be able to iterate over those players using a range-based for loop:

1#include "Party.h"
2
3int main() {
4  Party MyParty;
5  for (const auto& Player : MyParty) {
6    // ...
7  }
8}

In this lesson, we’ll show how we can implement this capability.

Adding Iterators to our Custom Types

In the next two lessons, we will see an example where we implement iterators for our types entirely from scratch. This gives us full control over the implementation, and how our iterators behave.

But, in most cases, this isn’t necessary. When we’re implementing a custom collection, two things are often true:

• Behind the scenes, our collection is letting some other type manage storage, such as a std::vector
• That type implements iterators, and we want our iterators to behave the same way

We’ll focus on this simpler scenario in this lesson. A typical Party class might look like this, where we’re relying on a private std::vector to manage the storage:

1#include <vector>
2
3class Player {};
4
5class Party {
6public:
7  // Party-specific logic
8  void AddMember() {};
9  void StartQuest() {};
10  void Disband() {};
11  void SetLeader() {};
12
13private:
14  // Underlying Collection
15  std::vector<Player> PartyMembers;
16};

To make our party iterable, we can just expose the begin() and end() methods of our underlying std::vector.

Note, that our begin() and end() methods must be made public for our container to be considered a range:

1#include <vector>
2
3class Player {};
4
5class Party {
6public:
7  // Party-specific logic
8  // ...
9
10  // Iterators
11  auto begin() {
12    return PartyMembers.begin();
13  }
14  auto end() {
15    return PartyMembers.end();
16  }
17private:
18  // Underlying Collection
19  std::vector<Player> PartyMembers;
20};

Iterator Types

Above, the return type of our new functions was set to auto. This is typical but if we ever need to be specific about the type of an iterator from the standard library containers, there’s a static iterator property that we can use:

1vector<Player>::iterator begin() {
2  return PartyMembers.begin();
3}
4
5vector<Player>::iterator end() {
6  return PartyMembers.end();
7}

Asserting a Type is a Range

If our type is intended to be a range, it’s useful to statically assert this using the range concepts we introduced in the previous lesson.

This ensures that if some future change to our type causes it to violate the range specification, we’re alerted.

Below, we assert our type is a random access range. This is the case because the iterators we use are from a std::vector, which is a container that supports random access:

1#include <vector>
2#include <ranges>
3
4class Player {};
5
Unchanged Code|Show
6class Party { /*...*/ }
20
21static_assert(
22  std::ranges::random_access_range<Party>);

In this case, our type is also a contiguous range. A contiguous range is simply a random access range, with the additional guarantee that adjacent elements are also adjacent in memory.

This is how arrays like std::vector work, so our type also satisfies this stricter concept:

1static_assert(
2  std::ranges::contiguous_range<Party>);

Using Range-Based For Loops

Now that our type implements all the range requirements, the objects instantiated from the class are now ranges.

This allows us to use them in range-based techniques, such as a range-based for loop:

1int main() {
2  Party MyParty;
3
4  for (const auto& Player : MyParty) {
5    // ...do things
6  }
7}

A complete example is available here:

1#include <vector>
2#include <iostream>
3#include <utility>
4
5class Player {
6public:
7  Player(std::string Name) : mName(Name) {}
8  std::string GetName() const { return mName; }
9private:
10  std::string mName;
11};
12
13class Party {
14public:
15  void AddMember(const std::string& NewMember) {
16    PartyMembers.emplace_back(NewMember);
17  }
18
19  // Iterators
20  auto begin() {
21    return PartyMembers.begin();
22  }
23  auto end() {
24    return PartyMembers.end();
25  }
26private:
27  std::vector<Player> PartyMembers;
28};
29
30int main() {
31  Party MyParty;
32  MyParty.AddMember("Legolas");
33  MyParty.AddMember("Gimli");
34  MyParty.AddMember("Frodo");
35
36  for (const auto& Player : MyParty) {
37    std::cout << Player.GetName() << '\n';
38  }
39}

1Legolas
2Gimli
3Frodo

Summary

In this lesson, we explored how to create a range using a custom type by implementing begin() and end() methods.

We also discussed how to assert that a type correctly implements the range requirements by combining static_assert and concepts from the standard library <ranges> header.

Key Takeaways:

• Custom types can be valid ranges by implementing begin() and end() methods. When they encapsulate a standard library container like std::vector, this can be done simply by returning that container’s iterators.
• The begin() and end() methods must be public for a type to be considered a range.
• Using auto for the return type of begin() and end() is common, but exact iterator types can also be explicitly specified.
• If our type is required to be a range, we should statically assert that it is.
• Once a type is confirmed as a range, it can be used with with range-based techniques, such as range-based for loops.

Next Lesson

Defining Ranges using Sentinels

An alternative way of defining ranges, and why we sometimes need to use them

ContinueView Course