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

Files changed (1) hide show

tmp/tmp2nd4n5nm/{from.md → to.md} +307 -0

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

	@@ -0,0 +1,307 @@

+### Common iterators <a id="iterators.common">[[iterators.common]]</a>
+#### Class template `common_iterator` <a id="common.iterator">[[common.iterator]]</a>
+Class template `common_iterator` is an iterator/sentinel adaptor that is
+capable of representing a non-common range of elements (where the types
+of the iterator and sentinel differ) as a common range (where they are
+the same). It does this by holding either an iterator or a sentinel, and
+implementing the equality comparison operators appropriately.
+[*Note 1*: The `common_iterator` type is useful for interfacing with
+legacy code that expects the begin and end of a range to have the same
+type. — *end note*]
+[*Example 1*:
+``` cpp
+template<class ForwardIterator>
+void fun(ForwardIterator begin, ForwardIterator end);
+list<int> s;
+// populate the list s
+using CI = common_iterator<counted_iterator<list<int>::iterator>, default_sentinel_t>;
+// call fun on a range of 10 ints
+fun(CI(counted_iterator(s.begin(), 10)), CI(default_sentinel));
+```
+— *end example*]
+``` cpp
+namespace std {
+  template<input_or_output_iterator I, sentinel_for<I> S>
+    requires (!same_as<I, S> && copyable<I>)
+  class common_iterator {
+  public:
+    constexpr common_iterator() = default;
+    constexpr common_iterator(I i);
+    constexpr common_iterator(S s);
+    template<class I2, class S2>
+      requires convertible_to<const I2&, I> && convertible_to<const S2&, S>
+        constexpr common_iterator(const common_iterator<I2, S2>& x);
+    template<class I2, class S2>
+      requires convertible_to<const I2&, I> && convertible_to<const S2&, S> &&
+               assignable_from<I&, const I2&> && assignable_from<S&, const S2&>
+        common_iterator& operator=(const common_iterator<I2, S2>& x);
+    decltype(auto) operator*();
+    decltype(auto) operator*() const
+      requires dereferenceable<const I>;
+    decltype(auto) operator->() const
+      requires see below;
+    common_iterator& operator++();
+    decltype(auto) operator++(int);
+    template<class I2, sentinel_for<I> S2>
+      requires sentinel_for<S, I2>
+    friend bool operator==(
+      const common_iterator& x, const common_iterator<I2, S2>& y);
+    template<class I2, sentinel_for<I> S2>
+      requires sentinel_for<S, I2> && equality_comparable_with<I, I2>
+    friend bool operator==(
+      const common_iterator& x, const common_iterator<I2, S2>& y);
+    template<sized_sentinel_for<I> I2, sized_sentinel_for<I> S2>
+      requires sized_sentinel_for<S, I2>
+    friend iter_difference_t<I2> operator-(
+      const common_iterator& x, const common_iterator<I2, S2>& y);
+    friend iter_rvalue_reference_t<I> iter_move(const common_iterator& i)
+      noexcept(noexcept(ranges::iter_move(declval<const I&>())))
+        requires input_iterator<I>;
+    template<indirectly_swappable<I> I2, class S2>
+      friend void iter_swap(const common_iterator& x, const common_iterator<I2, S2>& y)
+        noexcept(noexcept(ranges::iter_swap(declval<const I&>(), declval<const I2&>())));
+  private:
+    variant<I, S> v_;   // exposition only
+  };
+  template<class I, class S>
+  struct incrementable_traits<common_iterator<I, S>> {
+    using difference_type = iter_difference_t<I>;
+  };
+  template<input_iterator I, class S>
+  struct iterator_traits<common_iterator<I, S>> {
+    using iterator_concept = see below;
+    using iterator_category = see below;
+    using value_type = iter_value_t<I>;
+    using difference_type = iter_difference_t<I>;
+    using pointer = see below;
+    using reference = iter_reference_t<I>;
+  };
+}
+```
+#### Associated types <a id="common.iter.types">[[common.iter.types]]</a>
+The nested *typedef-name*s of the specialization of `iterator_traits`
+for `common_iterator<I, S>` are defined as follows.
+- `iterator_concept` denotes `forward_iterator_tag` if `I` models
+  `forward_iterator`; otherwise it denotes `input_iterator_tag`.
+- `iterator_category` denotes `forward_iterator_tag` if
+  `iterator_traits<I>::iterator_category` models
+  `derived_from<forward_iterator_tag>`; otherwise it denotes
+  `input_iterator_tag`.
+- If the expression `a.operator->()` is well-formed, where `a` is an
+  lvalue of type `const common_iterator<I, S>`, then `pointer` denotes
+  the type of that expression. Otherwise, `pointer` denotes `void`.
+#### Constructors and conversions <a id="common.iter.const">[[common.iter.const]]</a>
+``` cpp
+constexpr common_iterator(I i);
+```
+*Effects:* Initializes `v_` as if by
+`v_{in_place_type<I>, std::move(i)}`.
+``` cpp
+constexpr common_iterator(S s);
+```
+*Effects:* Initializes `v_` as if by
+`v_{in_place_type<S>, std::move(s)}`.
+``` cpp
+template<class I2, class S2>
+  requires convertible_to<const I2&, I> && convertible_to<const S2&, S>
+    constexpr common_iterator(const common_iterator<I2, S2>& x);
+```
+*Preconditions:* `x.v_.valueless_by_exception()` is `false`.
+*Effects:* Initializes `v_` as if by
+`v_{in_place_index<`i`>, get<`i`>(x.v_)}`, where i is `x.v_.index()`.
+``` cpp
+template<class I2, class S2>
+  requires convertible_to<const I2&, I> && convertible_to<const S2&, S> &&
+           assignable_from<I&, const I2&> && assignable_from<S&, const S2&>
+    common_iterator& operator=(const common_iterator<I2, S2>& x);
+```
+*Preconditions:* `x.v_.valueless_by_exception()` is `false`.
+*Effects:* Equivalent to:
+- If `v_.index() == x.v_.index()`, then `get<`i`>(v_) = get<`i`>(x.v_)`.
+- Otherwise, `v_.emplace<`i`>(get<`i`>(x.v_))`.
+where i is `x.v_.index()`.
+*Returns:* `*this`
+#### Accessors <a id="common.iter.access">[[common.iter.access]]</a>
+``` cpp
+decltype(auto) operator*();
+decltype(auto) operator*() const
+  requires dereferenceable<const I>;
+```
+*Preconditions:* `holds_alternative<I>(v_)`.
+*Effects:* Equivalent to: `return *get<I>(v_);`
+``` cpp
+decltype(auto) operator->() const
+  requires see below;
+```
+The expression in the requires clause is equivalent to:
+``` cpp
+indirectly_readable<const I> &&
+(requires(const I& i) { i.operator->(); } ||
+ is_reference_v<iter_reference_t<I>> ||
+ constructible_from<iter_value_t<I>, iter_reference_t<I>>)
+```
+*Preconditions:* `holds_alternative<I>(v_)`.
+*Effects:*
+- If `I` is a pointer type or if the expression
+  `get<I>(v_).operator->()` is well-formed, equivalent to:
+  `return get<I>(v_);`
+- Otherwise, if `iter_reference_t<I>` is a reference type, equivalent
+  to:
+  ``` cpp
+  auto&& tmp = *get<I>(v_);
+  return addressof(tmp);
+  ```
+- Otherwise, equivalent to: `return `*`proxy`*`(*get<I>(v_));` where
+  *proxy* is the exposition-only class:
+  ``` cpp
+  class proxy {
+    iter_value_t<I> keep_;
+    proxy(iter_reference_t<I>&& x)
+      : keep_(std::move(x)) {}
+  public:
+    const iter_value_t<I>* operator->() const {
+      return addressof(keep_);
+    }
+  };
+  ```
+#### Navigation <a id="common.iter.nav">[[common.iter.nav]]</a>
+``` cpp
+common_iterator& operator++();
+```
+*Preconditions:* `holds_alternative<I>(v_)`.
+*Effects:* Equivalent to `++get<I>(v_)`.
+*Returns:* `*this`.
+``` cpp
+decltype(auto) operator++(int);
+```
+*Preconditions:* `holds_alternative<I>(v_)`.
+*Effects:* If `I` models `forward_iterator`, equivalent to:
+``` cpp
+common_iterator tmp = *this;
+++*this;
+return tmp;
+```
+Otherwise, equivalent to: `return get<I>(v_)++;`
+#### Comparisons <a id="common.iter.cmp">[[common.iter.cmp]]</a>
+``` cpp
+template<class I2, sentinel_for<I> S2>
+  requires sentinel_for<S, I2>
+friend bool operator==(
+  const common_iterator& x, const common_iterator<I2, S2>& y);
+```
+*Preconditions:* `x.v_.valueless_by_exception()` and
+`y.v_.valueless_by_exception()` are each `false`.
+*Returns:* `true` if i` == `j, and otherwise
+`get<`i`>(x.v_) == get<`j`>(y.v_)`, where i is `x.v_.index()` and j is
+`y.v_.index()`.
+``` cpp
+template<class I2, sentinel_for<I> S2>
+  requires sentinel_for<S, I2> && equality_comparable_with<I, I2>
+friend bool operator==(
+  const common_iterator& x, const common_iterator<I2, S2>& y);
+```
+*Preconditions:* `x.v_.valueless_by_exception()` and
+`y.v_.valueless_by_exception()` are each `false`.
+*Returns:* `true` if i and j are each `1`, and otherwise
+`get<`i`>(x.v_) == get<`j`>(y.v_)`, where i is `x.v_.index()` and j is
+`y.v_.index()`.
+``` cpp
+template<sized_sentinel_for<I> I2, sized_sentinel_for<I> S2>
+  requires sized_sentinel_for<S, I2>
+friend iter_difference_t<I2> operator-(
+  const common_iterator& x, const common_iterator<I2, S2>& y);
+```
+*Preconditions:* `x.v_.valueless_by_exception()` and
+`y.v_.valueless_by_exception()` are each `false`.
+*Returns:* `0` if i and j are each `1`, and otherwise
+`get<`i`>(x.v_) - get<`j`>(y.v_)`, where i is `x.v_.index()` and j is
+`y.v_.index()`.
+#### Customization <a id="common.iter.cust">[[common.iter.cust]]</a>
+``` cpp
+friend iter_rvalue_reference_t<I> iter_move(const common_iterator& i)
+  noexcept(noexcept(ranges::iter_move(declval<const I&>())))
+    requires input_iterator<I>;
+```
+*Preconditions:* `holds_alternative<I>(v_)`.
+*Effects:* Equivalent to: `return ranges::iter_move(get<I>(i.v_));`
+``` cpp
+template<indirectly_swappable<I> I2, class S2>
+  friend void iter_swap(const common_iterator& x, const common_iterator<I2, S2>& y)
+    noexcept(noexcept(ranges::iter_swap(declval<const I&>(), declval<const I2&>())));
+```
+*Preconditions:* `holds_alternative<I>(x.v_)` and
+`holds_alternative<I2>(y.v_)` are each `true`.
+*Effects:* Equivalent to
+`ranges::iter_swap(get<I>(x.v_), get<I2>(y.v_))`.

Diff to HTML by rtfpessoa