Subranges and Range Interoperability

In the previous lessons, we successfully transitioned from raw loops to views and pipes. We saw how easy it is to take a container like std::vector, pipe it through std::views::filter(), and process the results lazily. But there is a catch.

The standard library views like transform(), filter(), and take() assume we are starting with a range - usually a container like std::vector or another view. But what if we aren't?

What if we are working with a legacy C API that gives us a raw pointer and a size? What if we are using an older algorithm that returns a std::pair of iterators? What if we are implementing a custom search algorithm that identifies a specific slice of some dataset?

In these scenarios, you have the raw materials of a range (a start and an end), but we don't have a range object. We have two separate variables.

To solve this, C++20 introduced the universal adaptor: std::ranges::subrange. It takes any pair of iterators (or an iterator and a sentinel) and wraps them into a lightweight object that satisfies the view concept. It allows us to bridge the gap between low-level pointer manipulation and high-level pipeline composition.

The most common place you will encounter this problem is when designing function return types.

Suppose we are writing a financial application. We have a massive ledger of transactions, sorted by date. We want to write a function GetTransactionsForDate() that returns all transactions for a specific day.

What type of data should we return here?

Option 1: Return by Value (The Performance Killer)

This is the "safe" approach:

1std::vector<Transaction> GetTransactionsForDate(Date d) {
2  std::vector<Transaction> result;
3  // ... copy matching transactions ...
4  return result;
5}

However, from a performance perspective, it is a disaster. We are allocating heap memory and copying data just to read it. If the day has 10,000 transactions, we are triggering a massive allocation and 10,000 copy operations. This violates our core principle: don't pay for what you don't use.

Option 2: Return Iterators (The Usability Killer)

This is fast. It returns two small iterators (likely 16 bytes total). No memory is allocated:

1std::pair<Iterator, Iterator> GetTransactionsForDate(Date d) {
2  // Find the range in O(log N)
3  auto start = std::lower_bound(...);
4  auto end = std::upper_bound(...);
5  return {start, end};
6}

But the usability is poor. The caller asked for a list of transactions, and they have received a std::pair. Once they figure out what that pair represents, they then need to access .first and .second members. And even then, they still don't have a cohesive list - they have two iterators. They cannot directly use it in a range-based for loop, and they cannot easily do further processing on it, such as pipe it into std::views::transform().

Option 3: std::ranges::subrange

This is the modern solution. A subrange is mechanically identical to the pair (it holds two iterators), but it exposes the begin() and end() interface required by the ranges library.

1#include <vector>
2#include <ranges>
3#include <algorithm>
4
5struct Transaction {
6  int id;
7  int date; // Simple integer date for example
8};
9
10using Iterator = std::vector<Transaction>::iterator;
11
12// Return a View
13std::ranges::subrange<Iterator> GetTransactionsForDate(
14  std::vector<Transaction>& ledger, int targetDate
15) {
16  auto start = std::ranges::lower_bound(
17    ledger, targetDate, {}, &Transaction::date
18  );
19  auto end = std::ranges::upper_bound(
20    ledger, targetDate, {}, &Transaction::date
21  );
22
23  // Wrap the iterators in a subrange
24  return std::ranges::subrange(start, end); 
25}
26
27void Process(std::vector<Transaction>& ledger) {
28  // Now it works in a loop
29  for (const auto& t : GetTransactionsForDate(ledger, 2026)) {
30    // ...
31  }
32}

By returning a subrange, we get the best of both worlds: the performance of raw pointers (zero-copy) and the usability of a container (iterable, pipeable).

The real power of subrange unlocks when we want to inject custom logic into a view pipeline.

Standard views like filter and transform are useful, but sometimes you need algorithmic logic that doesn't fit those patterns. For example, maybe you need to perform a binary search to find a starting point, and then take the next 10 items.

If your custom logic returns iterators, you can't chain it. If it returns a subrange, you can.

Let's look at how we can compose our GetTransactionsForDate() function with other views.

1void AnalyzeDay(std::vector<Transaction>& ledger, int date) {
2  // 1. Get the subrange (Lazy)
3  auto transactions = GetTransactionsForDate(ledger, date);
4
5  // 2. Pipe it immediately
6  auto ids = transactions
7    | std::views::transform(&Transaction::id) // Extract IDs
8    | std::views::take(5);                    // Only first 5
9
10  for (int id : ids) {
11    std::cout << id << "\n";
12  }
13}

Because subrange satisfies the view concept, it can be the source of a pipeline.

1. GetTransactionsForDate() does a binary search and finds two iterators. It wraps them in a std::ranges::subrange
2. transform() wraps that view.
3. take(5) wraps the transform view.
4. The loop pulls data through the chain.

We have composed a custom $O(log N)$ search algorithm with standard stream processing tools, with zero overhead.

C++ programmers frequently have to interact with C libraries or operating system APIs. These classic APIs almost always receive their collections as a pair of arguments: a pointer and a size.

1// Legacy C API
2void get_audio_buffer(float** buffer_out, size_t* size_out);

If we want to process this buffer using modern C++ tools, we need to convert it into a range.

We have two tools for this job: std::span and std::ranges::subrange. They are very similar, but they have distinct roles.

Using std::span

The std::span view is designed specifically for contiguous memory. It essentially holds a T* and a size_t. It is the preferred type for function parameters when you just want to receive "an array of things" and don't really care if it's a C-style array, a std::array, a std::vector, or any other contiguous container.

1void ProcessArray(std::span<int> data) {
2  // Works with any contiguous memory of ints
3  for (int i : data) {
4    // ...
5  }
6}
7
8int main() {
9  int c_array[5] = {1, 2, 3, 4, 5};
10  std::vector<int> vec = {1, 2, 3};
11  std::array<int, 3> arr = {1, 2, 3};
12
13  // std::span automatically wraps all of these
14  // No copying happens. It just grabs the pointer and size.
15  ProcessArray(c_array);
16  ProcessArray(vec);
17  ProcessArray(arr);
18}

Using std::ranges::subrange

Meanwhile, std::ranges::subrange is the generalized version. It holds an Iterator and a Sentinel. It works for contiguous memory, but it also works for linked lists, trees, filtered views, or any other weird iterator you can imagine.

When wrapping a raw C-array, std::span is often the better choice because it is simpler and more explicit about the contiguous nature of what it is viewing. However, subrange is more powerful if we are building a generic template that needs to handle any kind of range.

Here is how we wrap a raw pointer and size using subrange:

1#include <ranges>
2#include <iostream>
3#include <algorithm>
4
5void ProcessAudioBuffer(float* buffer, size_t size) {
6  // Convert Pointer+Size -> Pointer+Pointer
7  float* end = buffer + size;
8
9  // Create the view
10  auto range = std::ranges::subrange(buffer, end); 
11
12  // Now we can use algorithms
13  // Clip audio samples that are too loud
14  std::ranges::for_each(range, [](float& sample) {
15    sample = std::clamp(sample, -1.0f, 1.0f);
16  });
17}

By doing this immediately at the API boundary, we stop doing unsafe pointer arithmetic like buffer[i] and start using checked, safe iterators and algorithms.

Views are non-owning. They are references. This creates a risk: what if the thing we are viewing is destroyed while we are still looking at it?

1auto GetBadView() {
2  std::vector<int> temp{1, 2, 3};
3
4  // DANGER: Returning a view into a local variable
5  // 'temp' will be destroyed when this function returns
6  return std::ranges::subrange(temp);
7}

Historically, doing something like this would be a segmentation fault waiting to happen. The returned object would contain pointers to stack memory that no longer exists.

C++20 introduces the concept of borrowed ranges. The compiler understands that std::vector owns its memory. If we try to construct a subrange from an rvalue (a temporary) vector, the compiler knows that the resulting iterators will dangle.

The standard library algorithms protect us against this. If we try to call std::ranges::find() on a temporary vector, it won't return an iterator (which would dangle). It returns a special opaque type called std::ranges::dangling.

This allows the compiler to detect our misuse of this return value, and notify us with an error:

1std::vector<int> GetTempVector() { return {1, 2, 3}; }
2
3void Oops() {
4  // 'it' is not an iterator. It is of type std::ranges::dangling
5  auto it = std::ranges::find(GetTempVector(), 2);
6
7  // Compile Error: 'dangling' does not support dereference (*)
8  std::cout << *it; 
9}

The std::ranges::subrange type can also participate in this safety system:

1auto GetSafeView() {
2  // String views are "borrowed ranges" (safe to copy)
3  std::string_view sv = "Hello World";
4  return std::ranges::subrange(sv); // OK 
5}
6
7auto GetUnsafeView() {
8  // Vectors are NOT borrowed ranges as iterators die
9  // with the container
10  return std::ranges::subrange(std::vector<int>{1, 2, 3}); 
11}

However, if we manually construct a subrange from raw pointers (as in the C-API example), the compiler assumes we know what we are doing.

One of the most important features of subrange is that it is a chameleon. It changes its capabilities based on the iterators we give it.

If we construct a subrange from std::vector iterators, the subrange is random access. We can call .size() on it, and we can use the [] operator to access elements by index.

1std::vector<int> vec{10, 20, 30, 40, 50};
2
3// Create a subrange from vector iterators
4auto rng = std::ranges::subrange(vec.begin(), vec.end());
5
6// Because the underlying iterators are powerful, 
7// the subrange exposes powerful features:
8std::cout << rng.size(); // Prints 5
9std::cout << rng[2];     // Prints 30

If we construct a subrange from std::forward_list (singly linked list) iterators, the subrange loses these abilities.

It effectively "downgrades" itself. It will not have a [] operator and it won't have a .size() method by default.

This is all implemented in a type-safe way, so any misuse is flagged at compile time:

1std::forward_list<int> list{10, 20, 30};
2
3// Create a subrange from list iterators
4auto rng = std::ranges::subrange(list.begin(), list.end());
5
6// The compiler removes features that would be slow
7// Compile Error - No [] operator)
8std::cout << rng[2]; 
9
10// Compile Error - No .size() method
11std::cout << rng.size();

We can still get the size of a linked list, or a subrange based on a linked list, using std::distance():

1auto size = std::distance(rng.begin(), rng.end());

A subrange derived from a linked list does not provide this as the .size() method as it would be an $O(n)$ operation - we need to walk the list to get its size.

The ranges library philosophy is that properties like .size() should generally be $O(1)$. The design dislikes providing a slow function under an API that makes it seem like it would be fast.

Forcing the Size

However, sometimes we know the size. In the following networking example, we might receive a packet header that includes some metadata, such as the size of the packet. So even if we are using a forward iterator to read the stream, we know the count.

We can manually construct a sized subrange to include this information:

1#include <ranges>
2#include <forward_list>
3#include <iostream>
4
5void ProcessStream(
6  std::forward_list<char>& stream, int known_count
7) {
8  // Standard construction - No .size() method
9  // because forward_list is not random access
10  auto unsized = std::ranges::subrange(
11    stream.begin(), stream.end()
12  );
13  // unsized.size(); // <--- Compile Error 
14
15  // Sized construction:
16  // We explicitly tell it the size is 'known_count'
17  auto sized = std::ranges::subrange(
18    stream.begin(), stream.end(),
19    known_count 
20  );
21
22  // Now we can query size in O(1)
23  std::cout << "Bytes: " << sized.size();
24}

If we know the size, adding it to our subrange is generally worthwhile, even if we don't directly use it.

Behind the scenes, many algorithms can be implemented in a more optimal way if they know the size of the input they're working with. By including this metadata into the subrange, we can unlock those optimizations.

In this lesson, we added the subrange to our toolkit. It is the glue that binds the old world of iterators to the new world of views. Here are the key points:

1. The Adapter: std::ranges::subrange turns any pair of iterators (or iterator + sentinel) into a full-fledged view.
2. API Design: We learned that returning a subrange is superior to returning a pair of iterators (usability) or an entire container (performance).
3. Composition: We saw how subrange allows custom algorithms to act as the source for pipeable views.
4. Raw Memory: We compared subrange to std::span. Use span for contiguous buffers; use subrange for everything else.
5. Capability Propagation: We learned that subrange inherits the power of its underlying iterators, but we can manually override properties (like size) when we have external information.