[const.iterators] - C++20 → C++23

Files changed (1) hide show

tmp/tmpi436l8bs/{from.md → to.md} +411 -0

tmp/tmpi436l8bs/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,411 @@

+### Constant iterators and sentinels <a id="const.iterators">[[const.iterators]]</a>
+#### General <a id="const.iterators.general">[[const.iterators.general]]</a>
+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.
+#### Alias templates <a id="const.iterators.alias">[[const.iterators.alias]]</a>
+``` cpp
+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>`.
+``` cpp
+template<semiregular S>
+  using const_sentinel = see below;
+```
+*Result:* If `S` models `input_iterator`, `const_iterator<S>`.
+Otherwise, `S`.
+#### Class template `basic_const_iterator` <a id="const.iterators.iterator">[[const.iterators.iterator]]</a>
+``` cpp
+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.
+#### Member types <a id="const.iterators.types">[[const.iterators.types]]</a>
+`basic_const_iterator<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>::iterator_category` denotes the type
+`iterator_traits<{}Iterator>::iterator_category`.
+#### Operations <a id="const.iterators.ops">[[const.iterators.ops]]</a>
+``` cpp
+constexpr basic_const_iterator(Iterator current);
+```
+*Effects:* Initializes *current\_* with `std::move(current)`.
+``` cpp
+template<convertible_to<Iterator> U>
+  constexpr basic_const_iterator(basic_const_iterator<U> current);
+```
+*Effects:* Initializes *current\_* with
+`std::move(current.`*`current_`*`)`.
+``` cpp
+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)`.
+``` cpp
+constexpr const Iterator& base() const & noexcept;
+```
+*Effects:* Equivalent to: `return `*`current_`*`;`
+``` cpp
+constexpr Iterator base() &&;
+```
+*Effects:* Equivalent to: `return std::move(`*`current_`*`);`
+``` cpp
+constexpr reference operator*() const;
+```
+*Effects:* Equivalent to:
+`return static_cast<`*`reference`*`>(*`*`current_`*`);`
+``` cpp
+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_`*`)`.
+``` cpp
+constexpr basic_const_iterator& operator++();
+```
+*Effects:* Equivalent to:
+``` cpp
+++current_;
+return *this;
+```
+``` cpp
+constexpr void operator++(int);
+```
+*Effects:* Equivalent to: `++`*`current_`*`;`
+``` cpp
+constexpr basic_const_iterator operator++(int) requires forward_iterator<Iterator>;
+```
+*Effects:* Equivalent to:
+``` cpp
+auto tmp = *this;
+++*this;
+return tmp;
+```
+``` cpp
+constexpr basic_const_iterator& operator--() requires bidirectional_iterator<Iterator>;
+```
+*Effects:* Equivalent to:
+``` cpp
+--current_;
+return *this;
+```
+``` cpp
+constexpr basic_const_iterator operator--(int) requires bidirectional_iterator<Iterator>;
+```
+*Effects:* Equivalent to:
+``` cpp
+auto tmp = *this;
+--*this;
+return tmp;
+```
+``` cpp
+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:
+``` cpp
+current_ op n;
+return *this;
+```
+``` cpp
+constexpr reference operator[](difference_type n) const requires random_access_iterator<Iterator>
+```
+*Effects:* Equivalent to:
+`return static_cast<`*`reference`*`>(`*`current_`*`[n]);`
+``` cpp
+template<sentinel_for<Iterator> S>
+  constexpr bool operator==(const S& s) const;
+```
+*Effects:* Equivalent to: `return `*`current_`*` == s;`
+``` cpp
+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_`*`;`
+``` cpp
+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;`
+``` cpp
+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_`*`;`
+``` cpp
+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);`
+``` cpp
+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);`
+``` cpp
+template<sized_sentinel_for<Iterator> S>
+  constexpr difference_type operator-(const S& y) const;
+```
+*Effects:* Equivalent to: `return `*`current_`*` - y;`
+``` cpp
+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_`*`;`

Diff to HTML by rtfpessoa