37 KiB
[const.iterators]
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.2 Alias templates [const.iterators.alias]
`template<indirectly_readable It> using iter_const_reference_t = common_reference_t<const iter_value_t&&, iter_reference_t>;
template concept constant-iterator = // exposition only input_iterator && same_as<iter_const_reference_t, iter_reference_t>;
template<input_iterator I> using const_iterator = see below; `
Result: If I models constant-iterator, I.
Otherwise, basic_const_iterator.
template<[semiregular](concepts.object#concept:semiregular "18.6 Object concepts [concepts.object]") S> using [const_sentinel](#lib:const_sentinel "24.5.3.2 Alias templates [const.iterators.alias]") = see below;
Result: If S models input_iterator, const_iterator.
Otherwise, S.
24.5.3.3 Class template basic_const_iterator [const.iterators.iterator]
namespace std {templateconcept not-a-const-iterator = see below; // exposition onlytemplate<indirectly_readable I>using iter-const-rvalue-reference-t = // exposition only common_reference_t<const iter_value_t&&, iter_rvalue_reference_t>; template<input_iterator Iterator>class basic_const_iterator { Iterator current_ = Iterator(); // exposition onlyusing reference = iter_const_reference_t; // exposition onlyusing rvalue-reference = // exposition only**iter-const-rvalue-reference-t; public:using iterator_concept = see below; using iterator_category = see below; // not always presentusing value_type = iter_value_t; using difference_type = iter_difference_t;
basic_const_iterator() requires default_initializable = default; constexpr basic_const_iterator(Iterator current); template<convertible_to U>constexpr basic_const_iterator(basic_const_iterator 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->() constrequires is_lvalue_reference_v<iter_reference_t> &&same_as<remove_cvref_t<iter_reference_t>, value_type>; constexpr basic_const_iterator& operator++(); constexpr void operator++(int); constexpr basic_const_iterator operator++(int) requires forward_iterator; constexpr basic_const_iterator& operator--() requires bidirectional_iterator; constexpr basic_const_iterator operator--(int) requires bidirectional_iterator; constexpr basic_const_iterator& operator+=(difference_type n)requires random_access_iterator; constexpr basic_const_iterator& operator-=(difference_type n)requires random_access_iterator; constexpr reference operator[](difference_type n) constrequires random_access_iterator; template<sentinel_for S>constexpr bool operator==(const S& s) const; template<not-a-const-iterator CI>requires constant-iterator && convertible_to<Iterator const&, CI>constexpr operator CI() const &; template<not-a-const-iterator CI>requires constant-iterator && convertible_to<Iterator, CI>constexpr operator CI() &&; constexpr bool operator<(const basic_const_iterator& y) constrequires random_access_iterator; constexpr bool operator>(const basic_const_iterator& y) constrequires random_access_iterator; constexpr bool operator<=(const basic_const_iterator& y) constrequires random_access_iterator; constexpr bool operator>=(const basic_const_iterator& y) constrequires random_access_iterator; constexpr auto operator<=>(const basic_const_iterator& y) constrequires random_access_iterator && three_way_comparable; template<different-from<basic_const_iterator> I>constexpr bool operator<(const I& y) constrequires random_access_iterator && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I>constexpr bool operator>(const I& y) constrequires random_access_iterator && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I>constexpr bool operator<=(const I& y) constrequires random_access_iterator && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I>constexpr bool operator>=(const I& y) constrequires random_access_iterator && totally_ordered_with<Iterator, I>; template<different-from<basic_const_iterator> I>constexpr auto operator<=>(const I& y) constrequires random_access_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 && 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 && 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 && 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 && totally_ordered_with<Iterator, I>; friend constexpr basic_const_iterator operator+(const basic_const_iterator& i, difference_type n)requires random_access_iterator; friend constexpr basic_const_iterator operator+(difference_type n, const basic_const_iterator& i)requires random_access_iterator; friend constexpr basic_const_iterator operator-(const basic_const_iterator& i, difference_type n)requires random_access_iterator; template<sized_sentinel_for 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 andtrue otherwise.
24.5.3.4 Member types [const.iterators.types]
basic_const_iterator::iterator_concept is defined as follows:
-
If Iterator models contiguous_iterator, then iterator_concept denotes contiguous_iterator_tag.
-
Otherwise, if Iterator models random_access_iterator, then iterator_concept denotes random_access_iterator_tag.
-
Otherwise, if Iterator models bidirectional_iterator, then iterator_concept denotes bidirectional_iterator_tag.
-
Otherwise, if Iterator models forward_iterator, then iterator_concept denotes forward_iterator_tag.
-
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_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_to "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_).
template<[different-from](range.utility.helpers#concept:different-from "25.5.2 Helper concepts [range.utility.helpers]")<basic_const_iterator> T> requires [convertible_to](concept.convertible#concept:convertible_to "18.4.4 Concept convertible_to [concept.convertible]")<T, Iterator> constexpr basic_const_iterator(T&& current);
Effects: Initializes current_ with std::forward(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_as "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_iterator "24.3.4.11 Concept forward_iterator [iterator.concept.forward]")<Iterator>;
Effects: Equivalent to:auto tmp = *this;++*this;return tmp;
constexpr basic_const_iterator& operator--() requires [bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_iterator [iterator.concept.bidir]")<Iterator>;
Effects: Equivalent to:--current_;return *this;
constexpr basic_const_iterator operator--(int) requires [bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_iterator [iterator.concept.bidir]")<Iterator>;
Effects: Equivalent to:auto tmp = *this;--*this;return tmp;
constexpr basic_const_iterator& operator+=(difference_type n) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator>; constexpr basic_const_iterator& operator-=(difference_type n) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<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.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator>
Effects: Equivalent to: return static_cast<reference>(current_[n]);
template<[sentinel_for](iterator.concept.sentinel#concept:sentinel_for "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_to "18.4.4 Concept convertible_to [concept.convertible]")<Iterator const&, CI> constexpr operator CI() const &;
Returns: current_.
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_to "18.4.4 Concept convertible_to [concept.convertible]")<Iterator, CI> constexpr operator CI() &&;
Returns: std::move(current_).
constexpr bool operator<(const basic_const_iterator& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator>; constexpr bool operator>(const basic_const_iterator& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator>; constexpr bool operator<=(const basic_const_iterator& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator>; constexpr bool operator>=(const basic_const_iterator& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator>; constexpr auto operator<=>(const basic_const_iterator& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [three_way_comparable](cmp.concept#concept:three_way_comparable "17.12.4 Concept three_way_comparable [cmp.concept]")<Iterator>;
Let op be the operator.
Effects: Equivalent to:return current_ op y.current_;
template<[different-from](range.utility.helpers#concept:different-from "25.5.2 Helper concepts [range.utility.helpers]")<basic_const_iterator> I> constexpr bool operator<(const I& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[different-from](range.utility.helpers#concept:different-from "25.5.2 Helper concepts [range.utility.helpers]")<basic_const_iterator> I> constexpr bool operator>(const I& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[different-from](range.utility.helpers#concept:different-from "25.5.2 Helper concepts [range.utility.helpers]")<basic_const_iterator> I> constexpr bool operator<=(const I& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[different-from](range.utility.helpers#concept:different-from "25.5.2 Helper concepts [range.utility.helpers]")<basic_const_iterator> I> constexpr bool operator>=(const I& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[different-from](range.utility.helpers#concept:different-from "25.5.2 Helper concepts [range.utility.helpers]")<basic_const_iterator> I> constexpr auto operator<=>(const I& y) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I> && [three_way_comparable_with](cmp.concept#concept:three_way_comparable_with "17.12.4 Concept three_way_comparable [cmp.concept]")<Iterator, I>;
Let op be the operator.
Effects: Equivalent to: return current_ op y;
template<[not-a-const-iterator](#concept:not-a-const-iterator "24.5.3.3 Class template basic_const_iterator [const.iterators.iterator]") I> friend constexpr bool operator<(const I& x, const basic_const_iterator& y) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[not-a-const-iterator](#concept:not-a-const-iterator "24.5.3.3 Class template basic_const_iterator [const.iterators.iterator]") I> friend constexpr bool operator>(const I& x, const basic_const_iterator& y) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[not-a-const-iterator](#concept:not-a-const-iterator "24.5.3.3 Class template basic_const_iterator [const.iterators.iterator]") I> friend constexpr bool operator<=(const I& x, const basic_const_iterator& y) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>; template<[not-a-const-iterator](#concept:not-a-const-iterator "24.5.3.3 Class template basic_const_iterator [const.iterators.iterator]") I> friend constexpr bool operator>=(const I& x, const basic_const_iterator& y) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<Iterator> && [totally_ordered_with](concept.totallyordered#concept:totally_ordered_with "18.5.5 Concept totally_ordered [concept.totallyordered]")<Iterator, I>;
Let op be the operator.
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_access_iterator "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_access_iterator "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_access_iterator "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_sentinel_for "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_sentinel_for "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_;