\rSec0[ranges]{Ranges library}

\rSec1[ranges.general]{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 \tref{range.summary}.

\begin{libsumtab}{Ranges library summary}{range.summary}

\ref{range.access} & Range access & \tcode{<ranges>} \\

\ref{range.req} & Requirements & \\

\ref{range.utility} & Range utilities & \\

\ref{range.factories} & Range factories & \\

\ref{range.adaptors} & Range adaptors & \\

\end{libsumtab}

\rSec1[ranges.syn]{Header \tcode{<ranges>} synopsis}

\indexheader{ranges}%

\indexlibraryglobal{all_t}%

\begin{codeblock}

#include <compare> // see \ref{compare.syn}

#include <initializer_list> // see \ref{initializer.list.syn}

#include <iterator> // see \ref{iterator.synopsis}

namespace std::ranges {

inline namespace @\unspec@ {

// \ref{range.access}, range access

inline constexpr @\unspec@ begin = @\unspec@;

inline constexpr @\unspec@ end = @\unspec@;

inline constexpr @\unspec@ cbegin = @\unspec@;

inline constexpr @\unspec@ cend = @\unspec@;

inline constexpr @\unspec@ rbegin = @\unspec@;

inline constexpr @\unspec@ rend = @\unspec@;

inline constexpr @\unspec@ crbegin = @\unspec@;

inline constexpr @\unspec@ crend = @\unspec@;

inline constexpr @\unspec@ size = @\unspec@;

inline constexpr @\unspec@ ssize = @\unspec@;

inline constexpr @\unspec@ empty = @\unspec@;

inline constexpr @\unspec@ data = @\unspec@;

inline constexpr @\unspec@ cdata = @\unspec@;

}

// \ref{range.range}, ranges

template<class T>

concept range = @\seebelow@;

template<class T>

inline constexpr bool enable_borrowed_range = false;

template<class T>

concept borrowed_range = @\seebelow@;

template<class T>

using iterator_t = decltype(ranges::begin(declval<T&>()));

template<@\libconcept{range}@ R>

using sentinel_t = decltype(ranges::end(declval<R&>()));

template<@\libconcept{range}@ R>

using range_difference_t = iter_difference_t<iterator_t<R>>;

template<@\libconcept{sized_range}@ R>

using range_size_t = decltype(ranges::size(declval<R&>()));

template<@\libconcept{range}@ R>

using range_value_t = iter_value_t<iterator_t<R>>;

template<@\libconcept{range}@ R>

using range_reference_t = iter_reference_t<iterator_t<R>>;

template<@\libconcept{range}@ R>

using range_rvalue_reference_t = iter_rvalue_reference_t<iterator_t<R>>;

// \ref{range.sized}, sized ranges

template<class>

inline constexpr bool disable_sized_range = false;

template<class T>

concept sized_range = @\seebelow@;

// \ref{range.view}, views

template<class T>

inline constexpr bool enable_view = @\seebelow@;

struct view_base { };

template<class T>

concept view = @\seebelow@;

// \ref{range.refinements}, other range refinements

template<class R, class T>

concept output_range = @\seebelow@;

template<class T>

concept input_range = @\seebelow@;

template<class T>

concept forward_range = @\seebelow@;

template<class T>

concept bidirectional_range = @\seebelow@;

template<class T>

concept random_access_range = @\seebelow@;

template<class T>

concept contiguous_range = @\seebelow@;

template<class T>

concept common_range = @\seebelow@;

template<class T>

concept viewable_range = @\seebelow@;

// \ref{view.interface}, class template \tcode{view_interface}

template<class D>

requires is_class_v<D> && @\libconcept{same_as}@<D, remove_cv_t<D>>

class view_interface;

// \ref{range.subrange}, sub-ranges

enum class subrange_kind : bool { unsized, sized };

template<@\libconcept{input_or_output_iterator}@ I, @\libconcept{sentinel_for}@<I> S = I, subrange_kind K = @\seebelow@>

requires (K == subrange_kind::sized || !@\libconcept{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;

// \ref{range.dangling}, dangling iterator handling

struct dangling;

template<@\libconcept{range}@ R>

using borrowed_iterator_t = @\seebelow@;

template<@\libconcept{range}@ R>

using borrowed_subrange_t = @\seebelow@;

// \ref{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> @\libmember{empty}{views}@{};

}

// \ref{range.single}, single view

template<@\libconcept{copy_constructible}@ T>

requires is_object_v<T>

class single_view;

namespace views { inline constexpr @\unspec@ single = @\unspec@; }

template<bool Const, class T>

using @\exposid{maybe-const}@ = conditional_t<Const, const T, T>; // \expos

// \ref{range.iota}, iota view

template<@\libconcept{weakly_incrementable}@ W, @\libconcept{semiregular}@ Bound = unreachable_sentinel_t>

requires @\exposconcept{weakly-equality-comparable-with}@<W, Bound> && @\libconcept{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 @\unspec@ iota = @\unspec@; }

// \ref{range.istream}, istream view

template<@\libconcept{movable}@ Val, class CharT, class Traits = char_traits<CharT>>

requires @\seebelow@

class basic_istream_view;

template<class Val, class CharT, class Traits>

basic_istream_view<Val, CharT, Traits> istream_view(basic_istream<CharT, Traits>& s);

// \ref{range.all}, all view

namespace views {

inline constexpr @\unspec@ all = @\unspec@;

template<@\libconcept{viewable_range}@ R>

using all_t = decltype(all(declval<R>()));

}

template<@\libconcept{range}@ R>

requires is_object_v<R>

class ref_view;

template<class T>

inline constexpr bool enable_borrowed_range<ref_view<T>> = true;

// \ref{range.filter}, filter view

template<@\libconcept{input_range}@ V, @\libconcept{indirect_unary_predicate}@<iterator_t<V>> Pred>

requires @\libconcept{view}@<V> && is_object_v<Pred>

class filter_view;

namespace views { inline constexpr @\unspec@ filter = @\unspec@; }

// \ref{range.transform}, transform view

template<@\libconcept{input_range}@ V, @\libconcept{copy_constructible}@ F>

requires @\libconcept{view}@<V> && is_object_v<F> &&

@\libconcept{regular_invocable}@<F&, range_reference_t<V>> &&

@\exposconcept{can-reference}@<invoke_result_t<F&, range_reference_t<V>>>

class transform_view;

namespace views { inline constexpr @\unspec@ transform = @\unspec@; }

// \ref{range.take}, take view

template<@\libconcept{view}@> class take_view;

template<class T>

inline constexpr bool enable_borrowed_range<take_view<T>> = enable_borrowed_range<T>;

namespace views { inline constexpr @\unspec@ take = @\unspec@; }

// \ref{range.take.while}, take while view

template<@\libconcept{view}@ V, class Pred>

requires @\libconcept{input_range}@<V> && is_object_v<Pred> &&

@\libconcept{indirect_unary_predicate}@<const Pred, iterator_t<V>>

class take_while_view;

namespace views { inline constexpr @\unspec@ take_while = @\unspec@; }

// \ref{range.drop}, drop view

template<@\libconcept{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 @\unspec@ drop = @\unspec@; }

// \ref{range.drop.while}, drop while view

template<@\libconcept{view}@ V, class Pred>

requires @\libconcept{input_range}@<V> && is_object_v<Pred> &&

@\libconcept{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 @\unspec@ drop_while = @\unspec@; }

// \ref{range.join}, join view

template<@\libconcept{input_range}@ V>

requires @\libconcept{view}@<V> && @\libconcept{input_range}@<range_reference_t<V>>

class join_view;

namespace views { inline constexpr @\unspec@ join = @\unspec@; }

// \ref{range.lazy.split}, lazy split view

template<class R>

concept @\exposconcept{tiny-range}@ = @\seebelow@; // \expos

template<@\libconcept{input_range}@ V, @\libconcept{forward_range}@ Pattern>

requires @\libconcept{view}@<V> && @\libconcept{view}@<Pattern> &&

@\libconcept{indirectly_comparable}@<iterator_t<V>, iterator_t<Pattern>, ranges::equal_to> &&

(@\libconcept{forward_range}@<V> || @\exposconcept{tiny-range}@<Pattern>)

class lazy_split_view;

// \ref{range.split}, split view

template<@\libconcept{forward_range}@ V, @\libconcept{forward_range}@ Pattern>

requires @\libconcept{view}@<V> && @\libconcept{view}@<Pattern> &&

@\libconcept{indirectly_comparable}@<iterator_t<V>, iterator_t<Pattern>, ranges::equal_to>

class split_view;

namespace views {

inline constexpr @\unspec@ lazy_split = @\unspec@;

inline constexpr @\unspec@ split = @\unspec@;

}

// \ref{range.counted}, counted view

namespace views { inline constexpr @\unspec@ counted = @\unspec@; }

// \ref{range.common}, common view

template<@\libconcept{view}@ V>

requires (!@\libconcept{common_range}@<V> && @\libconcept{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 @\unspec@ common = @\unspec@; }

// \ref{range.reverse}, reverse view

template<@\libconcept{view}@ V>

requires @\libconcept{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 @\unspec@ reverse = @\unspec@; }

// \ref{range.elements}, elements view

template<@\libconcept{input_range}@ V, size_t N>

requires @\seebelow@

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 @\libglobal{keys_view}@ = elements_view<views::all_t<R>, 0>;

template<class R>

using @\libglobal{values_view}@ = elements_view<views::all_t<R>, 1>;

namespace views {

template<size_t N>

inline constexpr @\unspec@ elements = @\unspec@ ;

inline constexpr auto @\libmember{keys}{views}@ = elements<0>;

inline constexpr auto @\libmember{values}{views}@ = 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;

};

}

\end{codeblock}

\indextext{to-unsigned-like@\exposid{to-unsigned-like}}%

\indextext{make-unsigned-like-t@\exposid{make-unsigned-like-t}}%

Within this Clause,

for an integer-like type \tcode{X}\iref{iterator.concept.winc},

\tcode{\placeholdernc{make-unsigned-like-t}<X>} denotes

\tcode{make_unsigned_t<X>} if \tcode{X} is an integer type;

otherwise, it denotes a corresponding unspecified unsigned-integer-like type

of the same width as \tcode{X}.

For an expression \tcode{x} of type \tcode{X},

\tcode{\placeholdernc{to-unsigned-like}(x)} is

\tcode{x} explicitly converted to

\tcode{\placeholdernc{make-unsigned-like-t}<X>}.

Also within this Clause,

\tcode{\exposid{make-signed-like-t}<X>} for an integer-like type \tcode{X}

denotes \tcode{make_signed_t<X>} if \tcode{X} is an integer type;

otherwise, it denotes a corresponding unspecified signed-integer-like type

of the same width as \tcode{X}.

\rSec1[range.access]{Range access}

\rSec2[range.access.general]{General}

In addition to being available via inclusion of the \libheader{ranges}

header, the customization point objects in \ref{range.access} are

available when \libheaderrefx{iterator}{iterator.synopsis} is included.

Within \ref{range.access},

the \defnadj{reified}{object} of a subexpression \tcode{E} denotes

\begin{itemize}

the same object as \tcode{E} if \tcode{E} is a glvalue, or

the result of applying

the temporary materialization conversion\iref{conv.rval} to \tcode{E} otherwise.

\end{itemize}

\rSec2[range.access.begin]{\tcode{ranges::begin}}

\indexlibraryglobal{begin}%

The name \tcode{ranges::begin} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{E} is an rvalue and

\tcode{enable_borrowed_range<remove_cv_t<T>>} is \tcode{false},

\tcode{ranges::begin(E)} is ill-formed.

Otherwise, if \tcode{T} is an array type\iref{basic.compound} and

\tcode{remove_all_extents_t<T>} is an incomplete type,

\tcode{ranges::begin(E)} is ill-formed with no diagnostic required.

Otherwise, if \tcode{T} is an array type,

\tcode{ranges::begin(E)} is expression-equivalent to \tcode{t + 0}.

Otherwise, if \tcode{\placeholdernc{decay-copy}(t.begin())}

is a valid expression whose type models

\libconcept{input_or_output_iterator},

\tcode{ranges::begin(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(t.begin())}.

Otherwise, if \tcode{T} is a class or enumeration type and

\tcode{\placeholdernc{decay-copy}(begin(t))}

is a valid expression whose type models

\libconcept{input_or_output_iterator}

with overload resolution performed in a context in which

unqualified lookup for \tcode{begin} finds only the declarations

\begin{codeblock}

void begin(auto&) = delete;

void begin(const auto&) = delete;

\end{codeblock}

then \tcode{ranges::begin(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(begin(t))}

with overload resolution performed in the above context.

Otherwise, \tcode{ranges::begin(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above

result in substitution failure when \tcode{ranges::begin(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::begin(E)} is a valid expression, its type models

\libconcept{input_or_output_iterator}.

\end{note}

\rSec2[range.access.end]{\tcode{ranges::end}}

\indexlibraryglobal{end}%

The name \tcode{ranges::end} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{E} is an rvalue and

\tcode{enable_borrowed_range<remove_cv_t<T>>} is \tcode{false},

\tcode{ranges::end(E)} is ill-formed.

Otherwise, if \tcode{T} is an array type\iref{basic.compound} and

\tcode{remove_all_extents_t<T>} is an incomplete type,

\tcode{ranges::end(E)} is ill-formed with no diagnostic required.

Otherwise, if \tcode{T} is an array of unknown bound,

\tcode{ranges::end(E)} is ill-formed.

Otherwise, if \tcode{T} is an array,

\tcode{ranges::end(E)} is expression-equivalent to

\tcode{t + extent_v<T>}.

Otherwise, if \tcode{\placeholdernc{decay-copy}(t.end())}

is a valid expression whose type models

\tcode{\libconcept{sentinel_for}<iterator_t<T>>}

then \tcode{ranges::end(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(t.end())}.

Otherwise, if \tcode{T} is a class or enumeration type and

\tcode{\placeholdernc{decay-copy}(end(t))}

is a valid expression whose type models

\tcode{\libconcept{sentinel_for}<iterator_t<T>>}

with overload resolution performed in a context in which

unqualified lookup for \tcode{end} finds only the declarations

\begin{codeblock}

void end(auto&) = delete;

void end(const auto&) = delete;

\end{codeblock}

then \tcode{ranges::end(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(end(t))}

with overload resolution performed in the above context.

Otherwise, \tcode{ranges::end(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above

result in substitution failure when \tcode{ranges::end(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::end(E)} is a valid expression,

the types \tcode{S} and \tcode{I} of

\tcode{ranges::end(E)} and \tcode{ranges::begin(E)}

model \tcode{\libconcept{sentinel_for}<S, I>}.

\end{note}

\rSec2[range.access.cbegin]{\tcode{ranges::cbegin}}

\indexlibraryglobal{cbegin}%

The name \tcode{ranges::cbegin} denotes a customization point

object\iref{customization.point.object}. The expression

\tcode{ranges::\brk{}cbegin(E)} for a subexpression \tcode{E} of type \tcode{T}

is expression-equivalent to:

\begin{itemize}

\item \tcode{ranges::begin(static_cast<const T\&>(E))} if \tcode{E} is an lvalue.

\item Otherwise, \tcode{ranges::begin(static_cast<const T\&\&>(E))}.

\end{itemize}

\begin{note}

Whenever \tcode{ranges::cbegin(E)} is a valid expression, its type models

\libconcept{input_or_output_iterator}.

\end{note}

\rSec2[range.access.cend]{\tcode{ranges::cend}}

\indexlibraryglobal{cend}%

The name \tcode{ranges::cend} denotes a customization point

object\iref{customization.point.object}. The expression

\tcode{ranges::cend(E)} for a subexpression \tcode{E} of type \tcode{T}

is expression-equivalent to:

\begin{itemize}

\item \tcode{ranges::end(static_cast<const T\&>(E))} if \tcode{E} is an lvalue.

\item Otherwise, \tcode{ranges::end(static_cast<const T\&\&>(E))}.

\end{itemize}

\begin{note}

Whenever \tcode{ranges::cend(E)} is a valid expression,

the types \tcode{S} and \tcode{I} of the expressions

\tcode{ranges::cend(E)} and \tcode{ranges::cbegin(E)}

model \tcode{\libconcept{sentinel_for}<S, I>}.

\end{note}

\rSec2[range.access.rbegin]{\tcode{ranges::rbegin}}

\indexlibraryglobal{rbegin}%

The name \tcode{ranges::rbegin} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{E} is an rvalue and

\tcode{enable_borrowed_range<remove_cv_t<T>>} is \tcode{false},

\tcode{ranges::rbegin(E)} is ill-formed.

Otherwise, if \tcode{T} is an array type\iref{basic.compound} and

\tcode{remove_all_extents_t<T>} is an incomplete type,

\tcode{ranges::rbegin(E)} is ill-formed with no diagnostic required.

Otherwise, if \tcode{\placeholdernc{decay-copy}(t.rbegin())}

is a valid expression whose type models

\libconcept{input_or_output_iterator},

\tcode{ranges::rbegin(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(t.rbegin())}.

Otherwise, if \tcode{T} is a class or enumeration type and

\tcode{\placeholdernc{decay-copy}(rbegin(t))}

is a valid expression whose type models

\libconcept{input_or_output_iterator}

with overload resolution performed in a context in which

unqualified lookup for \tcode{rbegin} finds only the declarations

\begin{codeblock}

void rbegin(auto&) = delete;

void rbegin(const auto&) = delete;

\end{codeblock}

then \tcode{ranges::rbegin(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(rbegin(t))}

with overload resolution performed in the above context.

Otherwise, if both \tcode{ranges::begin(t)} and \tcode{ranges::end(t)}

are valid expressions of the same type which models

\libconcept{bidirectional_iterator}\iref{iterator.concept.bidir},

\tcode{ranges::rbegin(E)} is expression-equivalent to

\tcode{make_reverse_iterator(ranges::end(t))}.

Otherwise, \tcode{ranges::rbegin(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above result in substitution failure

when \tcode{ranges::rbegin(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::rbegin(E)} is a valid expression, its type models

\libconcept{input_or_output_iterator}.

\end{note}

\rSec2[range.access.rend]{\tcode{ranges::rend}}

\indexlibraryglobal{rend}%

The name \tcode{ranges::rend} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{E} is an rvalue and

\tcode{enable_borrowed_range<remove_cv_t<T>>} is \tcode{false},

\tcode{ranges::rend(E)} is ill-formed.

Otherwise, if \tcode{T} is an array type\iref{basic.compound} and

\tcode{remove_all_extents_t<T>} is an incomplete type,

\tcode{ranges::rend(E)} is ill-formed with no diagnostic required.

Otherwise, if \tcode{\placeholdernc{decay-copy}(t.rend())}

is a valid expression whose type models

\tcode{\libconcept{sentinel_for}<decl\-type(ranges::rbegin(E))>}

then \tcode{ranges::rend(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(t.rend(\brk{}))}.

Otherwise, if \tcode{T} is a class or enumeration type and

\tcode{\placeholdernc{decay-copy}(rend(t))}

is a valid expression whose type models

\tcode{\libconcept{sentinel_for}<decltype(ranges::rbegin(E))>}

with overload resolution performed in a context in which

unqualified lookup for \tcode{rend} finds only the declarations

\begin{codeblock}

void rend(auto&) = delete;

void rend(const auto&) = delete;

\end{codeblock}

then \tcode{ranges::rend(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(rend(t))}

with overload resolution performed in the above context.

Otherwise, if both \tcode{ranges::begin(t)} and \tcode{ranges::end(t)}

are valid expressions of the same type which models

\libconcept{bidirectional_iterator}\iref{iterator.concept.bidir},

then \tcode{ranges::rend(E)} is expression-equivalent to

\tcode{make_reverse_iterator(ranges::begin(t))}.

Otherwise, \tcode{ranges::rend(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above

result in substitution failure when \tcode{ranges::rend(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::rend(E)} is a valid expression,

the types \tcode{S} and \tcode{I} of the expressions

\tcode{ranges::rend(E)} and \tcode{ranges::rbegin(E)}

model \tcode{\libconcept{sentinel_for}<S, I>}.

\end{note}

\rSec2[range.access.crbegin]{\tcode{ranges::crbegin}}

\indexlibraryglobal{crbegin}%

The name \tcode{ranges::crbegin} denotes a customization point

object\iref{customization.point.object}. The expression

\tcode{ranges::\brk{}crbegin(E)} for a subexpression \tcode{E} of type

\tcode{T} is expression-equivalent to:

\begin{itemize}

\item \tcode{ranges::\brk{}rbegin(static_cast<const T\&>(E))} if \tcode{E} is

an lvalue.

\item Otherwise, \tcode{ranges::rbegin(static_cast<const T\&\&>(E))}.

\end{itemize}

\begin{note}

Whenever \tcode{ranges::crbegin(E)} is a valid expression, its

type models \libconcept{input_or_output_iterator}.

\end{note}

\rSec2[range.access.crend]{\tcode{ranges::crend}}

\indexlibraryglobal{crend}%

The name \tcode{ranges::crend} denotes a customization point

object\iref{customization.point.object}. The expression

\tcode{ranges::\brk{}crend(E)} for a subexpression \tcode{E} of type \tcode{T}

is expression-equivalent to:

\begin{itemize}

\item \tcode{ranges::rend(static_cast<const T\&>(E))} if \tcode{E} is an lvalue.

\item Otherwise, \tcode{ranges::rend(static_cast<const T\&\&>(E))}.

\end{itemize}

\begin{note}

Whenever \tcode{ranges::crend(E)} is a valid expression,

the types \tcode{S} and \tcode{I} of the expressions

\tcode{ranges::crend(E)} and \tcode{ranges::crbegin(E)}

model \tcode{\libconcept{sentinel_for}<S, I>}.

\end{note}

\rSec2[range.prim.size]{\tcode{ranges::size}}

\indexlibraryglobal{size}%

The name \tcode{ranges::size} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{T} is an array of unknown bound\iref{dcl.array},

\tcode{ranges::size(E)} is ill-formed.

Otherwise, if \tcode{T} is an array type,

\tcode{ranges::size(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(extent_v<T>)}.

Otherwise, if \tcode{disable_sized_range<remove_cv_t<T>>}\iref{range.sized}

is \tcode{false} and

\tcode{\placeholdernc{decay-copy}(t.size())}

is a valid expression of integer-like type\iref{iterator.concept.winc},

\tcode{ranges::size(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(t.size())}.

Otherwise, if \tcode{T} is a class or enumeration type,

\tcode{disable_sized_range<remove_cv_t<T>>} is \tcode{false} and

\tcode{\placeholdernc{decay-copy}(size(t))}

is a valid expression of integer-like type

with overload resolution performed in a context in which

unqualified lookup for \tcode{size} finds only the declarations

\begin{codeblock}

void size(auto&) = delete;

void size(const auto&) = delete;

\end{codeblock}

then \tcode{ranges::size(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(size(t))}

with overload resolution performed in the above context.

Otherwise, if

\tcode{\placeholdernc{to-unsigned-like}(ranges::end(t) - ranges::begin(t))}\iref{ranges.syn}

is a valid expression and

the types \tcode{I} and \tcode{S} of \tcode{ranges::begin(t)} and

\tcode{ranges::end(t)} (respectively) model both

\tcode{\libconcept{sized_sentinel_for}<S, I>}\iref{iterator.concept.sizedsentinel} and

\tcode{\libconcept{forward_iterator}<I>},

then \tcode{ranges::size(E)} is expres\-sion-equivalent to

\tcode{\placeholdernc{to-unsigned-like}(ranges::end(t) - ranges::begin(t))}.

Otherwise, \tcode{ranges::size(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above

result in substitution failure when \tcode{ranges::size(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::size(E)} is a valid expression, its

type is integer-like.

\end{note}

\rSec2[range.prim.ssize]{\tcode{ranges::ssize}}

\indexlibraryglobal{ssize}%

The name \tcode{ranges::ssize} denotes

a customization point object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

If \tcode{ranges::size(t)} is ill-formed,

\tcode{ranges::ssize(E)} is ill-formed.

Otherwise let \tcode{D} be

\tcode{\exposid{make-signed-like-t}<decltype(ranges::\brk{}size(t))>}, or

\tcode{ptrdiff_t} if it is wider than that type;

\tcode{ranges::ssize(E)} is expression-equivalent to

\tcode{static_cast<D>(ranges::size(t))}.

\rSec2[range.prim.empty]{\tcode{ranges::empty}}

\indexlibraryglobal{empty}%

The name \tcode{ranges::empty} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{T} is an array of unknown bound\iref{basic.compound},

\tcode{ranges::empty(E)} is ill-formed.

Otherwise, if \tcode{bool(t.empty())} is a valid expression,

\tcode{ranges::empty(E)} is expression-equivalent to

\tcode{bool(t.empty())}.

Otherwise, if \tcode{(ranges::size(t) == 0)} is a valid expression,

\tcode{ranges::empty(E)} is expression-equiva\-lent to

\tcode{(ranges::size(t) == 0)}.

Otherwise, if \tcode{bool(ranges::begin(t) == ranges::end(t))}

is a valid expression and

the type of \tcode{ranges::begin(t)} models \libconcept{forward_iterator},

\tcode{ranges::empty(E)} is expression-equivalent to

\tcode{bool(\brk{}ranges::begin(t) == ranges::end(t))}.

Otherwise, \tcode{ranges::empty(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above

result in substitution failure when \tcode{ranges::empty(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::empty(E)} is a valid expression,

it has type \tcode{bool}.

\end{note}

\rSec2[range.prim.data]{\tcode{ranges::data}}

\indexlibraryglobal{data}%

The name \tcode{ranges::data} denotes a customization point

object\iref{customization.point.object}.

Given a subexpression \tcode{E} with type \tcode{T},

let \tcode{t} be an lvalue that denotes the reified object for \tcode{E}.

Then:

\begin{itemize}

If \tcode{E} is an rvalue and

\tcode{enable_borrowed_range<remove_cv_t<T>>} is \tcode{false},

\tcode{ranges::data(E)} is ill-formed.

Otherwise, if \tcode{T} is an array type\iref{basic.compound} and

\tcode{remove_all_extents_t<T>} is an incomplete type,

\tcode{ranges::data(E)} is ill-formed with no diagnostic required.

Otherwise, if \tcode{\placeholdernc{decay-copy}(t.data())}

is a valid expression of pointer to object type,

\tcode{ranges::data(E)} is expression-equivalent to

\tcode{\placeholdernc{decay-copy}(t.data())}.

Otherwise, if \tcode{ranges::begin(t)}

is a valid expression whose type models

\libconcept{contiguous_iterator},

\tcode{ranges::data(E)} is expression-equivalent to

\tcode{to_address(ranges::begin(E))}.

Otherwise, \tcode{ranges::data(E)} is ill-formed.

\end{itemize}

\begin{note}

Diagnosable ill-formed cases above

result in substitution failure when \tcode{ranges::data(E)}

appears in the immediate context of a template instantiation.

\end{note}

\begin{note}

Whenever \tcode{ranges::data(E)} is a valid expression, it

has pointer to object type.

\end{note}

\rSec2[range.prim.cdata]{\tcode{ranges::cdata}}

\indexlibraryglobal{cdata}%

The name \tcode{ranges::cdata} denotes a customization point

object\iref{customization.point.object}. The expression

\tcode{ranges::\brk{}cdata(E)} for a subexpression \tcode{E} of type \tcode{T}

is expression-equivalent to:

\begin{itemize}

\item \tcode{ranges::data(static_cast<const T\&>(E))} if \tcode{E} is an lvalue.

\item Otherwise, \tcode{ranges::data(static_cast<const T\&\&>(E))}.

\end{itemize}

\begin{note}

Whenever \tcode{ranges::cdata(E)} is a valid expression, it

has pointer to object type.

\end{note}

\rSec1[range.req]{Range requirements}

\rSec2[range.req.general]{General}

Ranges are an abstraction that allow a \Cpp{} program

to operate on elements of data structures uniformly.

Calling \tcode{ranges::begin} on a range returns an object

whose type models \libconcept{input_or_output_iterator}\iref{iterator.concept.iterator}.

Calling \tcode{ranges::end} on a range returns an object whose type \tcode{S},

together with the type \tcode{I} of the object returned by \tcode{ranges::begin},

models \tcode{\libconcept{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 \libconcept{range} concept requires that

\tcode{ranges::begin} and \tcode{ranges::end}

return an iterator and a sentinel, respectively.

The \libconcept{sized_range} concept refines \libconcept{range} with

the requirement that \tcode{ranges::size} be amortized \bigoh{1}.

The \libconcept{view} concept specifies requirements on a \libconcept{range} type

with constant-time destruction and move operations.

Several refinements of \libconcept{range} group requirements

that arise frequently in concepts and algorithms.

Common ranges are ranges for which

\tcode{ranges::begin} and \tcode{ranges::end}

return objects of the same type.

Random access ranges are ranges for which \tcode{ranges::begin}

returns a type that models

\libconcept{random_access_iterator}\iref{iterator.concept.random.access}.