[range.utility.conv] - C++20 → C++23

Files changed (1) hide show

tmp/tmpb12u7kn7/{from.md → to.md} +174 -0

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

	@@ -0,0 +1,174 @@

+### Range conversions <a id="range.utility.conv">[[range.utility.conv]]</a>
+#### General <a id="range.utility.conv.general">[[range.utility.conv.general]]</a>
+The range conversion functions construct an object (usually a container)
+from a range, by using a constructor taking a range, a `from_range_t`
+tagged constructor, or a constructor taking a pair of iterators, or by
+inserting each element of the range into the default-constructed object.
+`ranges::to` is applied recursively, allowing the conversion of a range
+of ranges.
+[*Example 1*:
+``` cpp
+string_view str = "the quick brown fox";
+auto words = views::split(str, ' ') | to<vector<string>>();
+// words is vector<string>{"the", "quick", "brown", "fox"}
+```
+— *end example*]
+Let *`reservable-container`* be defined as follows:
+``` cpp
+template<class Container>
+constexpr bool reservable-container =          // exposition only
+  sized_range<Container> &&
+  requires(Container& c, range_size_t<Container> n) {
+    c.reserve(n);
+    { c.capacity() } -> same_as<decltype(n)>;
+    { c.max_size() } -> same_as<decltype(n)>;
+  };
+```
+Let *`container-insertable`* be defined as follows:
+``` cpp
+template<class Container, class Ref>
+constexpr bool container-insertable =          // exposition only
+  requires(Container& c, Ref&& ref) {
+    requires (requires { c.push_back(std::forward<Ref>(ref)); } ||
+              requires { c.insert(c.end(), std::forward<Ref>(ref)); });
+  };
+```
+Let *`container-inserter`* be defined as follows:
+``` cpp
+template<class Ref, class Container>
+constexpr auto container-inserter(Container& c) {                // exposition only
+  if constexpr (requires { c.push_back(declval<Ref>()); })
+    return back_inserter(c);
+  else
+    return inserter(c, c.end());
+}
+```
+#### `ranges::to` <a id="range.utility.conv.to">[[range.utility.conv.to]]</a>
+``` cpp
+template<class C, input_range R, class... Args> requires (!view<C>)
+  constexpr C to(R&& r, Args&&... args);
+```
+*Mandates:* `C` is a cv-unqualified class type.
+*Returns:* An object of type `C` constructed from the elements of `r` in
+the following manner:
+- If `C` does not satisfy `input_range` or
+  `convertible_to<range_reference_t<R>, range_value_t<C>>` is `true`:
+  - If `constructible_from<C, R, Args...>` is `true`:
+    ``` cpp
+    C(std::forward<R>(r), std::forward<Args>(args)...)
+    ```
+  - Otherwise, if `constructible_from<C, from_range_t, R, Args...>` is
+    `true`:
+    ``` cpp
+    C(from_range, std::forward<R>(r), std::forward<Args>(args)...)
+    ```
+  - Otherwise, if
+    - `common_range<R>` is `true`,
+    - the *qualified-id*
+      `iterator_traits<iterator_t<R>>::iterator_category` is valid and
+      denotes a type that models `derived_from<input_iterator_tag>`, and
+    - `constructible_from<C, iterator_t<R>, sentinel_t<R>, Args...>` is
+      `true`:
+    ``` cpp
+    C(ranges::begin(r), ranges::end(r), std::forward<Args>(args)...)
+    ```
+  - Otherwise, if
+    - `constructible_from<C, Args...>` is `true`, and
+    - *`container-insertable`*`<C, range_reference_t<R>>` is `true`:
+    ``` cpp
+    C c(std::forward<Args>(args)...);
+    if constexpr (sized_range<R> && reservable-container<C>)
+      c.reserve(static_cast<range_size_t<C>>(ranges::size(r)));
+    ranges::copy(r, container-inserter<range_reference_t<R>>(c));
+    ```
+- Otherwise, if `input_range<range_reference_t<R>>` is `true`:
+  ``` cpp
+  to<C>(r | views::transform([](auto&& elem) {
+    return to<range_value_t<C>>(std::forward<decltype(elem)>(elem));
+  }), std::forward<Args>(args)...);
+  ```
+- Otherwise, the program is ill-formed.
+``` cpp
+template<template<class...> class C, input_range R, class... Args>
+  constexpr auto to(R&& r, Args&&... args);
+```
+Let *input-iterator* be an exposition-only type:
+``` cpp
+struct input-iterator {                        // exposition only
+  using iterator_category = input_iterator_tag;
+  using value_type = range_value_t<R>;
+  using difference_type = ptrdiff_t;
+  using pointer = add_pointer_t<range_reference_t<R>>;
+  using reference = range_reference_t<R>;
+  reference operator*() const;
+  pointer operator->() const;
+  input-iterator& operator++();
+  input-iterator operator++(int);
+  bool operator==(const input-iterator&) const;
+};
+```
+[*Note 1*: *input-iterator* meets the syntactic requirements of
+*Cpp17InputIterator*. — *end note*]
+Let *`DEDUCE_EXPR`* be defined as follows:
+- `C(declval<R>(), declval<Args>()...)` if that is a valid expression,
+- otherwise, `C(from_range, declval<R>(), declval<Args>()...)` if that
+  is a valid expression,
+- otherwise,
+  ``` cpp
+  C(declval<input-iterator>(), declval<input-iterator>(), declval<Args>()...)
+  ```
+  if that is a valid expression,
+- otherwise, the program is ill-formed.
+*Returns:*
+`to<decltype(`*`DEDUCE_EXPR`*`)>(std::forward<R>(r), std::forward<Args>(args)...)`.
+#### `ranges::to` adaptors <a id="range.utility.conv.adaptors">[[range.utility.conv.adaptors]]</a>
+``` cpp
+template<class C, class... Args> requires (!view<C>)
+  constexpr auto to(Args&&... args);
+template<template<class...> class C, class... Args>
+  constexpr auto to(Args&&... args);
+```
+*Mandates:* For the first overload, `C` is a cv-unqualified class type.
+*Returns:* A range adaptor closure object [[range.adaptor.object]] `f`
+that is a perfect forwarding call
+wrapper [[term.perfect.forwarding.call.wrapper]] with the following
+properties:
+- It has no target object.
+- Its bound argument entities `bound_args` consist of objects of types
+  `decay_t<Args>...` direct-non-list-initialized with
+  `std::forward<Args>(args)...`, respectively.
+- Its call pattern is `to<C>(r, bound_args...)`, where `r` is the
+  argument used in a function call expression of `f`.

Diff to HTML by rtfpessoa