Free, Unlimited Access

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

Professional C++





<Excerpt>


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:


```c++
#include "Party.h"

int main() {
  Party MyParty;
  for (const auto& Player : MyParty) {
    // ...
  }
}
```


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


</Excerpt>


## 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:


```c++
#include <vector>

class Player {};

class Party {
public:
  // Party-specific logic
  void AddMember() {};
  void StartQuest() {};
  void Disband() {};
  void SetLeader() {};

private:
  // Underlying Collection
  std::vector<Player> PartyMembers;
};
```


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:


```c++
#include <vector>

class Player {};

class Party {
public:
  // Party-specific logic
  // ...

  // Iterators
  auto begin() {//<h>
    return PartyMembers.begin();//<h>
  }//<h>
  auto end() {//<h>
    return PartyMembers.end();//<h>
  }//<h>
private:
  // Underlying Collection
  std::vector<Player> PartyMembers;
};
```


## 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:


```c++
vector<Player>::iterator begin() {
  return PartyMembers.begin();
}

vector<Player>::iterator end() {
  return PartyMembers.end();
}
```


<Ad />


## 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:


```c++
#include <vector>
#include <ranges>//<h>

class Player {};

//<c>
//<l>class Party { /*...*/ }
class Party {
 public:
  // Party-specific logic
  // ...

  // Iterators
  auto begin() { return PartyMembers.begin(); }
  auto end() { return PartyMembers.end(); }

 private:
  // Underlying Collection
  std::vector<Player> PartyMembers;
};
//</c>

static_assert(//<h>
  std::ranges::random_access_range<Party>);//<h>
```


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:


```c++
static_assert(
  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:


```c++
int main() {
  Party MyParty;

  for (const auto& Player : MyParty) {
    // ...do things
  }
}
```


A complete example is available here:


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  // Iterators
  auto begin() {
    return PartyMembers.begin();
  }
  auto end() {
    return PartyMembers.end();
  }
private:
  std::vector<Player> PartyMembers;
};

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```c++
//<o>
Legolas
Gimli
Frodo
```


## 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.

<FAQ>


```javascript
//<m>
{
  slug: 'implementing-iterators-in-custom-types',
  title: 'Implementing Iterators in Custom Types',
  question: 'How can I implement iterators for my custom types in C++?',
}
```


To implement iterators for custom types in C++, you need to define `begin()` and `end()` methods in your class.


These methods should return iterators that can traverse the elements of your collection. Here's an example using a class `Party` that contains a collection of `Player` objects managed by an `std::vector`.


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  auto begin() {
    return PartyMembers.begin();
  }
  auto end() {
    return PartyMembers.end();
  }

private:
  std::vector<Player> PartyMembers;
};

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```text
//<o>
Legolas
Gimli
Frodo
```


</FAQ>
<FAQ>


```javascript
//<m>
{
  slug: 'iterator-types-in-cpp',
  title: 'What are iterator types in C++?',
  question: 'What are iterator types in C++ and how do I use them?',
}
```


Iterator types in C++ define how iterators access elements in a container. The most common types are:

- **Input Iterator**: Read elements from a sequence.
- **Output Iterator**: Write elements to a sequence.
- **Forward Iterator**: Traverse a sequence in one direction.
- **Bidirectional Iterator**: Traverse a sequence in both directions.
- **Random Access Iterator**: Access any element in constant time.

In most cases, using `auto` for the return type of `begin()` and `end()` is sufficient. However, if you need to specify the type explicitly, you can use the iterator type provided by the container. Here's how to do it with `std::vector`:


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  std::vector<Player>::iterator begin() {//<h>
    return PartyMembers.begin();
  }
  
  std::vector<Player>::iterator end() {//<h>
    return PartyMembers.end();
  }

private:
  std::vector<Player> PartyMembers;
};

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```text
//<o>
Legolas
Gimli
Frodo
```


</FAQ>
<FAQ>


```javascript
//<m>
{
  slug: 'asserting-range-in-cpp',
  title: 'How do I assert a type is a range in C++?',
  question: 'How can I ensure my custom type is a valid range in C++?',
}
```


To ensure your custom type is a valid range, you can use `static_assert` along with concepts from the `<ranges>` header in C++20.


This allows you to check that your type meets the criteria for being a range. Here's how you can assert that a type is a random access range and a contiguous range:


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  auto begin() {
    return PartyMembers.begin();
  }
  
  auto end() {
    return PartyMembers.end();
  }

private:
  std::vector<Player> PartyMembers;
};

static_assert(std::ranges::random_access_range<Party>);
static_assert(std::ranges::contiguous_range<Party>);

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```text
//<o>
Legolas
Gimli
Frodo
```


This ensures that if any future changes to `Party` violate the range requirements, you'll be alerted during compilation.
</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'range-based-for-loop-in-cpp',
  title: 'How to use range-based for loops in C++?',
  question: 'How can I use range-based for loops with my custom types in C++?',
}
```


To use range-based for loops with your custom types in C++, you need to implement `begin()` and `end()` methods that return iterators.


Once you have these methods in place, you can use the range-based for loop syntax to iterate over your collection. Here's an example:


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  auto begin() {
    return PartyMembers.begin();
  }
  
  auto end() {
    return PartyMembers.end();
  }

private:
  std::vector<Player> PartyMembers;
};

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```text
//<o>
Legolas
Gimli
Frodo
```


By defining `begin()` and `end()`, your custom type `Party` can be used in a range-based for loop to iterate over its elements.
</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'custom-collection-iterator',
  title: 'How to create a custom collection with iterators in C++?',
  question: 'How do I create a custom collection with iterators in C++?',
}
```


To create a custom collection with iterators in C++, you need to define your own collection class and provide `begin()` and `end()` methods.


These methods should return iterators that allow traversal of the collection. Here’s an example using a custom `Party` class:


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  auto begin() {
    return PartyMembers.begin();
  }
  auto end() {
    return PartyMembers.end();
  }

private:
  std::vector<Player> PartyMembers;
};

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```text
//<o>
Legolas
Gimli
Frodo
```


By defining these methods, you make your custom collection compatible with range-based for loops and other STL algorithms that require iterators.
</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'custom-range-concepts',
  title: 'How to use concepts with custom ranges in C++?',
  question: 'How can I use concepts to ensure my custom type is a valid range in C++?',
}
```


Using concepts with custom ranges in C++ allows you to enforce constraints at compile time, ensuring your custom type meets the criteria of a range.


Concepts from the `<ranges>` header can be used to assert properties like `random_access_range` and `contiguous_range`. Here’s how:


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

class Player {
public:
  Player(std::string Name) : mName(Name) {}
  std::string GetName() const { return mName; }
private:
  std::string mName;
};

class Party {
public:
  void AddMember(const std::string& NewMember) {
    PartyMembers.emplace_back(NewMember);
  }

  auto begin() {
    return PartyMembers.begin();
  }
  auto end() {
    return PartyMembers.end();
  }

private:
  std::vector<Player> PartyMembers;
};

static_assert(std::ranges::random_access_range<Party>);
static_assert(std::ranges::contiguous_range<Party>);

int main() {
  Party MyParty;
  MyParty.AddMember("Legolas");
  MyParty.AddMember("Gimli");
  MyParty.AddMember("Frodo");

  for (const auto& Player : MyParty) {
    std::cout << Player.GetName() << '\n';
  }
}
```


```text
//<o>
Legolas
Gimli
Frodo
```


Using `static_assert` with concepts ensures that your custom type `Party` remains a valid range, and any violations will be caught at compile time.
</FAQ>



Learn to implement iterators in custom types, and make them compatible with range-based techniques.

Implementing Iterators in Custom Types

What are iterator types in C++?

How do I assert a type is a range in C++?

How to use range-based for loops in C++?

How to create a custom collection with iterators in C++?

How to use concepts with custom ranges in C++?

C++ Iterators

Ranges library (C++20)

Range-based for loop

std::vector

Iterator

How to make my custom type to work with "range-based for loops"?

UPDATED FOR C++23 | Learn how to enhance our custom types by adding support for iterators and ranges | Clear explanations and simple code examples

Implementing C++20 Ranges for Custom Types | A Practical Guide

Implementing Ranges for Custom Types

Implementing Iterators in Custom Types

How can I implement iterators for my custom types in C++?

Implementing Ranges for Custom Types

What are iterator types in C++ and how do I use them?

How can I ensure my custom type is a valid range in C++?

How can I use range-based for loops with my custom types in C++?

How do I create a custom collection with iterators in C++?

How can I use concepts to ensure my custom type is a valid range in C++?

Implementing Ranges for Custom Types

Professional C++

This course includes:

Professional C++