[move.iterators] - C++17 → C++20

Files changed (1) hide show

tmp/tmpmm3z1mym/{from.md → to.md} +222 -110

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

@@ -1,6 +1,6 @@
-### Move iterators <a id="move.iterators">[[move.iterators]]</a>
 Class template `move_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 an rvalue. Some generic algorithms can be called
@@ -24,89 +24,82 @@ vector<string> v2(make_move_iterator(s.begin()),
 namespace std {
   template<class Iterator>
   class move_iterator {
   public:
     using iterator_type     = Iterator;
-    using iterator_category = typename iterator_traits<Iterator>::iterator_category;
-    using value_type        = typename iterator_traits<Iterator>::value_type;
-    using difference_type   = typename iterator_traits<Iterator>::difference_type;
     using pointer           = Iterator;
-    using reference         = see below;
     constexpr move_iterator();
     constexpr explicit move_iterator(Iterator i);
     template<class U> constexpr move_iterator(const move_iterator<U>& u);
     template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
-    constexpr iterator_type base() const;
     constexpr reference operator*() const;
-    constexpr pointer operator->() const;
     constexpr move_iterator& operator++();
-    constexpr move_iterator operator++(int);
     constexpr move_iterator& operator--();
     constexpr move_iterator operator--(int);
     constexpr move_iterator operator+(difference_type n) const;
     constexpr move_iterator& operator+=(difference_type n);
     constexpr move_iterator operator-(difference_type n) const;
     constexpr move_iterator& operator-=(difference_type n);
-    constexpr unspecified operator[](difference_type n) const;
   private:
     Iterator current;   // exposition only
   };
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator==(
-      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator!=(
-      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator<(
-      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator<=(
-      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator>(
-      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator>=(
-      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr auto operator-(
-      const move_iterator<Iterator1>& x,
-      const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
-  template <class Iterator>
-    constexpr move_iterator<Iterator> operator+(
-      typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
-  template <class Iterator>
-    constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
 }
 ```
-Let `R` denote `iterator_traits<Iterator>::reference`. If
-`is_reference_v<R>` is `true`, the template specialization
-`move_iterator<Iterator>` shall define the nested type named `reference`
-as a synonym for `remove_reference_t<R>&&`, otherwise as a synonym for
-`R`.
-#### `move_iterator` requirements <a id="move.iter.requirements">[[move.iter.requirements]]</a>
-The template parameter `Iterator` shall meet the requirements of an
-input iterator ([[input.iterators]]). Additionally, if any of the
-bidirectional or random access traversal functions are instantiated, the
-template parameter shall meet the requirements for a Bidirectional
-Iterator ([[bidirectional.iterators]]) or a Random Access Iterator (
-[[random.access.iterators]]), respectively.
-#### `move_iterator` operations <a id="move.iter.ops">[[move.iter.ops]]</a>
-##### `move_iterator` constructors <a id="move.iter.op.const">[[move.iter.op.const]]</a>
 ``` cpp
 constexpr move_iterator();
 ```
@@ -118,78 +111,84 @@ value-initialized iterator of type `Iterator`.
 ``` cpp
 constexpr explicit move_iterator(Iterator i);
 ```
 *Effects:* Constructs a `move_iterator`, initializing `current` with
-`i`.
 ``` cpp
 template<class U> constexpr move_iterator(const move_iterator<U>& u);
 ```
 *Effects:* Constructs a `move_iterator`, initializing `current` with
 `u.base()`.
-*Requires:* `U` shall be convertible to `Iterator`.
-##### `move_iterator::operator=` <a id="move.iter.op=">[[move.iter.op=]]</a>
 ``` cpp
 template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
 ```
 *Effects:* Assigns `u.base()` to `current`.
-*Requires:* `U` shall be convertible to `Iterator`.
-##### `move_iterator` conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
 ``` cpp
-constexpr Iterator base() const;
 ```
 *Returns:* `current`.
-##### `move_iterator::operator*` <a id="move.iter.op.star">[[move.iter.op.star]]</a>
 ``` cpp
 constexpr reference operator*() const;
 ```
-*Returns:* `static_cast<reference>(*current)`.
-##### `move_iterator::operator->` <a id="move.iter.op.ref">[[move.iter.op.ref]]</a>
 ``` cpp
-constexpr pointer operator->() const;
 ```
-*Returns:* `current`.
-##### `move_iterator::operator++` <a id="move.iter.op.incr">[[move.iter.op.incr]]</a>
 ``` cpp
 constexpr move_iterator& operator++();
 ```
 *Effects:* As if by `++current`.
 *Returns:* `*this`.
 ``` cpp
-constexpr move_iterator operator++(int);
 ```
-*Effects:* As if by:
 ``` cpp
 move_iterator tmp = *this;
 ++current;
 return tmp;
 ```
-##### `move_iterator::operator-{-}` <a id="move.iter.op.decr">[[move.iter.op.decr]]</a>
 ``` cpp
 constexpr move_iterator& operator--();
 ```
@@ -207,119 +206,232 @@ constexpr move_iterator operator--(int);
 move_iterator tmp = *this;
 --current;
 return tmp;
 ```
-##### `move_iterator::operator+` <a id="move.iter.op.+">[[move.iter.op.+]]</a>
 ``` cpp
 constexpr move_iterator operator+(difference_type n) const;
 ```
 *Returns:* `move_iterator(current + n)`.
-##### `move_iterator::operator+=` <a id="move.iter.op.+=">[[move.iter.op.+=]]</a>
 ``` cpp
 constexpr move_iterator& operator+=(difference_type n);
 ```
 *Effects:* As if by: `current += n;`
 *Returns:* `*this`.
-##### `move_iterator::operator-` <a id="move.iter.op.-">[[move.iter.op.-]]</a>
 ``` cpp
 constexpr move_iterator operator-(difference_type n) const;
 ```
 *Returns:* `move_iterator(current - n)`.
-##### `move_iterator::operator-=` <a id="move.iter.op.-=">[[move.iter.op.-=]]</a>
 ``` cpp
 constexpr move_iterator& operator-=(difference_type n);
 ```
 *Effects:* As if by: `current -= n;`
 *Returns:* `*this`.
-##### `move_iterator::operator[]` <a id="move.iter.op.index">[[move.iter.op.index]]</a>
-``` cpp
-constexpr unspecified operator[](difference_type n) const;
-```
-*Returns:* `std::move(current[n])`.
-##### `move_iterator` comparisons <a id="move.iter.op.comp">[[move.iter.op.comp]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
-constexpr bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
 *Returns:* `x.base() == y.base()`.
-``` cpp
-template <class Iterator1, class Iterator2>
-constexpr bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-```
-*Returns:* `!(x == y)`.
 ``` cpp
 template<class Iterator1, class Iterator2>
 constexpr bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
 *Returns:* `x.base() < y.base()`.
-``` cpp
-template <class Iterator1, class Iterator2>
-constexpr bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
-```
-*Returns:* `!(y < x)`.
 ``` cpp
 template<class Iterator1, class Iterator2>
 constexpr bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
 *Returns:* `y < x`.
 ``` cpp
 template<class Iterator1, class Iterator2>
 constexpr bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
 *Returns:* `!(x < y)`.
-##### `move_iterator` non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
- constexpr auto operator-(
- const move_iterator<Iterator1>& x,
- const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
 ```
 *Returns:* `x.base() - y.base()`.
 ``` cpp
 template<class Iterator>
-  constexpr move_iterator<Iterator> operator+(
- typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
 ```
 *Returns:* `x + n`.
 ``` cpp
 template<class Iterator>
 constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
 ```
-*Returns:* `move_iterator<Iterator>(i)`.

+### Move iterators and sentinels <a id="move.iterators">[[move.iterators]]</a>
 Class template `move_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 an rvalue. Some generic algorithms can be called
 namespace std {
   template<class Iterator>
   class move_iterator {
   public:
     using iterator_type     = Iterator;
+    using iterator_concept  = input_iterator_tag;
+    using iterator_category = see below;
+    using value_type        = iter_value_t<Iterator>;
+    using difference_type   = iter_difference_t<Iterator>;
     using pointer           = Iterator;
+    using reference         = iter_rvalue_reference_t<Iterator>;
     constexpr move_iterator();
     constexpr explicit move_iterator(Iterator i);
     template<class U> constexpr move_iterator(const move_iterator<U>& u);
     template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
+    constexpr iterator_type base() const &;
+    constexpr iterator_type base() &&;
     constexpr reference operator*() const;
     constexpr move_iterator& operator++();
+    constexpr auto operator++(int);
     constexpr move_iterator& operator--();
     constexpr move_iterator operator--(int);
     constexpr move_iterator operator+(difference_type n) const;
     constexpr move_iterator& operator+=(difference_type n);
     constexpr move_iterator operator-(difference_type n) const;
     constexpr move_iterator& operator-=(difference_type n);
+    constexpr reference operator[](difference_type n) const;
+    template<sentinel_for<Iterator> S>
+      friend constexpr bool
+        operator==(const move_iterator& x, const move_sentinel<S>& y);
+    template<sized_sentinel_for<Iterator> S>
+      friend constexpr iter_difference_t<Iterator>
+        operator-(const move_sentinel<S>& x, const move_iterator& y);
+    template<sized_sentinel_for<Iterator> S>
+      friend constexpr iter_difference_t<Iterator>
+        operator-(const move_iterator& x, const move_sentinel<S>& y);
+    friend constexpr iter_rvalue_reference_t<Iterator>
+      iter_move(const move_iterator& i)
+        noexcept(noexcept(ranges::iter_move(i.current)));
+    template<indirectly_swappable<Iterator> Iterator2>
+      friend constexpr void
+        iter_swap(const move_iterator& x, const move_iterator<Iterator2>& y)
+          noexcept(noexcept(ranges::iter_swap(x.current, y.current)));
   private:
     Iterator current;   // exposition only
   };
 }
 ```
+The member *typedef-name* `iterator_category` denotes
+- `random_access_iterator_tag` if the type
+  `iterator_traits<{}Iterator>::iterator_category` models
+  `derived_from<random_access_iterator_tag>`, and
+- `iterator_traits<{}Iterator>::iterator_category` otherwise.
+#### Requirements <a id="move.iter.requirements">[[move.iter.requirements]]</a>
+The template parameter `Iterator` shall either meet the
+*Cpp17InputIterator* requirements [[input.iterators]] or model
+`input_iterator` [[iterator.concept.input]]. Additionally, if any of the
+bidirectional traversal functions are instantiated, the template
+parameter shall either meet the *Cpp17BidirectionalIterator*
+requirements [[bidirectional.iterators]] or model
+`bidirectional_iterator` [[iterator.concept.bidir]]. If any of the
+random access traversal functions are instantiated, the template
+parameter shall either meet the *Cpp17RandomAccessIterator* requirements
+[[random.access.iterators]] or model `random_access_iterator`
+[[iterator.concept.random.access]].
+#### Construction and assignment <a id="move.iter.cons">[[move.iter.cons]]</a>
 ``` cpp
 constexpr move_iterator();
 ```
 ``` cpp
 constexpr explicit move_iterator(Iterator i);
 ```
 *Effects:* Constructs a `move_iterator`, initializing `current` with
+`std::move(i)`.
 ``` cpp
 template<class U> constexpr move_iterator(const move_iterator<U>& u);
 ```
+*Mandates:* `U` is convertible to `Iterator`.
 *Effects:* Constructs a `move_iterator`, initializing `current` with
 `u.base()`.
 ``` cpp
 template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
 ```
+*Mandates:* `U` is convertible to `Iterator`.
 *Effects:* Assigns `u.base()` to `current`.
+#### Conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
 ``` cpp
+constexpr Iterator base() const &;
 ```
+*Constraints:* `Iterator` satisfies `copy_constructible`.
+*Preconditions:* `Iterator` models `copy_constructible`.
 *Returns:* `current`.
+``` cpp
+constexpr Iterator base() &&;
+```
+*Returns:* `std::move(current)`.
+#### Element access <a id="move.iter.elem">[[move.iter.elem]]</a>
 ``` cpp
 constexpr reference operator*() const;
 ```
+*Effects:* Equivalent to: `return ranges::iter_move(current);`
 ``` cpp
+constexpr reference operator[](difference_type n) const;
 ```
+*Effects:* Equivalent to: `ranges::iter_move(current + n);`
+#### Navigation <a id="move.iter.nav">[[move.iter.nav]]</a>
 ``` cpp
 constexpr move_iterator& operator++();
 ```
 *Effects:* As if by `++current`.
 *Returns:* `*this`.
 ``` cpp
+constexpr auto operator++(int);
 ```
+*Effects:* If `Iterator` models `forward_iterator`, equivalent to:
 ``` cpp
 move_iterator tmp = *this;
 ++current;
 return tmp;
 ```
+Otherwise, equivalent to `++current`.
 ``` cpp
 constexpr move_iterator& operator--();
 ```
 move_iterator tmp = *this;
 --current;
 return tmp;
 ```
 ``` cpp
 constexpr move_iterator operator+(difference_type n) const;
 ```
 *Returns:* `move_iterator(current + n)`.
 ``` cpp
 constexpr move_iterator& operator+=(difference_type n);
 ```
 *Effects:* As if by: `current += n;`
 *Returns:* `*this`.
 ``` cpp
 constexpr move_iterator operator-(difference_type n) const;
 ```
 *Returns:* `move_iterator(current - n)`.
 ``` cpp
 constexpr move_iterator& operator-=(difference_type n);
 ```
 *Effects:* As if by: `current -= n;`
 *Returns:* `*this`.
+#### Comparisons <a id="move.iter.op.comp">[[move.iter.op.comp]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
+ constexpr bool operator==(const move_iterator<Iterator1>& x,
+                            const move_iterator<Iterator2>& y);
+template<sentinel_for<Iterator> S>
+  friend constexpr bool operator==(const move_iterator& x,
+                                   const move_sentinel<S>& y);
 ```
+*Constraints:* `x.base() == y.base()` is well-formed and convertible to
+`bool`.
 *Returns:* `x.base() == y.base()`.
 ``` cpp
 template<class Iterator1, class Iterator2>
 constexpr bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
+*Constraints:* `x.base() < y.base()` is well-formed and convertible to
+`bool`.
 *Returns:* `x.base() < y.base()`.
 ``` cpp
 template<class Iterator1, class Iterator2>
 constexpr bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
+*Constraints:* `y.base() < x.base()` is well-formed and convertible to
+`bool`.
 *Returns:* `y < x`.
+``` cpp
+template<class Iterator1, class Iterator2>
+constexpr bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
+```
+*Constraints:* `y.base() < x.base()` is well-formed and convertible to
+`bool`.
+*Returns:* `!(y < x)`.
 ``` cpp
 template<class Iterator1, class Iterator2>
 constexpr bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 ```
+*Constraints:* `x.base() < y.base()` is well-formed and convertible to
+`bool`.
 *Returns:* `!(x < y)`.
+``` cpp
+template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
+  constexpr compare_three_way_result_t<Iterator1, Iterator2>
+    operator<=>(const move_iterator<Iterator1>& x,
+                const move_iterator<Iterator2>& y);
+```
+*Returns:* `x.base() <=> y.base()`.
+#### Non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
+ constexpr auto operator-(const move_iterator<Iterator1>& x,
+ const move_iterator<Iterator2>& y)
+    -> decltype(x.base() - y.base());
+template<sized_sentinel_for<Iterator> S>
+  friend constexpr iter_difference_t<Iterator>
+    operator-(const move_sentinel<S>& x, const move_iterator& y);
+template<sized_sentinel_for<Iterator> S>
+  friend constexpr iter_difference_t<Iterator>
+    operator-(const move_iterator& x, const move_sentinel<S>& y);
 ```
 *Returns:* `x.base() - y.base()`.
 ``` cpp
 template<class Iterator>
+  constexpr move_iterator<Iterator>
+ operator+(iter_difference_t<Iterator> n, const move_iterator<Iterator>& x);
 ```
+*Constraints:* `x + n` is well-formed and has type `Iterator`.
 *Returns:* `x + n`.
+``` cpp
+friend constexpr iter_rvalue_reference_t<Iterator>
+  iter_move(const move_iterator& i)
+    noexcept(noexcept(ranges::iter_move(i.current)));
+```
+*Effects:* Equivalent to: `return ranges::iter_move(i.current);`
+``` cpp
+template<indirectly_swappable<Iterator> Iterator2>
+  friend constexpr void
+    iter_swap(const move_iterator& x, const move_iterator<Iterator2>& y)
+      noexcept(noexcept(ranges::iter_swap(x.current, y.current)));
+```
+*Effects:* Equivalent to: `ranges::iter_swap(x.current, y.current)`.
 ``` cpp
 template<class Iterator>
 constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
 ```
+*Returns:* `move_iterator<Iterator>(std::move(i))`.
+#### Class template `move_sentinel` <a id="move.sentinel">[[move.sentinel]]</a>
+Class template `move_sentinel` is a sentinel adaptor useful for denoting
+ranges together with `move_iterator`. When an input iterator type `I`
+and sentinel type `S` model `sentinel_for<S, I>`, `move_sentinel<S>` and
+`move_iterator<I>` model
+`sentinel_for<move_sentinel<S>, move_iterator<I>{>}` as well.
+[*Example 1*:
+A `move_if` algorithm is easily implemented with `copy_if` using
+`move_iterator` and `move_sentinel`:
+``` cpp
+template<input_iterator I, sentinel_for<I> S, weakly_incrementable O,
+         indirect_unary_predicate<I> Pred>
+  requires indirectly_movable<I, O>
+void move_if(I first, S last, O out, Pred pred) {
+  std::ranges::copy_if(move_iterator<I>{first}, move_sentinel<S>{last}, out, pred);
+}
+```
+— *end example*]
+``` cpp
+namespace std {
+  template<semiregular S>
+  class move_sentinel {
+  public:
+    constexpr move_sentinel();
+    constexpr explicit move_sentinel(S s);
+    template<class S2>
+      requires convertible_to<const S2&, S>
+        constexpr move_sentinel(const move_sentinel<S2>& s);
+    template<class S2>
+      requires assignable_from<S&, const S2&>
+        constexpr move_sentinel& operator=(const move_sentinel<S2>& s);
+    constexpr S base() const;
+  private:
+    S last;     // exposition only
+  };
+}
+```
+#### Operations <a id="move.sent.ops">[[move.sent.ops]]</a>
+``` cpp
+constexpr move_sentinel();
+```
+*Effects:* Value-initializes `last`. If
+`is_trivially_default_constructible_v<S>` is `true`, then this
+constructor is a `constexpr` constructor.
+``` cpp
+constexpr explicit move_sentinel(S s);
+```
+*Effects:* Initializes `last` with `std::move(s)`.
+``` cpp
+template<class S2>
+  requires convertible_to<const S2&, S>
+    constexpr move_sentinel(const move_sentinel<S2>& s);
+```
+*Effects:* Initializes `last` with `s.last`.
+``` cpp
+template<class S2>
+  requires assignable_from<S&, const S2&>
+    constexpr move_sentinel& operator=(const move_sentinel<S2>& s);
+```
+*Effects:* Equivalent to: `last = s.last; return *this;`
+``` cpp
+constexpr S base() const;
+```
+*Returns:* `last`.

Diff to HTML by rtfpessoa