[const.iterators] (original) (raw)

24 Iterators library [iterators]

24.5 Iterator adaptors [predef.iterators]

24.5.3 Constant iterators and sentinels [const.iterators]

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

24.5.3.3 Class template basic_const_iterator [const.iterators.iterator]

namespace std { template<class I> concept not-a-const-iterator = see below; template<indirectly_readable I> using iter-const-rvalue-reference-t = common_reference_t<const iter_value_t<I>&&, iter_rvalue_reference_t<I>>;template<input_iterator Iterator> class basic_const_iterator { Iterator current_ = Iterator(); using reference = iter_const_reference_t<Iterator>; using rvalue-reference = iter-const-rvalue-reference-t<Iterator>;public: using iterator_concept = see below;using iterator_category = see below; 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;template<not-a-const-iterator CI> requires constant-iterator<CI> && convertible_to<Iterator const&, CI> constexpr operator CI() const &;template<not-a-const-iterator CI> requires constant-iterator<CI> && convertible_to<Iterator, CI> constexpr operator CI() &&;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 falseif I is a specialization of basic_const_iterator andtrue otherwise.

24.5.3.4 Member types [const.iterators.types]

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

• Otherwise, if Iterator models forward_iterator, then iterator_concept denotes forward_iterator_tag.
• Otherwise, iterator_concept denotes input_iterator_tag.

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

24.5.3.5 Operations [const.iterators.ops]

constexpr basic_const_iterator(Iterator current);

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

template<[convertible_to](concept.convertible#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<Iterator> U> constexpr basic_const_iterator(basic_const_iterator<U> current);

Effects: Initializes _current__with std​::​move(current.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](concept.same#concept:same%5Fas "18.4.2 Concept same_­as [concept.same]")<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.concept.forward#concept:forward%5Fiterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]")<Iterator>;

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

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

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

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

Effects: Equivalent to: return static_cast<_reference_>(_current__[n]);

template<[sentinel_for](iterator.concept.sentinel#concept:sentinel%5Ffor "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<Iterator> S> constexpr bool operator==(const S& s) const;

Effects: Equivalent to: return current_ == s;

template<[_not-a-const-iterator_](#concept:not-a-const-iterator "24.5.3.3 Class template basic_­const_­iterator [const.iterators.iterator]") CI> requires [_constant-iterator_](#concept:constant-iterator "24.5.3.2 Alias templates [const.iterators.alias]")<CI> && [convertible_to](concept.convertible#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<Iterator const&, CI> constexpr operator CI() const &;

Returns: std​::​move(current_).

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

Effects: Equivalent to: return current_ op y;

Effects: 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.concept.random.access#concept:random%5Faccess%5Fiterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]")<Iterator>;friend constexpr basic_const_iterator operator+(difference_type n, const basic_const_iterator& i) requires [random_access_iterator](iterator.concept.random.access#concept:random%5Faccess%5Fiterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]")<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.concept.random.access#concept:random%5Faccess%5Fiterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]")<Iterator>;

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

template<[sized_sentinel_for](iterator.concept.sizedsentinel#concept:sized%5Fsentinel%5Ffor "24.3.4.8 Concept sized_­sentinel_­for [iterator.concept.sizedsentinel]")<Iterator> S> constexpr difference_type operator-(const S& y) const;

Effects: Equivalent to: return current_ - y;

template<[_not-a-const-iterator_](#concept:not-a-const-iterator "24.5.3.3 Class template basic_­const_­iterator [const.iterators.iterator]") S> requires [sized_sentinel_for](iterator.concept.sizedsentinel#concept:sized%5Fsentinel%5Ffor "24.3.4.8 Concept sized_­sentinel_­for [iterator.concept.sizedsentinel]")<S, Iterator> friend constexpr difference_type operator-(const S& x, const basic_const_iterator& y);

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