[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.

2

#

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

O (1)

.

The view concept specifies requirements on a range type with constant-time destruction and move operations.

3

#

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]

1

#

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);
    };

2

#

The required expressions ranges::begin(t) and ranges::end(t) of the range concept do not require implicit expression variations ([concepts.equality]).

3

#

Given an expression t such that decltype((t)) is T&, T models range only if

(3.1)
[ranges::begin(t), ranges::end(t)) denotes a range ([iterator.requirements.general]),
(3.2)
both ranges::begin(t) and ranges::end(t) are amortized constant time and non-modifying, and
(3.3)
if the type of ranges::begin(t) models forward_iterator, ranges::begin(t) is equality-preserving.

4

#

[Note

:

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, repeated calls might not return equal values or might not be well-defined; ranges::begin should be called at most once for such a range.

— end note

]

🔗

template<class T>
  concept borrowed_range =
    range<T> &&
      (is_lvalue_reference_v<T> || enable_borrowed_range<remove_cvref_t<T>>);

5

#

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.

6

#

[Note

:

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;

7

#

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.

8

#

[Example

:

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]

1

#

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); };

2

#

Given an lvalue t of type remove_reference_t<T>, T models sized_range only if

(2.1)
ranges::size(t) is amortized $O (1)$ , does not modify t, and is equal to ranges::distance(t), and
(2.2)
if iterator_t<T> models forward_iterator, ranges::size(t) is well-defined regardless of the evaluation of ranges::begin(t).
[Note
: ranges::size(t) is otherwise not required to be well-defined after evaluating ranges::begin(t). For example, ranges::size(t) might 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;

3

#

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.

4

#

[Note

:

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]

1

#

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> && default_initializable<T> && enable_view<T>;

2

#

T models view only if:

(2.1)
T has $O (1)$ move construction; and
(2.2)
T has $O (1)$ move assignment; and
(2.3)
T has $O (1)$ destruction; and
(2.4)
copy_constructible<T> is false, or T has $O (1)$ copy construction; and
(2.5)
copyable<T> is false, or T has $O (1)$ copy assignment.

3

#

[Example

:

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

]

4

#

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 enable_view = derived_from<T, view_base>;

5

#

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]

🔗

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>>;

🔗

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>>>;
    };

🔗

template<class T>
  concept common_range =
    range<T> && same_as<iterator_t<T>, sentinel_t<T>>;

🔗

template<class T>
  concept viewable_range =
    range<T> && (borrowed_range<T> || view<remove_cvref_t<T>>);

24 Ranges library [ranges]

24.4 Range requirements [range.req]

24.4.1 General [range.req.general]

24.4.2 Ranges [range.range]

24.4.3 Sized ranges [range.sized]

24.4.4 Views [range.view]