24 Ranges library [ranges]

24.1 General [ranges.general]

This Clause describes components for dealing with ranges of elements.
The following subclauses describe range and view requirements, and components for range primitives as summarized in Table 90.
Table 90: Ranges library summary [tab:range.summary]
Subclause
Header
Range access
<ranges>
Requirements
Range utilities
Range factories
Range adaptors

24.2 Header <ranges> synopsis [ranges.syn]

#include <compare> // see [compare.syn] #include <initializer_list> // see [initializer.list.syn] #include <iterator> // see [iterator.synopsis] namespace std::ranges { inline namespace unspecified { // [range.access], range access inline constexpr unspecified begin = unspecified; inline constexpr unspecified end = unspecified; inline constexpr unspecified cbegin = unspecified; inline constexpr unspecified cend = unspecified; inline constexpr unspecified rbegin = unspecified; inline constexpr unspecified rend = unspecified; inline constexpr unspecified crbegin = unspecified; inline constexpr unspecified crend = unspecified; inline constexpr unspecified size = unspecified; inline constexpr unspecified ssize = unspecified; inline constexpr unspecified empty = unspecified; inline constexpr unspecified data = unspecified; inline constexpr unspecified cdata = unspecified; } // [range.range], ranges template<class T> concept range = see below; template<class T> inline constexpr bool enable_borrowed_range = false; template<class T> concept borrowed_range = see below; template<class T> using iterator_t = decltype(ranges::begin(declval<T&>())); template<range R> using sentinel_t = decltype(ranges::end(declval<R&>())); template<range R> using range_difference_t = iter_difference_t<iterator_t<R>>; template<sized_­range R> using range_size_t = decltype(ranges::size(declval<R&>())); template<range R> using range_value_t = iter_value_t<iterator_t<R>>; template<range R> using range_reference_t = iter_reference_t<iterator_t<R>>; template<range R> using range_rvalue_reference_t = iter_rvalue_reference_t<iterator_t<R>>; // [range.sized], sized ranges template<class> inline constexpr bool disable_sized_range = false; template<class T> concept sized_range = see below; // [range.view], views template<class T> inline constexpr bool enable_view = see below; struct view_base { }; template<class T> concept view = see below; // [range.refinements], other range refinements template<class R, class T> concept output_range = see below; template<class T> concept input_range = see below; template<class T> concept forward_range = see below; template<class T> concept bidirectional_range = see below; template<class T> concept random_access_range = see below; template<class T> concept contiguous_range = see below; template<class T> concept common_range = see below; template<class T> concept viewable_range = see below; // [view.interface], class template view_­interface template<class D> requires is_class_v<D> && same_­as<D, remove_cv_t<D>> class view_interface; // [range.subrange], sub-ranges enum class subrange_kind : bool { unsized, sized }; template<input_­or_­output_­iterator I, sentinel_­for<I> S = I, subrange_kind K = see below> requires (K == subrange_kind::sized || !sized_­sentinel_­for<S, I>) class subrange; template<class I, class S, subrange_kind K> inline constexpr bool enable_borrowed_range<subrange<I, S, K>> = true; // [range.dangling], dangling iterator handling struct dangling; template<range R> using borrowed_iterator_t = see below; template<range R> using borrowed_subrange_t = see below; // [range.empty], empty view template<class T> requires is_object_v<T> class empty_view; template<class T> inline constexpr bool enable_borrowed_range<empty_view<T>> = true; namespace views { template<class T> inline constexpr empty_view<T> empty{}; } // [range.single], single view template<copy_­constructible T> requires is_object_v<T> class single_view; namespace views { inline constexpr unspecified single = unspecified; } template<bool Const, class T> using maybe-const = conditional_t<Const, const T, T>; // exposition only // [range.iota], iota view template<weakly_­incrementable W, semiregular Bound = unreachable_sentinel_t> requires weakly-equality-comparable-with<W, Bound> && copyable<W> class iota_view; template<class W, class Bound> inline constexpr bool enable_borrowed_range<iota_view<W, Bound>> = true; namespace views { inline constexpr unspecified iota = unspecified; } // [range.istream], istream view template<movable Val, class CharT, class Traits = char_traits<CharT>> requires see below class basic_istream_view; template<class Val, class CharT, class Traits> basic_istream_view<Val, CharT, Traits> istream_view(basic_istream<CharT, Traits>& s); // [range.all], all view namespace views { inline constexpr unspecified all = unspecified; template<viewable_­range R> using all_t = decltype(all(declval<R>())); } template<range R> requires is_object_v<R> class ref_view; template<class T> inline constexpr bool enable_borrowed_range<ref_view<T>> = true; // [range.filter], filter view template<input_­range V, indirect_­unary_­predicate<iterator_t<V>> Pred> requires view<V> && is_object_v<Pred> class filter_view; namespace views { inline constexpr unspecified filter = unspecified; } // [range.transform], transform view template<input_­range V, copy_­constructible F> requires view<V> && is_object_v<F> && regular_­invocable<F&, range_reference_t<V>> && can-reference<invoke_result_t<F&, range_reference_t<V>>> class transform_view; namespace views { inline constexpr unspecified transform = unspecified; } // [range.take], take view template<view> class take_view; template<class T> inline constexpr bool enable_borrowed_range<take_view<T>> = enable_borrowed_range<T>; namespace views { inline constexpr unspecified take = unspecified; } // [range.take.while], take while view template<view V, class Pred> requires input_­range<V> && is_object_v<Pred> && indirect_­unary_­predicate<const Pred, iterator_t<V>> class take_while_view; namespace views { inline constexpr unspecified take_while = unspecified; } // [range.drop], drop view template<view V> class drop_view; template<class T> inline constexpr bool enable_borrowed_range<drop_view<T>> = enable_borrowed_range<T>; namespace views { inline constexpr unspecified drop = unspecified; } // [range.drop.while], drop while view template<view V, class Pred> requires input_­range<V> && is_object_v<Pred> && indirect_­unary_­predicate<const Pred, iterator_t<V>> class drop_while_view; template<class T, class Pred> inline constexpr bool enable_borrowed_range<drop_while_view<T, Pred>> = enable_borrowed_range<T>; namespace views { inline constexpr unspecified drop_while = unspecified; } // [range.join], join view template<input_­range V> requires view<V> && input_­range<range_reference_t<V>> class join_view; namespace views { inline constexpr unspecified join = unspecified; } // [range.lazy.split], lazy split view template<class R> concept tiny-range = see below; // exposition only template<input_­range V, forward_­range Pattern> requires view<V> && view<Pattern> && indirectly_­comparable<iterator_t<V>, iterator_t<Pattern>, ranges::equal_to> && (forward_­range<V> || tiny-range<Pattern>) class lazy_split_view; // [range.split], split view template<forward_­range V, forward_­range Pattern> requires view<V> && view<Pattern> && indirectly_­comparable<iterator_t<V>, iterator_t<Pattern>, ranges::equal_to> class split_view; namespace views { inline constexpr unspecified lazy_split = unspecified; inline constexpr unspecified split = unspecified; } // [range.counted], counted view namespace views { inline constexpr unspecified counted = unspecified; } // [range.common], common view template<view V> requires (!common_­range<V> && copyable<iterator_t<V>>) class common_view; template<class T> inline constexpr bool enable_borrowed_range<common_view<T>> = enable_borrowed_range<T>; namespace views { inline constexpr unspecified common = unspecified; } // [range.reverse], reverse view template<view V> requires bidirectional_­range<V> class reverse_view; template<class T> inline constexpr bool enable_borrowed_range<reverse_view<T>> = enable_borrowed_range<T>; namespace views { inline constexpr unspecified reverse = unspecified; } // [range.elements], elements view template<input_­range V, size_t N> requires see below class elements_view; template<class T, size_t N> inline constexpr bool enable_borrowed_range<elements_view<T, N>> = enable_borrowed_range<T>; template<class R> using keys_view = elements_view<views::all_t<R>, 0>; template<class R> using values_view = elements_view<views::all_t<R>, 1>; namespace views { template<size_t N> inline constexpr unspecified elements = unspecified; inline constexpr auto keys = elements<0>; inline constexpr auto values = elements<1>; } } namespace std { namespace views = ranges::views; template<class T> struct tuple_size; template<size_t I, class T> struct tuple_element; template<class I, class S, ranges::subrange_kind K> struct tuple_size<ranges::subrange<I, S, K>> : integral_constant<size_t, 2> {}; template<class I, class S, ranges::subrange_kind K> struct tuple_element<0, ranges::subrange<I, S, K>> { using type = I; }; template<class I, class S, ranges::subrange_kind K> struct tuple_element<1, ranges::subrange<I, S, K>> { using type = S; }; template<class I, class S, ranges::subrange_kind K> struct tuple_element<0, const ranges::subrange<I, S, K>> { using type = I; }; template<class I, class S, ranges::subrange_kind K> struct tuple_element<1, const ranges::subrange<I, S, K>> { using type = S; }; }
Within this Clause, for an integer-like type X ([iterator.concept.winc]), make-unsigned-like-t<X> denotes make_­unsigned_­t<X> if X is an integer type; otherwise, it denotes a corresponding unspecified unsigned-integer-like type of the same width as X.
For an expression x of type X, to-unsigned-like(x) is x explicitly converted to make-unsigned-like-t<X>.
Also within this Clause, make-signed-like-t<X> for an integer-like type X denotes make_­signed_­t<X> if X is an integer type; otherwise, it denotes a corresponding unspecified signed-integer-like type of the same width as X.

24.3 Range access [range.access]

24.3.1 General [range.access.general]

In addition to being available via inclusion of the <ranges> header, the customization point objects in [range.access] are available when <iterator> is included.
Within [range.access], the reified object of a subexpression E denotes
  • the same object as E if E is a glvalue, or
  • the result of applying the temporary materialization conversion ([conv.rval]) to E otherwise.

24.3.2 ranges​::​begin [range.access.begin]

The name ranges​::​begin denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​begin(E) is ill-formed.
  • Otherwise, if T is an array type ([basic.compound]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​begin(E) is ill-formed with no diagnostic required.
  • Otherwise, if T is an array type, ranges​::​begin(E) is expression-equivalent to t + 0.
  • Otherwise, if decay-copy(t.begin()) is a valid expression whose type models input_­or_­output_­iterator, ranges​::​begin(E) is expression-equivalent to decay-copy(t.begin()).
  • Otherwise, if T is a class or enumeration type and decay-copy(begin(t)) is a valid expression whose type models input_­or_­output_­iterator with overload resolution performed in a context in which unqualified lookup for begin finds only the declarations void begin(auto&) = delete; void begin(const auto&) = delete; then ranges​::​begin(E) is expression-equivalent to decay-copy(begin(t)) with overload resolution performed in the above context.
  • Otherwise, ranges​::​begin(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​begin(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​begin(E) is a valid expression, its type models input_­or_­output_­iterator.
β€” end note]

24.3.3 ranges​::​end [range.access.end]

The name ranges​::​end denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​end(E) is ill-formed.
  • Otherwise, if T is an array type ([basic.compound]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​end(E) is ill-formed with no diagnostic required.
  • Otherwise, if T is an array of unknown bound, ranges​::​end(E) is ill-formed.
  • Otherwise, if T is an array, ranges​::​end(E) is expression-equivalent to t + extent_­v<T>.
  • Otherwise, if decay-copy(t.end()) is a valid expression whose type models sentinel_­for<iterator_­t<T>> then ranges​::​end(E) is expression-equivalent to decay-copy(t.end()).
  • Otherwise, if T is a class or enumeration type and decay-copy(end(t)) is a valid expression whose type models sentinel_­for<iterator_­t<T>> with overload resolution performed in a context in which unqualified lookup for end finds only the declarations void end(auto&) = delete; void end(const auto&) = delete; then ranges​::​end(E) is expression-equivalent to decay-copy(end(t)) with overload resolution performed in the above context.
  • Otherwise, ranges​::​end(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​end(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​end(E) is a valid expression, the types S and I of ranges​::​end(E) and ranges​::​begin(E) model sentinel_­for<S, I>.
β€” end note]

24.3.4 ranges​::​cbegin [range.access.cbegin]

The name ranges​::​cbegin denotes a customization point object ([customization.point.object]).
The expression ranges​::​​cbegin(E) for a subexpression E of type T is expression-equivalent to:
  • ranges​::​begin(static_­cast<const T&>(E)) if E is an lvalue.
  • Otherwise, ranges​::​begin(static_­cast<const T&&>(E)).
[Note 1:
Whenever ranges​::​cbegin(E) is a valid expression, its type models input_­or_­output_­iterator.
β€” end note]

24.3.5 ranges​::​cend [range.access.cend]

The name ranges​::​cend denotes a customization point object ([customization.point.object]).
The expression ranges​::​cend(E) for a subexpression E of type T is expression-equivalent to:
  • ranges​::​end(static_­cast<const T&>(E)) if E is an lvalue.
  • Otherwise, ranges​::​end(static_­cast<const T&&>(E)).
[Note 1:
Whenever ranges​::​cend(E) is a valid expression, the types S and I of the expressions ranges​::​cend(E) and ranges​::​cbegin(E) model sentinel_­for<S, I>.
β€” end note]

24.3.6 ranges​::​rbegin [range.access.rbegin]

The name ranges​::​rbegin denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​rbegin(E) is ill-formed.
  • Otherwise, if T is an array type ([basic.compound]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​rbegin(E) is ill-formed with no diagnostic required.
  • Otherwise, if decay-copy(t.rbegin()) is a valid expression whose type models input_­or_­output_­iterator, ranges​::​rbegin(E) is expression-equivalent to decay-copy(t.rbegin()).
  • Otherwise, if T is a class or enumeration type and decay-copy(rbegin(t)) is a valid expression whose type models input_­or_­output_­iterator with overload resolution performed in a context in which unqualified lookup for rbegin finds only the declarations void rbegin(auto&) = delete; void rbegin(const auto&) = delete; then ranges​::​rbegin(E) is expression-equivalent to decay-copy(rbegin(t)) with overload resolution performed in the above context.
  • Otherwise, if both ranges​::​begin(t) and ranges​::​end(t) are valid expressions of the same type which models bidirectional_­iterator ([iterator.concept.bidir]), ranges​::​rbegin(E) is expression-equivalent to make_­reverse_­iterator(ranges​::​end(t)).
  • Otherwise, ranges​::​rbegin(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​rbegin(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​rbegin(E) is a valid expression, its type models input_­or_­output_­iterator.
β€” end note]

24.3.7 ranges​::​rend [range.access.rend]

The name ranges​::​rend denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​rend(E) is ill-formed.
  • Otherwise, if T is an array type ([basic.compound]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​rend(E) is ill-formed with no diagnostic required.
  • Otherwise, if decay-copy(t.rend()) is a valid expression whose type models sentinel_­for<decltype(ranges​::​rbegin(E))> then ranges​::​rend(E) is expression-equivalent to decay-copy(t.rend()).
  • Otherwise, if T is a class or enumeration type and decay-copy(rend(t)) is a valid expression whose type models sentinel_­for<decltype(ranges​::​rbegin(E))> with overload resolution performed in a context in which unqualified lookup for rend finds only the declarations void rend(auto&) = delete; void rend(const auto&) = delete; then ranges​::​rend(E) is expression-equivalent to decay-copy(rend(t)) with overload resolution performed in the above context.
  • Otherwise, if both ranges​::​begin(t) and ranges​::​end(t) are valid expressions of the same type which models bidirectional_­iterator ([iterator.concept.bidir]), then ranges​::​rend(E) is expression-equivalent to make_­reverse_­iterator(ranges​::​begin(t)).
  • Otherwise, ranges​::​rend(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​rend(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​rend(E) is a valid expression, the types S and I of the expressions ranges​::​rend(E) and ranges​::​rbegin(E) model sentinel_­for<S, I>.
β€” end note]

24.3.8 ranges​::​crbegin [range.access.crbegin]

The name ranges​::​crbegin denotes a customization point object ([customization.point.object]).
The expression ranges​::​​crbegin(E) for a subexpression E of type T is expression-equivalent to:
  • ranges​::​​rbegin(static_­cast<const T&>(E)) if E is an lvalue.
  • Otherwise, ranges​::​rbegin(static_­cast<const T&&>(E)).
[Note 1:
Whenever ranges​::​crbegin(E) is a valid expression, its type models input_­or_­output_­iterator.
β€” end note]

24.3.9 ranges​::​crend [range.access.crend]

The name ranges​::​crend denotes a customization point object ([customization.point.object]).
The expression ranges​::​​crend(E) for a subexpression E of type T is expression-equivalent to:
  • ranges​::​rend(static_­cast<const T&>(E)) if E is an lvalue.
  • Otherwise, ranges​::​rend(static_­cast<const T&&>(E)).
[Note 1:
Whenever ranges​::​crend(E) is a valid expression, the types S and I of the expressions ranges​::​crend(E) and ranges​::​crbegin(E) model sentinel_­for<S, I>.
β€” end note]

24.3.10 ranges​::​size [range.prim.size]

The name ranges​::​size denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If T is an array of unknown bound ([dcl.array]), ranges​::​size(E) is ill-formed.
  • Otherwise, if T is an array type, ranges​::​size(E) is expression-equivalent to decay-copy(extent_­v<T>).
  • Otherwise, if disable_­sized_­range<remove_­cv_­t<T>> ([range.sized]) is false and decay-copy(t.size()) is a valid expression of integer-like type ([iterator.concept.winc]), ranges​::​size(E) is expression-equivalent to decay-copy(t.size()).
  • Otherwise, if T is a class or enumeration type, disable_­sized_­range<remove_­cv_­t<T>> is false and decay-copy(size(t)) is a valid expression of integer-like type with overload resolution performed in a context in which unqualified lookup for size finds only the declarations void size(auto&) = delete; void size(const auto&) = delete; then ranges​::​size(E) is expression-equivalent to decay-copy(size(t)) with overload resolution performed in the above context.
  • Otherwise, if to-unsigned-like(ranges​::​end(t) - ranges​::​begin(t)) ([ranges.syn]) is a valid expression and the types I and S of ranges​::​begin(t) and ranges​::​end(t) (respectively) model both sized_­sentinel_­for<S, I> ([iterator.concept.sizedsentinel]) and forward_­iterator<I>, then ranges​::​size(E) is expression-equivalent to to-unsigned-like(ranges​::​end(t) - ranges​::​begin(t)).
  • Otherwise, ranges​::​size(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​size(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​size(E) is a valid expression, its type is integer-like.
β€” end note]

24.3.11 ranges​::​ssize [range.prim.ssize]

The name ranges​::​ssize denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
If ranges​::​size(t) is ill-formed, ranges​::​ssize(E) is ill-formed.
Otherwise let D be make-signed-like-t<decltype(ranges​::​​size(t))>, or ptrdiff_­t if it is wider than that type; ranges​::​ssize(E) is expression-equivalent to static_­cast<D>(ranges​::​size(t)).

24.3.12 ranges​::​empty [range.prim.empty]

The name ranges​::​empty denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If T is an array of unknown bound ([basic.compound]), ranges​::​empty(E) is ill-formed.
  • Otherwise, if bool(t.empty()) is a valid expression, ranges​::​empty(E) is expression-equivalent to bool(t.empty()).
  • Otherwise, if (ranges​::​size(t) == 0) is a valid expression, ranges​::​empty(E) is expression-equivalent to (ranges​::​size(t) == 0).
  • Otherwise, if bool(ranges​::​begin(t) == ranges​::​end(t)) is a valid expression and the type of ranges​::​begin(t) models forward_­iterator, ranges​::​empty(E) is expression-equivalent to bool(​ranges​::​begin(t) == ranges​::​end(t)).
  • Otherwise, ranges​::​empty(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​empty(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​empty(E) is a valid expression, it has type bool.
β€” end note]

24.3.13 ranges​::​data [range.prim.data]

The name ranges​::​data denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​data(E) is ill-formed.
  • Otherwise, if T is an array type ([basic.compound]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​data(E) is ill-formed with no diagnostic required.
  • Otherwise, if decay-copy(t.data()) is a valid expression of pointer to object type, ranges​::​data(E) is expression-equivalent to decay-copy(t.data()).
  • Otherwise, if ranges​::​begin(t) is a valid expression whose type models contiguous_­iterator, ranges​::​data(E) is expression-equivalent to to_­address(ranges​::​begin(t)).
  • Otherwise, ranges​::​data(E) is ill-formed.
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​data(E) appears in the immediate context of a template instantiation.
β€” end note]
[Note 2:
Whenever ranges​::​data(E) is a valid expression, it has pointer to object type.
β€” end note]

24.3.14 ranges​::​cdata [range.prim.cdata]

The name ranges​::​cdata denotes a customization point object ([customization.point.object]).
The expression ranges​::​​cdata(E) for a subexpression E of type T is expression-equivalent to:
  • ranges​::​data(static_­cast<const T&>(E)) if E is an lvalue.
  • Otherwise, ranges​::​data(static_­cast<const T&&>(E)).
[Note 1:
Whenever ranges​::​cdata(E) is a valid expression, it has pointer to object type.
β€” end note]

24.4 Range requirements [range.req]

24.4.1 General [range.req.general]

Ranges are an abstraction that allow a C++ program to operate on elements of data structures uniformly.
Calling ranges​::​begin on a range returns an object whose type models input_­or_­output_­iterator ([iterator.concept.iterator]).
Calling ranges​::​end on a range returns an object whose type S, together with the type I of the object returned by ranges​::​begin, models sentinel_­for<S, I>.
The library formalizes the interfaces, semantics, and complexity of ranges to enable algorithms and range adaptors that work efficiently on different types of sequences.
The range concept requires that ranges​::​begin and ranges​::​end return an iterator and a sentinel, respectively.
The sized_­range concept refines range with the requirement that ranges​::​size be amortized .
The view concept specifies requirements on a range type with constant-time destruction and move operations.
Several refinements of range group requirements that arise frequently in concepts and algorithms.
Common ranges are ranges for which ranges​::​begin and ranges​::​end return objects of the same type.
Random access ranges are ranges for which ranges​::​begin returns a type that models random_­access_­iterator ([iterator.concept.random.access]).
(Contiguous, bidirectional, forward, input, and output ranges are defined similarly.)
Viewable ranges can be converted to views.

24.4.2 Ranges [range.range]

The range concept defines the requirements of a type that allows iteration over its elements by providing an iterator and sentinel that denote the elements of the range.
template<class T> concept range = requires(T& t) { ranges::begin(t); // sometimes equality-preserving (see below) ranges::end(t); };
The required expressions ranges​::​begin(t) and ranges​::​end(t) of the range concept do not require implicit expression variations ([concepts.equality]).
Given an expression t such that decltype((t)) is T&, T models range only if
  • [ranges​::​begin(t), ranges​::​end(t)) denotes a range ([iterator.requirements.general]),
  • both ranges​::​begin(t) and ranges​::​end(t) are amortized constant time and non-modifying, and
  • if the type of ranges​::​begin(t) models forward_­iterator, ranges​::​begin(t) is equality-preserving.
[Note 1:
Equality preservation of both ranges​::​begin and ranges​::​end enables passing a range whose iterator type models forward_­iterator to multiple algorithms and making multiple passes over the range by repeated calls to ranges​::​begin and ranges​::​end.
Since ranges​::​begin is not required to be equality-preserving when the return type does not model forward_­iterator, it is possible for repeated calls to not return equal values or to not be well-defined.
β€” end note]
template<class T> concept borrowed_­range = range<T> && (is_lvalue_reference_v<T> || enable_borrowed_range<remove_cvref_t<T>>);
Given an expression E such that decltype((E)) is T, T models borrowed_­range only if the validity of iterators obtained from the object denoted by E is not tied to the lifetime of that object.
[Note 2:
Since the validity of iterators is not tied to the lifetime of an object whose type models borrowed_­range, a function can accept arguments of such a type by value and return iterators obtained from it without danger of dangling.
β€” end note]
template<class> inline constexpr bool enable_borrowed_range = false;
Remarks: Pursuant to [namespace.std], users may specialize enable_­borrowed_­range for cv-unqualified program-defined types.
Such specializations shall be usable in constant expressions ([expr.const]) and have type const bool.
[Example 1:
Each specialization S of class template subrange ([range.subrange]) models borrowed_­range because
  • enable_­borrowed_­range<S> is specialized to have the value true, and
  • S's iterators do not have validity tied to the lifetime of an S object because they are β€œborrowed” from some other range.
β€” end example]

24.4.3 Sized ranges [range.sized]

The sized_­range concept refines range with the requirement that the number of elements in the range can be determined in amortized constant time using ranges​::​size.
template<class T> concept sized_­range = range<T> && requires(T& t) { ranges::size(t); };
Given an lvalue t of type remove_­reference_­t<T>, T models sized_­range only if
  • ranges​::​size(t) is amortized , does not modify t, and is equal to ranges​::​distance(t), and
  • if iterator_­t<T> models forward_­iterator, ranges​::​size(t) is well-defined regardless of the evaluation of ranges​::​begin(t).
    [Note 1:
    ranges​::​size(t) is otherwise not required to be well-defined after evaluating ranges​::​begin(t).
    For example, it is possible for ranges​::​size(t) to be well-defined for a sized_­range whose iterator type does not model forward_­iterator only if evaluated before the first call to ranges​::​begin(t).
    β€” end note]
template<class> inline constexpr bool disable_sized_range = false;
Remarks: Pursuant to [namespace.std], users may specialize disable_­sized_­range for cv-unqualified program-defined types.
Such specializations shall be usable in constant expressions ([expr.const]) and have type const bool.
[Note 2:
disable_­sized_­range allows use of range types with the library that satisfy but do not in fact model sized_­range.
β€” end note]

24.4.4 Views [range.view]

The view concept specifies the requirements of a range type that has constant time move construction, move assignment, and destruction; that is, the cost of these operations is independent of the number of elements in the view.
template<class T> concept view = range<T> && movable<T> && enable_view<T>;
T models view only if:
[Example 1:
Examples of views are:
  • A range type that wraps a pair of iterators.
  • A range type that holds its elements by shared_­ptr and shares ownership with all its copies.
  • A range type that generates its elements on demand.
Most containers are not views since destruction of the container destroys the elements, which cannot be done in constant time.
β€” end example]
Since the difference between range and view is largely semantic, the two are differentiated with the help of enable_­view.
template<class T> inline constexpr bool is-derived-from-view-interface = see below; // exposition only template<class T> inline constexpr bool enable_view = derived_­from<T, view_base> || is-derived-from-view-interface<T>;
For a type T, is-derived-from-view-interface<T> is true if and only if T has exactly one public base class view_­interface<U> for some type U and T has no base classes of type view_­interface<V> for any other type V.
Remarks: Pursuant to [namespace.std], users may specialize enable_­view to true for cv-unqualified program-defined types which model view, and false for types which do not.
Such specializations shall be usable in constant expressions ([expr.const]) and have type const bool.

24.4.5 Other range refinements [range.refinements]

The output_­range concept specifies requirements of a range type for which ranges​::​begin returns a model of output_­iterator ([iterator.concept.output]).
template<class R, class T> concept output_­range = range<R> && output_­iterator<iterator_t<R>, T>; template<class T> concept input_­range = range<T> && input_­iterator<iterator_t<T>>; template<class T> concept forward_­range = input_­range<T> && forward_­iterator<iterator_t<T>>; template<class T> concept bidirectional_­range = forward_­range<T> && bidirectional_­iterator<iterator_t<T>>; template<class T> concept random_­access_­range = bidirectional_­range<T> && random_­access_­iterator<iterator_t<T>>;
contiguous_­range additionally requires that the ranges​::​data customization point object ([range.prim.data]) is usable with the range.
template<class T> concept contiguous_­range = random_­access_­range<T> && contiguous_­iterator<iterator_t<T>> && requires(T& t) { { ranges::data(t) } -> same_­as<add_pointer_t<range_reference_t<T>>>; };
Given an expression t such that decltype((t)) is T&, T models contiguous_­range only if to_­address(​ranges​::​begin(t)) == ranges​::​data(t) is true.
The common_­range concept specifies requirements of a range type for which ranges​::​begin and ranges​::​end return objects of the same type.
[Example 1:
The standard containers ([containers]) model common_­range.
β€” end example]
template<class T> concept common_­range = range<T> && same_­as<iterator_t<T>, sentinel_t<T>>;
The viewable_­range concept specifies the requirements of a range type that can be converted to a view safely.
template<class T> concept viewable_­range = range<T> && ((view<remove_cvref_t<T>> && constructible_­from<remove_cvref_t<T>, T>) || (!view<remove_cvref_t<T>> && borrowed_­range<T>));

24.5 Range utilities [range.utility]

24.5.1 General [range.utility.general]

The components in [range.utility] are general utilities for representing and manipulating ranges.

24.5.2 Helper concepts [range.utility.helpers]

Many of the types in subclause [range.utility] are specified in terms of the following exposition-only concepts: template<class R> concept simple-view = // exposition only view<R> && range<const R> && same_­as<iterator_t<R>, iterator_t<const R>> && same_­as<sentinel_t<R>, sentinel_t<const R>>; template<class I> concept has-arrow = // exposition only input_­iterator<I> && (is_pointer_v<I> || requires(I i) { i.operator->(); }); template<class T, class U> concept different-from = // exposition only !same_­as<remove_cvref_t<T>, remove_cvref_t<U>>;

24.5.3 View interface [view.interface]

24.5.3.1 General [view.interface.general]

The class template view_­interface is a helper for defining view-like types that offer a container-like interface.
It is parameterized with the type that is derived from it.
namespace std::ranges { template<class D> requires is_class_v<D> && same_­as<D, remove_cv_t<D>> class view_interface { private: constexpr D& derived() noexcept { // exposition only return static_cast<D&>(*this); } constexpr const D& derived() const noexcept { // exposition only return static_cast<const D&>(*this); } public: constexpr bool empty() requires forward_­range<D> { return ranges::begin(derived()) == ranges::end(derived()); } constexpr bool empty() const requires forward_­range<const D> { return ranges::begin(derived()) == ranges::end(derived()); } constexpr explicit operator bool() requires requires { ranges::empty(derived()); } { return !ranges::empty(derived()); } constexpr explicit operator bool() const requires requires { ranges::empty(derived()); } { return !ranges::empty(derived()); } constexpr auto data() requires contiguous_­iterator<iterator_t<D>> { return to_address(ranges::begin(derived())); } constexpr auto data() const requires range<const D> && contiguous_­iterator<iterator_t<const D>> { return to_address(ranges::begin(derived())); } constexpr auto size() requires forward_­range<D> && sized_­sentinel_­for<sentinel_t<D>, iterator_t<D>> { return ranges::end(derived()) - ranges::begin(derived()); } constexpr auto size() const requires forward_­range<const D> && sized_­sentinel_­for<sentinel_t<const D>, iterator_t<const D>> { return ranges::end(derived()) - ranges::begin(derived()); } constexpr decltype(auto) front() requires forward_­range<D>; constexpr decltype(auto) front() const requires forward_­range<const D>; constexpr decltype(auto) back() requires bidirectional_­range<D> && common_­range<D>; constexpr decltype(auto) back() const requires bidirectional_­range<const D> && common_­range<const D>; template<random_­access_­range R = D> constexpr decltype(auto) operator[](range_difference_t<R> n) { return ranges::begin(derived())[n]; } template<random_­access_­range R = const D> constexpr decltype(auto) operator[](range_difference_t<R> n) const { return ranges::begin(derived())[n]; } }; }
The template parameter D for view_­interface may be an incomplete type.
Before any member of the resulting specialization of view_­interface other than special member functions is referenced, D shall be complete, and model both derived_­from<view_­interface<D>> and view.

24.5.3.2 Members [view.interface.members]

constexpr decltype(auto) front() requires forward_­range<D>; constexpr decltype(auto) front() const requires forward_­range<const D>;
Preconditions: !empty() is true.
Effects: Equivalent to: return *ranges​::​begin(derived());
constexpr decltype(auto) back() requires bidirectional_­range<D> && common_­range<D>; constexpr decltype(auto) back() const requires bidirectional_­range<const D> && common_­range<const D>;
Preconditions: !empty() is true.
Effects: Equivalent to: return *ranges​::​prev(ranges​::​end(derived()));

24.5.4 Sub-ranges [range.subrange]

24.5.4.1 General [range.subrange.general]

The subrange class template combines together an iterator and a sentinel into a single object that models the view concept.
Additionally, it models the sized_­range concept when the final template parameter is subrange_­kind​::​sized.
namespace std::ranges { template<class From, class To> concept convertible-to-non-slicing = // exposition only convertible_­to<From, To> && !(is_pointer_v<decay_t<From>> && is_pointer_v<decay_t<To>> && different-from<remove_pointer_t<decay_t<From>>, remove_pointer_t<decay_t<To>>>); template<class T> concept pair-like = // exposition only !is_reference_v<T> && requires(T t) { typename tuple_size<T>::type; // ensures tuple_­size<T> is complete requires derived_­from<tuple_size<T>, integral_constant<size_t, 2>>; typename tuple_element_t<0, remove_const_t<T>>; typename tuple_element_t<1, remove_const_t<T>>; { std::get<0>(t) } -> convertible_­to<const tuple_element_t<0, T>&>; { std::get<1>(t) } -> convertible_­to<const tuple_element_t<1, T>&>; }; template<class T, class U, class V> concept pair-like-convertible-from = // exposition only !range<T> && pair-like<T> && constructible_­from<T, U, V> && convertible-to-non-slicing<U, tuple_element_t<0, T>> && convertible_­to<V, tuple_element_t<1, T>>; template<input_­or_­output_­iterator I, sentinel_­for<I> S = I, subrange_kind K = sized_­sentinel_­for<S, I> ? subrange_kind::sized : subrange_kind::unsized> requires (K == subrange_kind::sized || !sized_­sentinel_­for<S, I>) class subrange : public view_interface<subrange<I, S, K>> { private: static constexpr bool StoreSize = // exposition only K == subrange_kind::sized && !sized_­sentinel_­for<S, I>; I begin_ = I(); // exposition only S end_ = S(); // exposition only make-unsigned-like-t<iter_difference_t<I>> size_ = 0; // exposition only; present only // when StoreSize is true public: subrange() requires default_­initializable<I> = default; constexpr subrange(convertible-to-non-slicing<I> auto i, S s) requires (!StoreSize); constexpr subrange(convertible-to-non-slicing<I> auto i, S s, make-unsigned-like-t<iter_difference_t<I>> n) requires (K == subrange_kind::sized); template<different-from<subrange> R> requires borrowed_­range<R> && convertible-to-non-slicing<iterator_t<R>, I> && convertible_­to<sentinel_t<R>, S> constexpr subrange(R&& r) requires (!StoreSize || sized_­range<R>); template<borrowed_­range R> requires convertible-to-non-slicing<iterator_t<R>, I> && convertible_­to<sentinel_t<R>, S> constexpr subrange(R&& r, make-unsigned-like-t<iter_difference_t<I>> n) requires (K == subrange_kind::sized) : subrange{ranges::begin(r), ranges::end(r), n} {} template<different-from<subrange> PairLike> requires pair-like-convertible-from<PairLike, const I&, const S&> constexpr operator PairLike() const; constexpr I begin() const requires copyable<I>; [[nodiscard]] constexpr I begin() requires (!copyable<I>); constexpr S end() const; constexpr bool empty() const; constexpr make-unsigned-like-t<iter_difference_t<I>> size() const requires (K == subrange_kind::sized); [[nodiscard]] constexpr subrange next(iter_difference_t<I> n = 1) const & requires forward_­iterator<I>; [[nodiscard]] constexpr subrange next(iter_difference_t<I> n = 1) &&; [[nodiscard]] constexpr subrange prev(iter_difference_t<I> n = 1) const requires bidirectional_­iterator<I>; constexpr subrange& advance(iter_difference_t<I> n); }; template<input_­or_­output_­iterator I, sentinel_­for<I> S> subrange(I, S) -> subrange<I, S>; template<input_­or_­output_­iterator I, sentinel_­for<I> S> subrange(I, S, make-unsigned-like-t<iter_difference_t<I>>) -> subrange<I, S, subrange_kind::sized>; template<borrowed_­range R> subrange(R&&) -> subrange<iterator_t<R>, sentinel_t<R>, (sized_­range<R> || sized_­sentinel_­for<sentinel_t<R>, iterator_t<R>>) ? subrange_kind::sized : subrange_kind::unsized>; template<borrowed_­range R> subrange(R&&, make-unsigned-like-t<range_difference_t<R>>) -> subrange<iterator_t<R>, sentinel_t<R>, subrange_kind::sized>; template<size_t N, class I, class S, subrange_kind K> requires (N < 2) constexpr auto get(const subrange<I, S, K>& r); template<size_t N, class I, class S, subrange_kind K> requires (N < 2) constexpr auto get(subrange<I, S, K>&& r); } namespace std { using ranges::get; }

24.5.4.2 Constructors and conversions [range.subrange.ctor]

constexpr subrange(convertible-to-non-slicing<I> auto i, S s) requires (!StoreSize);
Preconditions: [i, s) is a valid range.
Effects: Initializes begin_­ with std​::​move(i) and end_­ with s.
constexpr subrange(convertible-to-non-slicing<I> auto i, S s, make-unsigned-like-t<iter_difference_t<I>> n) requires (K == subrange_kind::sized);
Preconditions: [i, s) is a valid range, and n == to-unsigned-like(ranges​::​distance(i, s)) is true.
Effects: Initializes begin_­ with std​::​move(i) and end_­ with s.
If StoreSize is true, initializes size_­ with n.
[Note 1:
Accepting the length of the range and storing it to later return from size() enables subrange to model sized_­range even when it stores an iterator and sentinel that do not model sized_­sentinel_­for.
β€” end note]
template<different-from<subrange> R> requires borrowed_­range<R> && convertible-to-non-slicing<iterator_t<R>, I> && convertible_­to<sentinel_t<R>, S> constexpr subrange(R&& r) requires (!StoreSize || sized_­range<R>);
Effects: Equivalent to:
  • If StoreSize is true, subrange(r, ranges​::​size(r)).
  • Otherwise, subrange(ranges​::​begin(r), ranges​::​end(r)).
template<different-from<subrange> PairLike> requires pair-like-convertible-from<PairLike, const I&, const S&> constexpr operator PairLike() const;
Effects: Equivalent to: return PairLike(begin_­, end_­);

24.5.4.3 Accessors [range.subrange.access]

constexpr I begin() const requires copyable<I>;
Effects: Equivalent to: return begin_­;
[[nodiscard]] constexpr I begin() requires (!copyable<I>);
Effects: Equivalent to: return std​::​move(begin_­);
constexpr S end() const;
Effects: Equivalent to: return end_­;
constexpr bool empty() const;
Effects: Equivalent to: return begin_­ == end_­;
constexpr make-unsigned-like-t<iter_difference_t<I>> size() const requires (K == subrange_kind::sized);
Effects:
  • If StoreSize is true, equivalent to: return size_­;
  • Otherwise, equivalent to: return to-unsigned-like(end_­ - begin_­);
[[nodiscard]] constexpr subrange next(iter_difference_t<I> n = 1) const & requires forward_­iterator<I>;
Effects: Equivalent to: auto tmp = *this; tmp.advance(n); return tmp;
[[nodiscard]] constexpr subrange next(iter_difference_t<I> n = 1) &&;
Effects: Equivalent to: advance(n); return std::move(*this);
[[nodiscard]] constexpr subrange prev(iter_difference_t<I> n = 1) const requires bidirectional_­iterator<I>;
Effects: Equivalent to: auto tmp = *this; tmp.advance(-n); return tmp;
constexpr subrange& advance(iter_difference_t<I> n);
Effects: Equivalent to: if constexpr (bidirectional_iterator<I>) { if (n < 0) { ranges::advance(begin_, n); if constexpr (StoreSize) size_ += to-unsigned-like(-n); return *this; } } auto d = n - ranges::advance(begin_, n, end_); if constexpr (StoreSize) size_ -= to-unsigned-like(d); return *this;
template<size_t N, class I, class S, subrange_kind K> requires (N < 2) constexpr auto get(const subrange<I, S, K>& r); template<size_t N, class I, class S, subrange_kind K> requires (N < 2) constexpr auto get(subrange<I, S, K>&& r);
Effects: Equivalent to: if constexpr (N == 0) return r.begin(); else return r.end();

24.5.5 Dangling iterator handling [range.dangling]

The tag type dangling is used together with the template aliases borrowed_­iterator_­t and borrowed_­subrange_­t.
When an algorithm that typically returns an iterator into, or a subrange of, a range argument is called with an rvalue range argument that does not model borrowed_­range ([range.range]), the return value possibly refers to a range whose lifetime has ended.
In such cases, the tag type dangling is returned instead of an iterator or subrange.
namespace std::ranges { struct dangling { constexpr dangling() noexcept = default; template<class... Args> constexpr dangling(Args&&...) noexcept { } }; }
[Example 1: vector<int> f(); auto result1 = ranges::find(f(), 42); // #1 static_assert(same_­as<decltype(result1), ranges::dangling>); auto vec = f(); auto result2 = ranges::find(vec, 42); // #2 static_assert(same_­as<decltype(result2), vector<int>::iterator>); auto result3 = ranges::find(subrange{vec}, 42); // #3 static_assert(same_­as<decltype(result3), vector<int>::iterator>);
The call to ranges​::​find at #1 returns ranges​::​dangling since f() is an rvalue vector; it is possible for the vector to be destroyed before a returned iterator is dereferenced.
However, the calls at #2 and #3 both return iterators since the lvalue vec and specializations of subrange model borrowed_­range.
β€” end example]
For a type R that models range:
  • if R models borrowed_­range, then borrowed_­iterator_­t<R> denotes iterator_­t<R>, and borrowed_­subrange_­t<R> denotes subrange<iterator_­t<R>>;
  • otherwise, both borrowed_­iterator_­t<R> and borrowed_­subrange_­t<R> denote dangling.

24.6 Range factories [range.factories]

24.6.1 General [range.factories.general]

Subclause [range.factories] defines range factories, which are utilities to create a view.
Range factories are declared in namespace std​::​ranges​::​views.

24.6.2 Empty view [range.empty]

24.6.2.1 Overview [range.empty.overview]

empty_­view produces a view of no elements of a particular type.
[Example 1: auto e = views::empty<int>; static_assert(ranges::empty(e)); static_assert(0 == e.size()); β€” end example]

24.6.2.2 Class template empty_­view [range.empty.view]

namespace std::ranges { template<class T> requires is_object_v<T> class empty_view : public view_interface<empty_view<T>> { public: static constexpr T* begin() noexcept { return nullptr; } static constexpr T* end() noexcept { return nullptr; } static constexpr T* data() noexcept { return nullptr; } static constexpr size_t size() noexcept { return 0; } static constexpr bool empty() noexcept { return true; } }; }

24.6.3 Single view [range.single]

24.6.3.1 Overview [range.single.overview]

single_­view produces a view that contains exactly one element of a specified value.
The name views​::​single denotes a customization point object ([customization.point.object]).
Given a subexpression E, the expression views​::​single(E) is expression-equivalent to single_­view<decay_­t<decltype((E))>>(E).
[Example 1: for (int i : views::single(4)) cout << i; // prints 4 β€” end example]

24.6.3.2 Class template single_­view [range.single.view]

namespace std::ranges { template<copy_­constructible T> requires is_object_v<T> class single_view : public view_interface<single_view<T>> { private: copyable-box<T> value_; // exposition only (see [range.copy.wrap]) public: single_view() requires default_­initializable<T> = default; constexpr explicit single_view(const T& t); constexpr explicit single_view(T&& t); template<class... Args> requires constructible_­from<T, Args...> constexpr explicit single_view(in_place_t, Args&&... args); constexpr T* begin() noexcept; constexpr const T* begin() const noexcept; constexpr T* end() noexcept; constexpr const T* end() const noexcept; static constexpr size_t size() noexcept; constexpr T* data() noexcept; constexpr const T* data() const noexcept; }; template<class T> single_view(T) -> single_view<T>; }
constexpr explicit single_view(const T& t);
Effects: Initializes value_­ with t.
constexpr explicit single_view(T&& t);
Effects: Initializes value_­ with std​::​move(t).
template<class... Args> requires constructible_­from<T, Args...> constexpr explicit single_view(in_place_t, Args&&... args);
Effects: Initializes value_­ as if by value_­{in_­place, std​::​forward<Args>(args)...}.
constexpr T* begin() noexcept; constexpr const T* begin() const noexcept;
Effects: Equivalent to: return data();
constexpr T* end() noexcept; constexpr const T* end() const noexcept;
Effects: Equivalent to: return data() + 1;
static constexpr size_t size() noexcept;
Effects: Equivalent to: return 1;
constexpr T* data() noexcept; constexpr const T* data() const noexcept;
Effects: Equivalent to: return value_­.operator->();

24.6.4 Iota view [range.iota]

24.6.4.1 Overview [range.iota.overview]

iota_­view generates a sequence of elements by repeatedly incrementing an initial value.
The name views​::​iota denotes a customization point object ([customization.point.object]).
Given subexpressions E and F, the expressions views​::​iota(E) and views​::​iota(E, F) are expression-equivalent to iota_­view(E) and iota_­view(E, F), respectively.
[Example 1: for (int i : views::iota(1, 10)) cout << i << ' '; // prints: 1 2 3 4 5 6 7 8 9 β€” end example]

24.6.4.2 Class template iota_­view [range.iota.view]

namespace std::ranges { template<class I> concept decrementable = see below; // exposition only template<class I> concept advanceable = see below; // exposition only template<weakly_­incrementable W, semiregular Bound = unreachable_sentinel_t> requires weakly-equality-comparable-with<W, Bound> && copyable<W> class iota_view : public view_interface<iota_view<W, Bound>> { private: // [range.iota.iterator], class iota_­view​::​iterator struct iterator; // exposition only // [range.iota.sentinel], class iota_­view​::​sentinel struct sentinel; // exposition only W value_ = W(); // exposition only Bound bound_ = Bound(); // exposition only public: iota_view() requires default_­initializable<W> = default; constexpr explicit iota_view(W value); constexpr iota_view(type_identity_t<W> value, type_identity_t<Bound> bound); constexpr iota_view(iterator first, see below last); constexpr iterator begin() const; constexpr auto end() const; constexpr iterator end() const requires same_­as<W, Bound>; constexpr auto size() const requires see below; }; template<class W, class Bound> requires (!is-integer-like<W> || !is-integer-like<Bound> || (is-signed-integer-like<W> == is-signed-integer-like<Bound>)) iota_view(W, Bound) -> iota_view<W, Bound>; }
Let IOTA-DIFF-T(W) be defined as follows:
  • If W is not an integral type, or if it is an integral type and sizeof(iter_­difference_­t<W>) is greater than sizeof(W), then IOTA-DIFF-T(W) denotes iter_­difference_­t<W>.
  • Otherwise, IOTA-DIFF-T(W) is a signed integer type of width greater than the width of W if such a type exists.
  • Otherwise, IOTA-DIFF-T(W) is an unspecified signed-integer-like type ([iterator.concept.winc]) of width not less than the width of W.
    [Note 1:
    It is unspecified whether this type satisfies weakly_­incrementable.
    β€” end note]
The exposition-only decrementable concept is equivalent to:
template<class I> concept decrementable = incrementable<I> && requires(I i) { { --i } -> same_­as<I&>; { i-- } -> same_­as<I>; };
When an object is in the domain of both pre- and post-decrement, the object is said to be decrementable.
Let a and b be equal objects of type I.
I models decrementable only if
  • If a and b are decrementable, then the following are all true:
  • If a and b are incrementable, then bool(--(++a) == b).
The exposition-only advanceable concept is equivalent to:
template<class I> concept advanceable = decrementable<I> && totally_­ordered<I> && requires(I i, const I j, const IOTA-DIFF-T(I) n) { { i += n } -> same_­as<I&>; { i -= n } -> same_­as<I&>; I(j + n); I(n + j); I(j - n); { j - j } -> convertible_­to<IOTA-DIFF-T(I)>; };
Let D be IOTA-DIFF-T(I).
Let a and b be objects of type I such that b is reachable from a after n applications of ++a, for some value n of type D.
I models advanceable only if
  • (a += n) is equal to b.
  • addressof(a += n) is equal to addressof(a).
  • I(a + n) is equal to (a += n).
  • For any two positive values x and y of type D, if I(a + D(x + y)) is well-defined, then I(a + D(x + y)) is equal to I(I(a + x) + y).
  • I(a + D(0)) is equal to a.
  • If I(a + D(n - 1)) is well-defined, then I(a + n) is equal to [](I c) { return ++c; }(I(a + D(n - 1))).
  • (b += -n) is equal to a.
  • (b -= n) is equal to a.
  • addressof(b -= n) is equal to addressof(b).
  • I(b - n) is equal to (b -= n).
  • D(b - a) is equal to n.
  • D(a - b) is equal to D(-n).
  • bool(a <= b) is true.
constexpr explicit iota_view(W value);
Preconditions: Bound denotes unreachable_­sentinel_­t or Bound() is reachable from value.
Effects: Initializes value_­ with value.
constexpr iota_view(type_identity_t<W> value, type_identity_t<Bound> bound);
Preconditions: Bound denotes unreachable_­sentinel_­t or bound is reachable from value.
When W and Bound model totally_­ordered_­with, then bool(value <= bound) is true.
Effects: Initializes value_­ with value and bound_­ with bound.
constexpr iota_view(iterator first, see below last);
Effects: Equivalent to:
  • If same_­as<W, Bound> is true, iota_­view(first.value_­, last.value_­).
  • Otherwise, if Bound denotes unreachable_­sentinel_­t, iota_­view(first.value_­, last).
  • Otherwise, iota_­view(first.value_­, last.bound_­).
Remarks: The type of last is:
constexpr iterator begin() const;
Effects: Equivalent to: return iterator{value_­};
constexpr auto end() const;
Effects: Equivalent to: if constexpr (same_­as<Bound, unreachable_sentinel_t>) return unreachable_sentinel; else return sentinel{bound_};
constexpr iterator end() const requires same_­as<W, Bound>;
Effects: Equivalent to: return iterator{bound_­};
constexpr auto size() const requires see below;
Effects: Equivalent to: if constexpr (is-integer-like<W> && is-integer-like<Bound>) return (value_ < 0) ? ((bound_ < 0) ? to-unsigned-like(-value_) - to-unsigned-like(-bound_) : to-unsigned-like(bound_) + to-unsigned-like(-value_)) : to-unsigned-like(bound_) - to-unsigned-like(value_); else return to-unsigned-like(bound_ - value_);
Remarks: The expression in the requires-clause is equivalent to: (same_­as<W, Bound> && advanceable<W>) || (integral<W> && integral<Bound>) || sized_­sentinel_­for<Bound, W>

24.6.4.3 Class iota_­view​::​iterator [range.iota.iterator]

namespace std::ranges { template<weakly_­incrementable W, semiregular Bound> requires weakly-equality-comparable-with<W, Bound> && copyable<W> struct iota_view<W, Bound>::iterator { private: W value_ = W(); // exposition only public: using iterator_concept = see below; using iterator_category = input_iterator_tag; // present only if W models incrementable using value_type = W; using difference_type = IOTA-DIFF-T(W); iterator() requires default_­initializable<W> = default; constexpr explicit iterator(W value); constexpr W operator*() const noexcept(is_nothrow_copy_constructible_v<W>); constexpr iterator& operator++(); constexpr void operator++(int); constexpr iterator operator++(int) requires incrementable<W>; constexpr iterator& operator--() requires decrementable<W>; constexpr iterator operator--(int) requires decrementable<W>; constexpr iterator& operator+=(difference_type n) requires advanceable<W>; constexpr iterator& operator-=(difference_type n) requires advanceable<W>; constexpr W operator[](difference_type n) const requires advanceable<W>; friend constexpr bool operator==(const iterator& x, const iterator& y) requires equality_­comparable<W>; friend constexpr bool operator<(const iterator& x, const iterator& y) requires totally_­ordered<W>; friend constexpr bool operator>(const iterator& x, const iterator& y) requires totally_­ordered<W>; friend constexpr bool operator<=(const iterator& x, const iterator& y) requires totally_­ordered<W>; friend constexpr bool operator>=(const iterator& x, const iterator& y) requires totally_­ordered<W>; friend constexpr auto operator<=>(const iterator& x, const iterator& y) requires totally_­ordered<W> && three_­way_­comparable<W>; friend constexpr iterator operator+(iterator i, difference_type n) requires advanceable<W>; friend constexpr iterator operator+(difference_type n, iterator i) requires advanceable<W>; friend constexpr iterator operator-(iterator i, difference_type n) requires advanceable<W>; friend constexpr difference_type operator-(const iterator& x, const iterator& y) requires advanceable<W>; }; }
iterator​::​iterator_­concept is defined as follows:
  • If W models advanceable, then iterator_­concept is random_­access_­iterator_­tag.
  • Otherwise, if W models decrementable, then iterator_­concept is bidirectional_­iterator_­tag.
  • Otherwise, if W models incrementable, then iterator_­concept is forward_­iterator_­tag.
  • Otherwise, iterator_­concept is input_­iterator_­tag.
[Note 1:
Overloads for iter_­move and iter_­swap are omitted intentionally.
β€” end note]
constexpr explicit iterator(W value);
Effects: Initializes value_­ with value.
constexpr W operator*() const noexcept(is_nothrow_copy_constructible_v<W>);
Effects: Equivalent to: return value_­;
[Note 2:
The noexcept clause is needed by the default iter_­move implementation.
β€” end note]
constexpr iterator& operator++();
Effects: Equivalent to: ++value_; return *this;
constexpr void operator++(int);
Effects: Equivalent to ++*this.
constexpr iterator operator++(int) requires incrementable<W>;
Effects: Equivalent to: auto tmp = *this; ++*this; return tmp;
constexpr iterator& operator--() requires decrementable<W>;
Effects: Equivalent to: --value_; return *this;
constexpr iterator operator--(int) requires decrementable<W>;
Effects: Equivalent to: auto tmp = *this; --*this; return tmp;
constexpr iterator& operator+=(difference_type n) requires advanceable<W>;
Effects: Equivalent to: if constexpr (is-integer-like<W> && !is-signed-integer-like<W>) { if (n >= difference_type(0)) value_ += static_cast<W>(n); else value_ -= static_cast<W>(-n); } else { value_ += n; } return *this;
constexpr iterator& operator-=(difference_type n) requires advanceable<W>;
Effects: Equivalent to: if constexpr (is-integer-like<W> && !is-signed-integer-like<W>) { if (n >= difference_type(0)) value_ -= static_cast<W>(n); else value_ += static_cast<W>(-n); } else { value_ -= n; } return *this;
constexpr W operator[](difference_type n) const requires advanceable<W>;
Effects: Equivalent to: return W(value_­ + n);
friend constexpr bool operator==(const iterator& x, const iterator& y) requires equality_­comparable<W>;
Effects: Equivalent to: return x.value_­ == y.value_­;
friend constexpr bool operator<(const iterator& x, const iterator& y) requires totally_­ordered<W>;
Effects: Equivalent to: return x.value_­ < y.value_­;
friend constexpr bool operator>(const iterator& x, const iterator& y) requires totally_­ordered<W>;
Effects: Equivalent to: return y < x;
friend constexpr bool operator<=(const iterator& x, const iterator& y) requires totally_­ordered<W>;
Effects: Equivalent to: return !(y < x);
friend constexpr bool operator>=(const iterator& x, const iterator& y) requires totally_­ordered<W>;
Effects: Equivalent to: return !(x < y);
friend constexpr auto operator<=>(const iterator& x, const iterator& y) requires totally_­ordered<W> && three_­way_­comparable<W>;
Effects: Equivalent to: return x.value_­ <=> y.value_­;
friend constexpr iterator operator+(iterator i, difference_type n) requires advanceable<W>;
Effects: Equivalent to: return i += n;
friend constexpr iterator operator+(difference_type n, iterator i) requires advanceable<W>;
Effects: Equivalent to: return i + n;
friend constexpr iterator operator-(iterator i, difference_type n) requires advanceable<W>;
Effects: Equivalent to: return i -= n;
friend constexpr difference_type operator-(const iterator& x, const iterator& y) requires advanceable<W>;
Effects: Equivalent to: using D = difference_type; if constexpr (is-integer-like<W>) { if constexpr (is-signed-integer-like<W>) return D(D(x.value_) - D(y.value_)); else return (y.value_ > x.value_) ? D(-D(y.value_ - x.value_)) : D(x.value_ - y.value_); } else { return x.value_ - y.value_; }

24.6.4.4 Class iota_­view​::​sentinel [range.iota.sentinel]

namespace std::ranges { template<weakly_­incrementable W, semiregular Bound> requires weakly-equality-comparable-with<W, Bound> && copyable<W> struct iota_view<W, Bound>::sentinel { private: Bound bound_ = Bound(); // exposition only public: sentinel() = default; constexpr explicit sentinel(Bound bound); friend constexpr bool operator==(const iterator& x, const sentinel& y); friend constexpr iter_difference_t<W> operator-(const iterator& x, const sentinel& y) requires sized_­sentinel_­for<Bound, W>; friend constexpr iter_difference_t<W> operator-(const sentinel& x, const iterator& y) requires sized_­sentinel_­for<Bound, W>; }; }
constexpr explicit sentinel(Bound bound);
Effects: Initializes bound_­ with bound.
friend constexpr bool operator==(const iterator& x, const sentinel& y);
Effects: Equivalent to: return x.value_­ == y.bound_­;
friend constexpr iter_difference_t<W> operator-(const iterator& x, const sentinel& y) requires sized_­sentinel_­for<Bound, W>;
Effects: Equivalent to: return x.value_­ - y.bound_­;
friend constexpr iter_difference_t<W> operator-(const sentinel& x, const iterator& y) requires sized_­sentinel_­for<Bound, W>;
Effects: Equivalent to: return -(y - x);

24.6.5 Istream view [range.istream]

24.6.5.1 Overview [range.istream.overview]

basic_­istream_­view models input_­range and reads (using operator>>) successive elements from its corresponding input stream.
[Example 1: auto ints = istringstream{"0 1 2 3 4"}; ranges::copy(ranges::istream_view<int>(ints), ostream_iterator<int>{cout, "-"}); // prints 0-1-2-3-4- β€” end example]

24.6.5.2 Class template basic_­istream_­view [range.istream.view]

namespace std::ranges { template<class Val, class CharT, class Traits> concept stream-extractable = // exposition only requires(basic_istream<CharT, Traits>& is, Val& t) { is >> t; }; template<movable Val, class CharT, class Traits> requires default_­initializable<Val> && stream-extractable<Val, CharT, Traits> class basic_istream_view : public view_interface<basic_istream_view<Val, CharT, Traits>> { public: constexpr explicit basic_istream_view(basic_istream<CharT, Traits>& stream); constexpr auto begin() { *stream_ >> value_; return iterator{*this}; } constexpr default_sentinel_t end() const noexcept; private: struct iterator; // exposition only basic_istream<CharT, Traits>* stream_; // exposition only Val value_; // exposition only }; }
constexpr explicit basic_istream_view(basic_istream<CharT, Traits>& stream);
Effects: Initializes stream_­ with addressof(stream).
constexpr default_sentinel_t end() const noexcept;
Effects: Equivalent to: return default_­sentinel;
template<class Val, class CharT, class Traits> basic_istream_view<Val, CharT, Traits> istream_view(basic_istream<CharT, Traits>& s);
Effects: Equivalent to: return basic_­istream_­view<Val, CharT, Traits>{s};

24.6.5.3 Class template basic_­istream_­view​::​iterator [range.istream.iterator]

namespace std::ranges { template<movable Val, class CharT, class Traits> requires default_­initializable<Val> && stream-extractable<Val, CharT, Traits> class basic_istream_view<Val, CharT, Traits>::iterator { // exposition only public: using iterator_concept = input_iterator_tag; using difference_type = ptrdiff_t; using value_type = Val; constexpr explicit iterator(basic_istream_view& parent) noexcept; iterator(const iterator&) = delete; iterator(iterator&&) = default; iterator& operator=(const iterator&) = delete; iterator& operator=(iterator&&) = default; iterator& operator++(); void operator++(int); Val& operator*() const; friend bool operator==(const iterator& x, default_sentinel_t); private: basic_istream_view* parent_; // exposition only }; }
constexpr explicit iterator(basic_istream_view& parent) noexcept;
Effects: Initializes parent_­ with addressof(parent).
iterator& operator++();
Effects: Equivalent to: *parent_->stream_ >> parent_->value_; return *this;
void operator++(int);
Effects: Equivalent to ++*this.
Val& operator*() const;
Effects: Equivalent to: return parent_­->value_­;
friend bool operator==(const iterator& x, default_sentinel_t);
Effects: Equivalent to: return !*x.parent_­->stream_­;

24.7 Range adaptors [range.adaptors]

24.7.1 General [range.adaptors.general]

Subclause [range.adaptors] defines range adaptors, which are utilities that transform a range into a view with custom behaviors.
These adaptors can be chained to create pipelines of range transformations that evaluate lazily as the resulting view is iterated.
Range adaptors are declared in namespace std​::​ranges​::​views.
The bitwise OR operator is overloaded for the purpose of creating adaptor chain pipelines.
The adaptors also support function call syntax with equivalent semantics.
[Example 1: vector<int> ints{0,1,2,3,4,5}; auto even = [](int i) { return 0 == i % 2; }; auto square = [](int i) { return i * i; }; for (int i : ints | views::filter(even) | views::transform(square)) { cout << i << ' '; // prints: 0 4 16 } assert(ranges::equal(ints | views::filter(even), views::filter(ints, even))); β€” end example]

24.7.2 Range adaptor objects [range.adaptor.object]

A range adaptor closure object is a unary function object that accepts a viewable_­range argument and returns a view.
For a range adaptor closure object C and an expression R such that decltype((R)) models viewable_­range, the following expressions are equivalent and yield a view: C(R) R | C
Given an additional range adaptor closure object D, the expression C | D produces another range adaptor closure object E.
E is a perfect forwarding call wrapper ([func.require]) with the following properties:
  • Its target object is an object d of type decay_­t<decltype((D))> direct-non-list-initialized with D.
  • It has one bound argument entity, an object c of type decay_­t<decltype((C))> direct-non-list-initialized with C.
  • Its call pattern is d(c(arg)), where arg is the argument used in a function call expression of E.
The expression C | D is well-formed if and only if the initializations of the state entities of E are all well-formed.
A range adaptor object is a customization point object ([customization.point.object]) that accepts a viewable_­range as its first argument and returns a view.
If a range adaptor object accepts only one argument, then it is a range adaptor closure object.
If a range adaptor object adaptor accepts more than one argument, then let range be an expression such that decltype((range)) models viewable_­range, let args... be arguments such that adaptor(range, args...) is a well-formed expression as specified in the rest of subclause [range.adaptors], and let BoundArgs be a pack that denotes decay_­t<decltype((args))>....
The expression adaptor(args...) produces a range adaptor closure object f that is a perfect forwarding call wrapper with the following properties:
  • Its target object is a copy of adaptor.
  • Its bound argument entities bound_­args consist of objects of types BoundArgs... direct-non-list-initialized with std​::​forward<decltype((args))>(args)..., respectively.
  • Its call pattern is adaptor(r, bound_­args...), where r is the argument used in a function call expression of f.
The expression adaptor(args...) is well-formed if and only if the initialization of the bound argument entities of the result, as specified above, are all well-formed.

24.7.3 Copyable wrapper [range.copy.wrap]

Many types in this subclause are specified in terms of an exposition-only class template copyable-box.
copyable-box<T> behaves exactly like optional<T> with the following differences:
  • copyable-box<T> constrains its type parameter T with copy_­constructible<T> && is_­object_­v<T>.
  • The default constructor of copyable-box<T> is equivalent to: constexpr copyable-box() noexcept(is_nothrow_default_constructible_v<T>) requires default_­initializable<T> : copyable-box{in_place} { }
  • If copyable<T> is not modeled, the copy assignment operator is equivalent to: copyable-box& operator=(const copyable-box& that) noexcept(is_nothrow_copy_constructible_v<T>) { if (this != addressof(that)) { if (that) emplace(*that); else reset(); } return *this; }
  • If movable<T> is not modeled, the move assignment operator is equivalent to: copyable-box& operator=(copyable-box&& that) noexcept(is_nothrow_move_constructible_v<T>) { if (this != addressof(that)) { if (that) emplace(std::move(*that)); else reset(); } return *this; }
Recommended practice: copyable-box<T> should store only a T if either T models copyable or is_­nothrow_­move_­constructible_­v<T> && is_­nothrow_­copy_­constructible_­v<T> is true.

24.7.4 Non-propagating cache [range.nonprop.cache]

Some types in subclause [range.adaptors] are specified in terms of an exposition-only class template non-propagating-​cache.
non-propagating-cache<T> behaves exactly like optional<T> with the following differences:
  • non-propagating-cache<T> constrains its type parameter T with is_­object_­v<T>.
  • The copy constructor is equivalent to: constexpr non-propagating-cache(const non-propagating-cache&) noexcept { }
  • The move constructor is equivalent to: constexpr non-propagating-cache(non-propagating-cache&& other) noexcept { other.reset(); }
  • The copy assignment operator is equivalent to: constexpr non-propagating-cache& operator=(const non-propagating-cache& other) noexcept { if (addressof(other) != this) reset(); return *this; }
  • The move assignment operator is equivalent to: constexpr non-propagating-cache& operator=(non-propagating-cache&& other) noexcept { reset(); other.reset(); return *this; }
  • non-propagating-cache<T> has an additional member function template specified as follows:
    template<class I> constexpr T& emplace-deref(const I& i); // exposition only
    Mandates: The declaration T t(*i); is well-formed for some invented variable t.
    [Note 1:
    If *i is a prvalue of type cv T, there is no requirement that it is movable ([dcl.init.general]).
    β€” end note]
    Effects: Calls reset().
    Then initializes the contained value as if direct-non-list-initializing an object of type T with the argument *i.
    Postconditions: *this contains a value.
    Returns: A reference to the new contained value.
    Throws: Any exception thrown by the initialization of the contained value.
    Remarks: If an exception is thrown during the initialization of T, *this does not contain a value, and the previous value (if any) has been destroyed.
[Note 2:
non-propagating-cache enables an input view to temporarily cache values as it is iterated over.
β€” end note]

24.7.5 All view [range.all]

24.7.5.1 General [range.all.general]

views​::​all returns a view that includes all elements of its range argument.
The name views​::​all denotes a range adaptor object ([range.adaptor.object]).
Given a subexpression E, the expression views​::​all(E) is expression-equivalent to:
  • decay-copy(E) if the decayed type of E models view.
  • Otherwise, ref_­view{E} if that expression is well-formed.
  • Otherwise, subrange{E}.

24.7.5.2 Class template ref_­view [range.ref.view]

ref_­view is a view of the elements of some other range.
namespace std::ranges { template<range R> requires is_object_v<R> class ref_view : public view_interface<ref_view<R>> { private: R* r_; // exposition only public: template<different-from<ref_view> T> requires see below constexpr ref_view(T&& t); constexpr R& base() const { return *r_; } constexpr iterator_t<R> begin() const { return ranges::begin(*r_); } constexpr sentinel_t<R> end() const { return ranges::end(*r_); } constexpr bool empty() const requires requires { ranges::empty(*r_); } { return ranges::empty(*r_); } constexpr auto size() const requires sized_­range<R> { return ranges::size(*r_); } constexpr auto data() const requires contiguous_­range<R> { return ranges::data(*r_); } }; template<class R> ref_view(R&) -> ref_view<R>; }
template<different-from<ref_view> T> requires see below constexpr ref_view(T&& t);
Effects: Initializes r_­ with addressof(static_­cast<R&>(std​::​forward<T>(t))).
Remarks: Let FUN denote the exposition-only functions void FUN(R&); void FUN(R&&) = delete;
The expression in the requires-clause is equivalent to: convertible_­to<T, R&> && requires { FUN(declval<T>()); }

24.7.6 Filter view [range.filter]

24.7.6.1 Overview [range.filter.overview]

filter_­view presents a view of the elements of an underlying sequence that satisfy a predicate.
The name views​::​filter denotes a range adaptor object ([range.adaptor.object]).
Given subexpressions E and P, the expression views​::​filter(E, P) is expression-equivalent to filter_­view(E, P).
[Example 1: vector<int> is{ 0, 1, 2, 3, 4, 5, 6 }; auto evens = views::filter(is, [](int i) { return 0 == i % 2; }); for (int i : evens) cout << i << ' '; // prints: 0 2 4 6 β€” end example]

24.7.6.2 Class template filter_­view [range.filter.view]

namespace std::ranges { template<input_­range V, indirect_­unary_­predicate<iterator_t<V>> Pred> requires view<V> && is_object_v<Pred> class filter_view : public view_interface<filter_view<V, Pred>> { private: V base_ = V(); // exposition only copyable-box<Pred> pred_; // exposition only // [range.filter.iterator], class filter_­view​::​iterator class iterator; // exposition only // [range.filter.sentinel], class filter_­view​::​sentinel class sentinel; // exposition only public: filter_view() requires default_­initializable<V> && default_­initializable<Pred> = default; constexpr filter_view(V base, Pred pred); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr const Pred& pred() const; constexpr iterator begin(); constexpr auto end() { if constexpr (common_­range<V>) return iterator{*this, ranges::end(base_)}; else return sentinel{*this}; } }; template<class R, class Pred> filter_view(R&&, Pred) -> filter_view<views::all_t<R>, Pred>; }
constexpr filter_view(V base, Pred pred);
Effects: Initializes base_­ with std​::​move(base) and initializes pred_­ with std​::​move(pred).
constexpr const Pred& pred() const;
Effects: Equivalent to: return *pred_­;
constexpr iterator begin();
Preconditions: pred_­.has_­value() is true.
Returns: {*this, ranges​::​find_­if(base_­, ref(*pred_­))}.
Remarks: In order to provide the amortized constant time complexity required by the range concept when filter_­view models forward_­range, this function caches the result within the filter_­view for use on subsequent calls.

24.7.6.3 Class filter_­view​::​iterator [range.filter.iterator]

namespace std::ranges { template<input_­range V, indirect_­unary_­predicate<iterator_t<V>> Pred> requires view<V> && is_object_v<Pred> class filter_view<V, Pred>::iterator { private: iterator_t<V> current_ = iterator_t<V>(); // exposition only filter_view* parent_ = nullptr; // exposition only public: using iterator_concept = see below; using iterator_category = see below; // not always present using value_type = range_value_t<V>; using difference_type = range_difference_t<V>; iterator() requires default_­initializable<iterator_t<V>> = default; constexpr iterator(filter_view& parent, iterator_t<V> current); constexpr const iterator_t<V>& base() const &; constexpr iterator_t<V> base() &&; constexpr range_reference_t<V> operator*() const; constexpr iterator_t<V> operator->() const requires has-arrow<iterator_t<V>> && copyable<iterator_t<V>>; constexpr iterator& operator++(); constexpr void operator++(int); constexpr iterator operator++(int) requires forward_­range<V>; constexpr iterator& operator--() requires bidirectional_­range<V>; constexpr iterator operator--(int) requires bidirectional_­range<V>; friend constexpr bool operator==(const iterator& x, const iterator& y) requires equality_­comparable<iterator_t<V>>; friend constexpr range_rvalue_reference_t<V> iter_move(const iterator& i) noexcept(noexcept(ranges::iter_move(i.current_))); friend constexpr void iter_swap(const iterator& x, const iterator& y) noexcept(noexcept(ranges::iter_swap(x.current_, y.current_))) requires indirectly_­swappable<iterator_t<V>>; }; }
Modification of the element a filter_­view​::​iterator denotes is permitted, but results in undefined behavior if the resulting value does not satisfy the filter predicate.
iterator​::​iterator_­concept is defined as follows:
  • If V models bidirectional_­range, then iterator_­concept denotes bidirectional_­iterator_­tag.
  • Otherwise, if V models forward_­range, then iterator_­concept denotes forward_­iterator_­tag.
  • Otherwise, iterator_­concept denotes input_­iterator_­tag.
The member typedef-name iterator_­category is defined if and only if V models forward_­range.
In that case, iterator​::​iterator_­category is defined as follows:
  • Let C denote the type iterator_­traits<iterator_­t<V>>​::​iterator_­category.
  • If C models derived_­from<bidirectional_­iterator_­tag>, then iterator_­category denotes bidirectional_­iterator_­tag.
  • Otherwise, if C models derived_­from<forward_­iterator_­tag>, then iterator_­category denotes forward_­iterator_­tag.
  • Otherwise, iterator_­category denotes C.
constexpr iterator(filter_view& parent, iterator_t<V> current);
Effects: Initializes current_­ with std​::​move(current) and parent_­ with addressof(parent).
constexpr const iterator_t<V>& base() const &;
Effects: Equivalent to: return current_­;
constexpr iterator_t<V> base() &&;
Effects: Equivalent to: return std​::​move(current_­);
constexpr range_reference_t<V> operator*() const;
Effects: Equivalent to: return *current_­;
constexpr iterator_t<V> operator->() const requires has-arrow<iterator_t<V>> && copyable<iterator_t<V>>;
Effects: Equivalent to: return current_­;
constexpr iterator& operator++();
Effects: Equivalent to: current_ = ranges::find_if(std::move(++current_), ranges::end(parent_->base_), ref(*parent_->pred_)); return *this;
constexpr void operator++(int);
Effects: Equivalent to ++*this.
constexpr iterator operator++(int) requires forward_­range<V>;
Effects: Equivalent to: auto tmp = *this; ++*this; return tmp;
constexpr iterator& operator--() requires bidirectional_­range<V>;
Effects: Equivalent to: do --current_; while (!invoke(*parent_->pred_, *current_)); return *this;
constexpr iterator operator--(int) requires bidirectional_­range<V>;
Effects: Equivalent to: auto tmp = *this; --*this; return tmp;
friend constexpr bool operator==(const iterator& x, const iterator& y) requires equality_­comparable<iterator_t<V>>;
Effects: Equivalent to: return x.current_­ == y.current_­;
friend constexpr range_rvalue_reference_t<V> iter_move(const iterator& i) noexcept(noexcept(ranges::iter_move(i.current_­)));
Effects: Equivalent to: return ranges​::​iter_­move(i.current_­);
friend constexpr void iter_swap(const iterator& x, const iterator& y) noexcept(noexcept(ranges::iter_swap(x.current_­, y.current_­))) requires indirectly_­swappable<iterator_t<V>>;
Effects: Equivalent to ranges​::​iter_­swap(x.current_­, y.current_­).

24.7.6.4 Class filter_­view​::​sentinel [range.filter.sentinel]

namespace std::ranges { template<input_­range V, indirect_­unary_­predicate<iterator_t<V>> Pred> requires view<V> && is_object_v<Pred> class filter_view<V, Pred>::sentinel { private: sentinel_t<V> end_ = sentinel_t<V>(); // exposition only public: sentinel() = default; constexpr explicit sentinel(filter_view& parent); constexpr sentinel_t<V> base() const; friend constexpr bool operator==(const iterator& x, const sentinel& y); }; }
constexpr explicit sentinel(filter_view& parent);
Effects: Initializes end_­ with ranges​::​end(parent.base_­).
constexpr sentinel_t<V> base() const;
Effects: Equivalent to: return end_­;
friend constexpr bool operator==(const iterator& x, const sentinel& y);
Effects: Equivalent to: return x.current_­ == y.end_­;

24.7.7 Transform view [range.transform]

24.7.7.1 Overview [range.transform.overview]

transform_­view presents a view of an underlying sequence after applying a transformation function to each element.
The name views​::​transform denotes a range adaptor object ([range.adaptor.object]).
Given subexpressions E and F, the expression views​::​transform(E, F) is expression-equivalent to transform_­view(E, F).
[Example 1: vector<int> is{ 0, 1, 2, 3, 4 }; auto squares = views::transform(is, [](int i) { return i * i; }); for (int i : squares) cout << i << ' '; // prints: 0 1 4 9 16 β€” end example]

24.7.7.2 Class template transform_­view [range.transform.view]

namespace std::ranges { template<input_­range V, copy_­constructible F> requires view<V> && is_object_v<F> && regular_­invocable<F&, range_reference_t<V>> && can-reference<invoke_result_t<F&, range_reference_t<V>>> class transform_view : public view_interface<transform_view<V, F>> { private: // [range.transform.iterator], class template transform_­view​::​iterator template<bool> struct iterator; // exposition only // [range.transform.sentinel], class template transform_­view​::​sentinel template<bool> struct sentinel; // exposition only V base_ = V(); // exposition only copyable-box<F> fun_; // exposition only public: transform_view() requires default_­initializable<V> && default_­initializable<F> = default; constexpr transform_view(V base, F fun); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr iterator<false> begin(); constexpr iterator<true> begin() const requires range<const V> && regular_­invocable<const F&, range_reference_t<const V>>; constexpr sentinel<false> end(); constexpr iterator<false> end() requires common_­range<V>; constexpr sentinel<true> end() const requires range<const V> && regular_­invocable<const F&, range_reference_t<const V>>; constexpr iterator<true> end() const requires common_­range<const V> && regular_­invocable<const F&, range_reference_t<const V>>; constexpr auto size() requires sized_­range<V> { return ranges::size(base_); } constexpr auto size() const requires sized_­range<const V> { return ranges::size(base_); } }; template<class R, class F> transform_view(R&&, F) -> transform_view<views::all_t<R>, F>; }
constexpr transform_view(V base, F fun);
Effects: Initializes base_­ with std​::​move(base) and fun_­ with std​::​move(fun).
constexpr iterator<false> begin();
Effects: Equivalent to: return iterator<false>{*this, ranges::begin(base_)};
constexpr iterator<true> begin() const requires range<const V> && regular_­invocable<const F&, range_reference_t<const V>>;
Effects: Equivalent to: return iterator<true>{*this, ranges::begin(base_)};
constexpr sentinel<false> end();
Effects: Equivalent to: return sentinel<false>{ranges::end(base_)};
constexpr iterator<false> end() requires common_­range<V>;
Effects: Equivalent to: return iterator<false>{*this, ranges::end(base_)};
constexpr sentinel<true> end() const requires range<const V> && regular_­invocable<const F&, range_reference_t<const V>>;
Effects: Equivalent to: return sentinel<true>{ranges::end(base_)};
constexpr iterator<true> end() const requires common_­range<const V> && regular_­invocable<const F&, range_reference_t<const V>>;
Effects: Equivalent to: return iterator<true>{*this, ranges::end(base_)};

24.7.7.3 Class template transform_­view​::​iterator [range.transform.iterator]

namespace std::ranges { template<input_­range V, copy_­constructible F> requires view<V> && is_object_v<F> && regular_­invocable<F&, range_reference_t<V>> && can-reference<invoke_result_t<F&, range_reference_t<V>>> template<bool Const> class transform_view<V, F>::iterator { private: using Parent = maybe-const<Const, transform_view>; // exposition only using Base = maybe-const<Const, V>; // exposition only iterator_t<Base> current_ = iterator_t<Base>(); // exposition only Parent* parent_ = nullptr; // exposition only public: using iterator_concept = see below; using iterator_category = see below; // not always present using value_type = remove_cvref_t<invoke_result_t<F&, range_reference_t<Base>>>; using difference_type = range_difference_t<Base>; iterator() requires default_­initializable<iterator_t<Base>> = default; constexpr iterator(Parent& parent, iterator_t<Base> current); constexpr iterator(iterator<!Const> i) requires Const && convertible_­to<iterator_t<V>, iterator_t<Base>>; constexpr const iterator_t<Base>& base() const &; constexpr iterator_t<Base> base() &&; constexpr decltype(auto) operator*() const { return invoke(*parent_->fun_, *current_); } constexpr iterator& operator++(); constexpr void operator++(int); constexpr iterator operator++(int) requires forward_­range<Base>; constexpr iterator& operator--() requires bidirectional_­range<Base>; constexpr iterator operator--(int) requires bidirectional_­range<Base>; constexpr iterator& operator+=(difference_type n) requires random_­access_­range<Base>; constexpr iterator& operator-=(difference_type n) requires random_­access_­range<Base>; constexpr decltype(auto) operator[](difference_type n) const requires random_­access_­range<Base> { return invoke(*parent_->fun_, current_[n]); } friend constexpr bool operator==(const iterator& x, const iterator& y) requires equality_­comparable<iterator_t<Base>>; friend constexpr bool operator<(const iterator& x, const iterator& y) requires random_­access_­range<Base>; friend constexpr bool operator>(const iterator& x, const iterator& y) requires random_­access_­range<Base>; friend constexpr bool operator<=(const iterator& x, const iterator& y) requires random_­access_­range<Base>; friend constexpr bool operator>=(const iterator& x, const iterator& y) requires random_­access_­range<Base>; friend constexpr auto operator<=>(const iterator& x, const iterator& y) requires random_­access_­range<Base> && three_­way_­comparable<iterator_t<Base>>; friend constexpr iterator operator+(iterator i, difference_type n) requires random_­access_­range<Base>; friend constexpr iterator operator+(difference_type n, iterator i) requires random_­access_­range<Base>; friend constexpr iterator operator-(iterator i, difference_type n) requires random_­access_­range<Base>; friend constexpr difference_type operator-(const iterator& x, const iterator& y) requires sized_­sentinel_­for<iterator_t<Base>, iterator_t<Base>>; friend constexpr decltype(auto) iter_move(const iterator& i) noexcept(noexcept(invoke(*i.parent_->fun_, *i.current_))) { if constexpr (is_lvalue_reference_v<decltype(*i)>) return std::move(*i); else return *i; } }; }
iterator​::​iterator_­concept is defined as follows:
The member typedef-name iterator_­category is defined if and only if Base models forward_­range.
In that case, iterator​::​iterator_­category is defined as follows: Let C denote the type iterator_­traits<iterator_­t<Base>>​::​iterator_­category.
  • If is_­lvalue_­reference_­v<invoke_­result_­t<F&, range_­reference_­t<Base>>> is true, then
    • if C models derived_­from<contiguous_­iterator_­tag>, iterator_­category denotes random_­access_­iterator_­tag;
    • otherwise, iterator_­category denotes C.
  • Otherwise, iterator_­category denotes input_­iterator_­tag.
constexpr iterator(Parent& parent, iterator_t<Base> current);
Effects: Initializes current_­ with std​::​move(current) and parent_­ with addressof(parent).
constexpr iterator(iterator<!Const> i) requires Const && convertible_­to<iterator_t<V>, iterator_t<Base>>;
Effects: Initializes current_­ with std​::​move(i.current_­) and parent_­ with i.parent_­.
constexpr const iterator_t<Base>& base() const &;
Effects: Equivalent to: return current_­;
constexpr iterator_t<Base> base() &&;
Effects: Equivalent to: return std​::​move(current_­);
constexpr iterator& operator++();
Effects: Equivalent to: ++current_; return *this;
constexpr void operator++(int);
Effects: Equivalent to ++current_­.
constexpr iterator operator++(int) requires forward_­range<Base>;
Effects: Equivalent to: auto tmp = *this; ++*this; return tmp;
constexpr iterator& operator--() requires bidirectional_­range<Base>;
Effects: Equivalent to: --current_; return *this;
constexpr iterator operator--(int) requires bidirectional_­range<Base>;
Effects: Equivalent to: auto tmp = *this; --*this; return tmp;
constexpr iterator& operator+=(difference_type n) requires random_­access_­range<Base>;
Effects: Equivalent to: current_ += n; return *this;
constexpr iterator& operator-=(difference_type n) requires random_­access_­range<Base>;
Effects: Equivalent to: current_ -= n; return *this;
friend constexpr bool operator==(const iterator& x, const iterator& y) requires equality_­comparable<iterator_t<Base>>;
Effects: Equivalent to: return x.current_­ == y.current_­;
friend constexpr bool operator<(const iterator& x, const iterator& y) requires random_­access_­range<Base>;
Effects: Equivalent to: return x.current_­ < y.current_­;
friend constexpr bool operator>(const iterator& x, const iterator& y) requires random_­access_­range<Base>;
Effects: Equivalent to: return y < x;
friend constexpr bool operator<=(const iterator& x, const iterator& y) requires random_­access_­range<Base>;
Effects: Equivalent to: return !(y < x);
friend constexpr bool operator>=(const iterator& x, const iterator& y) requires random_­access_­range<Base>;
Effects: Equivalent to: return !(x < y);
friend constexpr auto operator<=>(const iterator& x, const iterator& y) requires random_­access_­range<Base> && three_­way_­comparable<iterator_t<Base>>;
Effects: Equivalent to: return x.current_­ <=> y.current_­;
friend constexpr iterator operator+(iterator i, difference_type n) requires random_­access_­range<Base>; friend constexpr iterator operator+(difference_type n, iterator i) requires random_­access_­range<Base>;
Effects: Equivalent to: return iterator{*i.parent_­, i.current_­ + n};
friend constexpr iterator operator-(iterator i, difference_type n) requires random_­access_­range<Base>;
Effects: Equivalent to: return iterator{*i.parent_­, i.current_­ - n};
friend constexpr difference_type operator-(const iterator& x, const iterator& y) requires sized_­sentinel_­for<iterator_t<Base>, iterator_t<Base>>;
Effects: Equivalent to: return x.current_­ - y.current_­;

24.7.7.4 Class template transform_­view​::​sentinel [range.transform.sentinel]

namespace std::ranges { template<input_­range V, copy_­constructible F> requires view<V> && is_object_v<F> && regular_­invocable<F&, range_reference_t<V>> && can-reference<invoke_result_t<F&, range_reference_t<V>>> template<bool Const> class transform_view<V, F>::sentinel { private: using Parent = maybe-const<Const, transform_view>; // exposition only using Base = maybe-const<Const, V>; // exposition only sentinel_t<Base> end_ = sentinel_t<Base>(); // exposition only public: sentinel() = default; constexpr explicit sentinel(sentinel_t<Base> end); constexpr sentinel(sentinel<!Const> i) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>; constexpr sentinel_t<Base> base() const; template<bool OtherConst> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const iterator<OtherConst>& x, const sentinel& y); template<bool OtherConst> requires sized_­sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr range_difference_t<maybe-const<OtherConst, V>> operator-(const iterator<OtherConst>& x, const sentinel& y); template<bool OtherConst> requires sized_­sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr range_difference_t<maybe-const<OtherConst, V>> operator-(const sentinel& y, const iterator<OtherConst>& x); }; }
constexpr explicit sentinel(sentinel_t<Base> end);
Effects: Initializes end_­ with end.
constexpr sentinel(sentinel<!Const> i) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>;
Effects: Initializes end_­ with std​::​move(i.end_­).
constexpr sentinel_t<Base> base() const;
Effects: Equivalent to: return end_­;
template<bool OtherConst> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const iterator<OtherConst>& x, const sentinel& y);
Effects: Equivalent to: return x.current_­ == y.end_­;
template<bool OtherConst> requires sized_­sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr range_difference_t<maybe-const<OtherConst, V>> operator-(const iterator<OtherConst>& x, const sentinel& y);
Effects: Equivalent to: return x.current_­ - y.end_­;
template<bool OtherConst> requires sized_­sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr range_difference_t<maybe-const<OtherConst, V>> operator-(const sentinel& y, const iterator<OtherConst>& x);
Effects: Equivalent to: return y.end_­ - x.current_­;

24.7.8 Take view [range.take]

24.7.8.1 Overview [range.take.overview]

take_­view produces a view of the first N elements from another view, or all the elements if the adapted view contains fewer than N.
The name views​::​take denotes a range adaptor object ([range.adaptor.object]).
Let E and F be expressions, let T be remove_­cvref_­t<decltype((E))>, and let D be range_­difference_­t<decltype((E))>.
If decltype((F)) does not model convertible_­to<D>, views​::​take(E, F) is ill-formed.
Otherwise, the expression views​::​take(E, F) is expression-equivalent to:
[Example 1: vector<int> is{0,1,2,3,4,5,6,7,8,9}; for (int i : is | views::take(5)) cout << i << ' '; // prints: 0 1 2 3 4 β€” end example]

24.7.8.2 Class template take_­view [range.take.view]

namespace std::ranges { template<view V> class take_view : public view_interface<take_view<V>> { private: V base_ = V(); // exposition only range_difference_t<V> count_ = 0; // exposition only // [range.take.sentinel], class template take_­view​::​sentinel template<bool> struct sentinel; // exposition only public: take_view() requires default_­initializable<V> = default; constexpr take_view(V base, range_difference_t<V> count); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr auto begin() requires (!simple-view<V>) { if constexpr (sized_­range<V>) { if constexpr (random_­access_­range<V>) return ranges::begin(base_); else { auto sz = size(); return counted_iterator(ranges::begin(base_), sz); } } else return counted_iterator(ranges::begin(base_), count_); } constexpr auto begin() const requires range<const V> { if constexpr (sized_­range<const V>) { if constexpr (random_­access_­range<const V>) return ranges::begin(base_); else { auto sz = size(); return counted_iterator(ranges::begin(base_), sz); } } else return counted_iterator(ranges::begin(base_), count_); } constexpr auto end() requires (!simple-view<V>) { if constexpr (sized_­range<V>) { if constexpr (random_­access_­range<V>) return ranges::begin(base_) + size(); else return default_sentinel; } else return sentinel<false>{ranges::end(base_)}; } constexpr auto end() const requires range<const V> { if constexpr (sized_­range<const V>) { if constexpr (random_­access_­range<const V>) return ranges::begin(base_) + size(); else return default_sentinel; } else return sentinel<true>{ranges::end(base_)}; } constexpr auto size() requires sized_­range<V> { auto n = ranges::size(base_); return ranges::min(n, static_cast<decltype(n)>(count_)); } constexpr auto size() const requires sized_­range<const V> { auto n = ranges::size(base_); return ranges::min(n, static_cast<decltype(n)>(count_)); } }; template<class R> take_view(R&&, range_difference_t<R>) -> take_view<views::all_t<R>>; }
constexpr take_view(V base, range_difference_t<V> count);
Effects: Initializes base_­ with std​::​move(base) and count_­ with count.

24.7.8.3 Class template take_­view​::​sentinel [range.take.sentinel]

namespace std::ranges { template<view V> template<bool Const> class take_view<V>::sentinel { private: using Base = maybe-const<Const, V>; // exposition only template<bool OtherConst> using CI = counted_iterator<iterator_t<maybe-const<OtherConst, V>>>; // exposition only sentinel_t<Base> end_ = sentinel_t<Base>(); // exposition only public: sentinel() = default; constexpr explicit sentinel(sentinel_t<Base> end); constexpr sentinel(sentinel<!Const> s) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>; constexpr sentinel_t<Base> base() const; friend constexpr bool operator==(const CI<Const>& y, const sentinel& x); template<bool OtherConst = !Const> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const CI<OtherConst>& y, const sentinel& x); }; }
constexpr explicit sentinel(sentinel_t<Base> end);
Effects: Initializes end_­ with end.
constexpr sentinel(sentinel<!Const> s) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>;
Effects: Initializes end_­ with std​::​move(s.end_­).
constexpr sentinel_t<Base> base() const;
Effects: Equivalent to: return end_­;
friend constexpr bool operator==(const CI<Const>& y, const sentinel& x); template<bool OtherConst = !Const> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const CI<OtherConst>& y, const sentinel& x);
Effects: Equivalent to: return y.count() == 0 || y.base() == x.end_­;

24.7.9 Take while view [range.take.while]

24.7.9.1 Overview [range.take.while.overview]

Given a unary predicate pred and a view r, take_­while_­view produces a view of the range [begin(r), ranges​::​find_­if_­not(r, pred)).
The name views​::​take_­while denotes a range adaptor object ([range.adaptor.object]).
Given subexpressions E and F, the expression views​::​take_­while(E, F) is expression-equivalent to take_­while_­view(E, F).
[Example 1: auto input = istringstream{"0 1 2 3 4 5 6 7 8 9"}; auto small = [](const auto x) noexcept { return x < 5; }; auto small_ints = istream_view<int>(input) | views::take_while(small); for (const auto i : small_ints) { cout << i << ' '; // prints 0 1 2 3 4 } auto i = 0; input >> i; cout << i; // prints 6 β€” end example]

24.7.9.2 Class template take_­while_­view [range.take.while.view]

namespace std::ranges { template<view V, class Pred> requires input_­range<V> && is_object_v<Pred> && indirect_­unary_­predicate<const Pred, iterator_t<V>> class take_while_view : public view_interface<take_while_view<V, Pred>> { // [range.take.while.sentinel], class template take_­while_­view​::​sentinel template<bool> class sentinel; // exposition only V base_ = V(); // exposition only copyable-box<Pred> pred_; // exposition only public: take_while_view() requires default_­initializable<V> && default_­initializable<Pred> = default; constexpr take_while_view(V base, Pred pred); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr const Pred& pred() const; constexpr auto begin() requires (!simple-view<V>) { return ranges::begin(base_); } constexpr auto begin() const requires range<const V> && indirect_­unary_­predicate<const Pred, iterator_t<const V>> { return ranges::begin(base_); } constexpr auto end() requires (!simple-view<V>) { return sentinel<false>(ranges::end(base_), addressof(*pred_)); } constexpr auto end() const requires range<const V> && indirect_­unary_­predicate<const Pred, iterator_t<const V>> { return sentinel<true>(ranges::end(base_), addressof(*pred_)); } }; template<class R, class Pred> take_while_view(R&&, Pred) -> take_while_view<views::all_t<R>, Pred>; }
constexpr take_while_view(V base, Pred pred);
Effects: Initializes base_­ with std​::​move(base) and pred_­ with std​::​move(pred).
constexpr const Pred& pred() const;
Effects: Equivalent to: return *pred_­;

24.7.9.3 Class template take_­while_­view​::​sentinel [range.take.while.sentinel]

namespace std::ranges { template<view V, class Pred> requires input_­range<V> && is_object_v<Pred> && indirect_­unary_­predicate<const Pred, iterator_t<V>> template<bool Const> class take_while_view<V, Pred>::sentinel { // exposition only using Base = maybe-const<Const, V>; // exposition only sentinel_t<Base> end_ = sentinel_t<Base>(); // exposition only const Pred* pred_ = nullptr; // exposition only public: sentinel() = default; constexpr explicit sentinel(sentinel_t<Base> end, const Pred* pred); constexpr sentinel(sentinel<!Const> s) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>; constexpr sentinel_t<Base> base() const { return end_; } friend constexpr bool operator==(const iterator_t<Base>& x, const sentinel& y); template<bool OtherConst = !Const> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const iterator_t<maybe-const<OtherConst, V>>& x, const sentinel& y); }; }
constexpr explicit sentinel(sentinel_t<Base> end, const Pred* pred);
Effects: Initializes end_­ with end and pred_­ with pred.
constexpr sentinel(sentinel<!Const> s) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>;
Effects: Initializes end_­ with s.end_­ and pred_­ with s.pred_­.
friend constexpr bool operator==(const iterator_t<Base>& x, const sentinel& y); template<bool OtherConst = !Const> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const iterator_t<maybe-const<OtherConst, V>>& x, const sentinel& y);
Effects: Equivalent to: return y.end_­ == x || !invoke(*y.pred_­, *x);

24.7.10 Drop view [range.drop]

24.7.10.1 Overview [range.drop.overview]

drop_­view produces a view excluding the first N elements from another view, or an empty range if the adapted view contains fewer than N elements.
The name views​::​drop denotes a range adaptor object ([range.adaptor.object]).
Let E and F be expressions, let T be remove_­cvref_­t<decltype((E))>, and let D be range_­difference_­t<decltype((E))>.
If decltype((F)) does not model convertible_­to<D>, views​::​drop(E, F) is ill-formed.
Otherwise, the expression views​::​drop(E, F) is expression-equivalent to:
[Example 1: auto ints = views::iota(0) | views::take(10); for (auto i : ints | views::drop(5)) { cout << i << ' '; // prints 5 6 7 8 9 } β€” end example]

24.7.10.2 Class template drop_­view [range.drop.view]

namespace std::ranges { template<view V> class drop_view : public view_interface<drop_view<V>> { public: drop_view() requires default_­initializable<V> = default; constexpr drop_view(V base, range_difference_t<V> count); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr auto begin() requires (!(simple-view<V> && random_­access_­range<const V> && sized_­range<const V>)); constexpr auto begin() const requires random_­access_­range<const V> && sized_­range<const V>; constexpr auto end() requires (!simple-view<V>) { return ranges::end(base_); } constexpr auto end() const requires range<const V> { return ranges::end(base_); } constexpr auto size() requires sized_­range<V> { const auto s = ranges::size(base_); const auto c = static_cast<decltype(s)>(count_); return s < c ? 0 : s - c; } constexpr auto size() const requires sized_­range<const V> { const auto s = ranges::size(base_); const auto c = static_cast<decltype(s)>(count_); return s < c ? 0 : s - c; } private: V base_ = V(); // exposition only range_difference_t<V> count_ = 0; // exposition only }; template<class R> drop_view(R&&, range_difference_t<R>) -> drop_view<views::all_t<R>>; }
constexpr drop_view(V base, range_difference_t<V> count);
Preconditions: count >= 0 is true.
Effects: Initializes base_­ with std​::​move(base) and count_­ with count.
constexpr auto begin() requires (!(simple-view<V> && random_­access_­range<const V> && sized_­range<const V>)); constexpr auto begin() const requires random_­access_­range<const V> && sized_­range<const V>;
Returns: ranges​::​next(ranges​::​begin(base_­), count_­, ranges​::​end(base_­)).
Remarks: In order to provide the amortized constant-time complexity required by the range concept when drop_­view models forward_­range, the first overload caches the result within the drop_­view for use on subsequent calls.
[Note 1:
Without this, applying a reverse_­view over a drop_­view would have quadratic iteration complexity.
β€” end note]

24.7.11 Drop while view [range.drop.while]

24.7.11.1 Overview [range.drop.while.overview]

Given a unary predicate pred and a view r, drop_­while_­view produces a view of the range [ranges​::​find_­if_­not(r, pred), ranges​::​end(r)).
The name views​::​drop_­while denotes a range adaptor object ([range.adaptor.object]).
Given subexpressions E and F, the expression views​::​drop_­while(E, F) is expression-equivalent to drop_­while_­view(E, F).
[Example 1: constexpr auto source = " \t \t \t hello there"; auto is_invisible = [](const auto x) { return x == ' ' || x == '\t'; }; auto skip_ws = views::drop_while(source, is_invisible); for (auto c : skip_ws) { cout << c; // prints hello there with no leading space } β€” end example]

24.7.11.2 Class template drop_­while_­view [range.drop.while.view]

namespace std::ranges { template<view V, class Pred> requires input_­range<V> && is_object_v<Pred> && indirect_­unary_­predicate<const Pred, iterator_t<V>> class drop_while_view : public view_interface<drop_while_view<V, Pred>> { public: drop_while_view() requires default_­initializable<V> && default_­initializable<Pred> = default; constexpr drop_while_view(V base, Pred pred); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr const Pred& pred() const; constexpr auto begin(); constexpr auto end() { return ranges::end(base_); } private: V base_ = V(); // exposition only copyable-box<Pred> pred_; // exposition only }; template<class R, class Pred> drop_while_view(R&&, Pred) -> drop_while_view<views::all_t<R>, Pred>; }
constexpr drop_while_view(V base, Pred pred);
Effects: Initializes base_­ with std​::​move(base) and pred_­ with std​::​move(pred).
constexpr const Pred& pred() const;
Effects: Equivalent to: return *pred_­;
constexpr auto begin();
Preconditions: pred_­.has_­value() is true.
Returns: ranges​::​find_­if_­not(base_­, cref(*pred_­)).
Remarks: In order to provide the amortized constant-time complexity required by the range concept when drop_­while_­view models forward_­range, the first call caches the result within the drop_­while_­view for use on subsequent calls.
[Note 1:
Without this, applying a reverse_­view over a drop_­while_­view would have quadratic iteration complexity.
β€” end note]

24.7.12 Join view [range.join]

24.7.12.1 Overview [range.join.overview]

join_­view flattens a view of ranges into a view.
The name views​::​join denotes a range adaptor object ([range.adaptor.object]).
Given a subexpression E, the expression views​::​join(E) is expression-equivalent to join_­view<views​::​all_­t<decltype((E))>>{E}.
[Example 1: vector<string> ss{"hello", " ", "world", "!"}; for (char ch : ss | views::join) cout << ch; // prints: hello world! β€” end example]

24.7.12.2 Class template join_­view [range.join.view]

namespace std::ranges { template<input_­range V> requires view<V> && input_­range<range_reference_t<V>> class join_view : public view_interface<join_view<V>> { private: using InnerRng = range_reference_t<V>; // exposition only // [range.join.iterator], class template join_­view​::​iterator template<bool Const> struct iterator; // exposition only // [range.join.sentinel], class template join_­view​::​sentinel template<bool Const> struct sentinel; // exposition only V base_ = V(); // exposition only non-propagating-cache<remove_cv_t<InnerRng>> inner_; // exposition only, present only // when !is_­reference_­v<InnerRng> public: join_view() requires default_­initializable<V> = default; constexpr explicit join_view(V base); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr auto begin() { constexpr bool use_const = simple-view<V> && is_reference_v<range_reference_t<V>>; return iterator<use_const>{*this, ranges::begin(base_)}; } constexpr auto begin() const requires input_­range<const V> && is_reference_v<range_reference_t<const V>> { return iterator<true>{*this, ranges::begin(base_)}; } constexpr auto end() { if constexpr (forward_­range<V> && is_reference_v<InnerRng> && forward_­range<InnerRng> && common_­range<V> && common_­range<InnerRng>) return iterator<simple-view<V>>{*this, ranges::end(base_)}; else return sentinel<simple-view<V>>{*this}; } constexpr auto end() const requires input_­range<const V> && is_reference_v<range_reference_t<const V>> { if constexpr (forward_­range<const V> && is_reference_v<range_reference_t<const V>> && forward_­range<range_reference_t<const V>> && common_­range<const V> && common_­range<range_reference_t<const V>>) return iterator<true>{*this, ranges::end(base_)}; else return sentinel<true>{*this}; } }; template<class R> explicit join_view(R&&) -> join_view<views::all_t<R>>; }
constexpr explicit join_view(V base);
Effects: Initializes base_­ with std​::​move(base).

24.7.12.3 Class template join_­view​::​iterator [range.join.iterator]

namespace std::ranges { template<input_­range V> requires view<V> && input_­range<range_reference_t<V>> template<bool Const> struct join_view<V>::iterator { private: using Parent = maybe-const<Const, join_view>; // exposition only using Base = maybe-const<Const, V>; // exposition only using OuterIter = iterator_t<Base>; // exposition only using InnerIter = iterator_t<range_reference_t<Base>>; // exposition only static constexpr bool ref-is-glvalue = // exposition only is_reference_v<range_reference_t<Base>>; OuterIter outer_ = OuterIter(); // exposition only InnerIter inner_ = InnerIter(); // exposition only Parent* parent_ = nullptr; // exposition only constexpr void satisfy(); // exposition only public: using iterator_concept = see below; using iterator_category = see below; // not always present using value_type = range_value_t<range_reference_t<Base>>; using difference_type = see below; iterator() requires default_­initializable<OuterIter> && default_­initializable<InnerIter> = default; constexpr iterator(Parent& parent, OuterIter outer); constexpr iterator(iterator<!Const> i) requires Const && convertible_­to<iterator_t<V>, OuterIter> && convertible_­to<iterator_t<InnerRng>, InnerIter>; constexpr decltype(auto) operator*() const { return *inner_; } constexpr InnerIter operator->() const requires has-arrow<InnerIter> && copyable<InnerIter>; constexpr iterator& operator++(); constexpr void operator++(int); constexpr iterator operator++(int) requires ref-is-glvalue && forward_­range<Base> && forward_­range<range_reference_t<Base>>; constexpr iterator& operator--() requires ref-is-glvalue && bidirectional_­range<Base> && bidirectional_­range<range_reference_t<Base>> && common_­range<range_reference_t<Base>>; constexpr iterator operator--(int) requires ref-is-glvalue && bidirectional_­range<Base> && bidirectional_­range<range_reference_t<Base>> && common_­range<range_reference_t<Base>>; friend constexpr bool operator==(const iterator& x, const iterator& y) requires ref-is-glvalue && equality_­comparable<iterator_t<Base>> && equality_­comparable<iterator_t<range_reference_t<Base>>>; friend constexpr decltype(auto) iter_move(const iterator& i) noexcept(noexcept(ranges::iter_move(i.inner_))) { return ranges::iter_move(i.inner_); } friend constexpr void iter_swap(const iterator& x, const iterator& y) noexcept(noexcept(ranges::iter_swap(x.inner_, y.inner_))) requires indirectly_­swappable<InnerIter>; }; }
iterator​::​iterator_­concept is defined as follows:
  • If ref-is-glvalue is true and Base and range_­reference_­t<Base> each model bidirectional_­range, then iterator_­concept denotes bidirectional_­iterator_­tag.
  • Otherwise, if ref-is-glvalue is true and Base and range_­reference_­t<Base> each model forward_­range, then iterator_­concept denotes forward_­iterator_­tag.
  • Otherwise, iterator_­concept denotes input_­iterator_­tag.
The member typedef-name iterator_­category is defined if and only if ref-is-glvalue is true, Base models forward_­range, and range_­reference_­t<Base> models forward_­range.
In that case, iterator​::​iterator_­category is defined as follows:
  • Let OUTERC denote iterator_­traits<iterator_­t<Base>>​::​iterator_­category, and let INNERC denote iterator_­traits<iterator_­t<range_­reference_­t<Base>>>​::​iterator_­category.
  • If OUTERC and INNERC each model derived_­from<bidirectional_­iterator_­tag>, iterator_­category denotes bidirectional_­iterator_­tag.
  • Otherwise, if OUTERC and INNERC each model derived_­from<forward_­iterator_­tag>, iterator_­category denotes forward_­iterator_­tag.
  • Otherwise, iterator_­category denotes input_­iterator_­tag.
iterator​::​difference_­type denotes the type: common_type_t< range_difference_t<Base>, range_difference_t<range_reference_t<Base>>>
join_­view iterators use the satisfy function to skip over empty inner ranges.
constexpr void satisfy(); // exposition only
Effects: Equivalent to: auto update_inner = [this](const iterator_t<Base>& x) -> auto&& { if constexpr (ref-is-glvalue) // *x is a reference return *x; else return parent_->inner_.emplace-deref(x); }; for (; outer_ != ranges::end(parent_->base_); ++outer_) { auto&& inner = update_inner(outer_); inner_ = ranges::begin(inner); if (inner_ != ranges::end(inner)) return; } if constexpr (ref-is-glvalue) inner_ = InnerIter();
constexpr iterator(Parent& parent, OuterIter outer);
Effects: Initializes outer_­ with std​::​move(outer) and parent_­ with addressof(parent); then calls satisfy().
constexpr iterator(iterator<!Const> i) requires Const && convertible_­to<iterator_t<V>, OuterIter> && convertible_­to<iterator_t<InnerRng>, InnerIter>;
Effects: Initializes outer_­ with std​::​move(i.outer_­), inner_­ with std​::​move(i.inner_­), and parent_­ with i.parent_­.
constexpr InnerIter operator->() const requires has-arrow<InnerIter> && copyable<InnerIter>;
Effects: Equivalent to return inner_­;
constexpr iterator& operator++();
Let inner-range be:
  • If ref-is-glvalue is true, *outer_­.
  • Otherwise, *parent_­->inner_­.
Effects: Equivalent to: auto&& inner_rng = inner-range; if (++inner_ == ranges::end(inner_rng)) { ++outer_; satisfy(); } return *this;
constexpr void operator++(int);
Effects: Equivalent to: ++*this.
constexpr iterator operator++(int) requires ref-is-glvalue && forward_­range<Base> && forward_­range<range_reference_t<Base>>;
Effects: Equivalent to: auto tmp = *this; ++*this; return tmp;
constexpr iterator& operator--() requires ref-is-glvalue && bidirectional_­range<Base> && bidirectional_­range<range_reference_t<Base>> && common_­range<range_reference_t<Base>>;
Effects: Equivalent to: if (outer_ == ranges::end(parent_->base_)) inner_ = ranges::end(*--outer_); while (inner_ == ranges::begin(*outer_)) inner_ = ranges::end(*--outer_); --inner_; return *this;
constexpr iterator operator--(int) requires ref-is-glvalue && bidirectional_­range<Base> && bidirectional_­range<range_reference_t<Base>> && common_­range<range_reference_t<Base>>;
Effects: Equivalent to: auto tmp = *this; --*this; return tmp;
friend constexpr bool operator==(const iterator& x, const iterator& y) requires ref-is-glvalue && equality_­comparable<iterator_t<Base>> && equality_­comparable<iterator_t<range_reference_t<Base>>>;
Effects: Equivalent to: return x.outer_­ == y.outer_­ && x.inner_­ == y.inner_­;
friend constexpr void iter_swap(const iterator& x, const iterator& y) noexcept(noexcept(ranges::iter_swap(x.inner_­, y.inner_­))) requires indirectly_­swappable<InnerIter>;
Effects: Equivalent to: return ranges​::​iter_­swap(x.inner_­, y.inner_­);

24.7.12.4 Class template join_­view​::​sentinel [range.join.sentinel]

namespace std::ranges { template<input_­range V> requires view<V> && input_­range<range_reference_t<V>> template<bool Const> struct join_view<V>::sentinel { private: using Parent = maybe-const<Const, join_view>; // exposition only using Base = maybe-const<Const, V>; // exposition only sentinel_t<Base> end_ = sentinel_t<Base>(); // exposition only public: sentinel() = default; constexpr explicit sentinel(Parent& parent); constexpr sentinel(sentinel<!Const> s) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>; template<bool OtherConst> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const iterator<OtherConst>& x, const sentinel& y); }; }
constexpr explicit sentinel(Parent& parent);
Effects: Initializes end_­ with ranges​::​end(parent.base_­).
constexpr sentinel(sentinel<!Const> s) requires Const && convertible_­to<sentinel_t<V>, sentinel_t<Base>>;
Effects: Initializes end_­ with std​::​move(s.end_­).
template<bool OtherConst> requires sentinel_­for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>> friend constexpr bool operator==(const iterator<OtherConst>& x, const sentinel& y);
Effects: Equivalent to: return x.outer_­ == y.end_­;

24.7.13 Lazy split view [range.lazy.split]

24.7.13.1 Overview [range.lazy.split.overview]

lazy_­split_­view takes a view and a delimiter, and splits the view into subranges on the delimiter.
The delimiter can be a single element or a view of elements.
The name views​::​lazy_­split denotes a range adaptor object ([range.adaptor.object]).
Given subexpressions E and F, the expression views​::​lazy_­split(E, F) is expression-equivalent to lazy_­split_­view(E, F).
[Example 1: string str{"the quick brown fox"}; for (auto word : str | views::lazy_split(' ')) { for (char ch : word) cout << ch; cout << '*'; } // The above prints: the*quick*brown*fox* β€” end example]

24.7.13.2 Class template lazy_­split_­view [range.lazy.split.view]

namespace std::ranges { template<auto> struct require-constant; // exposition only template<class R> concept tiny-range = // exposition only sized_­range<R> && requires { typename require-constant<remove_reference_t<R>::size()>; } && (remove_reference_t<R>::size() <= 1); template<input_­range V, forward_­range Pattern> requires view<V> && view<Pattern> && indirectly_­comparable<iterator_t<V>, iterator_t<Pattern>, ranges::equal_to> && (forward_­range<V> || tiny-range<Pattern>) class lazy_split_view : public view_interface<lazy_split_view<V, Pattern>> { private: V base_ = V(); // exposition only Pattern pattern_ = Pattern(); // exposition only non-propagating-cache<iterator_t<V>> current_; // exposition only, present only // if !forward_­range<V> // [range.lazy.split.outer], class template lazy_­split_­view​::​outer-iterator template<bool> struct outer-iterator; // exposition only // [range.lazy.split.inner], class template lazy_­split_­view​::​inner-iterator template<bool> struct inner-iterator; // exposition only public: lazy_split_view() requires default_­initializable<V> && default_­initializable<Pattern> = default; constexpr lazy_split_view(V base, Pattern pattern); template<input_­range R> requires constructible_­from<V, views::all_t<R>> && constructible_­from<Pattern, single_view<range_value_t<R>>> constexpr lazy_split_view(R&& r, range_value_t<R> e); constexpr V base() const& requires copy_­constructible<V> { return base_; } constexpr V base() && { return std::move(base_); } constexpr auto begin() { if constexpr (forward_­range<V>) return outer-iterator<simple-view<V>>{*this, ranges::begin(base_)}; else { current_ = ranges::begin(base_); return outer-iterator<false>{*this}; } } constexpr auto begin() const requires forward_­range<V> && forward_­range<const V> { return outer-iterator<true>{*this, ranges::begin(base_)}; } constexpr auto end() requires forward_­range<V> && common_­range<V> { return outer-iterator<simple-view<V>>{*this, ranges::end(base_)}; } constexpr auto end() const { if constexpr (forward_­range<V> && forward_­range<const V> && common_­range<const V>) return outer-iterator<true>{*this, ranges::end(base_)}; else return default_sentinel; } }; template<class R, class P> lazy_split_view(R&&, P&&) -> lazy_split_view<views::all_t<R>, views::all_t<P>>; template<input_­range R> lazy_split_view(R&&, range_value_t<R>) -> lazy_split_view<views::all_t<R>, single_view<range_value_t<R>>>; }
constexpr lazy_split_view(V base, Pattern pattern);
Effects: Initializes base_­ with std​::​move(base), and pattern_­ with std​::​move(pattern).
template<input_­range R> requires constructible_­from<V, views::all_t<R>> && constructible_­from<Pattern, single_view<range_value_t<R>>> constexpr lazy_split_view(R&& r, range_value_t<R> e);
Effects: Initializes base_­ with views​::​all(std​::​forward<R>(r)), and pattern_­ with views​::​
single(std​::​move(e))
.

24.7.13.3 Class template lazy_­split_­view​::​outer-iterator [range.lazy.split.outer]

namespace std::ranges { template<input_­range V, forward_­range Pattern> requires view<V> && view<Pattern> && indirectly_­comparable<iterator_t<V>, iterator_t<Pattern>, ranges::equal_to> && (forward_­range<V> || tiny-range<Pattern>) template<bool Const> struct lazy_split_view<V, Pattern>::outer-iterator { private: using Parent = maybe-const<Const, lazy_split_view>; // exposition only using Base = maybe-const<Const, V>; // exposition only Parent* parent_ = nullptr; // exposition only iterator_t<Base> current_ = iterator_t<Base>(); // exposition only, present only // if V models forward_­range bool trailing_empty_ = false; // exposition only public: using iterator_concept = conditional_t<forward_­range<Base>, forward_iterator_tag, input_iterator_tag>; using iterator_category = input_iterator_tag; // present only if Base // models forward_­range // [range.lazy.split.outer.value], class lazy_­split_­view​::​outer-iterator​::​value_­type struct value_type; using difference_type = range_difference_t<Base>; outer-iterator() = default; constexpr explicit outer-iterator(Parent& parent) requires (!forward_­range<Base>); constexpr outer-iterator(Parent& parent, iterator_t<Base> current) requires forward_­range<Base>; constexpr outer-iterator(outer-iterator<!Const> i) requires Const && convertible_­to<iterator_t<V>, iterator_t<Base>>; constexpr value_type operator*() const; constexpr outer-iterator& operator++(); constexpr decltype(auto) operator++(int) { if constexpr (forward_­range<Base>) { auto tmp = *this; ++*this; return tmp; } else ++*this; } friend constexpr bool operator==(const outer-iterator& x, const outer-iterator& y) requires forward_­range<Base>; friend constexpr bool operator==(const outer-iterator& x, default_sentinel_t); }; }
Many of the specifications in [range.lazy.split] refer to the notional member current of outer-iterator.
current is equivalent to current_­ if V models forward_­range, and *parent_­->current_­ otherwise.
constexpr explicit outer-iterator(Parent& parent) requires (!forward_­range<Base>);
Effects: Initializes parent_­ with addressof(parent)