25 Iterators library [iterators]

25.5 Iterator adaptors [predef.iterators]

25.5.3 Constant iterators and sentinels [const.iterators]

25.5.3.1 General [const.iterators.general]

Class template basic_const_iterator is an iterator adaptor with the same behavior as the underlying iterator except that its indirection operator implicitly converts the value returned by the underlying iterator's indirection operator to a type such that the adapted iterator is a constant iterator ([iterator.requirements]).

Some generic algorithms can be called with constant iterators to avoid mutation.

Specializations of basic_const_iterator are constant iterators.

25.5.3.2 Alias templates [const.iterators.alias]

🔗

template<indirectly_readable It>
  using iter_const_reference_t =
    common_reference_t<const iter_value_t<It>&&, iter_reference_t<It>>;

template<class It>
  concept constant-iterator =                                                   // exposition only
    input_iterator<It> && same_as<iter_const_reference_t<It>, iter_reference_t<It>>;

template<input_iterator I>
  using const_iterator = see below;

Result: If I models constant-iterator, I.

Otherwise, basic_const_iterator<I>.

🔗

template<semiregular S>
  using const_sentinel = see below;

Result: If S models input_iterator, const_iterator<S>.

Otherwise, S.

25.5.3.3 Class template basic_const_iterator [const.iterators.iterator]

namespace std { template<class I> concept not-a-const-iterator = see below; // exposition only template<indirectly_readable I> using iter-const-rvalue-reference-t = // exposition only common_reference_t<const iter_value_t<I>&&, iter_rvalue_reference_t<I>>; template<input_iterator Iterator> class basic_const_iterator { Iterator current_ = Iterator(); // exposition only using reference = iter_const_reference_t<Iterator>; // exposition only using rvalue-reference = // exposition only iter-const-rvalue-reference-t<Iterator>; public: using iterator_concept = see below; using iterator_category = see below; // not always present using value_type = iter_value_t<Iterator>; using difference_type = iter_difference_t<Iterator>; basic_const_iterator() requires default_initializable<Iterator> = default; constexpr basic_const_iterator(Iterator current); template<convertible_to<Iterator> U> constexpr basic_const_iterator(basic_const_iterator<U> current); template<different-from<basic_const_iterator> T> requires convertible_to<T, Iterator> constexpr basic_const_iterator(T&& current); constexpr const Iterator& base() const & noexcept; constexpr Iterator base() &&; constexpr reference operator*() const; constexpr const auto* operator->() const requires is_lvalue_reference_v<iter_reference_t<Iterator>> && same_as<remove_cvref_t<iter_reference_t<Iterator>>, value_type>; constexpr basic_const_iterator& operator++(); constexpr void operator++(int); constexpr basic_const_iterator operator++(int) requires forward_iterator<Iterator>; constexpr basic_const_iterator& operator--() requires bidirectional_iterator<Iterator>; constexpr basic_const_iterator operator--(int) requires bidirectional_iterator<Iterator>; constexpr basic_const_iterator& operator+=(difference_type n) requires random_access_iterator<Iterator>; constexpr basic_const_iterator& operator-=(difference_type n) requires random_access_iterator<Iterator>; constexpr reference operator[](difference_type n) const requires random_access_iterator<Iterator>; template<sentinel_for<Iterator> S> constexpr bool operator==(const S& s) const; constexpr bool operator<(const basic_const_iterator& y) const requires random_access_iterator<Iterator>; constexpr bool operator>(const basic_const_iterator& y) const requires random_access_iterator<Iterator>; constexpr bool operator<=(const basic_const_iterator& y) const requires random_access_iterator<Iterator>; constexpr bool operator>=(const basic_const_iterator& y) const requires random_access_iterator<Iterator>; constexpr auto operator<=>(const basic_const_iterator& y) const requires random_access_iterator<Iterator> && three_way_comparable<Iterator>; template<different-from<basic_const_iterator> I> constexpr bool operator<(const I& y) const requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I> constexpr bool operator>(const I& y) const requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I> constexpr bool operator<=(const I& y) const requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I> constexpr bool operator>=(const I& y) const requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I> constexpr auto operator<=>(const I& y) const requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I> && three_way_comparable_with<Iterator, I>; template<not-a-const-iterator I> friend constexpr bool operator<(const I& x, const basic_const_iterator& y) requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<not-a-const-iterator I> friend constexpr bool operator>(const I& x, const basic_const_iterator& y) requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<not-a-const-iterator I> friend constexpr bool operator<=(const I& x, const basic_const_iterator& y) requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; template<not-a-const-iterator I> friend constexpr bool operator>=(const I& x, const basic_const_iterator& y) requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>; friend constexpr basic_const_iterator operator+(const basic_const_iterator& i, difference_type n) requires random_access_iterator<Iterator>; friend constexpr basic_const_iterator operator+(difference_type n, const basic_const_iterator& i) requires random_access_iterator<Iterator>; friend constexpr basic_const_iterator operator-(const basic_const_iterator& i, difference_type n) requires random_access_iterator<Iterator>; template<sized_sentinel_for<Iterator> S> constexpr difference_type operator-(const S& y) const; template<not-a-const-iterator S> requires sized_sentinel_for<S, Iterator> friend constexpr difference_type operator-(const S& x, const basic_const_iterator& y); friend constexpr rvalue-reference iter_move(const basic_const_iterator& i) noexcept(noexcept(static_cast<rvalue-reference>(ranges::iter_move(i.current_)))) { return static_cast<rvalue-reference>(ranges::iter_move(i.current_)); } }; }

Given some type I, the concept not-a-const-iterator is defined as false if I is a specialization of basic_const_iterator and true otherwise.

25.5.3.4 Member types [const.iterators.types]

basic_const_iterator<Iterator>::iterator_concept is defined as follows:

(1.1)
If Iterator models contiguous_iterator, then iterator_concept denotes contiguous_iterator_tag.
(1.2)
Otherwise, if Iterator models random_access_iterator, then iterator_concept denotes random_access_iterator_tag.
(1.3)
Otherwise, if Iterator models bidirectional_iterator, then iterator_concept denotes bidirectional_iterator_tag.
(1.4)
Otherwise, if Iterator models forward_iterator, then iterator_concept denotes forward_iterator_tag.
(1.5)
Otherwise, iterator_concept denotes input_iterator_tag.

The member typedef-name iterator_category is defined if and only if Iterator models forward_iterator .

In that case, basic_const_iterator<Iterator>::iterator_category denotes the type iterator_traits<Iterator>::iterator_category.

25.5.3.5 Operations [const.iterators.ops]

🔗

constexpr basic_const_iterator(Iterator current);

Effects: Initializes current_ with std::move(current).

🔗

template<convertible_to<Iterator> U>
  constexpr basic_const_iterator(basic_const_iterator<U> current);

Effects: Initializes current_ with std::move(current.current_).

🔗

template<different-from<basic_const_iterator> T>
  requires convertible_to<T, Iterator>
  constexpr basic_const_iterator(T&& current);

Effects: Initializes current_ with std::forward<T>(current).

🔗

constexpr const Iterator& base() const & noexcept;

Effects: Equivalent to: return current_;

🔗

constexpr Iterator base() &&;

Effects: Equivalent to: return std::move(current_);

🔗

constexpr reference operator*() const;

Effects: Equivalent to: return static_cast<reference>(*current_);

🔗

constexpr const auto* operator->() const
  requires is_lvalue_reference_v<iter_reference_t<Iterator>> &&
           same_as<remove_cvref_t<iter_reference_t<Iterator>>, value_type>;

Returns: If Iterator models contiguous_iterator, to_address(current_); otherwise, addressof(*current_).

🔗

constexpr basic_const_iterator& operator++();

Effects: Equivalent to: ++current_; return *this;

🔗

constexpr void operator++(int);

Effects: Equivalent to: ++current_;

🔗

constexpr basic_const_iterator operator++(int) requires forward_iterator<Iterator>;

Effects: Equivalent to: auto tmp = *this; ++*this; return tmp;

🔗

constexpr basic_const_iterator& operator--() requires bidirectional_iterator<Iterator>;

Effects: Equivalent to: --current_; return *this;

🔗

constexpr basic_const_iterator operator--(int) requires bidirectional_iterator<Iterator>;

Effects: Equivalent to: auto tmp = *this; --*this; return tmp;

🔗

constexpr basic_const_iterator& operator+=(difference_type n)
  requires random_access_iterator<Iterator>;
constexpr basic_const_iterator& operator-=(difference_type n)
  requires random_access_iterator<Iterator>;

Let op be the operator.

Effects: Equivalent to: current_ op n; return *this;

🔗

constexpr reference operator[](difference_type n) const requires random_access_iterator<Iterator>

Effects: Equivalent to: return static_cast<reference>(current_[n]);

🔗

template<sentinel_for<Iterator> S>
  constexpr bool operator==(const S& s) const;

Effects: Equivalent to: return current_ == s;

🔗

constexpr bool operator<(const basic_const_iterator& y) const
  requires random_access_iterator<Iterator>;
constexpr bool operator>(const basic_const_iterator& y) const
  requires random_access_iterator<Iterator>;
constexpr bool operator<=(const basic_const_iterator& y) const
  requires random_access_iterator<Iterator>;
constexpr bool operator>=(const basic_const_iterator& y) const
  requires random_access_iterator<Iterator>;
constexpr auto operator<=>(const basic_const_iterator& y) const
  requires random_access_iterator<Iterator> && three_way_comparable<Iterator>;

Let op be the operator.

Effects: Equivalent to: return current_ op y.current_;

🔗

template<different-from<basic_const_iterator> I>
  constexpr bool operator<(const I& y) const
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<different-from<basic_const_iterator> I>
  constexpr bool operator>(const I& y) const
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<different-from<basic_const_iterator> I>
  constexpr bool operator<=(const I& y) const
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<different-from<basic_const_iterator> I>
  constexpr bool operator>=(const I& y) const
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<different-from<basic_const_iterator> I>
  constexpr auto operator<=>(const I& y) const
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I> &&
             three_way_comparable_with<Iterator, I>;

Let op be the operator.

Effects: Equivalent to: return current_ op y;

🔗

template<not-a-const-iterator I>
  friend constexpr bool operator<(const I& x, const basic_const_iterator& y)
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<not-a-const-iterator I>
  friend constexpr bool operator>(const I& x, const basic_const_iterator& y)
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<not-a-const-iterator I>
  friend constexpr bool operator<=(const I& x, const basic_const_iterator& y)
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
template<not-a-const-iterator I>
  friend constexpr bool operator>=(const I& x, const basic_const_iterator& y)
    requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;

Let op be the operator.

Returns: Equivalent to: return x op y.current_;

🔗

friend constexpr basic_const_iterator operator+(const basic_const_iterator& i, difference_type n)
  requires random_access_iterator<Iterator>;
friend constexpr basic_const_iterator operator+(difference_type n, const basic_const_iterator& i)
  requires random_access_iterator<Iterator>;

Effects: Equivalent to: return basic_const_iterator(i.current_ + n);

🔗

friend constexpr basic_const_iterator operator-(const basic_const_iterator& i, difference_type n)
  requires random_access_iterator<Iterator>;

Effects: Equivalent to: return basic_const_iterator(i.current_ - n);

🔗

template<sized_sentinel_for<Iterator> S>
  constexpr difference_type operator-(const S& y) const;

Effects: Equivalent to: return current_ - y;

🔗

template<not-a-const-iterator S>
  requires sized_sentinel_for<S, Iterator>
  friend constexpr difference_type operator-(const S& x, const basic_const_iterator& y);

Effects: Equivalent to: return x - y.current_;