Ranges library (C++20)

The ranges library provides components for dealing with ranges of elements, including a variety of view adaptors.

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 takes one viewable_range as its only argument. Other range adaptor objects takes 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.

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.