24 Iterators library [iterators]

24.3 Iterator requirements [iterator.requirements]

24.3.1 General [iterator.requirements.general]

Iterators are a generalization of pointers that allow a C++ program to work with different data structures (for example, containers and ranges) in a uniform manner.

To be able to construct template algorithms that work correctly and efficiently on different types of data structures, the library formalizes not just the interfaces but also the semantics and complexity assumptions of iterators.

An input iterator i supports the expression *i, resulting in a value of some object type T, called the value type of the iterator.

An output iterator i has a non-empty set of types that are writable to the iterator; for each such type T, the expression *i = o is valid where o is a value of type T.

For every iterator type X, there is a corresponding signed integer-like type ([iterator.concept.winc]) called the difference type of the iterator.

Since iterators are an abstraction of pointers, their semantics are a generalization of most of the semantics of pointers in C++.

This ensures that every function template that takes iterators works as well with regular pointers.

This document defines six categories of iterators, according to the operations defined on them: input iterators, output iterators, forward iterators, bidirectional iterators, random access iterators, and contiguous iterators, as shown in Table 72 .

Table 72 — Relations among iterator categories [tab:iterators.relations]

🔗 Contiguous	→ Random Access	→ Bidirectional	→ Forward	→ Input
🔗				→ Output

The six categories of iterators correspond to the iterator concepts

respectively.

The generic term iterator refers to any type that models the input_or_output_iterator concept ([iterator.concept.iterator]).

Forward iterators meet all the requirements of input iterators and can be used whenever an input iterator is specified; Bidirectional iterators also meet all the requirements of forward iterators and can be used whenever a forward iterator is specified; Random access iterators also meet all the requirements of bidirectional iterators and can be used whenever a bidirectional iterator is specified; Contiguous iterators also meet all the requirements of random access iterators and can be used whenever a random access iterator is specified.

Iterators that further meet the requirements of output iterators are called mutable iterators.

Nonmutable iterators are referred to as constant iterators.

In addition to the requirements in this subclause, the nested typedef-names specified in [iterator.traits] shall be provided for the iterator type.

[Note 1:

Either the iterator type must provide the typedef-names directly (in which case iterator_traits pick them up automatically), or an iterator_traits specialization must provide them.

— end note]

Just as a regular pointer to an array guarantees that there is a pointer value pointing past the last element of the array, so for any iterator type there is an iterator value that points past the last element of a corresponding sequence.

Such a value is called a past-the-end value.

Values of an iterator i for which the expression *i is defined are called dereferenceable.

The library never assumes that past-the-end values are dereferenceable.

Iterators can also have singular values that are not associated with any sequence.

Results of most expressions are undefined for singular values; the only exceptions are destroying an iterator that holds a singular value, the assignment of a non-singular value to an iterator that holds a singular value, and, for iterators that meet the Cpp17DefaultConstructible requirements, using a value-initialized iterator as the source of a copy or move operation.

[Note 2:

This guarantee is not offered for default-initialization, although the distinction only matters for types with trivial default constructors such as pointers or aggregates holding pointers.

— end note]

In these cases the singular value is overwritten the same way as any other value.

Dereferenceable values are always non-singular.

Most of the library's algorithmic templates that operate on data structures have interfaces that use ranges.

A range is an iterator and a sentinel that designate the beginning and end of the computation, or an iterator and a count that designate the beginning and the number of elements to which the computation is to be applied.201

An iterator and a sentinel denoting a range are comparable.

A range [i, s) is empty if i == s; otherwise, [i, s) refers to the elements in the data structure starting with the element pointed to by i and up to but not including the element, if any, pointed to by the first iterator j such that j == s.

A sentinel s is called reachable from an iterator i if and only if there is a finite sequence of applications of the expression ++i that makes i == s.

If s is reachable from i, [i, s) denotes a valid range.

A counted range

i + [0, n)

is empty if n == 0; otherwise,

i + [0, n)

refers to the n elements in the data structure starting with the element pointed to by i and up to but not including the element, if any, pointed to by the result of n applications of ++i.

A counted range

i + [0, n)

is valid if and only if n == 0; or n is positive, i is dereferenceable, and

++i + [0, --n)

is valid.

The result of the application of library functions to invalid ranges is undefined.

All the categories of iterators require only those functions that are realizable for a given category in constant time (amortized).

Therefore, requirement tables and concept definitions for the iterators do not specify complexity.

Destruction of an iterator may invalidate pointers and references previously obtained from that iterator if its type does not meet the Cpp17ForwardIterator requirements and does not model forward_iterator .

An invalid iterator is an iterator that may be singular.202

Iterators meet the constexpr iterators requirements if all operations provided to meet iterator category requirements are constexpr functions.

[Note 3:

For example, the types “pointer to int” and reverse_iterator<int*> meet the constexpr iterator requirements.

— end note]

201)201)

The sentinel denoting the end of a range can have the same type as the iterator denoting the beginning of the range, or a different type.

202)202)

This definition applies to pointers, since pointers are iterators.

The effect of dereferencing an iterator that has been invalidated is undefined.

24.3.2 Associated types [iterator.assoc.types]

24.3.2.1 Incrementable traits [incrementable.traits]

To implement algorithms only in terms of incrementable types, it is often necessary to determine the difference type that corresponds to a particular incrementable type.

Accordingly, it is required that if WI is the name of a type that models the weakly_incrementable concept ([iterator.concept.winc]), the type iter_difference_t<WI> be defined as the incrementable type's difference type.

🔗

namespace std { template<class> struct incrementable_traits { }; template<class T> requires is_object_v<T> struct incrementable_traits<T*> { using difference_type = ptrdiff_t; }; template<class I> struct incrementable_traits<const I> : incrementable_traits { }; template<class T> requires requires { typename T::difference_type; } struct incrementable_traits<T> { using difference_type = typename T::difference_type; }; template<class T> requires (!requires { typename T::difference_type; } && requires(const T& a, const T& b) { { a - b } -> integral; }) struct incrementable_traits<T> { using difference_type = make_signed_t<decltype(declval<T>() - declval<T>())>; }; template<class T> using iter_difference_t = see below; }

Let

R_{I}

be remove_cvref_t.

The type iter_difference_t denotes

(2.1)
incrementable_traits< $R_{I}$ >::difference_type if iterator_traits< $R_{I}$ > names a specialization generated from the primary template, and
(2.2)
iterator_traits< $R_{I}$ >::difference_type otherwise.

Users may specialize incrementable_traits on program-defined types.

24.3.2.2 Indirectly readable traits [readable.traits]

To implement algorithms only in terms of indirectly readable types, it is often necessary to determine the value type that corresponds to a particular indirectly readable type.

Accordingly, it is required that if R is the name of a type that models the indirectly_readable concept ([iterator.concept.readable]), the type iter_value_t<R> be defined as the indirectly readable type's value type.

🔗

template<class> struct cond-value-type { }; // exposition only template<class T> requires is_object_v<T> struct cond-value-type<T> { using value_type = remove_cv_t<T>; }; template<class T> concept has-member-value-type = requires { typename T::value_type; }; // exposition only template<class T> concept has-member-element-type = requires { typename T::element_type; }; // exposition only template<class> struct indirectly_readable_traits { }; template<class T> struct indirectly_readable_traits<T*> : cond-value-type<T> { }; template<class I> requires is_array_v struct indirectly_readable_traits { using value_type = remove_cv_t<remove_extent_t>; }; template<class I> struct indirectly_readable_traits<const I> : indirectly_readable_traits { }; template<has-member-value-type T> struct indirectly_readable_traits<T> : cond-value-type<typename T::value_type> { }; template<has-member-element-type T> struct indirectly_readable_traits<T> : cond-value-type<typename T::element_type> { }; template<has-member-value-type T> requires has-member-element-type<T> struct indirectly_readable_traits<T> { }; template<has-member-value-type T> requires has-member-element-type<T> && same_as<remove_cv_t<typename T::element_type>, remove_cv_t<typename T::value_type>> struct indirectly_readable_traits<T> : cond-value-type<typename T::value_type> { }; template<class T> using iter_value_t = see below;

Let

R_{I}

be remove_cvref_t.

The type iter_value_t denotes

(2.1)
indirectly_readable_traits< $R_{I}$ >::value_type if iterator_traits< $R_{I}$ > names a specialization generated from the primary template, and
(2.2)
iterator_traits< $R_{I}$ >::value_type otherwise.

Class template indirectly_readable_traits may be specialized on program-defined types.

[Note 1:

Some legacy output iterators define a nested type named value_type that is an alias for void.

These types are not indirectly_readable and have no associated value types.

— end note]

[Note 2:

Smart pointers like shared_ptr<int> are indirectly_readable and have an associated value type, but a smart pointer like shared_ptr<void> is not indirectly_readable and has no associated value type.

— end note]

24.3.2.3 Iterator traits [iterator.traits]

To implement algorithms only in terms of iterators, it is sometimes necessary to determine the iterator category that corresponds to a particular iterator type.

Accordingly, it is required that if I is the type of an iterator, the type

🔗

iterator_traits::iterator_category be defined as the iterator's iterator category.

In addition, the types

🔗

iterator_traits::pointer iterator_traits::reference shall be defined as the iterator's pointer and reference types; that is, for an iterator object a of class type, the same type as decltype(a.operator->()) and decltype(*a), respectively.

The type iterator_traits::pointer shall be void for an iterator of class type I that does not support operator->.

Additionally, in the case of an output iterator, the types iterator_traits::value_type iterator_traits::difference_type iterator_traits::reference may be defined as void.

The definitions in this subclause make use of the following exposition-only concepts: template<class I> concept cpp17-iterator = requires(I i) { { *i } -> can-reference; { ++i } -> same_as<I&>; { *i++ } -> can-reference; } && copyable; template<class I> concept cpp17-input-iterator = cpp17-iterator && equality_comparable && requires(I i) { typename incrementable_traits::difference_type; typename indirectly_readable_traits::value_type; typename common_reference_t<iter_reference_t&&, typename indirectly_readable_traits::value_type&>; typename common_reference_t<decltype(*i++)&&, typename indirectly_readable_traits::value_type&>; requires signed_integral<typename incrementable_traits::difference_type>; }; template<class I> concept cpp17-forward-iterator = cpp17-input-iterator && constructible_from && is_reference_v<iter_reference_t> && same_as<remove_cvref_t<iter_reference_t>, typename indirectly_readable_traits::value_type> && requires(I i) { { i++ } -> convertible_to<const I&>; { *i++ } -> same_as<iter_reference_t>; }; template<class I> concept cpp17-bidirectional-iterator = cpp17-forward-iterator && requires(I i) { { --i } -> same_as<I&>; { i-- } -> convertible_to<const I&>; { *i-- } -> same_as<iter_reference_t>; }; template<class I> concept cpp17-random-access-iterator = cpp17-bidirectional-iterator && totally_ordered && requires(I i, typename incrementable_traits::difference_type n) { { i += n } -> same_as<I&>; { i -= n } -> same_as<I&>; { i + n } -> same_as; { n + i } -> same_as; { i - n } -> same_as; { i - i } -> same_as<decltype(n)>; { i[n] } -> convertible_to<iter_reference_t>; };

The members of a specialization iterator_traits generated from the iterator_traits primary template are computed as follows:

(3.1)
If I has valid ([temp.deduct]) member types difference_type, value_type, reference, and iterator_category, then iterator_traits has the following publicly accessible members: using iterator_category = typename I::iterator_category; using value_type = typename I::value_type; using difference_type = typename I::difference_type; using pointer = see below; using reference = typename I::reference;
If the qualified-id I::pointer is valid and denotes a type, then iterator_traits::pointer names that type; otherwise, it names void.
(3.2)
Otherwise, if I satisfies the exposition-only concept cpp17-input-iterator, iterator_traits has the following publicly accessible members: using iterator_category = see below; using value_type = typename indirectly_readable_traits::value_type; using difference_type = typename incrementable_traits::difference_type; using pointer = see below; using reference = see below;
- (3.2.1)
 If the qualified-id I::pointer is valid and denotes a type, pointer names that type.
 
 Otherwise, if decltype(declval<I&>().operator->()) is well-formed, then pointer names that type.
 
 Otherwise, pointer names void.
- (3.2.2)
 If the qualified-id I::reference is valid and denotes a type, reference names that type.
 
 Otherwise, reference names iter_reference_t.
- (3.2.3)
 If the qualified-id I::iterator_category is valid and denotes a type, iterator_category names that type.
 Otherwise, iterator_category names:
 - (3.2.3.1)
 random_access_iterator_tag if I satisfies cpp17-random-access-iterator, or otherwise
 - (3.2.3.2)
 bidirectional_iterator_tag if I satisfies cpp17-bidirectional-iterator, or otherwise
 - (3.2.3.3)
 forward_iterator_tag if I satisfies cpp17-forward-iterator, or otherwise
 - (3.2.3.4)
 input_iterator_tag.
(3.3)
Otherwise, if I satisfies the exposition-only concept cpp17-iterator, then iterator_traits has the following publicly accessible members: using iterator_category = output_iterator_tag; using value_type = void; using difference_type = see below; using pointer = void; using reference = void;
If the qualified-id incrementable_traits::difference_type is valid and denotes a type, then difference_type names that type; otherwise, it names void.
(3.4)
Otherwise, iterator_traits has no members by any of the above names.

Explicit or partial specializations of iterator_traits may have a member type iterator_concept that is used to indicate conformance to the iterator concepts ([iterator.concepts]).

[Example 1:

To indicate conformance to the input_iterator concept but a lack of conformance to the Cpp17InputIterator requirements ([input.iterators]), an iterator_traits specialization might have iterator_concept denote input_iterator_tag but not define iterator_category.

— end example]

iterator_traits is specialized for pointers as namespace std { template<class T> requires is_object_v<T> struct iterator_traits<T*> { using iterator_concept = contiguous_iterator_tag; using iterator_category = random_access_iterator_tag; using value_type = remove_cv_t<T>; using difference_type = ptrdiff_t; using pointer = T*; using reference = T&; }; }

[Example 2:

To implement a generic reverse function, a C++ program can do the following: template<class BI> void reverse(BI first, BI last) { typename iterator_traits<BI>::difference_type n = distance(first, last); --n; while(n > 0) { typename iterator_traits<BI>::value_type tmp = *first; *first++ = *--last; *last = tmp; n -= 2; } }

— end example]

24.3.3 Customization point objects [iterator.cust]

24.3.3.1 ranges::iter_move [iterator.cust.move]

The name ranges::iter_move denotes a customization point object ([customization.point.object]).

The expression ranges::iter_move(E) for a subexpression E is expression-equivalent to:

(1.1)
iter_move(E), if E has class or enumeration type and iter_move(E) is a well-formed expression when treated as an unevaluated operand, where the meaning of iter_move is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
(1.2)
Otherwise, if the expression *E is well-formed:
- (1.2.1)
  if *E is an lvalue, std::move(*E);
- (1.2.2)
  otherwise, *E.
(1.3)
Otherwise, ranges::iter_move(E) is ill-formed.

[Note 1:
This case can result in substitution failure when ranges::iter_move(E) appears in the immediate context of a template instantiation.
— end note]

If ranges::iter_move(E) is not equal to *E, the program is ill-formed, no diagnostic required.

24.3.3.2 ranges::iter_swap [iterator.cust.swap]

The name ranges::iter_swap denotes a customization point object ([customization.point.object]) that exchanges the values ([concept.swappable]) denoted by its arguments.

Let iter-exchange-move be the exposition-only function template:

🔗

template<class X, class Y>
  constexpr iter_value_t<X> iter-exchange-move(X&& x, Y&& y)
    noexcept(noexcept(iter_value_t<X>(iter_move(x))) &&
             noexcept(*x = iter_move(y)));

Effects: Equivalent to: iter_value_t<X> old_value(iter_move(x)); *x = iter_move(y); return old_value;

The expression ranges::iter_swap(E1, E2) for subexpressions E1 and E2 is expression-equivalent to:

(4.1)
(void)iter_swap(E1, E2), if either E1 or E2 has class or enumeration type and iter_swap(E1, E2) is a well-formed expression with overload resolution performed in a context that includes the declaration template<class I1, class I2> void iter_swap(I1, I2) = delete; and does not include a declaration of ranges::iter_swap.

If the function selected by overload resolution does not exchange the values denoted by E1 and E2, the program is ill-formed, no diagnostic required.

[Note 1:
This precludes calling unconstrained std::iter_swap.

When the deleted overload is viable, program-defined overloads need to be more specialized ([temp.func.order]) to be selected.
— end note]
(4.2)
Otherwise, if the types of E1 and E2 each model indirectly_readable, and if the reference types of E1 and E2 model swappable_with ([concept.swappable]), then ranges::swap(*E1, *E2).
(4.3)
Otherwise, if the types T1 and T2 of E1 and E2 model indirectly_movable_storable<T1, T2> and indirectly_movable_storable<T2, T1>, then (void)(*E1 = iter-exchange-move(E2, E1)), except that E1 is evaluated only once.
(4.4)
Otherwise, ranges::iter_swap(E1, E2) is ill-formed.

[Note 2:
This case can result in substitution failure when ranges::iter_swap(E1, E2) appears in the immediate context of a template instantiation.
— end note]

24.3.4 Iterator concepts [iterator.concepts]

24.3.4.1 General [iterator.concepts.general]

For a type I, let ITER_TRAITS(I) denote the type I if iterator_traits names a specialization generated from the primary template.

Otherwise, ITER_TRAITS(I) denotes iterator_traits.

(1.1)
If the qualified-id ITER_TRAITS(I)::iterator_concept is valid and names a type, then ITER_CONCEPT(I) denotes that type.
(1.2)
Otherwise, if the qualified-id ITER_TRAITS(I)::iterator_category is valid and names a type, then ITER_CONCEPT(I) denotes that type.
(1.3)
Otherwise, if iterator_traits names a specialization generated from the primary template, then ITER_CONCEPT(I) denotes random_access_iterator_tag.
(1.4)
Otherwise, ITER_CONCEPT(I) does not denote a type.

[Note 1:

ITER_TRAITS enables independent syntactic determination of an iterator's category and concept.

— end note]

[Example 1:

struct I { using value_type = int; using difference_type = int; int operator*() const; I& operator++(); I operator++(int); I& operator--(); I operator--(int); bool operator==(I) const; }; iterator_traits::iterator_category denotes input_iterator_tag, and ITER_CONCEPT(I) denotes random_access_iterator_tag.

— end example]

24.3.4.2 Concept indirectly_readable [iterator.concept.readable]

Types that are indirectly readable by applying operator* model the indirectly_readable concept, including pointers, smart pointers, and iterators.

template<class In> concept indirectly-readable-impl = // exposition only requires(const In in) { typename iter_value_t<In>; typename iter_reference_t<In>; typename iter_rvalue_reference_t<In>; { *in } -> same_as<iter_reference_t<In>>; { ranges::iter_move(in) } -> same_as<iter_rvalue_reference_t<In>>; } && common_reference_with<iter_reference_t<In>&&, iter_value_t<In>&> && common_reference_with<iter_reference_t<In>&&, iter_rvalue_reference_t<In>&&> && common_reference_with<iter_rvalue_reference_t<In>&&, const iter_value_t<In>&>;

template<class In> concept indirectly_readable = indirectly-readable-impl<remove_cvref_t<In>>;

Given a value i of type I, I models indirectly_readable only if the expression *i is equality-preserving.

24.3.4.3 Concept indirectly_writable [iterator.concept.writable]

The indirectly_writable concept specifies the requirements for writing a value into an iterator's referenced object.

template<class Out, class T> concept indirectly_writable = requires(Out&& o, T&& t) { *o = std::forward<T>(t); // not required to be equality-preserving *std::forward<Out>(o) = std::forward<T>(t); // not required to be equality-preserving const_cast<const iter_reference_t<Out>&&>(*o) = std::forward<T>(t); // not required to be equality-preserving const_cast<const iter_reference_t<Out>&&>(*std::forward<Out>(o)) = std::forward<T>(t); // not required to be equality-preserving };

Let E be an expression such that decltype((E)) is T, and let o be a dereferenceable object of type Out.

Out and T model indirectly_writable<Out, T> only if:

(2.1)
If Out and T model indirectly_readable<Out> && same_as<iter_value_t<Out>, decay_t<T>>, then *o after any above assignment is equal to the value of E before the assignment.

After evaluating any above assignment expression, o is not required to be dereferenceable.

If E is an xvalue ([basic.lval]), the resulting state of the object it denotes is valid but unspecified ([lib.types.movedfrom]).

[Note 1:

The only valid use of an operator* is on the left side of the assignment statement.

Assignment through the same value of the indirectly writable type happens only once.

— end note]

[Note 2:

indirectly_writable has the awkward const_cast expressions to reject iterators with prvalue non-proxy reference types that permit rvalue assignment but do not also permit const rvalue assignment.

Consequently, an iterator type I that returns std::string by value does not model indirectly_writable<I, std::string>.

— end note]

24.3.4.4 Concept weakly_incrementable [iterator.concept.winc]

The weakly_incrementable concept specifies the requirements on types that can be incremented with the pre- and post-increment operators.

The increment operations are not required to be equality-preserving, nor is the type required to be equality_comparable .

template<class T> constexpr bool is-integer-like = see below; // exposition only template<class T> constexpr bool is-signed-integer-like = see below; // exposition only template<class I> concept weakly_incrementable = movable && requires(I i) { typename iter_difference_t; requires is-signed-integer-like<iter_difference_t>; { ++i } -> same_as<I&>; // not required to be equality-preserving i++; // not required to be equality-preserving };

A type I is an integer-class type if it is in a set of implementation-defined types that behave as integer types do, as defined below.

[Note 1:

An integer-class type is not necessarily a class type.

— end note]

The range of representable values of an integer-class type is the continuous set of values over which it is defined.

For any integer-class type, its range of representable values is either

- 2^{N - 1}

2^{N - 1} - 1

(inclusive) for some integer N, in which case it is a signed-integer-class type, or 0 to

2^{N} - 1

(inclusive) for some integer N, in which case it is an unsigned-integer-class type.

In both cases, N is called the width of the integer-class type.

The width of an integer-class type is greater than that of every integral type of the same signedness.

A type I other than cv bool is integer-like if it models integral or if it is an integer-class type.

An integer-like type I is signed-integer-like if it models signed_integral or if it is a signed-integer-class type.

An integer-like type I is unsigned-integer-like if it models unsigned_integral or if it is an unsigned-integer-class type.

For every integer-class type I, let B(I) be a unique hypothetical extended integer type of the same signedness with the same width ([basic.fundamental]) as I.

[Note 2:

The corresponding hypothetical specialization numeric_limits<B(I)> meets the requirements on numeric_limits specializations for integral types ([numeric.limits]).

— end note]

For every integral type J, let B(J) be the same type as J.

Expressions of integer-class type are explicitly convertible to any integer-like type, and implicitly convertible to any integer-class type of equal or greater width and the same signedness.

Expressions of integral type are both implicitly and explicitly convertible to any integer-class type.

Conversions between integral and integer-class types and between two integer-class types do not exit via an exception.

The result of such a conversion is the unique value of the destination type that is congruent to the source modulo

2^{N}

, where N is the width of the destination type.

Let a be an object of integer-class type I, let b be an object of integer-like type I2 such that the expression b is implicitly convertible to I, let x and y be, respectively, objects of type B(I) and B(I2) as described above that represent the same values as a and b, and let c be an lvalue of any integral type.

(7.1)
The expressions a++ and a-- shall be prvalues of type I whose values are equal to that of a prior to the evaluation of the expressions.

The expression a++ shall modify the value of a by adding 1 to it.

The expression a-- shall modify the value of a by subtracting 1 from it.
(7.2)
The expressions ++a, --a, and &a shall be expression-equivalent to a += 1, a -= 1, and addressof(a), respectively.
(7.3)
For every unary-operator @ other than & for which the expression @x is well-formed, @a shall also be well-formed and have the same value, effects, and value category as @x.

If @x has type bool, so too does @a; if @x has type B(I), then @a has type I.
(7.4)
For every assignment operator @= for which c @= x is well-formed, c @= a shall also be well-formed and shall have the same value and effects as c @= x.

The expression c @= a shall be an lvalue referring to c.
(7.5)
For every assignment operator @= for which x @= y is well-formed, a @= b shall also be well-formed and shall have the same effects as x @= y, except that the value that would be stored into x is stored into a.

The expression a @= b shall be an lvalue referring to a.
(7.6)
For every non-assignment binary operator @ for which x @ y and y @ x are well-formed, a @ b and b @ a shall also be well-formed and shall have the same value, effects, and value category as x @ y and y @ x, respectively.

If x @ y or y @ x has type B(I), then a @ b or b @ a, respectively, has type I; if x @ y or y @ x has type B(I2), then a @ b or b @ a, respectively, has type I2; if x @ y or y @ x has any other type, then a @ b or b @ a, respectively, has that type.

An expression E of integer-class type I is contextually convertible to bool as if by bool(E != I(0)).

All integer-class types model regular ([concepts.object]) and three_way_comparable<strong_ordering> ([cmp.concept]).

A value-initialized object of integer-class type has value 0.

For every (possibly cv-qualified) integer-class type I, numeric_limits is specialized such that each static data member m has the same value as numeric_limits<B(I)>::m, and each static member function f returns I(numeric_limits<B(I)>::f()).

For any two integer-like types I1 and I2, at least one of which is an integer-class type, common_type_t<I1, I2> denotes an integer-class type whose width is not less than that of I1 or I2.

If both I1 and I2 are signed-integer-like types, then common_type_t<I1, I2> is also a signed-integer-like type.

is-integer-like is true if and only if I is an integer-like type.

is-signed-integer-like is true if and only if I is a signed-integer-like type.

Let i be an object of type I.

When i is in the domain of both pre- and post-increment, i is said to be incrementable.

I models weakly_incrementable only if:

(14.1)
The expressions ++i and i++ have the same domain.
(14.2)
If i is incrementable, then both ++i and i++ advance i to the next element.
(14.3)
If i is incrementable, then addressof(++i) is equal to addressof(i).

Recommended practice: The implementation of an algorithm on a weakly incrementable type should never attempt to pass through the same incrementable value twice; such an algorithm should be a single-pass algorithm.

[Note 3:

For weakly_incrementable types, a equals b does not imply that ++a equals ++b.

(Equality does not guarantee the substitution property or referential transparency.)

Such algorithms can be used with istreams as the source of the input data through the istream_iterator class template.

— end note]

24.3.4.5 Concept incrementable [iterator.concept.inc]

The incrementable concept specifies requirements on types that can be incremented with the pre- and post-increment operators.

The increment operations are required to be equality-preserving, and the type is required to be equality_comparable .

[Note 1:

This supersedes the annotations on the increment expressions in the definition of weakly_incrementable .

— end note]

template<class I> concept incrementable = regular && weakly_incrementable && requires(I i) { { i++ } -> same_as; };

Let a and b be incrementable objects of type I.

I models incrementable only if:

(2.1)
If bool(a == b) then bool(a++ == b).
(2.2)
If bool(a == b) then bool(((void)a++, a) == ++b).

[Note 2:

The requirement that a equals b implies ++a equals ++b (which is not true for weakly incrementable types) allows the use of multi-pass one-directional algorithms with types that model incrementable .

— end note]

24.3.4.6 Concept input_or_output_iterator [iterator.concept.iterator]

The input_or_output_iterator concept forms the basis of the iterator concept taxonomy; every iterator models input_or_output_iterator .

This concept specifies operations for dereferencing and incrementing an iterator.

Most algorithms will require additional operations to compare iterators with sentinels ([iterator.concept.sentinel]), to read ([iterator.concept.input]) or write ([iterator.concept.output]) values, or to provide a richer set of iterator movements ([iterator.concept.forward], [iterator.concept.bidir], [iterator.concept.random.access]).

template<class I> concept input_or_output_iterator = requires(I i) { { *i } -> can-reference; } && weakly_incrementable;

[Note 1:

Unlike the Cpp17Iterator requirements, the input_or_output_iterator concept does not require copyability.

— end note]

24.3.4.7 Concept sentinel_for [iterator.concept.sentinel]

The sentinel_for concept specifies the relationship between an input_or_output_iterator type and a semiregular type whose values denote a range.

🔗

template<class S, class I>
  concept sentinel_for =
    semiregular<S> &&
    input_or_output_iterator<I> &&
    weakly-equality-comparable-with<S, I>;      // see [concept.equalitycomparable]

Let s and i be values of type S and I such that [i, s) denotes a range.

Types S and I model sentinel_for<S, I> only if:

(2.1)
i == s is well-defined.
(2.2)
If bool(i != s) then i is dereferenceable and [++i, s) denotes a range.
(2.3)
assignable_from<I&, S> is either modeled or not satisfied.

The domain of == is not static.

Given an iterator i and sentinel s such that [i, s) denotes a range and i != s, i and s are not required to continue to denote a range after incrementing any other iterator equal to i.

Consequently, i == s is no longer required to be well-defined.

24.3.4.8 Concept sized_sentinel_for [iterator.concept.sizedsentinel]

The sized_sentinel_for concept specifies requirements on an input_or_output_iterator type I and a corresponding sentinel_for that allow the use of the - operator to compute the distance between them in constant time.

🔗

template<class S, class I>
  concept sized_sentinel_for =
    sentinel_for<S, I> &&
    !disable_sized_sentinel_for<remove_cv_t<S>, remove_cv_t<I>> &&
    requires(const I& i, const S& s) {
      { s - i } -> same_as<iter_difference_t<I>>;
      { i - s } -> same_as<iter_difference_t<I>>;
    };

Let i be an iterator of type I, and s a sentinel of type S such that [i, s) denotes a range.

Let N be the smallest number of applications of ++i necessary to make bool(i == s) be true.

S and I model sized_sentinel_for<S, I> only if:

(2.1)
If N is representable by iter_difference_t, then s - i is well-defined and equals N.
(2.2)
If $- N$ is representable by iter_difference_t, then i - s is well-defined and equals $- N$ .

🔗

template<class S, class I>
  constexpr bool disable_sized_sentinel_for = false;

Remarks: Pursuant to [namespace.std], users may specialize disable_sized_sentinel_for for cv-unqualified non-array object types S and I if S and/or I is a program-defined type.

Such specializations shall be usable in constant expressions ([expr.const]) and have type const bool.

[Note 1:

disable_sized_sentinel_for allows use of sentinels and iterators with the library that satisfy but do not in fact model sized_sentinel_for .

— end note]

[Example 1:

The sized_sentinel_for concept is modeled by pairs of random_access_iterators ([iterator.concept.random.access]) and by counted iterators and their sentinels ([counted.iterator]).

— end example]

24.3.4.9 Concept input_iterator [iterator.concept.input]

The input_iterator concept defines requirements for a type whose referenced values can be read (from the requirement for indirectly_readable ([iterator.concept.readable])) and which can be both pre- and post-incremented.

[Note 1:

Unlike the Cpp17InputIterator requirements ([input.iterators]), the input_iterator concept does not need equality comparison since iterators are typically compared to sentinels.

— end note]

template<class I> concept input_iterator = input_or_output_iterator && indirectly_readable && requires { typename ITER_CONCEPT(I); } && derived_from<ITER_CONCEPT(I), input_iterator_tag>;

24.3.4.10 Concept output_iterator [iterator.concept.output]

The output_iterator concept defines requirements for a type that can be used to write values (from the requirement for indirectly_writable ([iterator.concept.writable])) and which can be both pre- and post-incremented.

[Note 1:

Output iterators are not required to model equality_comparable .

— end note]

template<class I, class T> concept output_iterator = input_or_output_iterator && indirectly_writable<I, T> && requires(I i, T&& t) { *i++ = std::forward<T>(t); // not required to be equality-preserving };

Let E be an expression such that decltype((E)) is T, and let i be a dereferenceable object of type I.

I and T model output_iterator<I, T> only if *i++ = E; has effects equivalent to: *i = E; ++i;

Recommended practice: The implementation of an algorithm on output iterators should never attempt to pass through the same iterator twice; such an algorithm should be a single-pass algorithm.

24.3.4.11 Concept forward_iterator [iterator.concept.forward]

The forward_iterator concept adds copyability, equality comparison, and the multi-pass guarantee, specified below.

template<class I> concept forward_iterator = input_iterator && derived_from<ITER_CONCEPT(I), forward_iterator_tag> && incrementable && sentinel_for<I, I>;

The domain of == for forward iterators is that of iterators over the same underlying sequence.

However, value-initialized iterators of the same type may be compared and shall compare equal to other value-initialized iterators of the same type.

[Note 1:

Value-initialized iterators behave as if they refer past the end of the same empty sequence.

— end note]

Pointers and references obtained from a forward iterator into a range [i, s) shall remain valid while [i, s) continues to denote a range.

Two dereferenceable iterators a and b of type X offer the multi-pass guarantee if

(4.1)
a == b implies ++a == ++b and
(4.2)
the expression ((void)[](X x){++x;}(a), *a) is equivalent to the expression *a.

[Note 2:

The requirement that a == b implies ++a == ++b and the removal of the restrictions on the number of assignments through a mutable iterator (which applies to output iterators) allow the use of multi-pass one-directional algorithms with forward iterators.

— end note]

24.3.4.12 Concept bidirectional_iterator [iterator.concept.bidir]

The bidirectional_iterator concept adds the ability to move an iterator backward as well as forward.

template<class I> concept bidirectional_iterator = forward_iterator && derived_from<ITER_CONCEPT(I), bidirectional_iterator_tag> && requires(I i) { { --i } -> same_as<I&>; { i-- } -> same_as; };

A bidirectional iterator r is decrementable if and only if there exists some q such that ++q == r.

Decrementable iterators r shall be in the domain of the expressions --r and r--.

Let a and b be equal objects of type I.

I models bidirectional_iterator only if:

(3.1)
If a and b are decrementable, then all of the following are true:
- (3.1.1)
  addressof(--a) == addressof(a)
- (3.1.2)
  bool(a-- == b)
- (3.1.3)
  after evaluating both a-- and --b, bool(a == b) is still true
- (3.1.4)
  bool(++(--a) == b)
(3.2)
If a and b are incrementable, then bool(--(++a) == b).

24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]

The random_access_iterator concept adds support for constant-time advancement with +=, +, -=, and -, as well as the computation of distance in constant time with -.

Random access iterators also support array notation via subscripting.

template<class I> concept random_access_iterator = bidirectional_iterator && derived_from<ITER_CONCEPT(I), random_access_iterator_tag> && totally_ordered && sized_sentinel_for<I, I> && requires(I i, const I j, const iter_difference_t n) { { i += n } -> same_as<I&>; { j + n } -> same_as; { n + j } -> same_as; { i -= n } -> same_as<I&>; { j - n } -> same_as; { j[n] } -> same_as<iter_reference_t>; };

Let a and b be valid iterators of type I such that b is reachable from a after n applications of ++a, let D be iter_difference_t, and let n denote a value of type D.

I models random_access_iterator only if:

(2.1)
(a += n) is equal to b.
(2.2)
addressof(a += n) is equal to addressof(a).
(2.3)
(a + n) is equal to (a += n).
(2.4)
For any two positive values x and y of type D, if (a + D(x + y)) is valid, then (a + D(x + y)) is equal to ((a + x) + y).
(2.5)
(a + D(0)) is equal to a.
(2.6)
If (a + D(n - 1)) is valid, then (a + n) is equal to [](I c){ return ++c; }(a + D(n - 1)).
(2.7)
(b += D(-n)) is equal to a.
(2.8)
(b -= n) is equal to a.
(2.9)
addressof(b -= n) is equal to addressof(b).
(2.10)
(b - n) is equal to (b -= n).
(2.11)
If b is dereferenceable, then a[n] is valid and is equal to *b.
(2.12)
bool(a <= b) is true.

24.3.4.14 Concept contiguous_iterator [iterator.concept.contiguous]

The contiguous_iterator concept provides a guarantee that the denoted elements are stored contiguously in memory.

template<class I> concept contiguous_iterator = random_access_iterator && derived_from<ITER_CONCEPT(I), contiguous_iterator_tag> && is_lvalue_reference_v<iter_reference_t> && same_as<iter_value_t, remove_cvref_t<iter_reference_t>> && requires(const I& i) { { to_address(i) } -> same_as<add_pointer_t<iter_reference_t>>; };

Let a and b be dereferenceable iterators and c be a non-dereferenceable iterator of type I such that b is reachable from a and c is reachable from b, and let D be iter_difference_t.

The type I models contiguous_iterator only if

(2.1)
to_address(a) == addressof(*a),
(2.2)
to_address(b) == to_address(a) + D(b - a),
(2.3)
to_address(c) == to_address(a) + D(c - a),
(2.4)
to_address(I{}) is well-defined,
(2.5)
ranges::iter_move(a) has the same type, value category, and effects as std::move(*a), and
(2.6)
if ranges::iter_swap(a, b) is well-formed, it has effects equivalent to ranges::swap(*a, *b).

24.3.5 C++17 iterator requirements [iterator.cpp17]

24.3.5.1 General [iterator.cpp17.general]

In the following sections, a and b denote values of type X or const X, difference_type and reference refer to the types iterator_traits<X>::difference_type and iterator_traits<X>::reference, respectively, n denotes a value of difference_type, u, tmp, and m denote identifiers, r denotes a value of X&, t denotes a value of value type T, o denotes a value of some type that is writable to the output iterator.

[Note 1:

For an iterator type X there must be an instantiation of iterator_traits<X> ([iterator.traits]).

— end note]

24.3.5.2 Cpp17Iterator [iterator.iterators]

The Cpp17Iterator requirements form the basis of the iterator taxonomy; every iterator meets the Cpp17Iterator requirements.

This set of requirements specifies operations for dereferencing and incrementing an iterator.

Most algorithms will require additional operations to read ([input.iterators]) or write ([output.iterators]) values, or to provide a richer set of iterator movements ([forward.iterators], [bidirectional.iterators], [random.access.iterators]).

A type X meets the Cpp17Iterator requirements if

(2.1)
X meets the Cpp17CopyConstructible, Cpp17CopyAssignable, Cpp17Swappable, and Cpp17Destructible requirements ([utility.arg.requirements], [swappable.requirements]), and
(2.2)
iterator_traits<X>::difference_type is a signed integer type or void, and
(2.3)
the expressions in Table 73 are valid and have the indicated semantics.

Table 73 — Cpp17Iterator requirements [tab:iterator]

🔗 Expression	Return type	Operational	Assertion/note
🔗		semantics	pre-/post-condition
🔗 *r	unspecified		Preconditions: r is dereferenceable.
🔗 ++r	X&

24.3.5.3 Input iterators [input.iterators]

A class or pointer type X meets the requirements of an input iterator for the value type T if X meets the Cpp17Iterator ([iterator.iterators]) and Cpp17EqualityComparable (Table 28) requirements and the expressions in Table 74 are valid and have the indicated semantics.

In Table 74, the term the domain of == is used in the ordinary mathematical sense to denote the set of values over which == is (required to be) defined.

This set can change over time.

Each algorithm places additional requirements on the domain of == for the iterator values it uses.

These requirements can be inferred from the uses that algorithm makes of == and !=.

[Example 1:

The call find(a,b,x) is defined only if the value of a has the property p defined as follows: b has property p and a value i has property p if (*i==x) or if (*i!=x and ++i has property p).

— end example]

Table 74 — Cpp17InputIterator requirements (in addition to Cpp17Iterator) [tab:inputiterator]

🔗 Expression	Return type	Operational	Assertion/note
🔗		semantics	pre-/post-condition
🔗 a != b	decltype(a != b) models boolean-testable	!(a == b)	Preconditions: (a, b) is in the domain of ==.
🔗 *a	reference, convertible to T		Preconditions: a is dereferenceable. The expression (void)a, a is equivalent to a. If a == b and (a, b) is in the domain of == then a is equivalent to *b.
🔗 a->m		(*a).m	Preconditions: a is dereferenceable.
🔗 ++r	X&		Preconditions: r is dereferenceable. Postconditions: r is dereferenceable or r is past-the-end; any copies of the previous value of r are no longer required to be dereferenceable nor to be in the domain of ==.
🔗 (void)r++			equivalent to (void)++r
🔗 *r++	convertible to T	{ T tmp = *r; ++r; return tmp; }

Recommended practice: The implementation of an algorithm on input iterators should never attempt to pass through the same iterator twice; such an algorithm should be a single pass algorithm.

[Note 1:

For input iterators, a == b does not imply ++a == ++b.

(Equality does not guarantee the substitution property or referential transparency.)

Value type T is not required to be a Cpp17CopyAssignable type (Table 34).

Such an algorithm can be used with istreams as the source of the input data through the istream_iterator class template.

— end note]

24.3.5.4 Output iterators [output.iterators]

A class or pointer type X meets the requirements of an output iterator if X meets the Cpp17Iterator requirements ([iterator.iterators]) and the expressions in Table 75 are valid and have the indicated semantics.

Table 75 — Cpp17OutputIterator requirements (in addition to Cpp17Iterator) [tab:outputiterator]

🔗 Expression	Return type	Operational	Assertion/note
🔗		semantics	pre-/post-condition
🔗 *r = o	result is not used		Remarks: After this operation r is not required to be dereferenceable. Postconditions: r is incrementable.
🔗 ++r	X&		addressof(r) == addressof(++r). Remarks: After this operation r is not required to be dereferenceable. Postconditions: r is incrementable.
🔗 r++	convertible to const X&	{ X tmp = r; ++r; return tmp; }	Remarks: After this operation r is not required to be dereferenceable. Postconditions: r is incrementable.
🔗 *r++ = o	result is not used		Remarks: After this operation r is not required to be dereferenceable. Postconditions: r is incrementable.

Recommended practice: The implementation of an algorithm on output iterators should never attempt to pass through the same iterator twice; such an algorithm should be a single-pass algorithm.

[Note 1:

The only valid use of an operator* is on the left side of the assignment statement.

Assignment through the same value of the iterator happens only once.

Equality and inequality are not necessarily defined.

— end note]

24.3.5.5 Forward iterators [forward.iterators]

A class or pointer type X meets the Cpp17ForwardIterator requirements if

(1.1)
X meets the Cpp17InputIterator requirements ([input.iterators]),
(1.2)
X meets the Cpp17DefaultConstructible requirements ([utility.arg.requirements]),
(1.3)
if X is a mutable iterator, reference is a reference to T; if X is a constant iterator, reference is a reference to const T,
(1.4)
the expressions in Table 76 are valid and have the indicated semantics, and
(1.5)
objects of type X offer the multi-pass guarantee, described below.

The domain of == for forward iterators is that of iterators over the same underlying sequence.

However, value-initialized iterators may be compared and shall compare equal to other value-initialized iterators of the same type.

[Note 1:

Value-initialized iterators behave as if they refer past the end of the same empty sequence.

— end note]

Two dereferenceable iterators a and b of type X offer the multi-pass guarantee if

(3.1)
a == b implies ++a == ++b and
(3.2)
X is a pointer type or the expression (void)++X(a), *a is equivalent to the expression *a.

[Note 2:

The requirement that a == b implies ++a == ++b (which is not true for input and output iterators) and the removal of the restrictions on the number of the assignments through a mutable iterator (which applies to output iterators) allows the use of multi-pass one-directional algorithms with forward iterators.

— end note]

Table 76 — Cpp17ForwardIterator requirements (in addition to Cpp17InputIterator) [tab:forwarditerator]

🔗 Expression	Return type	Operational	Assertion/note
🔗		semantics	pre-/post-condition
🔗 r++	convertible to const X&	{ X tmp = r; ++r; return tmp; }
🔗 *r++	reference

If a and b are equal, then either a and b are both dereferenceable or else neither is dereferenceable.

If a and b are both dereferenceable, then a == b if and only if *a and *b are bound to the same object.

24.3.5.6 Bidirectional iterators [bidirectional.iterators]

A class or pointer type X meets the requirements of a bidirectional iterator if, in addition to meeting the Cpp17ForwardIterator requirements, the following expressions are valid as shown in Table 77 .

Table 77 — Cpp17BidirectionalIterator requirements (in addition to Cpp17ForwardIterator) [tab:bidirectionaliterator]

🔗 Expression	Return type	Operational	Assertion/note
🔗		semantics	pre-/post-condition
🔗 --r	X&		Preconditions: there exists s such that r == ++s. Postconditions: r is dereferenceable. --(++r) == r. --r == --s implies r == s. addressof(r) == addressof(--r).
🔗 r--	convertible to const X&	{ X tmp = r; --r; return tmp; }
🔗 *r--	reference

[Note 1:

Bidirectional iterators allow algorithms to move iterators backward as well as forward.

— end note]

24.3.5.7 Random access iterators [random.access.iterators]

A class or pointer type X meets the requirements of a random access iterator if, in addition to meeting the Cpp17BidirectionalIterator requirements, the following expressions are valid as shown in Table 78 .

Table 78 — Cpp17RandomAccessIterator requirements (in addition to Cpp17BidirectionalIterator) [tab:randomaccessiterator]

🔗 Expression	Return type	Operational	Assertion/note
🔗		semantics	pre-/post-condition
🔗 r += n	X&	{ difference_type m = n; if (m >= 0) while (m--) ++r; else while (m++) --r; return r; }
🔗 a + n n + a	X	{ X tmp = a; return tmp += n; }	a + n == n + a.
🔗 r -= n	X&	return r += -n;	Preconditions: the absolute value of n is in the range of representable values of difference_type.
🔗 a - n	X	{ X tmp = a; return tmp -= n; }
🔗 b - a	difference_type	return n;	Preconditions: there exists a value n of type difference_type such that a + n == b. b == a + (b - a).
🔗 a[n]	convertible to reference	*(a + n)
🔗 a < b	decltype(a < b) models boolean-testable	Effects: Equivalent to: return b - a > 0;	< is a total ordering relation
🔗 a > b	decltype(a > b) models boolean-testable	b < a	> is a total ordering relation opposite to <.
🔗 a >= b	decltype(a >= b) models boolean-testable	!(a < b)
🔗 a <= b	decltype(a <= b) models boolean-testable	!(a > b)

24.3.6 Indirect callable requirements [indirectcallable]

24.3.6.1 General [indirectcallable.general]

There are several concepts that group requirements of algorithms that take callable objects ([func.def]) as arguments.

24.3.6.2 Indirect callable traits [indirectcallable.traits]

To implement algorithms taking projections, it is necessary to determine the projected type of an iterator's value type.

For the exposition-only alias template indirect-value-t, indirect-value-t<T> denotes

(1.1)
invoke_result_t<Proj&, indirect-value-t> if T names projected<I, Proj>, and
(1.2)
iter_value_t<T>& otherwise.

24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]

The indirect callable concepts are used to constrain those algorithms that accept callable objects ([func.def]) as arguments.

namespace std { template<class F, class I> concept indirectly_unary_invocable = indirectly_readable && copy_constructible<F> && invocable<F&, indirect-value-t> && invocable<F&, iter_reference_t> && common_reference_with< invoke_result_t<F&, indirect-value-t>, invoke_result_t<F&, iter_reference_t>>; template<class F, class I> concept indirectly_regular_unary_invocable = indirectly_readable && copy_constructible<F> && regular_invocable<F&, indirect-value-t> && regular_invocable<F&, iter_reference_t> && common_reference_with< invoke_result_t<F&, indirect-value-t>, invoke_result_t<F&, iter_reference_t>>; template<class F, class I> concept indirect_unary_predicate = indirectly_readable && copy_constructible<F> && predicate<F&, indirect-value-t> && predicate<F&, iter_reference_t>; template<class F, class I1, class I2> concept indirect_binary_predicate = indirectly_readable<I1> && indirectly_readable<I2> && copy_constructible<F> && predicate<F&, indirect-value-t<I1>, indirect-value-t<I2>> && predicate<F&, indirect-value-t<I1>, iter_reference_t<I2>> && predicate<F&, iter_reference_t<I1>, indirect-value-t<I2>> && predicate<F&, iter_reference_t<I1>, iter_reference_t<I2>>; template<class F, class I1, class I2 = I1> concept indirect_equivalence_relation = indirectly_readable<I1> && indirectly_readable<I2> && copy_constructible<F> && equivalence_relation<F&, indirect-value-t<I1>, indirect-value-t<I2>> && equivalence_relation<F&, indirect-value-t<I1>, iter_reference_t<I2>> && equivalence_relation<F&, iter_reference_t<I1>, indirect-value-t<I2>> && equivalence_relation<F&, iter_reference_t<I1>, iter_reference_t<I2>>; template<class F, class I1, class I2 = I1> concept indirect_strict_weak_order = indirectly_readable<I1> && indirectly_readable<I2> && copy_constructible<F> && strict_weak_order<F&, indirect-value-t<I1>, indirect-value-t<I2>> && strict_weak_order<F&, indirect-value-t<I1>, iter_reference_t<I2>> && strict_weak_order<F&, iter_reference_t<I1>, indirect-value-t<I2>> && strict_weak_order<F&, iter_reference_t<I1>, iter_reference_t<I2>>; }

24.3.6.4 Class template projected [projected]

Class template projected is used to constrain algorithms that accept callable objects and projections ([defns.projection]).

It combines an indirectly_readable type I and a callable object type Proj into a new indirectly_readable type whose reference type is the result of applying Proj to the iter_reference_t of I.

🔗

namespace std { template<class I, class Proj> struct projected-impl { // exposition only struct type { // exposition only using value_type = remove_cvref_t<indirect_result_t<Proj&, I>>; using difference_type = iter_difference_t; // present only if I // models weakly_incrementable indirect_result_t<Proj&, I> operator*() const; // not defined }; }; template<indirectly_readable I, indirectly_regular_unary_invocable Proj> using projected = projected-impl<I, Proj>::type; }

24.3.7 Common algorithm requirements [alg.req]

24.3.7.1 General [alg.req.general]

There are several additional iterator concepts that are commonly applied to families of algorithms.

These group together iterator requirements of algorithm families.

There are three relational concepts that specify how element values are transferred between indirectly_readable and indirectly_writable types: indirectly_movable, indirectly_copyable, and indirectly_swappable .

There are three relational concepts for rearrangements: permutable, mergeable, and sortable .

There is one relational concept for comparing values from different sequences: indirectly_comparable .

[Note 1:

The ranges::less function object type used in the concepts below imposes constraints on the concepts' arguments in addition to those that appear in the concepts' bodies ([range.cmp]).

— end note]

24.3.7.2 Concept indirectly_movable [alg.req.ind.move]

The indirectly_movable concept specifies the relationship between an indirectly_readable type and an indirectly_writable type between which values may be moved.

template<class In, class Out> concept indirectly_movable = indirectly_readable<In> && indirectly_writable<Out, iter_rvalue_reference_t<In>>;

The indirectly_movable_storable concept augments indirectly_movable with additional requirements enabling the transfer to be performed through an intermediate object of the indirectly_readable type's value type.

template<class In, class Out> concept indirectly_movable_storable = indirectly_movable<In, Out> && indirectly_writable<Out, iter_value_t<In>> && movable<iter_value_t<In>> && constructible_from<iter_value_t<In>, iter_rvalue_reference_t<In>> && assignable_from<iter_value_t<In>&, iter_rvalue_reference_t<In>>;

Let i be a dereferenceable value of type In.

In and Out model indirectly_movable_storable<In, Out> only if after the initialization of the object obj in iter_value_t<In> obj(ranges::iter_move(i)); obj is equal to the value previously denoted by *i.

If iter_rvalue_reference_t<In> is an rvalue reference type, the resulting state of the value denoted by *i is valid but unspecified ([lib.types.movedfrom]).

24.3.7.3 Concept indirectly_copyable [alg.req.ind.copy]

The indirectly_copyable concept specifies the relationship between an indirectly_readable type and an indirectly_writable type between which values may be copied.

template<class In, class Out> concept indirectly_copyable = indirectly_readable<In> && indirectly_writable<Out, iter_reference_t<In>>;

The indirectly_copyable_storable concept augments indirectly_copyable with additional requirements enabling the transfer to be performed through an intermediate object of the indirectly_readable type's value type.

It also requires the capability to make copies of values.

template<class In, class Out> concept indirectly_copyable_storable = indirectly_copyable<In, Out> && indirectly_writable<Out, iter_value_t<In>&> && indirectly_writable<Out, const iter_value_t<In>&> && indirectly_writable<Out, iter_value_t<In>&&> && indirectly_writable<Out, const iter_value_t<In>&&> && copyable<iter_value_t<In>> && constructible_from<iter_value_t<In>, iter_reference_t<In>> && assignable_from<iter_value_t<In>&, iter_reference_t<In>>;

Let i be a dereferenceable value of type In.

In and Out model indirectly_copyable_storable<In, Out> only if after the initialization of the object obj in iter_value_t<In> obj(*i); obj is equal to the value previously denoted by *i.

If iter_reference_t<In> is an rvalue reference type, the resulting state of the value denoted by *i is valid but unspecified ([lib.types.movedfrom]).

24.3.7.4 Concept indirectly_swappable [alg.req.ind.swap]

The indirectly_swappable concept specifies a swappable relationship between the values referenced by two indirectly_readable types.

template<class I1, class I2 = I1> concept indirectly_swappable = indirectly_readable<I1> && indirectly_readable<I2> && requires(const I1 i1, const I2 i2) { ranges::iter_swap(i1, i1); ranges::iter_swap(i2, i2); ranges::iter_swap(i1, i2); ranges::iter_swap(i2, i1); };

24.3.7.5 Concept indirectly_comparable [alg.req.ind.cmp]

The indirectly_comparable concept specifies the common requirements of algorithms that compare values from two different sequences.

template<class I1, class I2, class R, class P1 = identity, class P2 = identity> concept indirectly_comparable = indirect_binary_predicate<R, projected<I1, P1>, projected<I2, P2>>;

24.3.7.6 Concept permutable [alg.req.permutable]

The permutable concept specifies the common requirements of algorithms that reorder elements in place by moving or swapping them.

template<class I> concept permutable = forward_iterator && indirectly_movable_storable<I, I> && indirectly_swappable<I, I>;

24.3.7.7 Concept mergeable [alg.req.mergeable]

The mergeable concept specifies the requirements of algorithms that merge sorted sequences into an output sequence by copying elements.

template<class I1, class I2, class Out, class R = ranges::less, class P1 = identity, class P2 = identity> concept mergeable = input_iterator<I1> && input_iterator<I2> && weakly_incrementable<Out> && indirectly_copyable<I1, Out> && indirectly_copyable<I2, Out> && indirect_strict_weak_order<R, projected<I1, P1>, projected<I2, P2>>;

24.3.7.8 Concept sortable [alg.req.sortable]

The sortable concept specifies the common requirements of algorithms that permute sequences into ordered sequences (e.g., sort).

template<class I, class R = ranges::less, class P = identity> concept sortable = permutable && indirect_strict_weak_order<R, projected<I, P>>;

24 Iterators library [iterators]

24.3 Iterator requirements [iterator.requirements]

24.3.1 General [iterator.requirements.general]

24.3.2 Associated types [iterator.assoc.types]

24.3.2.1 Incrementable traits [incrementable.traits]

24.3.2.2 Indirectly readable traits [readable.traits]

24.3.2.3 Iterator traits [iterator.traits]

24.3.3 Customization point objects [iterator.cust]

24.3.3.1 ranges​::​iter_move [iterator.cust.move]

24.3.3.2 ranges​::​iter_swap [iterator.cust.swap]

24.3.4 Iterator concepts [iterator.concepts]

24.3.4.1 General [iterator.concepts.general]

24.3.4.2 Concept indirectly_readable [iterator.concept.readable]

24.3.4.3 Concept indirectly_writable [iterator.concept.writable]

24.3.4.4 Concept weakly_incrementable [iterator.concept.winc]

24.3.4.5 Concept incrementable [iterator.concept.inc]

24.3.4.6 Concept input_or_output_iterator [iterator.concept.iterator]

24.3.4.7 Concept sentinel_for [iterator.concept.sentinel]

24.3.4.8 Concept sized_sentinel_for [iterator.concept.sizedsentinel]

24.3.4.9 Concept input_iterator [iterator.concept.input]

24.3.4.10 Concept output_iterator [iterator.concept.output]

24.3.4.11 Concept forward_iterator [iterator.concept.forward]

24.3.4.12 Concept bidirectional_iterator [iterator.concept.bidir]

24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]

24.3.4.14 Concept contiguous_iterator [iterator.concept.contiguous]

24.3.5 C++17 iterator requirements [iterator.cpp17]

24.3.5.1 General [iterator.cpp17.general]

24.3.5.2 Cpp17Iterator [iterator.iterators]

24.3.5.3 Input iterators [input.iterators]

24.3.5.4 Output iterators [output.iterators]

24.3.5.5 Forward iterators [forward.iterators]

24.3.5.6 Bidirectional iterators [bidirectional.iterators]

24.3.5.7 Random access iterators [random.access.iterators]

24.3.6 Indirect callable requirements [indirectcallable]

24.3.6.1 General [indirectcallable.general]

24.3.6.2 Indirect callable traits [indirectcallable.traits]

24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]

24.3.6.4 Class template projected [projected]

24.3.7 Common algorithm requirements [alg.req]

24.3.7.1 General [alg.req.general]

24.3.7.2 Concept indirectly_movable [alg.req.ind.move]

24.3.7.3 Concept indirectly_copyable [alg.req.ind.copy]

24.3.7.4 Concept indirectly_swappable [alg.req.ind.swap]

24.3.7.5 Concept indirectly_comparable [alg.req.ind.cmp]

24.3.7.6 Concept permutable [alg.req.permutable]

24.3.7.7 Concept mergeable [alg.req.mergeable]

24.3.7.8 Concept sortable [alg.req.sortable]

24.3.3.1 ranges::iter_move [iterator.cust.move]

24.3.3.2 ranges::iter_swap [iterator.cust.swap]