23 Iterators library [iterators]

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.

Let $R_{\text{I}}$ be remove_­cvref_­t<I>.

The type iter_­difference_­t<I> denotes

• (2.1)
  incrementable_­traits<$R_{\text{I}}$>​::​difference_­type if iterator_­traits<$R_{\text{I}}$> names a specialization generated from the primary template, and
• (2.2)
  iterator_­traits<$R_{\text{I}}$>​::​difference_­type otherwise.

Users may specialize incrementable_­traits on program-defined types.

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.

Let $R_{\text{I}}$ be remove_­cvref_­t<I>.

The type iter_­value_­t<I> denotes

• (2.1)
  indirectly_­readable_­traits<$R_{\text{I}}$>​::​value_­type if iterator_­traits<$R_{\text{I}}$> names a specialization generated from the primary template, and
• (2.2)
  iterator_­traits<$R_{\text{I}}$>​::​value_­type otherwise.

Class template indirectly_­readable_­traits may be specialized on program-defined types.

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<I>::iterator_category be defined as the iterator's iterator category.

In addition, the types iterator_traits<I>::pointer iterator_traits<I>::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<I>​::​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<I>::value_type iterator_traits<I>::difference_type iterator_traits<I>::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 = copyable<I> && requires(I i) { { *i } -> can-reference; { ++i } -> same_­as<I&>; { *i++ } -> can-reference; }; template<class I> concept cpp17-input-iterator = cpp17-iterator<I> && equality_­comparable<I> && requires(I i) { typename incrementable_traits<I>::difference_type; typename indirectly_readable_traits<I>::value_type; typename common_reference_t<iter_reference_t<I>&&, typename indirectly_readable_traits<I>::value_type&>; typename common_reference_t<decltype(*i++)&&, typename indirectly_readable_traits<I>::value_type&>; requires signed_integral<typename incrementable_traits<I>::difference_type>; }; template<class I> concept cpp17-forward-iterator = cpp17-input-iterator<I> && constructible_­from<I> && is_lvalue_reference_v<iter_reference_t<I>> && same_­as<remove_cvref_t<iter_reference_t<I>>, typename indirectly_readable_traits<I>::value_type> && requires(I i) { { i++ } -> convertible_­to<const I&>; { *i++ } -> same_­as<iter_reference_t<I>>; }; template<class I> concept cpp17-bidirectional-iterator = cpp17-forward-iterator<I> && requires(I i) { { --i } -> same_­as<I&>; { i-- } -> convertible_­to<const I&>; { *i-- } -> same_­as<iter_reference_t<I>>; }; template<class I> concept cpp17-random-access-iterator = cpp17-bidirectional-iterator<I> && totally_­ordered<I> && requires(I i, typename incrementable_traits<I>::difference_type n) { { i += n } -> same_­as<I&>; { i -= n } -> same_­as<I&>; { i + n } -> same_­as<I>; { n + i } -> same_­as<I>; { i - n } -> same_­as<I>; { i - i } -> same_­as<decltype(n)>; { i[n] } -> convertible_­to<iter_reference_t<I>>; };

The members of a specialization iterator_­traits<I> 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<I> 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<I>​::​pointer names that type; otherwise, it names void.
• (3.2)
  Otherwise, if I satisfies the exposition-only concept cpp17-input-iterator, iterator_­traits<I> has the following publicly accessible members: using iterator_category = see below; using value_type = typename indirectly_readable_traits<I>::value_type; using difference_type = typename incrementable_traits<I>::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<I>.
  • (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<I> 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<I>​::​difference_­type is valid and denotes a type, then difference_­type names that type; otherwise, it names void.
• (3.4)
  Otherwise, iterator_­traits<I> 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]).

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