[range.factories] - C++17 → C++20

Files changed (1) hide show

tmp/tmp39f0s42m/{from.md → to.md} +812 -0

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

	@@ -0,0 +1,812 @@

+## Range factories <a id="range.factories">[[range.factories]]</a>
+This subclause defines *range factories*, which are utilities to create
+a `view`.
+Range factories are declared in namespace `std::ranges::views`.
+### Empty view <a id="range.empty">[[range.empty]]</a>
+#### Overview <a id="range.empty.overview">[[range.empty.overview]]</a>
+`empty_view` produces a `view` of no elements of a particular type.
+[*Example 1*:
+``` cpp
+empty_view<int> e;
+static_assert(ranges::empty(e));
+static_assert(0 == e.size());
+```
+— *end example*]
+#### Class template `empty_view` <a id="range.empty.view">[[range.empty.view]]</a>
+``` cpp
+namespace std::ranges {
+  template<class T>
+    requires is_object_v<T>
+  class empty_view : public view_interface<empty_view<T>> {
+  public:
+    static constexpr T* begin() noexcept { return nullptr; }
+    static constexpr T* end() noexcept { return nullptr; }
+    static constexpr T* data() noexcept { return nullptr; }
+    static constexpr size_t size() noexcept { return 0; }
+    static constexpr bool empty() noexcept { return true; }
+  };
+}
+```
+### Single view <a id="range.single">[[range.single]]</a>
+#### Overview <a id="range.single.overview">[[range.single.overview]]</a>
+`single_view` produces a `view` that contains exactly one element of a
+specified value.
+The name `views::single` denotes a customization point object
+[[customization.point.object]]. Given a subexpression `E`, the
+expression `views::single(E)` is expression-equivalent to
+`single_view{E}`.
+[*Example 1*:
+``` cpp
+single_view s{4};
+for (int i : s)
+  cout << i;        // prints 4
+```
+— *end example*]
+#### Class template `single_view` <a id="range.single.view">[[range.single.view]]</a>
+``` cpp
+namespace std::ranges {
+  template<copy_constructible T>
+    requires is_object_v<T>
+  class single_view : public view_interface<single_view<T>> {
+  private:
+    semiregular-box<T> value_;      // exposition only{} (see [range.semi.wrap])
+  public:
+    single_view() = default;
+    constexpr explicit single_view(const T& t);
+    constexpr explicit single_view(T&& t);
+    template<class... Args>
+      requires constructible_from<T, Args...>
+    constexpr single_view(in_place_t, Args&&... args);
+    constexpr T* begin() noexcept;
+    constexpr const T* begin() const noexcept;
+    constexpr T* end() noexcept;
+    constexpr const T* end() const noexcept;
+    static constexpr size_t size() noexcept;
+    constexpr T* data() noexcept;
+    constexpr const T* data() const noexcept;
+  };
+}
+```
+``` cpp
+constexpr explicit single_view(const T& t);
+```
+*Effects:* Initializes *value\_* with `t`.
+``` cpp
+constexpr explicit single_view(T&& t);
+```
+*Effects:* Initializes *value\_* with `std::move(t)`.
+``` cpp
+template<class... Args>
+constexpr single_view(in_place_t, Args&&... args);
+```
+*Effects:* Initializes *value\_* as if by
+*`value_`*`{in_place, std::forward<Args>(args)...}`.
+``` cpp
+constexpr T* begin() noexcept;
+constexpr const T* begin() const noexcept;
+```
+*Effects:* Equivalent to: `return data();`
+``` cpp
+constexpr T* end() noexcept;
+constexpr const T* end() const noexcept;
+```
+*Effects:* Equivalent to: `return data() + 1;`
+``` cpp
+static constexpr size_t size() noexcept;
+```
+*Effects:* Equivalent to: `return 1;`
+``` cpp
+constexpr T* data() noexcept;
+constexpr const T* data() const noexcept;
+```
+*Effects:* Equivalent to: `return `*`value_`*`.operator->();`
+### Iota view <a id="range.iota">[[range.iota]]</a>
+#### Overview <a id="range.iota.overview">[[range.iota.overview]]</a>
+`iota_view` generates a sequence of elements by repeatedly incrementing
+an initial value.
+The name `views::iota` denotes a customization point object
+[[customization.point.object]]. Given subexpressions `E` and `F`, the
+expressions `views::iota(E)` and `views::iota(E, F)` are
+expression-equivalent to `iota_view{E}` and `iota_view{E, F}`,
+respectively.
+[*Example 1*:
+``` cpp
+for (int i : iota_view{1, 10})
+  cout << i << ' '; // prints: 1 2 3 4 5 6 7 8 9
+```
+— *end example*]
+#### Class template `iota_view` <a id="range.iota.view">[[range.iota.view]]</a>
+``` cpp
+namespace std::ranges {
+  template<class I>
+    concept decrementable =     // exposition only
+      see below;
+  template<class I>
+    concept advanceable =       // exposition only
+      see below;
+  template<weakly_incrementable W, semiregular Bound = unreachable_sentinel_t>
+    requires weakly-equality-comparable-with<W, Bound> && semiregular<W>
+  class iota_view : public view_interface<iota_view<W, Bound>> {
+  private:
+    // [range.iota.iterator], class iota_view::iterator
+    struct iterator;            // exposition only
+    // [range.iota.sentinel], class iota_view::sentinel
+    struct sentinel;            // exposition only
+    W value_ = W();             // exposition only
+    Bound bound_ = Bound();     // exposition only
+  public:
+    iota_view() = default;
+    constexpr explicit iota_view(W value);
+    constexpr iota_view(type_identity_t<W> value,
+                        type_identity_t<Bound> bound);
+    constexpr iota_view(iterator first, sentinel last) : iota_view(*first, last.bound_) {}
+    constexpr iterator begin() const;
+    constexpr auto end() const;
+    constexpr iterator end() const requires same_as<W, Bound>;
+    constexpr auto size() const requires see below;
+  };
+  template<class W, class Bound>
+    requires (!is-integer-like<W> || !is-integer-like<Bound> ||
+              (is-signed-integer-like<W> == is-signed-integer-like<Bound>))
+    iota_view(W, Bound) -> iota_view<W, Bound>;
+}
+```
+Let `IOTA-DIFF-T(W)` be defined as follows:
+- If `W` is not an integral type, or if it is an integral type and
+  `sizeof(iter_difference_t<W>)` is greater than `sizeof(W)`, then
+  `IOTA-DIFF-T(W)` denotes `iter_difference_t<W>`.
+- Otherwise, `IOTA-DIFF-T(W)` is a signed integer type of width greater
+  than the width of `W` if such a type exists.
+- Otherwise, `IOTA-DIFF-T(W)` is an unspecified signed-integer-like type
+  [[iterator.concept.winc]] of width not less than the width of `W`.
+  \[*Note 1*: It is unspecified whether this type satisfies
+  `weakly_incrementable`. — *end note*]
+The exposition-only *decrementable* concept is equivalent to:
+``` cpp
+template<class I>
+  concept decrementable =
+    incrementable<I> && requires(I i) {
+      { --i } -> same_as<I&>;
+      { i-- } -> same_as<I>;
+    };
+```
+When an object is in the domain of both pre- and post-decrement, the
+object is said to be *decrementable*.
+Let `a` and `b` be equal objects of type `I`. `I` models `decrementable`
+only if
+- If `a` and `b` are decrementable, then the following are all true:
+  - `addressof(–a) == addressof(a)`
+  - `bool(a– == b)`
+  - `bool(((void)a–, a) == –b)`
+  - `bool(++(–a) == b)`.
+- If `a` and `b` are incrementable, then `bool(–(++a) == b)`.
+The exposition-only *advanceable* concept is equivalent to:
+``` cpp
+template<class I>
+  concept advanceable =
+    decrementable<I> && totally_ordered<I> &&
+    requires(I i, const I j, const IOTA-DIFF-T(I) n) {
+      { i += n } -> same_as<I&>;
+      { i -= n } -> same_as<I&>;
+      I(j + n);
+      I(n + j);
+      I(j - n);
+      { j - j } -> convertible_to<IOTA-DIFF-T(I)>;
+    };
+```
+Let `D` be `IOTA-DIFF-T(I)`. Let `a` and `b` be objects of type `I` such
+that `b` is reachable from `a` after `n` applications of `++a`, for some
+value `n` of type `D`. `I` models `advanceable` only if
+- `(a += n)` is equal to `b`.
+- `addressof(a += n)` is equal to `addressof(a)`.
+- `I(a + n)` is equal to `(a += n)`.
+- For any two positive values `x` and `y` of type `D`, if
+  `I(a + D(x + y))` is well-defined, then `I(a + D(x + y))` is equal to
+  `I(I(a + x) + y)`.
+- `I(a + D(0))` is equal to `a`.
+- If `I(a + D(n - 1))` is well-defined, then `I(a + n)` is equal to
+  `[](I c) { return ++c; }(I(a + D(n - 1)))`.
+- `(b += -n)` is equal to `a`.
+- `(b -= n)` is equal to `a`.
+- `addressof(b -= n)` is equal to `addressof(b)`.
+- `I(b - n)` is equal to `(b -= n)`.
+- `D(b - a)` is equal to `n`.
+- `D(a - b)` is equal to `D(-n)`.
+- `bool(a <= b)` is `true`.
+``` cpp
+constexpr explicit iota_view(W value);
+```
+*Preconditions:* `Bound` denotes `unreachable_sentinel_t` or `Bound()`
+is reachable from `value`.
+*Effects:* Initializes *value\_* with `value`.
+``` cpp
+constexpr iota_view(type_identity_t<W> value, type_identity_t<Bound> bound);
+```
+*Preconditions:* `Bound` denotes `unreachable_sentinel_t` or `bound` is
+reachable from `value`. When `W` and `Bound` model
+`totally_ordered_with`, then `bool(value <= bound)` is `true`.
+*Effects:* Initializes *value\_* with `value` and *bound\_* with
+`bound`.
+``` cpp
+constexpr iterator begin() const;
+```
+*Effects:* Equivalent to: `return iterator{`*`value_`*`};`
+``` cpp
+constexpr auto end() const;
+```
+*Effects:* Equivalent to:
+``` cpp
+if constexpr (same_as<Bound, unreachable_sentinel_t>)
+  return unreachable_sentinel;
+else
+  return sentinel{bound_};
+```
+``` cpp
+constexpr iterator end() const requires same_as<W, Bound>;
+```
+*Effects:* Equivalent to: `return iterator{bound_};`
+``` cpp
+constexpr auto size() const requires see below;
+```
+*Effects:* Equivalent to:
+``` cpp
+if constexpr (is-integer-like<W> && is-integer-like<Bound>)
+  return (value_ < 0)
+    ? ((bound_ < 0)
+      ? to-unsigned-like(-value_) - to-unsigned-like(-bound_)
+      : to-unsigned-like(bound_) + to-unsigned-like(-value_))
+    : to-unsigned-like(bound_) - to-unsigned-like(value_);
+else
+  return to-unsigned-like(bound_ - value_);
+```
+*Remarks:* The expression in the *requires-clause* is equivalent to
+``` cpp
+(same_as<W, Bound> && advanceable<W>) || (integral<W> && integral<Bound>) ||
+  sized_sentinel_for<Bound, W>
+```
+#### Class `iota_view::iterator` <a id="range.iota.iterator">[[range.iota.iterator]]</a>
+``` cpp
+namespace std::ranges {
+  template<weakly_incrementable W, semiregular Bound>
+    requires weakly-equality-comparable-with<W, Bound>
+  struct iota_view<W, Bound>::iterator {
+  private:
+    W value_ = W();             // exposition only
+  public:
+    using iterator_concept = see below;
+    using iterator_category = input_iterator_tag;
+    using value_type = W;
+    using difference_type = IOTA-DIFF-T(W);
+    iterator() = default;
+    constexpr explicit iterator(W value);
+    constexpr W operator*() const noexcept(is_nothrow_copy_constructible_v<W>);
+    constexpr iterator& operator++();
+    constexpr void operator++(int);
+    constexpr iterator operator++(int) requires incrementable<W>;
+    constexpr iterator& operator--() requires decrementable<W>;
+    constexpr iterator operator--(int) requires decrementable<W>;
+    constexpr iterator& operator+=(difference_type n)
+      requires advanceable<W>;
+    constexpr iterator& operator-=(difference_type n)
+      requires advanceable<W>;
+    constexpr W operator[](difference_type n) const
+      requires advanceable<W>;
+    friend constexpr bool operator==(const iterator& x, const iterator& y)
+      requires equality_comparable<W>;
+    friend constexpr bool operator<(const iterator& x, const iterator& y)
+      requires totally_ordered<W>;
+    friend constexpr bool operator>(const iterator& x, const iterator& y)
+      requires totally_ordered<W>;
+    friend constexpr bool operator<=(const iterator& x, const iterator& y)
+      requires totally_ordered<W>;
+    friend constexpr bool operator>=(const iterator& x, const iterator& y)
+      requires totally_ordered<W>;
+    friend constexpr auto operator<=>(const iterator& x, const iterator& y)
+      requires totally_ordered<W> && three_way_comparable<W>;
+    friend constexpr iterator operator+(iterator i, difference_type n)
+      requires advanceable<W>;
+    friend constexpr iterator operator+(difference_type n, iterator i)
+      requires advanceable<W>;
+    friend constexpr iterator operator-(iterator i, difference_type n)
+      requires advanceable<W>;
+    friend constexpr difference_type operator-(const iterator& x, const iterator& y)
+      requires advanceable<W>;
+  };
+}
+```
+`iterator::iterator_concept` is defined as follows:
+- If `W` models `advanceable`, then `iterator_concept` is
+  `random_access_iterator_tag`.
+- Otherwise, if `W` models `decrementable`, then `iterator_concept` is
+  `bidirectional_iterator_tag`.
+- Otherwise, if `W` models `incrementable`, then `iterator_concept` is
+  `forward_iterator_tag`.
+- Otherwise, `iterator_concept` is `input_iterator_tag`.
+[*Note 1*: Overloads for `iter_move` and `iter_swap` are omitted
+intentionally. — *end note*]
+``` cpp
+constexpr explicit iterator(W value);
+```
+*Effects:* Initializes *value\_* with `value`.
+``` cpp
+constexpr W operator*() const noexcept(is_nothrow_copy_constructible_v<W>);
+```
+*Effects:* Equivalent to: `return `*`value_`*`;`
+[*Note 1*: The `noexcept` clause is needed by the default `iter_move`
+implementation. — *end note*]
+``` cpp
+constexpr iterator& operator++();
+```
+*Effects:* Equivalent to:
+``` cpp
+++value_;
+return *this;
+```
+``` cpp
+constexpr void operator++(int);
+```
+*Effects:* Equivalent to `++*this`.
+``` cpp
+constexpr iterator operator++(int) requires incrementable<W>;
+```
+*Effects:* Equivalent to:
+``` cpp
+auto tmp = *this;
+++*this;
+return tmp;
+```
+``` cpp
+constexpr iterator& operator--() requires decrementable<W>;
+```
+*Effects:* Equivalent to:
+``` cpp
+--value_;
+return *this;
+```
+``` cpp
+constexpr iterator operator--(int) requires decrementable<W>;
+```
+*Effects:* Equivalent to:
+``` cpp
+auto tmp = *this;
+--*this;
+return tmp;
+```
+``` cpp
+constexpr iterator& operator+=(difference_type n)
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to:
+``` cpp
+if constexpr (is-integer-like<W> && !is-signed-integer-like<W>) {
+  if (n >= difference_type(0))
+    value_ += static_cast<W>(n);
+  else
+    value_ -= static_cast<W>(-n);
+} else {
+  value_ += n;
+}
+return *this;
+```
+``` cpp
+constexpr iterator& operator-=(difference_type n)
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to:
+``` cpp
+if constexpr (is-integer-like<W> && !is-signed-integer-like<W>) {
+  if (n >= difference_type(0))
+    value_ -= static_cast<W>(n);
+  else
+    value_ += static_cast<W>(-n);
+} else {
+  value_ -= n;
+}
+return *this;
+```
+``` cpp
+constexpr W operator[](difference_type n) const
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to: `return W(`*`value_`*` + n);`
+``` cpp
+friend constexpr bool operator==(const iterator& x, const iterator& y)
+  requires equality_comparable<W>;
+```
+*Effects:* Equivalent to: `return x.`*`value_`*` == y.`*`value_`*`;`
+``` cpp
+friend constexpr bool operator<(const iterator& x, const iterator& y)
+  requires totally_ordered<W>;
+```
+*Effects:* Equivalent to: `return x.`*`value_`*` < y.`*`value_`*`;`
+``` cpp
+friend constexpr bool operator>(const iterator& x, const iterator& y)
+  requires totally_ordered<W>;
+```
+*Effects:* Equivalent to: `return y < x;`
+``` cpp
+friend constexpr bool operator<=(const iterator& x, const iterator& y)
+  requires totally_ordered<W>;
+```
+*Effects:* Equivalent to: `return !(y < x);`
+``` cpp
+friend constexpr bool operator>=(const iterator& x, const iterator& y)
+  requires totally_ordered<W>;
+```
+*Effects:* Equivalent to: `return !(x < y);`
+``` cpp
+friend constexpr auto operator<=>(const iterator& x, const iterator& y)
+  requires totally_ordered<W> && three_way_comparable<W>;
+```
+*Effects:* Equivalent to: `return x.`*`value_`*` <=> y.`*`value_`*`;`
+``` cpp
+friend constexpr iterator operator+(iterator i, difference_type n)
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to: `return i += n;`
+``` cpp
+friend constexpr iterator operator+(difference_type n, iterator i)
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to: `return i + n;`
+``` cpp
+friend constexpr iterator operator-(iterator i, difference_type n)
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to: `return i -= n;`
+``` cpp
+friend constexpr difference_type operator-(const iterator& x, const iterator& y)
+  requires advanceable<W>;
+```
+*Effects:* Equivalent to:
+``` cpp
+using D = difference_type;
+if constexpr (is-integer-like<W>) {
+  if constexpr (is-signed-integer-like<W>)
+    return D(D(x.value_) - D(y.value_));
+  else
+    return (y.value_ > x.value_)
+      ? D(-D(y.value_ - x.value_))
+      : D(x.value_ - y.value_);
+} else {
+  return x.value_ - y.value_;
+}
+```
+#### Class `iota_view::sentinel` <a id="range.iota.sentinel">[[range.iota.sentinel]]</a>
+``` cpp
+namespace std::ranges {
+  template<weakly_incrementable W, semiregular Bound>
+    requires weakly-equality-comparable-with<W, Bound>
+  struct iota_view<W, Bound>::sentinel {
+  private:
+    Bound bound_ = Bound();     // exposition only
+  public:
+    sentinel() = default;
+    constexpr explicit sentinel(Bound bound);
+    friend constexpr bool operator==(const iterator& x, const sentinel& y);
+    friend constexpr iter_difference_t<W> operator-(const iterator& x, const sentinel& y)
+      requires sized_sentinel_for<Bound, W>;
+    friend constexpr iter_difference_t<W> operator-(const sentinel& x, const iterator& y)
+      requires sized_sentinel_for<Bound, W>;
+  };
+}
+```
+``` cpp
+constexpr explicit sentinel(Bound bound);
+```
+*Effects:* Initializes *bound\_* with `bound`.
+``` cpp
+friend constexpr bool operator==(const iterator& x, const sentinel& y);
+```
+*Effects:* Equivalent to: `return x.`*`value_`*` == y.`*`bound_`*`;`
+``` cpp
+friend constexpr iter_difference_t<W> operator-(const iterator& x, const sentinel& y)
+  requires sized_sentinel_for<Bound, W>;
+```
+*Effects:* Equivalent to: `return x.`*`value_`*` - y.`*`bound_`*`;`
+``` cpp
+friend constexpr iter_difference_t<W> operator-(const sentinel& x, const iterator& y)
+  requires sized_sentinel_for<Bound, W>;
+```
+*Effects:* Equivalent to: `return -(y - x);`
+### Istream view <a id="range.istream">[[range.istream]]</a>
+#### Overview <a id="range.istream.overview">[[range.istream.overview]]</a>
+`basic_istream_view` models `input_range` and reads (using `operator>>`)
+successive elements from its corresponding input stream.
+[*Example 1*:
+``` cpp
+auto ints = istringstream{"0 1  2   3     4"};
+ranges::copy(istream_view<int>(ints), ostream_iterator<int>{cout, "-"});
+// prints 0-1-2-3-4-
+```
+— *end example*]
+#### Class template `basic_istream_view` <a id="range.istream.view">[[range.istream.view]]</a>
+``` cpp
+namespace std::ranges {
+  template<class Val, class CharT, class Traits>
+    concept stream-extractable =                // exposition only
+      requires(basic_istream<CharT, Traits>& is, Val& t) {
+         is >> t;
+      };
+  template<movable Val, class CharT, class Traits>
+    requires default_initializable<Val> &&
+             stream-extractable<Val, CharT, Traits>
+  class basic_istream_view : public view_interface<basic_istream_view<Val, CharT, Traits>> {
+  public:
+    basic_istream_view() = default;
+    constexpr explicit basic_istream_view(basic_istream<CharT, Traits>& stream);
+    constexpr auto begin()
+    {
+      if (stream_) {
+        *stream_ >> object_;
+      }
+      return iterator{*this};
+    }
+    constexpr default_sentinel_t end() const noexcept;
+  private:
+    struct iterator;                                    // exposition only
+    basic_istream<CharT, Traits>* stream_ = nullptr;    // exposition only
+    Val object_ = Val();                                // exposition only
+  };
+}
+```
+``` cpp
+constexpr explicit basic_istream_view(basic_istream<CharT, Traits>& stream);
+```
+*Effects:* Initializes *stream\_* with `addressof(stream)`.
+``` cpp
+constexpr default_sentinel_t end() const noexcept;
+```
+*Effects:* Equivalent to: `return default_sentinel;`
+``` cpp
+template<class Val, class CharT, class Traits>
+basic_istream_view<Val, CharT, Traits> istream_view(basic_istream<CharT, Traits>& s);
+```
+*Effects:* Equivalent to:
+`return basic_istream_view<Val, CharT, Traits>{s};`
+#### Class template `basic_istream_view::iterator` <a id="range.istream.iterator">[[range.istream.iterator]]</a>
+``` cpp
+namespace std::ranges {
+  template<movable Val, class CharT, class Traits>
+    requires default_initializable<Val> &&
+             stream-extractable<Val, CharT, Traits>
+  class basic_istream_view<Val, CharT, Traits>::iterator {      // exposition only
+  public:
+    using iterator_concept = input_iterator_tag;
+    using difference_type = ptrdiff_t;
+    using value_type = Val;
+    iterator() = default;
+    constexpr explicit iterator(basic_istream_view& parent) noexcept;
+    iterator(const iterator&) = delete;
+    iterator(iterator&&) = default;
+    iterator& operator=(const iterator&) = delete;
+    iterator& operator=(iterator&&) = default;
+    iterator& operator++();
+    void operator++(int);
+    Val& operator*() const;
+    friend bool operator==(const iterator& x, default_sentinel_t);
+  private:
+    basic_istream_view* parent_ = nullptr;                      // exposition only
+  };
+}
+```
+``` cpp
+constexpr explicit iterator(basic_istream_view& parent) noexcept;
+```
+*Effects:* Initializes *parent\_* with `addressof(parent)`.
+``` cpp
+iterator& operator++();
+```
+*Preconditions:* *`parent_`*`->`*`stream_`*` != nullptr` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+*parent_->stream_>> parent_->object_;
+return *this;
+```
+``` cpp
+void operator++(int);
+```
+*Preconditions:* *`parent_`*`->`*`stream_`*` != nullptr` is `true`.
+*Effects:* Equivalent to `++*this`.
+``` cpp
+Val& operator*() const;
+```
+*Preconditions:* *`parent_`*`->`*`stream_`*` != nullptr` is `true`.
+*Effects:* Equivalent to: `return `*`parent_`*`->`*`object_`*`;`
+``` cpp
+friend bool operator==(const iterator& x, default_sentinel_t);
+```
+*Effects:* Equivalent to:
+`return x.`*`parent_`*` == nullptr || !*x.`*`parent_`*`->`*`stream_`*`;`

Diff to HTML by rtfpessoa