23 Iterators library [iterators]

23.3 Iterator requirements [iterator.requirements]

23.3.4 Iterator concepts [iterator.concepts]

23.3.4.1 General [iterator.concepts.general]

For a type I, let ITER_­TRAITS(I) denote the type I if iterator_­traits<I> names a specialization generated from the primary template.
Otherwise, ITER_­TRAITS(I) denotes iterator_­traits<I>.
  • If the qualified-id ITER_­TRAITS(I)​::​iterator_­concept is valid and names a type, then ITER_­CONCEPT(I) denotes that type.
  • Otherwise, if the qualified-id ITER_­TRAITS(I)​::​iterator_­category is valid and names a type, then ITER_­CONCEPT(I) denotes that type.
  • Otherwise, if iterator_­traits<I> names a specialization generated from the primary template, then ITER_­CONCEPT(I) denotes random_­access_­iterator_­tag.
  • Otherwise, ITER_­CONCEPT(I) does not denote a type.
[Note
:
ITER_­TRAITS enables independent syntactic determination of an iterator's category and concept.
— end note
]
[Example
:
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<I>​::​iterator_­category denotes input_­iterator_­tag, and ITER_­CONCEPT(I) denotes random_­access_­iterator_­tag.
— end example
]

23.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 =
    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.
[Note
:
The expression *i is indirectly required to be valid via the exposition-only dereferenceable concept ([iterator.synopsis]).
— end note
]

23.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
  • 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
:
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
:
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
]

23.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>
  inline constexpr bool is-integer-like = see below;            // exposition only

template<class T>
  inline constexpr bool is-signed-integer-like = see below;     // exposition only

template<class I>
  concept weakly_incrementable =
    default_initializable<I> && movable<I> &&
    requires(I i) {
      typename iter_difference_t<I>;
      requires is-signed-integer-like<iter_difference_t<I>>;
      { ++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 class types that behave as integer types do, as defined in below.
The range of representable values of an integer-class type is the continuous set of values over which it is defined.
The values 0 and 1 are part of the range of every integer-class type.
If any negative numbers are part of the range, the type is a signed-integer-class type; otherwise, it is an unsigned-integer-class type.
For every integer-class type I, let B(I) be a hypothetical extended integer type of the same signedness with the smallest width ([basic.fundamental]) capable of representing the same range of values.
The width of I is equal to the width of B(I).
Let a and b be objects of integer-class type I, let x and y be objects of type B(I) as described above that represent the same values as a and b respectively, and let c be an lvalue of any integral type.
  • For every unary operator @ 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 provided that value is representable by I.
    If @x has type bool, so too does @a; if @x has type B(I), then @a has type I.
  • 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.
  • For every binary operator @ for which x @ y is well-formed, a @ b shall also be well-formed and shall have the same value, effects, and value category as x @ y provided that value is representable by I.
    If x @ y has type bool, so too does a @ b; if x @ y has type B(I), then a @ b has type I.
Expressions of integer-class type are explicitly convertible to any integral type.
Expressions of integral type are both implicitly and explicitly convertible to any integer-class type.
Conversions between integral and integer-class types do not exit via an exception.
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 totally_­ordered ([concept.totallyordered]).
A value-initialized object of integer-class type has value 0.
For every (possibly cv-qualified) integer-class type I, numeric_­limits<I> is specialized such that:
  • numeric_­limits<I>​::​is_­specialized is true,
  • numeric_­limits<I>​::​is_­signed is true if and only if I is a signed-integer-class type,
  • numeric_­limits<I>​::​is_­integer is true,
  • numeric_­limits<I>​::​is_­exact is true,
  • numeric_­limits<I>​::​digits is equal to the width of the integer-class type,
  • numeric_­limits<I>​::​digits10 is equal to static_­cast<int>(digits * log10(2)), and
  • numeric_­limits<I>​::​min() and numeric_­limits<I>​::​max() return the lowest and highest representable values of I, respectively, and numeric_­limits<I>​::​lowest() returns numeric_­limits<I>​::​​min().
A type I is integer-like if it models integral<I> or if it is an integer-class type.
A type I is signed-integer-like if it models signed_­integral<I> or if it is a signed-integer-class type.
A type I is unsigned-integer-like if it models unsigned_­integral<I> or if it is an unsigned-integer-class type.
is-integer-like<I> is true if and only if I is an integer-like type.
is-signed-integer-like<I> 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<I> only if
  • The expressions ++i and i++ have the same domain.
  • If i is incrementable, then both ++i and i++ advance i to the next element.
  • If i is incrementable, then addressof(++i) is equal to addressof(i).
[Note
:
For weakly_­incrementable types, a equals b does not imply that ++a equals ++b.
(Equality does not guarantee the substitution property or referential transparency.)
Algorithms on weakly incrementable types should never attempt to pass through the same incrementable value twice.
They should be single-pass algorithms.
These algorithms can be used with istreams as the source of the input data through the istream_­iterator class template.
— end note
]

23.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
:
This supersedes the annotations on the increment expressions in the definition of weakly_­incrementable.
— end note
]
template<class I>
  concept incrementable =
    regular<I> &&
    weakly_incrementable<I> &&
    requires(I i) {
      { i++ } -> same_as<I>;
    };
Let a and b be incrementable objects of type I.
I models incrementable only if
  • If bool(a == b) then bool(a++ == b).
  • If bool(a == b) then bool(((void)a++, a) == ++b).
[Note
:
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
]

23.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<I>;
[Note
:
Unlike the Cpp17Iterator requirements, the input_­or_­output_­iterator concept does not require copyability.
— end note
]

23.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
  • i == s is well-defined.
  • If bool(i != s) then i is dereferenceable and [++i, s) denotes a range.
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.

23.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<I> 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
  • If N is representable by iter_­difference_­t<I>, then s - i is well-defined and equals N.
  • If is representable by iter_­difference_­t<I>, then i - s is well-defined and equals .
template<class S, class I> inline 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
:
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
:
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
]

23.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
:
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<I> &&
    indirectly_readable<I> &&
    requires { typename ITER_CONCEPT(I); } &&
    derived_from<ITER_CONCEPT(I), input_iterator_tag>;

23.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
:
Output iterators are not required to model equality_­comparable.
— end note
]
template<class I, class T>
  concept output_iterator =
    input_or_output_iterator<I> &&
    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;
[Note
:
Algorithms on output iterators should never attempt to pass through the same iterator twice.
They should be single-pass algorithms.
— end note
]

23.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<I> &&
    derived_from<ITER_CONCEPT(I), forward_iterator_tag> &&
    incrementable<I> &&
    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
:
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:
  • a == b implies ++a == ++b and
  • the expression ((void)[](X x){++x;}(a), *a) is equivalent to the expression *a.
[Note
:
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
]

23.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<I> &&
    derived_from<ITER_CONCEPT(I), bidirectional_iterator_tag> &&
    requires(I i) {
      { --i } -> same_as<I&>;
      { i-- } -> same_as<I>;
    };
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:
  • If a and b are decrementable, then all of the following are true:
    • addressof(--a) == addressof(a)
    • bool(a-- == b)
    • after evaluating both a-- and --b, bool(a == b) is still true
    • bool(++(--a) == b)
  • If a and b are incrementable, then bool(--(++a) == b).

23.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<I> &&
    derived_from<ITER_CONCEPT(I), random_access_iterator_tag> &&
    totally_ordered<I> &&
    sized_sentinel_for<I, I> &&
    requires(I i, const I j, const iter_difference_t<I> n) {
      { i += n } -> same_as<I&>;
      { j +  n } -> same_as<I>;
      { n +  j } -> same_as<I>;
      { i -= n } -> same_as<I&>;
      { j -  n } -> same_as<I>;
      {  j[n]  } -> same_as<iter_reference_t<I>>;
    };
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<I>, and let n denote a value of type D.
I models random_­access_­iterator only if
  • (a += n) is equal to b.
  • addressof(a += n) is equal to addressof(a).
  • (a + n) is equal to (a += n).
  • 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).
  • (a + D(0)) is equal to a.
  • If (a + D(n - 1)) is valid, then (a + n) is equal to [](I c){ return ++c; }(a + D(n - 1)).
  • (b += D(-n)) is equal to a.
  • (b -= n) is equal to a.
  • addressof(b -= n) is equal to addressof(b).
  • (b - n) is equal to (b -= n).
  • If b is dereferenceable, then a[n] is valid and is equal to *b.
  • bool(a <= b) is true.

23.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<I> &&
    derived_from<ITER_CONCEPT(I), contiguous_iterator_tag> &&
    is_lvalue_reference_v<iter_reference_t<I>> &&
    same_as<iter_value_t<I>, remove_cvref_t<iter_reference_t<I>>> &&
    requires(const I& i) {
      { to_address(i) } -> same_as<add_pointer_t<iter_reference_t<I>>>;
    };
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<I>.
The type I models contiguous_­iterator only if
  • to_­address(a) == addressof(*a),
  • to_­address(b) == to_­address(a) + D(b - a), and
  • to_­address(c) == to_­address(a) + D(c - a).