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.
)
begin + [0, size) – counted sequences, e.g. range returned by
[begin, predicate) – conditionally-terminated sequences, e.g. range returned by
[begin, ..) – unbounded sequences, e.g. range returned by
The ranges library includes
, which are applied to ranges eagerly, and
, which are applied to views lazily. Adaptors can be composed into pipelines, so that their actions take place as the view is iterated.
namespacestd{namespaceviews=ranges::views;}(since C++20)The namespace alias std::views is provided as a shorthand for std::ranges::views.
Defined in namespace std::ranges
Range access Defined in header
Defined in header
(C++20)
returns an iterator to the beginning of a range
(customization point object)
(C++20)
returns a sentinel indicating the end of a range
(customization point object)
(C++20)
returns an iterator to the beginning of a read-only range
(customization point object)
(C++20)
returns a sentinel indicating the end of a read-only range
(customization point object)
(C++20)
returns a reverse iterator to a range
(customization point object)
(C++20)
returns a reverse end iterator to a range
(customization point object)
(C++20)
returns a reverse iterator to a read-only range
(customization point object)
(C++20)
returns a reverse end iterator to a read-only range
(customization point object)
(C++26)
returns an integer equal to the reserve hint given by a range
(customization point object)
(C++20)
returns an integer equal to the size of a range
(customization point object)
(C++20)
returns a signed integer equal to the size of a range
(customization point object)
(C++20)
checks whether a range is empty
(customization point object)
(C++20)
obtains a pointer to the beginning of a contiguous range
(customization point object)
(C++20)
obtains a pointer to the beginning of a read-only contiguous range
(customization point object)
Range primitives Defined in header
ranges::iterator_tranges::const_iterator_tranges::sentinel_tranges::const_sentinel_t
(C++20)(C++23)(C++20)(C++23)
obtains iterator and sentinel types of a range
(alias template)
ranges::range_difference_tranges::range_size_tranges::range_value_t
(C++20)(C++20)(C++20)
obtains size, difference, and value types of a range
(alias template)
(C++20)(C++23)(C++20)(C++20)
obtains reference types of a range
(alias template)
Dangling iterator handling Defined in header
(C++20)
a placeholder type indicating that an iterator or a subrange should not be returned since it would be dangling
(class)
ranges::borrowed_iterator_tranges::borrowed_subrange_t
(C++20)
obtains iterator type or subrange type of a
(alias template)
Other utilities Defined in header
(C++23)
tags a range to be treated as a sequence rather than a single value
(class template)
Range concepts Defined in header
(C++20)
specifies that a type is a range, that is, it provides a begin iterator and an end sentinel
(concept)
(C++20)
specifies that a type is a
and iterators obtained from an expression of it can be safely returned without danger of dangling
(concept)
ranges::approximately_sized_range
(C++26)
specifies that a range can estimate its size in constant time
(concept)
(C++20)
specifies that a range knows its size in constant time
(concept)
(C++20)
specifies that a range is a view, that is, it has constant time copy/move/assignment
(concept)
(C++20)
specifies a range whose iterator type satisfies
(concept)
(C++20)
specifies a range whose iterator type satisfies
(concept)
(C++20)
specifies a range whose iterator type satisfies
(concept)
(C++20)
specifies a range whose iterator type satisfies
(concept)
(C++20)
specifies a range whose iterator type satisfies
(concept)
(C++20)
specifies a range whose iterator type satisfies
(concept)
(C++20)
specifies that a range has identical iterator and sentinel types
(concept)
(C++20)
specifies the requirements for a
to be safely convertible to a
(concept)
(C++23)
specifies that a range has read-only elements
(concept)
(C++26)
specifies that a range knows its size in constant time and allows random access to its elements
(exposition-only concept*)
Range conversions Defined in header
(C++23)
constructs a new non-view object from an input range
(function template)
Views Defined in header
(C++20)
helper class template for defining a
, using the
curiously recurring template pattern
(class template)
(C++20)
combines an iterator-sentinel pair into a
(class template)
Range factories
Defined in header
Defined in namespace std::ranges
ranges::empty_viewviews::empty
(C++20)
an empty
with no elements
(class template)(variable template)
ranges::single_viewviews::single
(C++20)
a
that contains a single element of a specified value
(class template)(customization point object)
(C++20)
a
consisting of a sequence generated by repeatedly incrementing an initial value
(class template)(customization point object)
(C++26)
a
that generates a sequence of increasing values from 0 up to n
(customization point object)
ranges::repeat_viewviews::repeat
(C++23)
a
consisting of a generated sequence by repeatedly producing the same value
(class template)(customization point object)
ranges::basic_istream_viewviews::istream
(C++20)
a
consisting of the elements obtained by successive application of operator>> on the associated input stream
(class template)(customization point object)
Range adaptors
Defined in header
Defined in namespace std::ranges
(C++23)
helper base class template for defining a range adaptor closure object
(class template)
(C++20)
a
that includes all elements of a
(alias template)(range adaptor object)
(C++20)
a
of the elements of some other
(class template)
(C++20)
a
with unique ownership of some
(class template)
ranges::as_rvalue_viewviews::as_rvalue
(C++23)
a
of a sequence that casts each element to an rvalue
(class template)(range adaptor object)
ranges::filter_viewviews::filter
(C++20)
a
that consists of the elements of a
that satisfy a predicate
(class template)(range adaptor object)
ranges::transform_viewviews::transform
(C++20)
a
of a sequence that applies a transformation function to each element
(class template)(range adaptor object)
(C++20)
a
consisting of the first N elements of another
(class template)(range adaptor object)
ranges::take_while_viewviews::take_while
(C++20)
a
consisting of the initial elements of another
, until the first element on which a predicate returns false
(class template)(range adaptor object)
(C++20)
a
consisting of elements of another
, skipping the first N elements
(class template)(range adaptor object)
ranges::drop_while_viewviews::drop_while
(C++20)
a
consisting of the elements of another
, skipping the initial subsequence of elements until the first element where the predicate returns false
(class template)(range adaptor object)
(C++20)
a
consisting of the sequence obtained from flattening a
of
(class template)(range adaptor object)
ranges::join_with_viewviews::join_with
(C++23)
a
consisting of the sequence obtained from flattening a view of ranges, with the delimiter in between elements
(class template)(range adaptor object)
ranges::lazy_split_viewviews::lazy_split
(C++20)
a
over the subranges obtained from splitting another
using a delimiter
(class template)(range adaptor object)
ranges::split_viewviews::split
(C++20)
a
over the subranges obtained from splitting another
using a delimiter
(class template)(range adaptor object)
ranges::concat_viewviews::concat
(C++26)
a
consisting of concatenation of the adapted views
(class template)(customization point object)
(C++20)
creates a subrange from an iterator and a count
(customization point object)
ranges::common_viewviews::common
(C++20)
converts a
into a
(class template)(range adaptor object)
ranges::reverse_viewviews::reverse
(C++20)
a
that iterates over the elements of another bidirectional view in reverse order
(class template)(range adaptor object)
ranges::as_const_viewviews::as_const
(C++23)
converts a
into a
(class template)(range adaptor object)
ranges::elements_viewviews::elements
(C++20)
takes a
consisting of
values and a number N and produces a
of Nth element of each tuple
(class template)(range adaptor object)
(C++20)
takes a
consisting of pair-like values and produces a
of the first elements of each pair
(class template)(range adaptor object)
ranges::values_viewviews::values
(C++20)
takes a
consisting of pair-like values and produces a
of the second elements of each pair
(class template)(range adaptor object)
ranges::enumerate_viewviews::enumerate
(C++23)
a
that maps each element of adapted sequence to a tuple of both the element's position and its value
(class template)(range adaptor object)
(C++23)
a
consisting of tuples of references to corresponding elements of the adapted views
(class template)(customization point object)
ranges::zip_transform_viewviews::zip_transform
(C++23)
a
consisting of results of application of a transformation function to corresponding elements of the adapted views
(class template)(customization point object)
ranges::adjacent_viewviews::adjacent
(C++23)
a
consisting of tuples of references to adjacent elements of the adapted view
(class template)(range adaptor object)
(C++23)
a
consisting of pairs of references to adjacent elements of the adapted view
(customization point object)
ranges::adjacent_transform_viewviews::adjacent_transform
(C++23)
a
consisting of results of application of a transformation function to adjacent elements of the adapted view
(class template)(range adaptor object)
(C++23)
a
consisting of results of application of a transformation function to each pair of adjacent elements of the adapted view
(customization point object)
ranges::chunk_viewviews::chunk
(C++23)
a range of
that are N-sized non-overlapping successive chunks of the elements of another
(class template)(range adaptor object)
ranges::slide_viewviews::slide
(C++23)
a
whose Mth element is a
over the Mth through (M + N - 1)th elements of another
(class template)(range adaptor object)
ranges::chunk_by_viewviews::chunk_by
(C++23)
splits the
into subranges between each pair of adjacent elements for which the given predicate returns false
(class template)(range adaptor object)
ranges::stride_viewviews::stride
(C++23)
a
consisting of elements of another
, advancing over N elements at a time
(class template)(range adaptor object)
ranges::cartesian_product_viewviews::cartesian_product
(C++23)
a
consisting of tuples of results calculated by the n-ary cartesian product of the adapted views
(class template)(customization point object)
ranges::cache_latest_viewviews::cache_latest
(C++26)
a
that caches the last-accessed element of its underlying sequence
(class template)(range adaptor object)
ranges::as_input_viewviews::as_input
(C++26)
converts a
into a range that is
-only and non-
(class template)(range adaptor object)
Range generators (since C++23)
Helper items
Range adaptor objects
See
(RAO).
Range adaptor closure objects
See
(RACO).
Customization point objects
See
(CPO).
Assignable wrapper
Some range adaptors wrap their elements or function objects with the
(until C++23)
(since C++23). The wrapper augments the wrapped object with assignability when needed.
Non-propagating cache
Some range adaptors are specified in terms of an exposition-only class template
, which behaves almost like std::optional<T> (see description for differences).
Conditionally-const type
template<boolConst,classT>using/*maybe-const*/=std::conditional_t<Const,constT,T>;(exposition only*)The alias template /*maybe-const*/ is a shorthand used to conditionally apply a const qualifier to the type T.
Integer-like type helper templates
template</*is-integer-like*/T>using/*make-signed-like-t*/<T>=/* see description */; (1)(exposition only*)template</*is-integer-like*/T>using/*make-unsigned-like-t*/<T>=/* see description */; (2)(exposition only*)template</*is-integer-like*/T>/*make-unsigned-like-t*/<T>/*to-unsigned-like*/(Tt){returnstatic_cast</*make-unsigned-like-t*/<T>>(t);} (3)(exposition only*)1) For an
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.
2) 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.
3) Explicitly converts t to /*make-unsigned-like-t*/<T>.
Customization point object helpers
template<ranges::input_rangeR>constexprauto&/*possibly-const-range*/(R&r)noexcept{ifconstexpr(ranges::input_range<constR>)returnconst_cast<constR&>(r);elsereturnr;} (1)(exposition only*)template<classT>constexprauto/*as-const-pointer*/(constT*p)noexcept{returnp;} (2)(exposition only*)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 constR models
; otherwise, returns r without any casting.
2)/*as-const-pointer*/ returns a pointer to object of constant type.
Range adaptor helpers
template<classF,classTuple>constexprauto/*tuple-transform*/(F&&f,Tuple&&tuple){returnstd::apply([&]<class...Ts>(Ts&&...args){returnstd::tuple<std::invoke_result_t<F&,Ts>...>(std::invoke(f,std::forward<Ts>(args))...);},std::forward<Tuple>(tuple));} (1)(exposition only*)template<classF,classTuple>constexprvoid/*tuple-for-each*/(F&&f,Tuple&&tuple){std::apply([&]<class...Ts>(Ts&&...args){(static_cast<void>(std::invoke(f,std::forward<Ts>(args))),...);},std::forward<Tuple>(tuple));} (2)(exposition only*)template<classT>constexprT&/*as-lvalue*/(T&&t){returnstatic_cast<T&>(t);} (3)(exposition only*)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.
Helper concepts
Following exposition-only concepts are used for several types, but they are not parts of the interface of standard library.
template<classR>concept/*simple-view*/=ranges::view<R>&&ranges::range<constR>&&std::same_as<ranges::iterator_t<R>,ranges::iterator_t<constR>>&&std::same_as<ranges::sentinel_t<R>,ranges::sentinel_t<constR>>; (1)(exposition only*)template<classI>concept/*has-arrow*/=ranges::input_iterator<I>&&(std::is_pointer_v<I>||requires(constIi){i.operator->();}); (2)(exposition only*)template<classT,classU>concept/*different-from*/=!std::same_as<std::remove_cvref_t<T>,std::remove_cvref_t<U>>; (3)(exposition only*)template<classR>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<boolC,class...Views>concept/*all-random-access*/=(ranges::random_access_range<std::conditional_t<C,constViews,Views>>&&...); (5)(exposition only*)template<boolC,class...Views>concept/*all-bidirectional*/=(ranges::bidirectional_range<std::conditional_t<C,constViews,Views>>&&...); (6)(exposition only*)template<boolC,class...Views>concept/*all-forward*/=(ranges::forward_range<std::conditional_t<C,constViews,Views>>&&...); (7)(exposition only*)Notes
macro ValueStdFeature
(C++23)std::generator – synchronous coroutine generator for ranges
(C++20)Ranges library and
(C++23)
(DR20)Non-
(C++23)
(DR20)
with
(C++23)ranges::range_adaptor_closure
(C++23)Relaxing
to allow for move-only types
(C++23)Removing "poison pills"
overloads in ranges::begin etc
(C++23)Relaxing ranges to allow certain projections
(C++26)
(DR20)Removing the common reference requirement from the indirectly invocable concepts
(C++23)std::const_iterator, ranges::as_const_view
(C++23)ranges::as_rvalue_view
(C++26)ranges::cache_latest_view
__cpp_lib_ranges_cartesian_product
(C++23)ranges::cartesian_product_view
(C++23)ranges::chunk_view
(C++23)ranges::chunk_by_view
(C++26)ranges::concat_view
(C++23)ranges::enumerate_view
(C++26)ranges::views::indices
(C++23)ranges::join_with_view
(C++23)ranges::repeat_view
(C++26)ranges::reserve_hint and ranges::approximately_sized_range
(C++23)ranges::slide_view
(C++23)ranges::stride_view
(C++23)ranges::to
(C++26)ranges::as_input_view
(C++23)ranges::zip_view,
ranges::zip_transform_view,
ranges::adjacent_view,
ranges::adjacent_transform_viewExample
Run this code
#include<iostream>#include<ranges>intmain(){autoconstints={0,1,2,3,4,5};autoeven=[](inti){return0==i%2;};autosquare=[](inti){returni*i;};// the "pipe" syntax of composing the views:for(inti:ints|std::views::filter(even)|std::views::transform(square))std::cout<<i<<' ';std::cout<<'\n';// a traditional "functional" composing syntax:for(inti:std::views::transform(std::views::filter(ints,even),square))std::cout<<i<<' ';}Output:
0 4 16 0 4 16 Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
(
) C++20 it was unclear how range adaptor objects bound trailing arguments they are bound
by value
C++23 possibly-const-range and as-const-pointer
were not declared noexceptdeclared noexcept
C++23 possibly-const-range would not add const-qualification
for ranges that has already modeled
adds const-qualification
for such ranges
C++20 has-arrow did not require i to be const-qualified requires See also