# Range adaptors and pipelines

> A range adaptor turns one view into another lazily, and the pipe operator only rearranges the call. What each adaptor keeps of its input's iterator category, and what it caches, decides where a pipeline compiles, how often your functions run, and when it quietly misbehaves.

- **Source:** C++ Atlas (https://cppatlas.com/topics/range-adaptors-and-pipelines)
- **Track:** Iterators, algorithms and ranges
- **Estimated reading time:** 13 minutes
- **ISO C++ clauses:** [range.adaptor.object] (https://eel.is/c++draft/range.adaptor.object), [range.range] (https://eel.is/c++draft/range.range), [range.filter] (https://eel.is/c++draft/range.filter), [range.filter.iterator] (https://eel.is/c++draft/range.filter.iterator), [range.transform] (https://eel.is/c++draft/range.transform), [range.take] (https://eel.is/c++draft/range.take), [range.split] (https://eel.is/c++draft/range.split), [range.lazy.split] (https://eel.is/c++draft/range.lazy.split), [range.join] (https://eel.is/c++draft/range.join), [range.zip] (https://eel.is/c++draft/range.zip), [range.enumerate] (https://eel.is/c++draft/range.enumerate), [range.chunk] (https://eel.is/c++draft/range.chunk), [range.slide] (https://eel.is/c++draft/range.slide), [range.stride] (https://eel.is/c++draft/range.stride), [range.cartesian] (https://eel.is/c++draft/range.cartesian)
- **cppreference links:** [Ranges library (range adaptors)](https://en.cppreference.com/w/cpp/ranges), [std::ranges::range_adaptor_closure](https://en.cppreference.com/w/cpp/ranges/range_adaptor_closure), [std::ranges::filter_view](https://en.cppreference.com/w/cpp/ranges/filter_view), [std::ranges::transform_view](https://en.cppreference.com/w/cpp/ranges/transform_view), [std::ranges::take_view](https://en.cppreference.com/w/cpp/ranges/take_view), [std::ranges::zip_view](https://en.cppreference.com/w/cpp/ranges/zip_view)
- **Prerequisites:** ranges-and-views, iterator-categories-and-concepts, lambdas

## The one idea

A pipeline such as `xs | views::filter(p) | views::transform(f)` does no work when you write it. It builds a nested type, here a `transform_view` of a `filter_view` of a `ref_view` of `xs`, and every element is computed on demand when someone dereferences and increments its iterators. The pipe is only notation. `r | views::filter(p)` means exactly `views::filter(r, p)`.

Two consequences follow from laziness, and most surprises in this area come from one or the other. First, each layer can only offer what its input offers, and often less: an adaptor that cannot jump ahead in constant time turns a random-access range into a bidirectional one. Second, because work happens at iteration time, a function in the pipeline runs whenever an iterator is dereferenced, which may be more than once per element, and a view may remember results from an earlier pass.

> **Mental model.** A pipeline is a recipe, not a container. Each adaptor wraps the iterator of the layer below it, so the category, the cost of dereferencing, and any cached state are those of the wrapped iterators, layer by layer.

What a view is, and how `views::all` chooses between `ref_view` and `owning_view`, is covered in the ranges-and-views topic. This topic is about the adaptors themselves.

## Adaptor objects, closures, and how the pipe composes

Every name in `std::views` is a function object, not a function. [range.adaptor.object] gives them two shapes.

A **range adaptor closure object** takes exactly one range. `views::reverse`, `views::join`, `views::enumerate`, `views::as_const`, `views::as_rvalue` and `views::common` are closures already. For a closure `C`, the expressions `C(r)` and `r | C` are equivalent.

A **range adaptor object** takes a range plus extra arguments, like `views::filter(r, p)` or `views::take(r, 3)`. Calling it with only the extra arguments returns a closure that stores them, so `views::filter(p)` is a closure, and `r | views::filter(p)` calls it with `r` in front.

Two closures can be piped together without a range. `C | D` produces a new closure such that `r | (C | D)` is equivalent to `r | C | D`, which is `D(C(r))`. Because the pipe is left-associative, the order you read is the order data flows.

```cpp
#include <ranges>
#include <vector>
#include <cstdio>
namespace views = std::views;

int main() {
  auto even_squares = views::filter([](int x) { return x % 2 == 0; })
                    | views::transform([](int x) { return x * x; });
  std::vector<int> xs{1, 2, 3, 4};
  for (int x : xs | even_squares) std::printf("%d ", x);  // prints 4 16
}
```

Not everything in `std::views` is pipeable. `views::zip`, `views::cartesian_product` and the C++26 `views::concat` take any number of ranges, so they are customization point objects rather than adaptor objects. `views::zip(ys)` is a perfectly good one-range zip view, which means `xs | views::zip(ys)` tries to pipe `xs` into a view and fails to compile. Write `views::zip(xs, ys)`.

## The adaptors worth knowing

The C++20 core covers selection and reshaping. `filter` keeps elements satisfying a predicate. `transform` applies a function at dereference time. `take` and `drop` keep or skip a count, and `take_while` and `drop_while` do the same by predicate. `join` flattens a range of ranges. `split` breaks a range into subranges at a delimiter. `reverse`, `keys`, `values` and `elements` round out the set.

C++23 added the adaptors people used to borrow from range-v3. `zip` walks several ranges in lockstep and yields tuples of references, stopping at the shortest. `enumerate` pairs each element with its index. `chunk(n)` cuts a range into non-overlapping pieces of `n`, the last possibly shorter, and `slide(n)` yields every overlapping window of `n`. `stride(n)` keeps every `n`th element. `cartesian_product` yields every combination of elements from several ranges. `as_rvalue` makes elements rvalues so a consumer can move from them, and `as_const` makes them const.

`split` and `lazy_split` deserve a note. They swapped names by a defect report against C++20 (P2210). `split` now needs a forward range, and each piece it yields is a `subrange` of the underlying iterators, so splitting a `string_view` gives pieces you can convert to `string_view`. `lazy_split` also works on input ranges, such as a stream, but each piece is a lazily searched range that is never even bidirectional.

```cpp
#include <ranges>
#include <string_view>
using namespace std::literals;

void pieces() {
  for (auto w : "a,b,,c"sv | std::views::split(','))
    std::string_view s(w);                     // OK: w is a contiguous subrange
  // for (auto w : "a b"sv | std::views::lazy_split(' '))
  //   std::string_view s(w);                  // error: no such conversion
}
```

## What each adaptor keeps and loses

An adaptor's iterator can only be as strong as the operations it can implement in constant time. Expect these from the common adaptors:

| Adaptor | Best category | Sized | Notes |
| --- | --- | --- | --- |
| `filter` | bidirectional | never | common if the input is common |
| `transform` | random access | if input is | never contiguous |
| `take` | input's category | if input is | common only if input is sized and random access |
| `drop` | input's category | if input is | caches `begin()` unless random access and sized |
| `join` | bidirectional | never | needs inner ranges bidirectional and common |
| `zip` | weakest of inputs | if all are | size is the minimum |
| `split` | forward | never | pieces keep the input's category |
| `chunk`, `stride` | input's category | if input is | `chunk` on an input range is input only |
| `slide` | input's category | if input is | needs a forward range |

`filter` cannot know how far apart two matching elements are, so it can never be random access or sized, and `ranges::size` does not compile on it. `transform` loses contiguity because the elements it yields are computed, not stored. `take` is the subtle one: on a `std::list`, it knows its size but cannot compute its end iterator in constant time, so it pairs a `counted_iterator` with `default_sentinel` and stops being a common range.

```cpp
#include <list>
#include <ranges>
#include <vector>

std::list<int> l{1, 2, 3};
std::vector<int> v{1, 2, 3};
static_assert(std::ranges::sized_range<decltype(l | std::views::take(2))>);
static_assert(!std::ranges::common_range<decltype(l | std::views::take(2))>);
static_assert(std::ranges::common_range<decltype(v | std::views::take(2))>);
```

Some adaptors do not wrap at all when they can return a cheaper type. `take` and `drop` applied to a `std::span`, a `std::basic_string_view`, a sized `iota_view` or a suitable `subrange` return that same kind of type, so `span | views::take(2)` is a `std::span`. `views::reverse` applied to a `reverse_view` unwraps it instead of stacking another layer.

## Functions run on every dereference

`transform` calls its function inside `operator*`. It does not store the result. `filter` must dereference elements to test them. Put `transform` before `filter`, and each element that passes is computed once to be tested and again when the loop reads it.

```cpp
#include <ranges>
#include <vector>
#include <cstdio>

int main() {
  int calls = 0;
  std::vector<int> xs{1, 2, 3, 4};
  auto r = xs | std::views::transform([&](int x) { ++calls; return x * x; })
              | std::views::filter([](int x) { return x % 2 == 0; });
  for (int x : r) (void)x;
  std::printf("%d\n", calls);  // prints 6: four tests plus two reads
}
```

For a cheap function this does not matter. For an expensive or side-effecting one, filter first when you can, or materialize the transformed values with `std::ranges::to`. A function in a view should be regular in the sense of the `regular_invocable` concept: same input, same output, no observable side effects. A counter, as above, is fine for measuring and wrong for logic.

> **Pitfall.** Writing through a `filter_view` is allowed, but if the new value no longer satisfies the predicate, the behaviour is undefined. A loop like `for (int& x : v | views::filter(is_even)) ++x;` breaks the view's invariant for every element it touches.

> **Standardese.** [range.filter.iterator] says that modifying the element a `filter_view` iterator denotes is permitted, but results in undefined behavior if the resulting value does not satisfy the filter predicate. The view never re-tests a position it has already accepted, so nothing diagnoses the violation.

## Caching, and why some views cannot be const

The `range` concept requires `ranges::begin` and `ranges::end` to run in amortized constant time ([range.range]). `filter_view` has to search for its first matching element, which is linear. To meet the requirement it searches once and caches the iterator inside the view. `drop_view` caches unless its input is random access and sized, `reverse_view` caches when its input is not a common range, and `split_view` and `chunk_by_view` always cache.

Caching mutates the view, so those `begin()` members are not `const`. A `const filter_view` is not a range at all, and a function template that takes its argument as `const auto&` cannot iterate it.

```cpp
#include <ranges>
#include <vector>
#include <cstdio>

void print(const auto& r) { for (int x : r) std::printf("%d ", x); }

void demo(std::vector<int>& xs) {
  print(xs | std::views::transform([](int x) { return x + 1; }));  // OK
  // print(xs | std::views::filter([](int x) { return x > 1; }));
  // error: filter_view::begin() is not const
}
```

Take views by forwarding reference, `auto&&`, or by value, since views are cheap to copy or move. The cache also outlives changes to the underlying data. If you iterate a filter view, then change the first elements of the vector so that an earlier element would now match, the next iteration still starts from the cached position. Treat a cached view as single-use when its underlying data changes; recreate it rather than reuse it.

## Writing your own adaptor

C++23 added `std::ranges::range_adaptor_closure<D>`. Derive from it using the curiously recurring pattern, give your type a call operator that takes a range, and your object gains the pipe: `r | yours` calls it, and `yours | other` composes with any standard closure. The type must have exactly one such base and must not itself be a range.

```cpp
#include <ranges>
#include <vector>
#include <cstdio>

struct evens_fn : std::ranges::range_adaptor_closure<evens_fn> {
  template <std::ranges::viewable_range R>
  constexpr auto operator()(R&& r) const {
    return std::forward<R>(r) | std::views::filter([](int x) { return x % 2 == 0; });
  }
};
inline constexpr evens_fn evens;

int main() {
  std::vector<int> xs{1, 2, 3, 4, 5, 6};
  auto pipeline = evens | std::views::transform([](int x) { return x * 10; })
                | std::views::take(2);
  for (int x : xs | pipeline) std::printf("%d ", x);  // prints 20 40
}
```

For an adaptor that takes arguments, store them as members of the closure, as `evens_fn` could store a divisor, or produce the closure with `std::bind_back` over an adaptor object. In C++20 there was no portable way to do this; libraries relied on each implementation's internal base class.

## What to remember

- `r | A(args)` is `A(r, args)`, and `r | (C | D)` is `D(C(r))`; the pipe adds nothing but syntax.
- `zip`, `cartesian_product` and C++26 `concat` are not adaptor objects; call them with all their ranges.
- `filter` is at most bidirectional and never sized; `transform` is never contiguous; `take` on a non-random-access range is not common.
- `take` and `drop` return a `span`, `string_view` or `iota_view` when given one, instead of wrapping it.
- `split` needs a forward range and yields subranges; `lazy_split` accepts input ranges but its pieces are weak.
- `transform` before `filter` calls the function twice for every element that passes.
- Writing a value through a `filter_view` that fails the predicate is undefined behaviour.
- Views that cache `begin()`, such as `filter`, `split`, and `drop` over a non-random-access input, cannot be iterated as const; pass views by `auto&&` or by value.
- C++23 `range_adaptor_closure` lets your own function objects join a pipeline.

## Concept Map Outline

- **Range adaptors and pipelines:** Lazy views built from adaptor objects; the pipe only rearranges the call.
  - **Adaptor objects:** Every views:: name is a function object, specified in [range.adaptor.object].
    - **Closure objects:** Take one range; C(r) and r | C are equivalent, as with views::reverse or views::join.
    - **Partial application:** views::filter(p) stores p and returns a closure; r | views::filter(p) is views::filter(r, p).
    - **Composing closures:** C | D is a closure, and r | (C | D) means D(C(r)), the same as r | C | D.
    - **Not pipeable:** zip, cartesian_product and concat take many ranges; xs | views::zip(ys) does not compile.
  - **Adaptors to know:** C++20 gave selection and reshaping; C++23 added the range-v3 favourites.
    - **C++20 core:** filter, transform, take, drop, take_while, drop_while, join, split, reverse, keys, values.
    - **C++23 additions:** zip, enumerate, chunk, slide, stride, cartesian_product, as_rvalue, as_const.
    - **split vs lazy_split:** split needs a forward range and yields subranges; lazy_split takes input ranges, weak pieces.
  - **Category kept or lost:** An adaptor offers only what it can do in constant time on its input.
    - **filter:** At most bidirectional and never sized, since gaps between matches are unknown.
    - **transform:** Keeps random access and size but is never contiguous: values are computed.
    - **take on a list:** Sized but not common: counted_iterator paired with default_sentinel.
    - **Cheaper return types:** take and drop on span, string_view or sized iota_view return that same kind of type.
  - **Evaluation surprises:** Work happens at dereference time, every time.
    - **transform then filter:** The function runs once to test and again to read every element that passes.
    - **Writing through filter:** Undefined behavior if the new value fails the predicate, per [range.filter.iterator].
    - **Regular functions:** transform and filter require regular_invocable: same input, same output.
  - **Caching:** begin() must be amortized O(1), so some views remember their first position.
    - **Who caches:** filter, split, chunk_by, drop on non-random-access inputs, reverse on non-common inputs.
    - **No const iteration:** Caching begin() is non-const, so a const filter_view is not a range.
    - **Stale cache:** Changing underlying data after a pass does not move the cached begin; recreate the view.
  - **Custom adaptors:** C++23 range_adaptor_closure gives your own function object the pipe.
    - **CRTP base:** Derive D from range_adaptor_closure<D> exactly once; D must not itself be a range.
    - **Arguments:** Store them as members, or build the closure with std::bind_back over an adaptor.

## Standardese Quiz Questions

### Question 1 [warmup] ([range.adaptor.object])

What does this program print?

```cpp
#include <cstdio>
#include <ranges>
#include <vector>

int main() {
  auto p = std::views::transform([](int x) { return x * 10; })
         | std::views::filter([](int x) { return x > 15; });
  std::vector<int> xs{1, 2, 3};
  for (int x : xs | p) std::printf("%d ", x);
}
```

A. `10 20 30 `
B. `2 3 `
C. `20 30 `
D. Nothing: a closure cannot be composed before it is applied to a range

**Answer (C):** `20 30 `

**Why:** Piping two closures together yields a closure `p` such that `xs | p` is `xs | transform(...) | filter(...)`, so data flows left to right. The transform runs first, giving 10, 20 and 30, and the filter keeps the values above 15. The answer `2 3 ` would be right if the filter were applied before the transform, which is the order a reader of nested function calls might expect.

### Question 2 [warmup] ([range.zip], [range.adaptor.object])

In C++23, what happens with the marked line?

```cpp
#include <ranges>
#include <vector>

int main() {
  std::vector<int> xs{1, 2, 3};
  std::vector<int> ys{4, 5, 6};
  auto z = xs | std::views::zip(ys);  // this line
  (void)z;
}
```

A. It produces a view of the tuples (1, 4), (2, 5) and (3, 6)
B. It is ill-formed: `views::zip(ys)` is already a one-range zip view, and a range cannot be piped into a view
C. It produces a view of the tuples (4, 1), (5, 2) and (6, 3)
D. It compiles, but iterating it is undefined behavior

**Answer (B):** It is ill-formed: `views::zip(ys)` is already a one-range zip view, and a range cannot be piped into a view

**Why:** `views::zip` is a customization point object that takes any number of ranges, not a range adaptor object with partial application. `views::zip(ys)` is a complete `zip_view` over one range, and there is no `operator|` taking a vector on the left and a view on the right, so the line does not compile. Write `views::zip(xs, ys)` instead.

### Question 3 [warmup] ([range.transform], [range.filter.iterator])

What does this program print?

```cpp
#include <cstdio>
#include <ranges>
#include <vector>

int main() {
  int calls = 0;
  std::vector<int> xs{1, 2, 3, 4};
  auto r = xs | std::views::transform([&](int x) { ++calls; return x * x; })
              | std::views::filter([](int x) { return x % 2 == 0; });
  for (int x : r) (void)x;
  std::printf("%d\n", calls);
}
```

A. `4`
B. `2`
C. `8`
D. `6`

**Answer (D):** `6`

**Why:** The filter dereferences each of the four transformed elements to test it, which calls the function four times. The range-based for then dereferences the filter iterator at the two elements that passed, 4 and 16, and a transform iterator recomputes its value on every dereference, adding two more calls. `4` is the tempting answer if you assume the transform caches its result; it does not.

### Question 4 [tricky] ([range.take.view], [iterators.counted])

Which of these static assertions fails?

```cpp
#include <list>
#include <ranges>

std::list<int> l{1, 2, 3};
using T = decltype(l | std::views::take(2));

static_assert(std::ranges::bidirectional_range<T>);  // A
static_assert(std::ranges::sized_range<T>);          // B
static_assert(std::ranges::common_range<T>);         // C
static_assert(std::ranges::view<T>);                 // D
```

A. A: `take` on a list is only a forward range
B. B: `take` never knows its size
C. C: the iterator and sentinel types differ
D. None of them fails

**Answer (C):** C: the iterator and sentinel types differ

**Why:** `take_view` is common only when its input is both sized and random access, because only then can it compute its end iterator as `begin() + n`. For a sized list it instead uses a `counted_iterator` as the iterator and `default_sentinel_t` as the sentinel, so the view is sized and bidirectional but not common. Assertion A holds because `take` preserves the input's category, and B holds because a list is sized. Assertion C therefore fails and the program does not compile.

### Question 5 [tricky] ([range.filter.view], [range.range])

Which call to `print` is ill-formed?

```cpp
#include <cstdio>
#include <ranges>
#include <vector>

void print(const auto& r) { for (int x : r) std::printf("%d ", x); }

int main() {
  std::vector<int> xs{1, 2, 3};
  print(xs | std::views::transform([](int x) { return x + 1; }));  // 1
  print(xs | std::views::filter([](int x) { return x > 1; }));     // 2
  print(xs | std::views::take(2));                                 // 3
}
```

A. Only call 2
B. Calls 1 and 2, because both store a lambda
C. None of them; all three views are const-iterable
D. All three, because a view must not be passed by const reference

**Answer (A):** Only call 2

**Why:** `filter_view::begin()` caches the first matching position to meet the amortized constant-time requirement of `range`, so it is a non-const member, a `const filter_view` is not a range, and call 2 is ill-formed. `transform_view` and `take_view` over a `ref_view` provide const `begin()` members, so calls 1 and 3 compile. Storing a lambda is not the problem; caching is.

### Question 6 [tricky] ([range.take.overview])

What is the type of `t`?

```cpp
#include <ranges>
#include <span>
#include <vector>

std::vector<int> v{1, 2, 3, 4};
std::span<int> s(v);
auto t = s | std::views::take(2);
```

A. `std::ranges::take_view<std::span<int>>`
B. `std::ranges::take_view<std::ranges::ref_view<std::span<int>>>`
C. `std::ranges::subrange<int*>`
D. `std::span<int>`

**Answer (D):** `std::span<int>`

**Why:** `views::take` is specified to return a cheaper type when it can: for a `std::span` it returns a `span` of the first `n` elements, and it does the same for `basic_string_view`, sized random-access `iota_view` and suitable `subrange` specializations. The `take_view` answers describe what you get for a general view. A span is itself a view, so it would never be wrapped in a `ref_view` either.

### Question 7 [standardese] ([range.filter.iterator])

What does the standard say about this program?

```cpp
#include <ranges>
#include <vector>

int main() {
  std::vector<int> v{2, 4, 6};
  for (int& x : v | std::views::filter([](int x) { return x % 2 == 0; }))
    ++x;
}
```

A. It is ill-formed: a `filter_view` yields const references
B. It is well-defined and leaves `v` as `{3, 5, 7}`
C. It has undefined behavior
D. The final contents of `v` are unspecified

**Answer (C):** It has undefined behavior

**Why:** [range.filter.iterator] permits modifying the element a `filter_view` iterator denotes, but the behavior is undefined if the new value does not satisfy the predicate. Each increment makes an even number odd. In practice you will likely observe `{3, 5, 7}`, which is why the second option is tempting, but the standard gives no such guarantee. The references are not const, so the code does compile.

### Question 8 [standardese] ([range.adaptor.object])

For range adaptor closure objects `C` and `D` and a viewable range `r`, what does [range.adaptor.object] make `r | (C | D)` equivalent to?

A. `C(D(r))`
B. `D(C(r))`
C. Either order; it is unspecified
D. Nothing: closures only combine with ranges

**Answer (B):** `D(C(r))`

**Why:** The standard defines `C | D` as a closure whose application to `r` is `D(C(r))`, which is the same as `r | C | D`. That is what makes a stored pipeline behave exactly like writing the stages out inline. `C(D(r))` is how function composition is often written in mathematics, which makes it the tempting choice.
