[utility] - C++20 → C++23

Files changed (1) hide show

tmp/tmps27t5hpw/{from.md → to.md} +130 -19

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

@@ -4,10 +4,11 @@
 The header `<utility>` contains some basic function and class templates
 that are used throughout the rest of the library.
 ``` cpp
 #include <compare>              // see [compare.syn]
 #include <initializer_list>     // see [initializer.list.syn]
 namespace std {
   // [utility.swap], swap
@@ -16,17 +17,19 @@ namespace std {
   template<class T, size_t N>
     constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);
   // [utility.exchange], exchange
   template<class T, class U = T>
-    constexpr T exchange(T& obj, U&& new_val);
   // [forward], forward/move
   template<class T>
     constexpr T&& forward(remove_reference_t<T>& t) noexcept;
   template<class T>
     constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
   template<class T>
     constexpr remove_reference_t<T>&& move(T&&) noexcept;
   template<class T>
     constexpr conditional_t<
         !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>
@@ -58,10 +61,17 @@ namespace std {
     constexpr bool cmp_greater_equal(T t, U u) noexcept;
   template<class R, class T>
     constexpr bool in_range(T t) noexcept;
   // [intseq], compile-time integer sequences%
 %
 %
   template<class T, T...>
@@ -79,20 +89,38 @@ namespace std {
   // [pairs], class template pair
   template<class T1, class T2>
     struct pair;
   // [pairs.spec], pair specialized algorithms
-  template<class T1, class T2>
-    constexpr bool operator==(const pair<T1, T2>&, const pair<T1, T2>&);
-  template<class T1, class T2>
-    constexpr common_comparison_category_t<synth-three-way-result<T1>,
-                                           synth-three-way-result<T2>>
-      operator<=>(const pair<T1, T2>&, const pair<T1, T2>&);
   template<class T1, class T2>
     constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
   template<class T1, class T2>
     constexpr see below make_pair(T1&&, T2&&);
   // [pair.astuple], tuple-like access to pair
@@ -148,17 +176,17 @@ namespace std {
   template<class T>
     struct in_place_type_t {
       explicit in_place_type_t() = default;
     };
-  template<class T> inline constexpr in_place_type_t<T> in_place_type{};
   template<size_t I>
     struct in_place_index_t {
       explicit in_place_index_t() = default;
     };
-  template<size_t I> inline constexpr in_place_index_t<I> in_place_index{};
 }
 ```
 ### `swap` <a id="utility.swap">[[utility.swap]]</a>
@@ -174,13 +202,11 @@ template<class T>
 ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
 ([[cpp17.moveassignable]]) requirements.
 *Effects:* Exchanges values stored in two locations.
-*Remarks:* This function is a designated customization
-point [[namespace.std]]. The expression inside `noexcept` is equivalent
-to:
 ``` cpp
 is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>
 ```
@@ -198,21 +224,27 @@ template<class T, size_t N>
 ### `exchange` <a id="utility.exchange">[[utility.exchange]]</a>
 ``` cpp
 template<class T, class U = T>
-  constexpr T exchange(T& obj, U&& new_val);
 ```
 *Effects:* Equivalent to:
 ``` cpp
 T old_val = std::move(obj);
 obj = std::forward<U>(new_val);
 return old_val;
 ```
 ### Forward/move helpers <a id="forward">[[forward]]</a>
 The library provides templated helper functions to simplify applying
 move semantics to an lvalue and to simplify the implementation of
 forwarding functions. All functions specified in this subclause are
@@ -253,17 +285,58 @@ forwarded to `A`’s constructor as an rvalue. In the second call to
 constructor as an lvalue. In both cases, `A2` is deduced as `double`, so
 1.414 is forwarded to `A`’s constructor as an rvalue.
 — *end example*]
 ``` cpp
 template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;
 ```
 *Returns:* `static_cast<remove_reference_t<T>&&>(t)`.
-[*Example 2*:
 ``` cpp
 template<class T, class A1>
 shared_ptr<T> factory(A1&& a1) {
   return shared_ptr<T>(new T(std::forward<A1>(a1)));
@@ -276,11 +349,11 @@ struct A {
 };
 void g() {
   A a;
   shared_ptr<A> sp1 = factory<A>(a);                // ``a'' binds to A(const A&)
-  shared_ptr<A> sp1 = factory<A>(std::move(a));     // ``a'' binds to A(A&&)
 }
 ```
 In the first call to `factory`, `A1` is deduced as `A&`, so `a` is
 forwarded as a non-const lvalue. This binds to the constructor
@@ -309,17 +382,17 @@ template<class T> constexpr add_const_t<T>& as_const(T& t) noexcept;
 ### Function template `declval` <a id="declval">[[declval]]</a>
 The library provides the function template `declval` to simplify the
 definition of expressions which occur as unevaluated operands
-[[expr.prop]].
 ``` cpp
 template<class T> add_rvalue_reference_t<T> declval() noexcept;    // as unevaluated operand
 ```
-*Mandates:* This function is not odr-used [[basic.def.odr]].
 *Remarks:* The template parameter `T` of `declval` may be an incomplete
 type.
 [*Example 1*:
@@ -327,12 +400,12 @@ type.
 ``` cpp
 template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&);
 ```
 declares a function template `convert` which only participates in
-overloading if the type `From` can be explicitly converted to type `To`.
-For another example see class template `common_type`
 [[meta.trans.other]].
 — *end example*]
 ### Integer comparison functions <a id="utility.intcmp">[[utility.intcmp]]</a>
@@ -424,5 +497,43 @@ return cmp_greater_equal(t, numeric_limits<R>::min()) &&
 [*Note 1*: These function templates cannot be used to compare `byte`,
 `char`, `char8_t`, `char16_t`, `char32_t`, `wchar_t`, and
 `bool`. — *end note*]

 The header `<utility>` contains some basic function and class templates
 that are used throughout the rest of the library.
 ``` cpp
+// all freestanding
 #include <compare>              // see [compare.syn]
 #include <initializer_list>     // see [initializer.list.syn]
 namespace std {
   // [utility.swap], swap
   template<class T, size_t N>
     constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);
   // [utility.exchange], exchange
   template<class T, class U = T>
+    constexpr T exchange(T& obj, U&& new_val) noexcept(see below);
   // [forward], forward/move
   template<class T>
     constexpr T&& forward(remove_reference_t<T>& t) noexcept;
   template<class T>
     constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
+  template<class T, class U>
+    [[nodiscard]] constexpr auto forward_like(U&& x) noexcept -> see below;
   template<class T>
     constexpr remove_reference_t<T>&& move(T&&) noexcept;
   template<class T>
     constexpr conditional_t<
         !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>
     constexpr bool cmp_greater_equal(T t, U u) noexcept;
   template<class R, class T>
     constexpr bool in_range(T t) noexcept;
+  // [utility.underlying], to_underlying
+  template<class T>
+    constexpr underlying_type_t<T> to_underlying(T value) noexcept;
+  // [utility.unreachable], unreachable
+  [[noreturn]] void unreachable();
   // [intseq], compile-time integer sequences%
 %
 %
   template<class T, T...>
   // [pairs], class template pair
   template<class T1, class T2>
     struct pair;
+  template<class T1, class T2, class U1, class U2,
+           template<class> class TQual, template<class> class UQual>
+    requires requires { typename pair<common_reference_t<TQual<T1>, UQual<U1>>,
+                                      common_reference_t<TQual<T2>, UQual<U2>>>; }
+  struct basic_common_reference<pair<T1, T2>, pair<U1, U2>, TQual, UQual> {
+    using type = pair<common_reference_t<TQual<T1>, UQual<U1>>,
+                      common_reference_t<TQual<T2>, UQual<U2>>>;
+  };
+  template<class T1, class T2, class U1, class U2>
+    requires requires { typename pair<common_type_t<T1, U1>, common_type_t<T2, U2>>; }
+  struct common_type<pair<T1, T2>, pair<U1, U2>> {
+    using type = pair<common_type_t<T1, U1>, common_type_t<T2, U2>>;
+  };
   // [pairs.spec], pair specialized algorithms
+  template<class T1, class T2, class U1, class U2>
+    constexpr bool operator==(const pair<T1, T2>&, const pair<U1, U2>&);
+  template<class T1, class T2, class U1, class U2>
+    constexpr common_comparison_category_t<synth-three-way-result<T1, U1>,
+                                           synth-three-way-result<T2, U2>>
+      operator<=>(const pair<T1, T2>&, const pair<U1, U2>&);
   template<class T1, class T2>
     constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
+  template<class T1, class T2>
+    constexpr void swap(const pair<T1, T2>& x, const pair<T1, T2>& y)
+      noexcept(noexcept(x.swap(y)));
   template<class T1, class T2>
     constexpr see below make_pair(T1&&, T2&&);
   // [pair.astuple], tuple-like access to pair
   template<class T>
     struct in_place_type_t {
       explicit in_place_type_t() = default;
     };
+  template<class T> constexpr in_place_type_t<T> in_place_type{};
   template<size_t I>
     struct in_place_index_t {
       explicit in_place_index_t() = default;
     };
+  template<size_t I> constexpr in_place_index_t<I> in_place_index{};
 }
 ```
 ### `swap` <a id="utility.swap">[[utility.swap]]</a>
 ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
 ([[cpp17.moveassignable]]) requirements.
 *Effects:* Exchanges values stored in two locations.
+*Remarks:* The exception specification is equivalent to:
 ``` cpp
 is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>
 ```
 ### `exchange` <a id="utility.exchange">[[utility.exchange]]</a>
 ``` cpp
 template<class T, class U = T>
+  constexpr T exchange(T& obj, U&& new_val) noexcept(see below);
 ```
 *Effects:* Equivalent to:
 ``` cpp
 T old_val = std::move(obj);
 obj = std::forward<U>(new_val);
 return old_val;
 ```
+*Remarks:* The exception specification is equivalent to:
+``` cpp
+is_nothrow_move_constructible_v<T> && is_nothrow_assignable_v<T&, U>
+```
 ### Forward/move helpers <a id="forward">[[forward]]</a>
 The library provides templated helper functions to simplify applying
 move semantics to an lvalue and to simplify the implementation of
 forwarding functions. All functions specified in this subclause are
 constructor as an lvalue. In both cases, `A2` is deduced as `double`, so
 1.414 is forwarded to `A`’s constructor as an rvalue.
 — *end example*]
+``` cpp
+template<class T, class U>
+  [[nodiscard]] constexpr auto forward_like(U&& x) noexcept -> see below;
+```
+*Mandates:* `T` is a referenceable type [[defns.referenceable]].
+- Let *`COPY_CONST`*`(A, B)` be `const B` if `A` is a const type,
+  otherwise `B`.
+- Let *`OVERRIDE_REF`*`(A, B)` be `remove_reference_t<B>&&` if `A` is an
+  rvalue reference type, otherwise `B&`.
+- Let `V` be
+  ``` cpp
+  OVERRIDE_REF(T&&, COPY_CONST(remove_reference_t<T>, remove_reference_t<U>))
+  ```
+*Returns:* `static_cast<V>(x)`.
+*Remarks:* The return type is `V`.
+[*Example 2*:
+``` cpp
+struct accessor {
+  vector<string>* container;
+  decltype(auto) operator[](this auto&& self, size_t i) {
+    return std::forward_like<decltype(self)>((*container)[i]);
+  }
+};
+void g() {
+  vector v{"a"s, "b"s};
+  accessor a{&v};
+  string& x = a[0];                             // OK, binds to lvalue reference
+  string&& y = std::move(a)[0];                 // OK, is rvalue reference
+  string const&& z = std::move(as_const(a))[1]; // OK, is const&&
+  string& w = as_const(a)[1];                   // error: will not bind to non-const
+}
+```
+— *end example*]
 ``` cpp
 template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;
 ```
 *Returns:* `static_cast<remove_reference_t<T>&&>(t)`.
+[*Example 3*:
 ``` cpp
 template<class T, class A1>
 shared_ptr<T> factory(A1&& a1) {
   return shared_ptr<T>(new T(std::forward<A1>(a1)));
 };
 void g() {
   A a;
   shared_ptr<A> sp1 = factory<A>(a);                // ``a'' binds to A(const A&)
+  shared_ptr<A> sp2 = factory<A>(std::move(a));     // ``a'' binds to A(A&&)
 }
 ```
 In the first call to `factory`, `A1` is deduced as `A&`, so `a` is
 forwarded as a non-const lvalue. This binds to the constructor
 ### Function template `declval` <a id="declval">[[declval]]</a>
 The library provides the function template `declval` to simplify the
 definition of expressions which occur as unevaluated operands
+[[term.unevaluated.operand]].
 ``` cpp
 template<class T> add_rvalue_reference_t<T> declval() noexcept;    // as unevaluated operand
 ```
+*Mandates:* This function is not odr-used [[term.odr.use]].
 *Remarks:* The template parameter `T` of `declval` may be an incomplete
 type.
 [*Example 1*:
 ``` cpp
 template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&);
 ```
 declares a function template `convert` which only participates in
+overload resolution if the type `From` can be explicitly converted to
+type `To`. For another example see class template `common_type`
 [[meta.trans.other]].
 — *end example*]
 ### Integer comparison functions <a id="utility.intcmp">[[utility.intcmp]]</a>
 [*Note 1*: These function templates cannot be used to compare `byte`,
 `char`, `char8_t`, `char16_t`, `char32_t`, `wchar_t`, and
 `bool`. — *end note*]
+### Function template `to_underlying` <a id="utility.underlying">[[utility.underlying]]</a>
+``` cpp
+template<class T>
+  constexpr underlying_type_t<T> to_underlying(T value) noexcept;
+```
+*Returns:* `static_cast<underlying_type_t<T>>(value)`.
+### Function `unreachable` <a id="utility.unreachable">[[utility.unreachable]]</a>
+``` cpp
+[[noreturn]] void unreachable();
+```
+*Preconditions:* `false` is `true`.
+[*Note 1*: This precondition cannot be satisfied, thus the behavior of
+calling `unreachable` is undefined. — *end note*]
+[*Example 1*:
+``` cpp
+int f(int x) {
+  switch (x) {
+  case 0:
+  case 1:
+    return x;
+  default:
+    std::unreachable();
+  }
+}
+int a = f(1);           // OK, a has value 1
+int b = f(3);           // undefined behavior
+```
+— *end example*]

Diff to HTML by rtfpessoa