Ranges library (since C++20) - cppreference.com (original) (raw)

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)
• begin+ [​0​, size) – counted sequences, e.g. range returned by views::counted
• [begin, predicate) – conditionally-terminated sequences, e.g. range returned by views::take_while
• [begin, ..) – 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; } | | (since C++20) |

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

[edit] Range factories

[edit] Range adaptors

[edit] Range generators (since C++23)

[edit] Helper items

[edit] Range adaptor objects

See RangeAdaptorObject (RAO).

[edit] Range adaptor closure objects

See RangeAdaptorClosureObject (RACO).

[edit] Customization point objects

See Customization point object (CPO).

[edit] Assignable wrapper

Some range adaptors wrap their elements or function objects with the copyable-box(until C++23)movable-box(since C++23). The wrapper augments the wrapped object with assignability when needed.

[edit] Non-propagating cache

Some range adaptors are specified in terms of an exposition-only class template non-propagating-cache, which behaves almost like std::optional<T> (see description for differences).

[edit] Conditionally-const type

| template< bool Const, class T > using /*maybe-const*/ = std::conditional_t<Const, const T, T>; | | (exposition only*) | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------- |

The alias template /*maybe-const*/ is a shorthand used to conditionally apply a const qualifier to the type T.

[edit] Integer-like type helper templates

1. For an integer-like type T:

• If T is an integer type, /*make-signed-like-t*/<T> is std::make_signed_t<T>.
• Otherwise, /*make-signed-like-t*/<T> is a corresponding unspecified signed-integer-like type of the same width as T.

1. For an integer-like type T:

• If T is an integer type, /*make-unsigned-like-t*/<T> is std::make_unsigned_t<T>.
• Otherwise, /*make-signed-like-t*/<T> is a corresponding unspecified unsigned-integer-like type of the same width as T.

1. Explicitly converts t to /*make-unsigned-like-t*/<T>.

[edit] Customization point object helpers

Some range access customization point objects are specified in terms of these exposition-only function templates.

1. /*possibly-const-range*/ returns the const-qualified version of r if const R models input_range; otherwise, returns r without any casting.

2. /*as-const-pointer*/ returns a pointer to object of constant type.

[edit] Range adaptor helpers

Some range adaptors are specified in terms of these exposition-only function templates.

1. /*tuple-transform*/ returns a new tuple constructed by applying f to each element of tuple.

2. /*tuple-for-each*/ applies f to each element of tuple and returns nothing.

3. /*as-lvalue*/ forwards rvalue t as lvalue.

[edit] 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 /*simple-view*/ = ranges::view<R> && ranges::range<const R> && std::same_as<ranges::iterator_t<R>, ranges::iterator_t<const R>> && std::same_as<ranges::sentinel_t<R>, ranges::sentinel_t<const R>>;	(1)	(exposition only*)
template< class I > concept /*has-arrow*/ = ranges::input_iterator<I> && (std::is_pointer_v<I> |	requires(const I i) { i.operator->(); });	(2)
template< class T, class U > concept /*different-from*/ = <std::remove_cvref_t<T>, std::remove_cvref_t<U>>;	(3)	(exposition only*)
template< class R > concept /*range-with-movable-references*/ = ranges::input_range<R> && std::move_constructible<ranges::range_reference_t<R>> && std::move_constructible<ranges::range_rvalue_reference_t<R>>;	(4)	(exposition only*)
template< bool C, class... Views > concept /*all-random-access*/ = (ranges::random_access_range <std::conditional_t<C, const Views, Views>> && ...);	(5)	(exposition only*)
template< bool C, class... Views > concept /*all-bidirectional*/ = (ranges::bidirectional_range <std::conditional_t<C, const Views, Views>> && ...);	(6)	(exposition only*)
template< bool C, class... Views > concept /*all-forward*/ = (ranges::forward_range <std::conditional_t<C, const Views, Views>> && ...);	(7)	(exposition only*)

[edit] Notes

[edit] Example

#include #include   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; };   // the "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 << ' '; }

Output:

[edit] Defect reports

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

[edit] See also

• Iterator library
• Constrained algorithms