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

Files changed (1) hide show

tmp/tmp1m5_t9m6/{from.md → to.md} +175 -140

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

@@ -1,35 +1,34 @@
 ### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
 Class template `reverse_iterator` is an iterator adaptor that iterates
 from the end of the sequence defined by its underlying iterator to the
-beginning of that sequence. The fundamental relation between a reverse
-iterator and its corresponding iterator `i` is established by the
-identity: `&*(reverse_iterator(i)) == &*(i - 1)`.
 #### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
 ``` cpp
 namespace std {
   template<class Iterator>
   class reverse_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           = typename iterator_traits<Iterator>::pointer;
-    using reference         = typename iterator_traits<Iterator>::reference;
     constexpr reverse_iterator();
     constexpr explicit reverse_iterator(Iterator x);
     template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
     template<class U> constexpr reverse_iterator& operator=(const reverse_iterator<U>& u);
-    constexpr Iterator base() const;      // explicit
     constexpr reference operator*() const;
-    constexpr pointer   operator->() const;
     constexpr reverse_iterator& operator++();
     constexpr reverse_iterator  operator++(int);
     constexpr reverse_iterator& operator--();
     constexpr reverse_iterator  operator--(int);
@@ -37,72 +36,60 @@ namespace std {
     constexpr reverse_iterator  operator+ (difference_type n) const;
     constexpr reverse_iterator& operator+=(difference_type n);
     constexpr reverse_iterator  operator- (difference_type n) const;
     constexpr reverse_iterator& operator-=(difference_type n);
     constexpr unspecified operator[](difference_type n) const;
   protected:
     Iterator current;
   };
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator==(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator<(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator!=(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator>(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator>=(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr bool operator<=(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y);
-  template <class Iterator1, class Iterator2>
-    constexpr auto operator-(
-      const reverse_iterator<Iterator1>& x,
-      const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
-  template <class Iterator>
-    constexpr reverse_iterator<Iterator> operator+(
-      typename reverse_iterator<Iterator>::difference_type n,
-      const reverse_iterator<Iterator>& x);
-  template <class Iterator>
-    constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
 }
 ```
-#### `reverse_iterator` requirements <a id="reverse.iter.requirements">[[reverse.iter.requirements]]</a>
-The template parameter `Iterator` shall meet all the requirements of a
-Bidirectional Iterator ([[bidirectional.iterators]]).
-Additionally, `Iterator` shall meet the requirements of a random access
-iterator ([[random.access.iterators]]) if any of the members
-`operator+` ([[reverse.iter.op+]]), `operator-` (
-[[reverse.iter.op-]]), `operator+=` ([[reverse.iter.op+=]]),
-`operator-=` ([[reverse.iter.op-=]]), `operator[]` (
-[[reverse.iter.opindex]]), or the non-member operators `operator<` (
-[[reverse.iter.op<]]), `operator>` ([[reverse.iter.op>]]),
-`operator<=` ([[reverse.iter.op<=]]), `operator>=` (
-[[reverse.iter.op>=]]), `operator-` ([[reverse.iter.opdiff]]) or
-`operator+` ([[reverse.iter.opsum]]) are referenced in a way that
-requires instantiation ([[temp.inst]]).
-#### `reverse_iterator` operations <a id="reverse.iter.ops">[[reverse.iter.ops]]</a>
-##### `reverse_iterator` constructor <a id="reverse.iter.cons">[[reverse.iter.cons]]</a>
 ``` cpp
 constexpr reverse_iterator();
 ```
@@ -121,31 +108,29 @@ constexpr explicit reverse_iterator(Iterator x);
 template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
 ```
 *Effects:* Initializes `current` with `u.current`.
-##### `reverse_iterator::operator=` <a id="reverse.iter.op=">[[reverse.iter.op=]]</a>
 ``` cpp
 template<class U>
   constexpr reverse_iterator&
     operator=(const reverse_iterator<U>& u);
 ```
-*Effects:* Assigns `u.base()` to current.
 *Returns:* `*this`.
-##### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
 ``` cpp
 constexpr Iterator base() const;          // explicit
 ```
 *Returns:* `current`.
-##### `operator*` <a id="reverse.iter.op.star">[[reverse.iter.op.star]]</a>
 ``` cpp
 constexpr reference operator*() const;
 ```
@@ -154,19 +139,41 @@ constexpr reference operator*() const;
 ``` cpp
 Iterator tmp = current;
 return *--tmp;
 ```
-##### `operator->` <a id="reverse.iter.opref">[[reverse.iter.opref]]</a>
 ``` cpp
-constexpr pointer operator->() const;
 ```
-*Returns:* `addressof(operator*())`.
-##### `operator++` <a id="reverse.iter.op++">[[reverse.iter.op++]]</a>
 ``` cpp
 constexpr reverse_iterator& operator++();
 ```
@@ -184,12 +191,10 @@ constexpr reverse_iterator operator++(int);
 reverse_iterator tmp = *this;
 --current;
 return tmp;
 ```
-\[reverse.iter.op\]`operator\dcr`
 ``` cpp
 constexpr reverse_iterator& operator--();
 ```
 *Effects:* As if by `++current`.
@@ -206,143 +211,173 @@ constexpr reverse_iterator operator--(int);
 reverse_iterator tmp = *this;
 ++current;
 return tmp;
 ```
-##### `operator+` <a id="reverse.iter.op+">[[reverse.iter.op+]]</a>
-``` cpp
-constexpr reverse_iterator operator+(difference_type n) const;
-```
-*Returns:* `reverse_iterator(current-n)`.
-##### `operator+=` <a id="reverse.iter.op+=">[[reverse.iter.op+=]]</a>
 ``` cpp
 constexpr reverse_iterator& operator+=(difference_type n);
 ```
 *Effects:* As if by: `current -= n;`
 *Returns:* `*this`.
-##### `operator-` <a id="reverse.iter.op-">[[reverse.iter.op-]]</a>
-``` cpp
-constexpr reverse_iterator operator-(difference_type n) const;
-```
-*Returns:* `reverse_iterator(current+n)`.
-##### `operator-=` <a id="reverse.iter.op-=">[[reverse.iter.op-=]]</a>
 ``` cpp
 constexpr reverse_iterator& operator-=(difference_type n);
 ```
 *Effects:* As if by: `current += n;`
 *Returns:* `*this`.
-##### `operator[]` <a id="reverse.iter.opindex">[[reverse.iter.opindex]]</a>
-``` cpp
-constexpr unspecified operator[](difference_type n) const;
-```
-*Returns:* `current[-n-1]`.
-##### `operator==` <a id="reverse.iter.op==">[[reverse.iter.op==]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr bool operator==(
     const reverse_iterator<Iterator1>& x,
     const reverse_iterator<Iterator2>& y);
 ```
-*Returns:* `x.current == y.current`.
-##### `operator<` <a id="reverse.iter.op<">[[reverse.iter.op<]]</a>
-``` cpp
-template <class Iterator1, class Iterator2>
-  constexpr bool operator<(
-    const reverse_iterator<Iterator1>& x,
-    const reverse_iterator<Iterator2>& y);
-```
-*Returns:* `x.current > y.current`.
-##### `operator!=` <a id="reverse.iter.op!=">[[reverse.iter.op!=]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr bool operator!=(
     const reverse_iterator<Iterator1>& x,
     const reverse_iterator<Iterator2>& y);
 ```
-*Returns:* `x.current != y.current`.
-##### `operator>` <a id="reverse.iter.op>">[[reverse.iter.op>]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr bool operator>(
     const reverse_iterator<Iterator1>& x,
     const reverse_iterator<Iterator2>& y);
 ```
-*Returns:* `x.current < y.current`.
-##### `operator>=` <a id="reverse.iter.op>=">[[reverse.iter.op>=]]</a>
-``` cpp
-template <class Iterator1, class Iterator2>
-  constexpr bool operator>=(
-    const reverse_iterator<Iterator1>& x,
-    const reverse_iterator<Iterator2>& y);
-```
-*Returns:* `x.current <= y.current`.
-##### `operator<=` <a id="reverse.iter.op<=">[[reverse.iter.op<=]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr bool operator<=(
     const reverse_iterator<Iterator1>& x,
     const reverse_iterator<Iterator2>& y);
 ```
-*Returns:* `x.current >= y.current`.
-##### `operator-` <a id="reverse.iter.opdiff">[[reverse.iter.opdiff]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr auto operator-(
     const reverse_iterator<Iterator1>& x,
     const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
 ```
-*Returns:* `y.current - x.current`.
-##### `operator+` <a id="reverse.iter.opsum">[[reverse.iter.opsum]]</a>
 ``` cpp
 template<class Iterator>
   constexpr reverse_iterator<Iterator> operator+(
     typename reverse_iterator<Iterator>::difference_type n,
     const reverse_iterator<Iterator>& x);
 ```
-*Returns:* `reverse_iterator<Iterator> (x.current - n)`.
-##### Non-member function `make_reverse_iterator()` <a id="reverse.iter.make">[[reverse.iter.make]]</a>
 ``` cpp
 template<class Iterator>
   constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
 ```

 ### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
 Class template `reverse_iterator` is an iterator adaptor that iterates
 from the end of the sequence defined by its underlying iterator to the
+beginning of that sequence.
 #### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
 ``` cpp
 namespace std {
   template<class Iterator>
   class reverse_iterator {
   public:
     using iterator_type     = Iterator;
+    using iterator_concept  = see below;
+    using iterator_category = see below;
+    using value_type        = iter_value_t<Iterator>;
+    using difference_type   = iter_difference_t<Iterator>;
     using pointer           = typename iterator_traits<Iterator>::pointer;
+    using reference         = iter_reference_t<Iterator>;
     constexpr reverse_iterator();
     constexpr explicit reverse_iterator(Iterator x);
     template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
     template<class U> constexpr reverse_iterator& operator=(const reverse_iterator<U>& u);
+    constexpr Iterator base() const;
     constexpr reference operator*() const;
+    constexpr pointer   operator->() const requires see below;
     constexpr reverse_iterator& operator++();
     constexpr reverse_iterator  operator++(int);
     constexpr reverse_iterator& operator--();
     constexpr reverse_iterator  operator--(int);
     constexpr reverse_iterator  operator+ (difference_type n) const;
     constexpr reverse_iterator& operator+=(difference_type n);
     constexpr reverse_iterator  operator- (difference_type n) const;
     constexpr reverse_iterator& operator-=(difference_type n);
     constexpr unspecified operator[](difference_type n) const;
+    friend constexpr iter_rvalue_reference_t<Iterator>
+      iter_move(const reverse_iterator& i) noexcept(see below);
+    template<indirectly_swappable<Iterator> Iterator2>
+      friend constexpr void
+        iter_swap(const reverse_iterator& x,
+                  const reverse_iterator<Iterator2>& y) noexcept(see below);
   protected:
     Iterator current;
   };
 }
 ```
+The member *typedef-name* `iterator_concept` denotes
+- `random_access_iterator_tag` if `Iterator` models
+  `random_access_iterator`, and
+- `bidirectional_iterator_tag` otherwise.
+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="reverse.iter.requirements">[[reverse.iter.requirements]]</a>
+The template parameter `Iterator` shall either meet the requirements of
+a *Cpp17BidirectionalIterator* [[bidirectional.iterators]] or model
+`bidirectional_iterator` [[iterator.concept.bidir]].
+Additionally, `Iterator` shall either meet the requirements of a
+*Cpp17RandomAccessIterator* [[random.access.iterators]] or model
+`random_access_iterator` [[iterator.concept.random.access]] if the
+definitions of any of the members
+- `operator+`, `operator-`, `operator+=`, `operator-=`
+  [[reverse.iter.nav]], or
+- `operator[]` [[reverse.iter.elem]],
+or the non-member operators [[reverse.iter.cmp]]
+- `operator<`, `operator>`, `operator<=`, `operator>=`, `operator-`, or
+  `operator+` [[reverse.iter.nonmember]]
+are instantiated [[temp.inst]].
+#### Construction and assignment <a id="reverse.iter.cons">[[reverse.iter.cons]]</a>
 ``` cpp
 constexpr reverse_iterator();
 ```
 template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
 ```
 *Effects:* Initializes `current` with `u.current`.
 ``` cpp
 template<class U>
   constexpr reverse_iterator&
     operator=(const reverse_iterator<U>& u);
 ```
+*Effects:* Assigns `u.base()` to `current`.
 *Returns:* `*this`.
+#### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
 ``` cpp
 constexpr Iterator base() const;          // explicit
 ```
 *Returns:* `current`.
+#### Element access <a id="reverse.iter.elem">[[reverse.iter.elem]]</a>
 ``` cpp
 constexpr reference operator*() const;
 ```
 ``` cpp
 Iterator tmp = current;
 return *--tmp;
 ```
+``` cpp
+constexpr pointer operator->() const
+  requires (is_pointer_v<Iterator> ||
+            requires (const Iterator i) { i.operator->(); });
+```
+*Effects:*
+- If `Iterator` is a pointer type, equivalent to:
+  `return prev(current);`
+- Otherwise, equivalent to: `return prev(current).operator->();`
+``` cpp
+constexpr unspecified operator[](difference_type n) const;
+```
+*Returns:* `current[-n-1]`.
+#### Navigation <a id="reverse.iter.nav">[[reverse.iter.nav]]</a>
 ``` cpp
+constexpr reverse_iterator operator+(difference_type n) const;
 ```
+*Returns:* `reverse_iterator(current-n)`.
+``` cpp
+constexpr reverse_iterator operator-(difference_type n) const;
+```
+*Returns:* `reverse_iterator(current+n)`.
 ``` cpp
 constexpr reverse_iterator& operator++();
 ```
 reverse_iterator tmp = *this;
 --current;
 return tmp;
 ```
 ``` cpp
 constexpr reverse_iterator& operator--();
 ```
 *Effects:* As if by `++current`.
 reverse_iterator tmp = *this;
 ++current;
 return tmp;
 ```
 ``` cpp
 constexpr reverse_iterator& operator+=(difference_type n);
 ```
 *Effects:* As if by: `current -= n;`
 *Returns:* `*this`.
 ``` cpp
 constexpr reverse_iterator& operator-=(difference_type n);
 ```
 *Effects:* As if by: `current += n;`
 *Returns:* `*this`.
+#### Comparisons <a id="reverse.iter.cmp">[[reverse.iter.cmp]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr bool operator==(
     const reverse_iterator<Iterator1>& x,
     const reverse_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 reverse_iterator<Iterator1>& x,
     const reverse_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 reverse_iterator<Iterator1>& x,
+    const reverse_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 reverse_iterator<Iterator1>& x,
     const reverse_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 reverse_iterator<Iterator1>& x,
     const reverse_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 reverse_iterator<Iterator1>& x,
+    const reverse_iterator<Iterator2>& y);
+```
+*Constraints:* `x.base() <= y.base()` is well-formed and convertible to
+`bool`.
+*Returns:* `x.base() <= y.base()`.
+``` cpp
+template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
+  constexpr compare_three_way_result_t<Iterator1, Iterator2>
+    operator<=>(const reverse_iterator<Iterator1>& x,
+                const reverse_iterator<Iterator2>& y);
+```
+*Returns:* `y.base() <=> x.base()`.
+[*Note 1*: The argument order in the *Returns:* element is reversed
+because this is a reverse iterator. — *end note*]
+#### Non-member functions <a id="reverse.iter.nonmember">[[reverse.iter.nonmember]]</a>
 ``` cpp
 template<class Iterator1, class Iterator2>
   constexpr auto operator-(
     const reverse_iterator<Iterator1>& x,
     const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
 ```
+*Returns:* `y.base() - x.base()`.
 ``` cpp
 template<class Iterator>
   constexpr reverse_iterator<Iterator> operator+(
     typename reverse_iterator<Iterator>::difference_type n,
     const reverse_iterator<Iterator>& x);
 ```
+*Returns:* `reverse_iterator<Iterator>(x.base() - n)`.
+``` cpp
+friend constexpr iter_rvalue_reference_t<Iterator>
+  iter_move(const reverse_iterator& i) noexcept(see below);
+```
+*Effects:* Equivalent to:
+``` cpp
+auto tmp = i.base();
+return ranges::iter_move(--tmp);
+```
+*Remarks:* The expression in `noexcept` is equivalent to:
+``` cpp
+is_nothrow_copy_constructible_v<Iterator> &&
+noexcept(ranges::iter_move(--declval<Iterator&>()))
+```
+``` cpp
+template<indirectly_swappable<Iterator> Iterator2>
+  friend constexpr void
+    iter_swap(const reverse_iterator& x,
+              const reverse_iterator<Iterator2>& y) noexcept(see below);
+```
+*Effects:* Equivalent to:
+``` cpp
+auto xtmp = x.base();
+auto ytmp = y.base();
+ranges::iter_swap(--xtmp, --ytmp);
+```
+*Remarks:* The expression in `noexcept` is equivalent to:
+``` cpp
+is_nothrow_copy_constructible_v<Iterator> &&
+is_nothrow_copy_constructible_v<Iterator2> &&
+noexcept(ranges::iter_swap(--declval<Iterator&>(), --declval<Iterator2&>()))
+```
 ``` cpp
 template<class Iterator>
   constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
 ```

Diff to HTML by rtfpessoa