[range.join.with] - C++20 → C++23

Files changed (1) hide show

tmp/tmpkp4yspkt/{from.md → to.md} +524 -0

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

	@@ -0,0 +1,524 @@

+### Join with view <a id="range.join.with">[[range.join.with]]</a>
+#### Overview <a id="range.join.with.overview">[[range.join.with.overview]]</a>
+`join_with_view` takes a view and a delimiter, and flattens the view,
+inserting every element of the delimiter in between elements of the
+view. The delimiter can be a single element or a view of elements.
+The name `views::join_with` denotes a range adaptor object
+[[range.adaptor.object]]. Given subexpressions `E` and `F`, the
+expression `views::join_with(E, F)` is expression-equivalent to
+`join_with_view(E, F)`.
+[*Example 1*:
+``` cpp
+vector<string> vs = {"the", "quick", "brown", "fox"};
+for (char c : vs | views::join_with('-')) {
+  cout << c;
+}
+// The above prints the-quick-brown-fox
+```
+— *end example*]
+#### Class template `join_with_view` <a id="range.join.with.view">[[range.join.with.view]]</a>
+``` cpp
+namespace std::ranges {
+  template<class R, class P>
+  concept compatible-joinable-ranges =            // exposition only
+      common_with<range_value_t<R>, range_value_t<P>> &&
+      common_reference_with<range_reference_t<R>, range_reference_t<P>> &&
+      common_reference_with<range_rvalue_reference_t<R>, range_rvalue_reference_t<P>>;
+  template<class R>
+  concept bidirectional-common = bidirectional_range<R> && common_range<R>;    // exposition only
+  template<input_range V, forward_range Pattern>
+    requires view<V> && input_range<range_reference_t<V>>
+          && view<Pattern>
+          && compatible-joinable-ranges<range_reference_t<V>, Pattern>
+  class join_with_view : public view_interface<join_with_view<V, Pattern>> {
+    using InnerRng = range_reference_t<V>;                  // exposition only
+    V base_ = V();                                          // exposition only
+    non-propagating-cache<iterator_t<V>> outer_it_;         // exposition only, present only
+                                                            // when !forward_range<V>
+    non-propagating-cache<remove_cv_t<InnerRng>> inner_;   // exposition only, present only
+                                                            // if is_reference_v<InnerRng> is false
+    Pattern pattern_ = Pattern();                           // exposition only
+    // [range.join.with.iterator], class template join_with_view::iterator
+    template<bool Const> struct iterator;                   // exposition only
+    // [range.join.with.sentinel], class template join_with_view::sentinel
+    template<bool Const> struct sentinel;                   // exposition only
+  public:
+    join_with_view()
+      requires default_initializable<V> && default_initializable<Pattern> = default;
+    constexpr explicit join_with_view(V base, Pattern pattern);
+    template<input_range R>
+      requires constructible_from<V, views::all_t<R>> &&
+               constructible_from<Pattern, single_view<range_value_t<InnerRng>>>
+    constexpr explicit join_with_view(R&& r, range_value_t<InnerRng> e);
+    constexpr V base() const & requires copy_constructible<V> { return base_; }
+    constexpr V base() && { return std::move(base_); }
+    constexpr auto begin() {
+      if constexpr (forward_range<V>) {
+        constexpr bool use_const =
+          simple-view<V> && is_reference_v<InnerRng> && simple-view<Pattern>;
+        return iterator<use_const>{*this, ranges::begin(base_)};
+      }
+      else {
+        outer_it_ = ranges::begin(base_);
+        return iterator<false>{*this};
+      }
+    }
+    constexpr auto begin() const
+      requires forward_range<const V> &&
+               forward_range<const Pattern> &&
+               is_reference_v<range_reference_t<const V>> &&
+               input_range<range_reference_t<const V>> {
+      return iterator<true>{*this, ranges::begin(base_)};
+    }
+    constexpr auto end() {
+      if constexpr (forward_range<V> &&
+                    is_reference_v<InnerRng> && forward_range<InnerRng> &&
+                    common_range<V> && common_range<InnerRng>)
+        return iterator<simple-view<V> && simple-view<Pattern>>{*this, ranges::end(base_)};
+      else
+        return sentinel<simple-view<V> && simple-view<Pattern>>{*this};
+    }
+    constexpr auto end() const
+      requires forward_range<const V> && forward_range<const Pattern> &&
+               is_reference_v<range_reference_t<const V>> &&
+               input_range<range_reference_t<const V>> {
+      using InnerConstRng = range_reference_t<const V>;
+      if constexpr (forward_range<InnerConstRng> &&
+                    common_range<const V> && common_range<InnerConstRng>)
+        return iterator<true>{*this, ranges::end(base_)};
+      else
+        return sentinel<true>{*this};
+    }
+  };
+  template<class R, class P>
+    join_with_view(R&&, P&&) -> join_with_view<views::all_t<R>, views::all_t<P>>;
+  template<input_range R>
+    join_with_view(R&&, range_value_t<range_reference_t<R>>)
+      -> join_with_view<views::all_t<R>, single_view<range_value_t<range_reference_t<R>>>>;
+}
+```
+``` cpp
+constexpr explicit join_with_view(V base, Pattern pattern);
+```
+*Effects:* Initializes *base\_* with `std::move(base)` and *pattern\_*
+with `std::move(pattern)`.
+``` cpp
+template<input_range R>
+  requires constructible_from<V, views::all_t<R>> &&
+           constructible_from<Pattern, single_view<range_value_t<InnerRng>>>
+constexpr explicit join_with_view(R&& r, range_value_t<InnerRng> e);
+```
+*Effects:* Initializes *base\_* with `views::all(std::forward<R>(r))`
+and *pattern\_* with `views::single(std::move(e))`.
+#### Class template `join_with_view::iterator` <a id="range.join.with.iterator">[[range.join.with.iterator]]</a>
+``` cpp
+namespace std::ranges {
+  template<input_range V, forward_range Pattern>
+    requires view<V> && input_range<range_reference_t<V>>
+          && view<Pattern> && compatible-joinable-ranges<range_reference_t<V>, Pattern>
+  template<bool Const>
+  class join_with_view<V, Pattern>::iterator {
+    using Parent = maybe-const<Const, join_with_view>;                  // exposition only
+    using Base = maybe-const<Const, V>;                                 // exposition only
+    using InnerBase = range_reference_t<Base>;                          // exposition only
+    using PatternBase = maybe-const<Const, Pattern>;                    // exposition only
+    using OuterIter = iterator_t<Base>;                                 // exposition only
+    using InnerIter = iterator_t<InnerBase>;                            // exposition only
+    using PatternIter = iterator_t<PatternBase>;                        // exposition only
+    static constexpr bool ref-is-glvalue = is_reference_v<InnerBase>;   // exposition only
+    Parent* parent_ = nullptr;                                          // exposition only
+    OuterIter outer_it_ = OuterIter();                          // exposition only, present only
+                                                                // if Base models forward_range
+    variant<PatternIter, InnerIter> inner_it_;                          // exposition only
+    constexpr iterator(Parent& parent, OuterIter outer)
+      requires forward_range<Base>;                                     // exposition only
+    constexpr explicit iterator(Parent& parent)
+      requires (!forward_range<Base>);                                  // exposition only
+    constexpr OuterIter& outer();                                       // exposition only
+    constexpr const OuterIter& outer() const;                           // exposition only
+    constexpr auto& update-inner();                                     // exposition only
+    constexpr auto& get-inner();                                        // exposition only
+    constexpr void satisfy();                                           // exposition only
+  public:
+    using iterator_concept = see below;
+    using iterator_category = see below;                                // not always present
+    using value_type = see below;
+    using difference_type = see below;
+    iterator() = default;
+    constexpr iterator(iterator<!Const> i)
+      requires Const && convertible_to<iterator_t<V>, OuterIter> &&
+               convertible_to<iterator_t<InnerRng>, InnerIter> &&
+               convertible_to<iterator_t<Pattern>, PatternIter>;
+    constexpr decltype(auto) operator*() const;
+    constexpr iterator& operator++();
+    constexpr void operator++(int);
+    constexpr iterator operator++(int)
+      requires ref-is-glvalue && forward_iterator<OuterIter> &&
+               forward_iterator<InnerIter>;
+    constexpr iterator& operator--()
+      requires ref-is-glvalue && bidirectional_range<Base> &&
+               bidirectional-common<InnerBase> && bidirectional-common<PatternBase>;
+    constexpr iterator operator--(int)
+      requires ref-is-glvalue && bidirectional_range<Base> &&
+               bidirectional-common<InnerBase> && bidirectional-common<PatternBase>;
+    friend constexpr bool operator==(const iterator& x, const iterator& y)
+      requires ref-is-glvalue && forward_range<Base> &&
+               equality_comparable<InnerIter>;
+    friend constexpr decltype(auto) iter_move(const iterator& x) {
+      using rvalue_reference = common_reference_t<
+        iter_rvalue_reference_t<InnerIter>,
+        iter_rvalue_reference_t<PatternIter>>;
+      return visit<rvalue_reference>(ranges::iter_move, x.inner_it_);
+    }
+    friend constexpr void iter_swap(const iterator& x, const iterator& y)
+      requires indirectly_swappable<InnerIter, PatternIter> {
+      visit(ranges::iter_swap, x.inner_it_, y.inner_it_);
+    }
+  };
+}
+```
+`iterator::iterator_concept` is defined as follows:
+- If *`ref-is-glvalue`* is `true`, *`Base`* models
+  `bidirectional_range`, and *`InnerBase`* and *`PatternBase`* each
+  model `bidirectional-common`, then `iterator_concept` denotes
+  `bidirectional_iterator_tag`.
+- Otherwise, if *`ref-is-glvalue`* is `true` and *`Base`* and
+  *`InnerBase`* each model `forward_range`, 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
+*`ref-is-glvalue`* is `true`, and *`Base`* and *`InnerBase`* each model
+`forward_range`. In that case, `iterator::iterator_category` is defined
+as follows:
+- Let *OUTERC* denote `iterator_traits<OuterIter>::iterator_category`,
+  let *INNERC* denote `iterator_traits<InnerIter>::iterator_category`,
+  and let *PATTERNC* denote
+  `iterator_-traits<PatternIter>::iterator_category`.
+- If
+  ``` cpp
+  is_reference_v<common_reference_t<iter_reference_t<InnerIter>,
+                                    iter_reference_t<PatternIter>>>
+  ```
+  is `false`, `iterator_category` denotes `input_iterator_tag`.
+- Otherwise, if *OUTERC*, *INNERC*, and *PATTERNC* each model
+  `derived_from<bidirectional_iterator_category>` and *`InnerBase`* and
+  *`PatternBase`* each model `common_range`, `iterator_category` denotes
+  `bidirectional_iterator_tag`.
+- Otherwise, if *OUTERC*, *INNERC*, and *PATTERNC* each model
+  `derived_from<forward_iterator_tag>`, `iterator_category` denotes
+  `forward_iterator_tag`.
+- Otherwise, `iterator_category` denotes `input_iterator_tag`.
+`iterator::value_type` denotes the type:
+``` cpp
+common_type_t<iter_value_t<InnerIter>, iter_value_t<PatternIter>>
+```
+`iterator::difference_type` denotes the type:
+``` cpp
+common_type_t<
+    iter_difference_t<OuterIter>,
+    iter_difference_t<InnerIter>,
+    iter_difference_t<PatternIter>>
+```
+``` cpp
+constexpr OuterIter& outer();
+constexpr const OuterIter& outer() const;
+```
+*Returns:* *outer_it\_* if *Base* models `forward_range`; otherwise,
+`*`*`parent_`*`->`*`outer_it_`*.
+``` cpp
+constexpr auto& update-inner();
+```
+*Effects:* Equivalent to:
+``` cpp
+if constexpr (ref-is-glvalue)
+  return as-lvalue(*outer());
+else
+  return parent_->inner_.emplace-deref(outer());
+```
+``` cpp
+constexpr auto& get-inner();
+```
+*Effects:* Equivalent to:
+``` cpp
+if constexpr (ref-is-glvalue)
+  return as-lvalue(*outer());
+else
+  return *parent_->inner_;
+```
+``` cpp
+constexpr void satisfy();
+```
+*Effects:* Equivalent to:
+``` cpp
+while (true) {
+  if (inner_it_.index() == 0) {
+    if (std::get<0>(inner_it_) != ranges::end(parent_->pattern_))
+      break;
+    inner_it_.emplace<1>(ranges::begin(update-inner()));
+  } else {
+    if (std::get<1>(inner_it_) != ranges::end(get-inner()))
+      break;
+    if (++outer() == ranges::end(parent_->base_)) {
+      if constexpr (ref-is-glvalue)
+        inner_it_.emplace<0>();
+      break;
+    }
+    inner_it_.emplace<0>(ranges::begin(parent_->pattern_));
+  }
+}
+```
+[*Note 1*: `join_with_view` iterators use the *satisfy* function to
+skip over empty inner ranges. — *end note*]
+``` cpp
+constexpr iterator(Parent& parent, OuterIter outer)
+  requires forward_range<Base>;
+constexpr explicit iterator(Parent& parent)
+  requires (!forward_range<Base>);
+```
+*Effects:* Initializes *parent\_* with `addressof(parent)`. For the
+first overload, also initializes *outer_it\_* with `std::move(outer)`.
+Then, equivalent to:
+``` cpp
+if (outer() != ranges::end(parent_->base_)) {
+  inner_it_.emplace<1>(ranges::begin(update-inner()));
+  satisfy();
+}
+```
+``` cpp
+constexpr iterator(iterator<!Const> i)
+    requires Const && convertible_to<iterator_t<V>, OuterIter> &&
+             convertible_to<iterator_t<InnerRng>, InnerIter> &&
+             convertible_to<iterator_t<Pattern>, PatternIter>;
+```
+*Effects:* Initializes *outer_it\_* with `std::move(i.`*`outer_it_`*`)`
+and *parent\_* with `i.`*`parent_`*. Then, equivalent to:
+``` cpp
+if (i.inner_it_.index() == 0)
+  inner_it_.emplace<0>(std::get<0>(std::move(i.inner_it_)));
+else
+  inner_it_.emplace<1>(std::get<1>(std::move(i.inner_it_)));
+```
+[*Note 2*: `Const` can only be `true` when *Base* models
+`forward_range`. — *end note*]
+``` cpp
+constexpr decltype(auto) operator*() const;
+```
+*Effects:* Equivalent to:
+``` cpp
+using reference =
+  common_reference_t<iter_reference_t<InnerIter>, iter_reference_t<PatternIter>>;
+return visit([](auto& it) -> reference { return *it; }, inner_it_);
+```
+``` cpp
+constexpr iterator& operator++();
+```
+*Effects:* Equivalent to:
+``` cpp
+visit([](auto& it){ ++it; }, inner_it_);
+satisfy();
+return *this;
+```
+``` cpp
+constexpr void operator++(int);
+```
+*Effects:* Equivalent to `++*this`.
+``` cpp
+constexpr iterator operator++(int)
+  requires ref-is-glvalue && forward_iterator<OuterIter> && forward_iterator<InnerIter>;
+```
+*Effects:* Equivalent to:
+``` cpp
+iterator tmp = *this;
+++*this;
+return tmp;
+```
+``` cpp
+constexpr iterator& operator--()
+  requires ref-is-glvalue && bidirectional_range<Base> &&
+           bidirectional-common<InnerBase> && bidirectional-common<PatternBase>;
+```
+*Effects:* Equivalent to:
+``` cpp
+if (outer_it_ == ranges::end(parent_->base_)) {
+  auto&& inner = *--outer_it_;
+  inner_it_.emplace<1>(ranges::end(inner));
+}
+while (true) {
+  if (inner_it_.index() == 0) {
+    auto& it = std::get<0>(inner_it_);
+    if (it == ranges::begin(parent_->pattern_)) {
+      auto&& inner = *--outer_it_;
+      inner_it_.emplace<1>(ranges::end(inner));
+    } else {
+      break;
+    }
+  } else {
+    auto& it = std::get<1>(inner_it_);
+    auto&& inner = *outer_it_;
+    if (it == ranges::begin(inner)) {
+      inner_it_.emplace<0>(ranges::end(parent_->pattern_));
+    } else {
+      break;
+    }
+  }
+}
+visit([](auto& it){ --it; }, inner_it_);
+return *this;
+```
+``` cpp
+constexpr iterator operator--(int)
+  requires ref-is-glvalue && bidirectional_range<Base> &&
+           bidirectional-common<InnerBase> && bidirectional-common<PatternBase>;
+```
+*Effects:* Equivalent to:
+``` cpp
+iterator tmp = *this;
+--*this;
+return tmp;
+```
+``` cpp
+friend constexpr bool operator==(const iterator& x, const iterator& y)
+  requires ref-is-glvalue && forward_range<Base> &&
+           equality_comparable<InnerIter>;
+```
+*Effects:* Equivalent to:
+``` cpp
+return x.outer_it_ == y.outer_it_ && x.inner_it_ == y.inner_it_;
+```
+#### Class template `join_with_view::sentinel` <a id="range.join.with.sentinel">[[range.join.with.sentinel]]</a>
+``` cpp
+namespace std::ranges {
+  template<input_range V, forward_range Pattern>
+    requires view<V> && input_range<range_reference_t<V>>
+          && view<Pattern> && compatible-joinable-ranges<range_reference_t<V>, Pattern>
+  template<bool Const>
+  class join_with_view<V, Pattern>::sentinel {
+    using Parent = maybe-const<Const, join_with_view>;  // exposition only
+    using Base = maybe-const<Const, V>;                 // exposition only
+    sentinel_t<Base> end_ = sentinel_t<Base>();         // exposition only
+    constexpr explicit sentinel(Parent& parent);        // exposition only
+  public:
+    sentinel() = default;
+    constexpr sentinel(sentinel<!Const> s)
+      requires Const && convertible_to<sentinel_t<V>, sentinel_t<Base>>;
+    template<bool OtherConst>
+      requires sentinel_for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>>
+    friend constexpr bool operator==(const iterator<OtherConst>& x, const sentinel& y);
+  };
+}
+```
+``` cpp
+constexpr explicit sentinel(Parent& parent);
+```
+*Effects:* Initializes *end\_* with `ranges::end(parent.`*`base_`*`)`.
+``` cpp
+constexpr sentinel(sentinel<!Const> s)
+  requires Const && convertible_to<sentinel_t<V>, sentinel_t<Base>>;
+```
+*Effects:* Initializes *end\_* with `std::move(s.`*`end_`*`)`.
+``` cpp
+template<bool OtherConst>
+  requires sentinel_for<sentinel_t<Base>, iterator_t<maybe-const<OtherConst, V>>>
+friend constexpr bool operator==(const iterator<OtherConst>& x, const sentinel& y);
+```
+*Effects:* Equivalent to: `return x.`*`outer`*`() == y.`*`end_`*`;`

Diff to HTML by rtfpessoa