Ranges library (C++20)

The ranges library is an extension and generalization of the algorithms and iterator libraries that makes them more powerful by making them composable and less error-prone.

The library creates and manipulates range views, lightweight objects that indirectly represent iterable sequences (ranges). Ranges are an abstraction on top of.

• [begin, end) iterator pairs, e.g. ranges made by implicit conversion from containers. All algorithms that take iterator pairs now have overloads that accept ranges (e.g ranges::sort)
• [start, size) counted sequences, e.g. range returned by views::counted
• [start, predicate) conditionally-terminated sequences, e.g. range returned by views::take_while
• [start..) unbounded sequences, e.g. range returned by views::iota

The ranges library includes range algorithms, which are applied to ranges eagerly, and range adaptors, which are applied to views lazily. Adaptors can be composed into pipelines, so that their actions take place as the view is iterated.

namespace std {
    namespace views = ranges::views;
}

The namespace alias std::views is provided as a shorthand for std::ranges::views.

Range factories

Range adaptors

Some range adaptors wrap their elements or function objects with the copyable wrapper.

Range adaptor objects

Range adaptor objects are customization point objects that accept viewable_range as their first arguments and return a view. Some range adaptor objects are unary, i.e. they take one viewable_range as their only argument. Other range adaptor objects take a viewable_range and other trailing arguments.

If a range adaptor object takes more than one argument, it also supports partial application: let.

• a be such a range adaptor object, and
• args... be arguments (generally suitable for trailing arguments),

expression a(args...) has following properties:

• it is valid if and only if for every argument e in args... such that E is decltype((e)), std::is_constructible_v<std::decay_t<E>, E> is true,
• when the call is valid, its result object stores a subobject of type std::decay_t<E> direct-non-list-initialized with std::forward<E>(e), for every argument e in args... (in other words, range adaptor objects bind arguments by value), and
• the result object is a range adaptor closure object.

Like other customization point objects, let.

• a be an object of the cv-unqualified version of the type of any range adaptor objects,
• args... be any group of arguments that satisfies the constraints of the operator() of the type of a,

calls to.

• a(args...),
• std::as_const(a)(args...),
• std::move(a)(args...), and
• std::move(std::as_const(a))(args...)

are all equivalent.

The result object of each of these expressions is either a view object or a range adaptor closure object.

Notes: operator() is unsupported for volatile-qualified or const-volatile-qualified version of range adaptor object types. Arrays and functions are converted to pointers while binding.

Range adaptor closure objects

Range adaptor closure objects are objects whose type is the same as one of the following objects (ignoring cv-qualification):

• unary range adaptor objects,
• the results of binding trailing arguments by range adaptor objects, and
• the results of chaining two range adaptor closure objects by operator|.

Range adaptor closure objects take one viewable_range as its only argument and return a view. They are callable via the pipe operator: if C is a range adaptor closure object and R is a viewable_range, these two expressions are equivalent (both well-formed or ill-formed):

C(R)
R | C

This call forwards the bound arguments (if any) to the associated range adaptor object. The bound arguments (if any) are identically treated as lvalue or rvalue and cv-qualified to C.

Two range adaptor closure objects can be chained by operator| to produce another range adaptor closure object: if C and D are range adaptor closure objects, then C | D is also a range adaptor closure object if it is valid.

The bound arguments of C | D is determined as follows:

• there is a subobject in the result object of the same type (cv-qualification discarded) for every subobject in both operands that is a bound argument,
• such a bound argument is direct-non-list-initialized with the source subobject in its containing operand, where the source is identically treated as lvalue or rvalue and cv-qualified to the operand,
• the result is valid if and only if the initialization of all bound arguments are valid.

The effect and validity of the operator() of the result is determined as follows: given a viewable_range R, these two expressions are equivalent (both well-formed or ill-formed):

R | C | D // (R | C) | D
R | (C | D)

Notes: operator() is unsupported for volatile-qualified or const-volatile-qualified version of range adaptor object closure types.

Helper concepts

Following exposition-only concepts are used for several types, but they are not parts of the interface of standard library.

template<class R>
  concept __SimpleView =                         // exposition only
    ranges::view<R> && ranges::range<const R> &&
    std::same_as<std::ranges::iterator_t<R>, std::ranges::iterator_t<const R>> &&
    std::same_as<std::ranges::sentinel_t<R>, std::ranges::sentinel_t<const R>>;

Notes

Feature testing macro: __cpp_lib_ranges.

Example

#include <ranges>
#include <iostream>
 
int main()
{
    auto const ints = {0,1,2,3,4,5};
    auto even = [](int i) { return 0 == i % 2; };
    auto square = [](int i) { return i * i; };
 
    // "pipe" syntax of composing the views:
    for (int i : ints | std::views::filter(even) | std::views::transform(square)) {
        std::cout << i << ' ';
    }
 
    std::cout << '\n';
 
    // a traditional "functional" composing syntax:
    for (int i : std::views::transform(std::views::filter(ints, even), square)) {
        std::cout << i << ' ';
    }
}

0 4 16
0 4 16

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.