From Jason Turner

[utilities]

Large diff (277.4 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpx3u4hpu1/{from.md → to.md} +1901 -3124
tmp/tmpx3u4hpu1/{from.md → to.md} RENAMED
@@ -8,24 +8,20 @@ standard library. These utilities are summarized in
8
  [[utilities.summary]].
9
 
10
  **Table: General utilities library summary** <a id="utilities.summary">[utilities.summary]</a>
11
 
12
  | Subclause | | Header |
13
- | -------------------- | ----------------------------- | -------------- |
14
  | [[utility]] | Utility components | `<utility>` |
15
  | [[pairs]] | Pairs | |
16
  | [[tuple]] | Tuples | `<tuple>` |
17
  | [[optional]] | Optional objects | `<optional>` |
18
  | [[variant]] | Variants | `<variant>` |
19
  | [[any]] | Storage for any type | `<any>` |
20
  | [[expected]] | Expected objects | `<expected>` |
21
  | [[bitset]] | Fixed-size sequences of bits | `<bitset>` |
22
  | [[function.objects]] | Function objects | `<functional>` |
23
- | [[type.index]] | Type indexes | `<typeindex>` |
24
- | [[execpol]] | Execution policies | `<execution>` |
25
- | [[charconv]] | Primitive numeric conversions | `<charconv>` |
26
- | [[format]] | Formatting | `<format>` |
27
  | [[bit]] | Bit manipulation | `<bit>` |
28
 
29
 
30
  ## Utility components <a id="utility">[[utility]]</a>
31
 
@@ -54,11 +50,11 @@ namespace std {
54
  template<class T>
55
  constexpr T&& forward(remove_reference_t<T>& t) noexcept;
56
  template<class T>
57
  constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
58
  template<class T, class U>
59
- [[nodiscard]] constexpr auto forward_like(U&& x) noexcept -> see below;
60
  template<class T>
61
  constexpr remove_reference_t<T>&& move(T&&) noexcept;
62
  template<class T>
63
  constexpr conditional_t<
64
  !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>
@@ -94,12 +90,13 @@ namespace std {
94
 
95
  // [utility.underlying], to_underlying
96
  template<class T>
97
  constexpr underlying_type_t<T> to_underlying(T value) noexcept;
98
 
99
- // [utility.unreachable], unreachable
100
  [[noreturn]] void unreachable();
 
101
 
102
  // [intseq], compile-time integer sequences%
103
  %
104
  %
105
 
@@ -212,10 +209,33 @@ namespace std {
212
  template<size_t I>
213
  struct in_place_index_t {
214
  explicit in_place_index_t() = default;
215
  };
216
  template<size_t I> constexpr in_place_index_t<I> in_place_index{};
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
217
  }
218
  ```
219
 
220
  ### `swap` <a id="utility.swap">[[utility.swap]]</a>
221
 
@@ -316,11 +336,11 @@ constructor as an lvalue. In both cases, `A2` is deduced as `double`, so
316
 
317
  — *end example*]
318
 
319
  ``` cpp
320
  template<class T, class U>
321
- [[nodiscard]] constexpr auto forward_like(U&& x) noexcept -> see below;
322
  ```
323
 
324
  *Mandates:* `T` is a referenceable type [[defns.referenceable]].
325
 
326
  - Let *`COPY_CONST`*`(A, B)` be `const B` if `A` is a const type,
@@ -535,11 +555,11 @@ template<class T>
535
  constexpr underlying_type_t<T> to_underlying(T value) noexcept;
536
  ```
537
 
538
  *Returns:* `static_cast<underlying_type_t<T>>(value)`.
539
 
540
- ### Function `unreachable` <a id="utility.unreachable">[[utility.unreachable]]</a>
541
 
542
  ``` cpp
543
  [[noreturn]] void unreachable();
544
  ```
545
 
@@ -564,13 +584,19 @@ int a = f(1); // OK, a has value 1
564
  int b = f(3); // undefined behavior
565
  ```
566
 
567
  — *end example*]
568
 
 
 
 
 
 
 
569
  ## Pairs <a id="pairs">[[pairs]]</a>
570
 
571
- ### In general <a id="pairs.general">[[pairs.general]]</a>
572
 
573
  The library provides a template for heterogeneous pairs of values. The
574
  library also provides a matching function template to simplify their
575
  construction and several templates that provide access to `pair` objects
576
  as if they were `tuple` objects (see  [[tuple.helper]] and 
@@ -632,28 +658,28 @@ namespace std {
632
  template<class T1, class T2>
633
  pair(T1, T2) -> pair<T1, T2>;
634
  }
635
  ```
636
 
637
- Constructors and member functions of `pair` do not throw exceptions
638
- unless one of the element-wise operations specified to be called for
639
- that operation throws an exception.
640
 
641
  The defaulted move and copy constructor, respectively, of `pair` is a
642
  constexpr function if and only if all required element-wise
643
  initializations for move and copy, respectively, would be
644
  constexpr-suitable [[dcl.constexpr]].
645
 
646
  If
647
  `(is_trivially_destructible_v<T1> && is_trivially_destructible_v<T2>)`
648
  is `true`, then the destructor of `pair` is trivial.
649
 
650
- `pair<T, U>` is a structural type [[temp.param]] if `T` and `U` are both
651
- structural types. Two values `p1` and `p2` of type `pair<T, U>` are
652
- template-argument-equivalent [[temp.type]] if and only if `p1.first` and
653
- `p2.first` are template-argument-equivalent and `p1.second` and
654
- `p2.second` are template-argument-equivalent.
655
 
656
  ``` cpp
657
  constexpr explicit(see below) pair();
658
  ```
659
 
@@ -829,12 +855,12 @@ constexpr pair& operator=(pair&& p) noexcept(see below);
829
  *Constraints:*
830
 
831
  - `is_move_assignable_v<T1>` is `true` and
832
  - `is_move_assignable_v<T2>` is `true`.
833
 
834
- *Effects:* Assigns to `first` with `std::forward<T1>(p.first)` and to
835
- `second` with `std::forward<T2>(p.second)`.
836
 
837
  *Returns:* `*this`.
838
 
839
  *Remarks:* The exception specification is equivalent to:
840
 
@@ -863,13 +889,12 @@ template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p);
863
  *Constraints:*
864
 
865
  - `is_assignable_v<T1&, U1>` is `true` and
866
  - `is_assignable_v<T2&, U2>` is `true`.
867
 
868
- *Effects:* Assigns to `first` with `std::forward<U1>(p.first)` and to
869
- `second` with
870
- `std::forward<U2>(p.second)`.
871
 
872
  *Returns:* `*this`.
873
 
874
  ``` cpp
875
  template<pair-like P> constexpr pair& operator=(P&& p);
@@ -950,12 +975,13 @@ constexpr void swap(const pair& p) const noexcept(see below);
950
  ``` cpp
951
  template<class T1, class T2, class U1, class U2>
952
  constexpr bool operator==(const pair<T1, T2>& x, const pair<U1, U2>& y);
953
  ```
954
 
955
- *Preconditions:* Each of `decltype(x.first == y.first)` and
956
- `decltype(x.second == y.second)` models `boolean-testable`.
 
957
 
958
  *Returns:* `x.first == y.first && x.second == y.second`.
959
 
960
  ``` cpp
961
  template<class T1, class T2, class U1, class U2>
@@ -1029,11 +1055,11 @@ template<size_t I, class T1, class T2>
1029
  };
1030
  ```
1031
 
1032
  *Mandates:* `I` < 2.
1033
 
1034
- *Type:* The type `T1` if `I` is 0, otherwise the type `T2`.
1035
 
1036
  ``` cpp
1037
  template<size_t I, class T1, class T2>
1038
  constexpr tuple_element_t<I, pair<T1, T2>>& get(pair<T1, T2>& p) noexcept;
1039
  template<size_t I, class T1, class T2>
@@ -1097,20 +1123,24 @@ the first argument, immediately followed by two `tuple` [[tuple]]
1097
  arguments used for piecewise construction of the elements of the `pair`
1098
  object.
1099
 
1100
  ## Tuples <a id="tuple">[[tuple]]</a>
1101
 
1102
- ### In general <a id="tuple.general">[[tuple.general]]</a>
1103
 
1104
  Subclause  [[tuple]] describes the tuple library that provides a tuple
1105
  type as the class template `tuple` that can be instantiated with any
1106
  number of arguments. Each template argument specifies the type of an
1107
  element in the `tuple`. Consequently, tuples are heterogeneous,
1108
  fixed-size collections of values. An instantiation of `tuple` with two
1109
  arguments is similar to an instantiation of `pair` with the same two
1110
  arguments. See  [[pairs]].
1111
 
 
 
 
 
1112
  ### Header `<tuple>` synopsis <a id="tuple.syn">[[tuple.syn]]</a>
1113
 
1114
  ``` cpp
1115
  // all freestanding
1116
  #include <compare> // see [compare.syn]
@@ -1132,13 +1162,18 @@ namespace std {
1132
  template<class> class TQual, template<class> class UQual>
1133
  struct basic_common_reference<TTuple, UTuple, TQual, UQual>;
1134
  template<exposition onlyconceptnc{tuple-like} TTuple, exposition onlyconceptnc{tuple-like} UTuple>
1135
  struct common_type<TTuple, UTuple>;
1136
 
 
 
 
 
 
 
 
1137
  // [tuple.creation], tuple creation functions
1138
- inline constexpr unspecified ignore;
1139
-
1140
  template<class... TTypes>
1141
  constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&...);
1142
 
1143
  template<class... TTypes>
1144
  constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&...) noexcept;
@@ -1149,11 +1184,12 @@ namespace std {
1149
  template<exposition onlyconceptnc{tuple-like}... Tuples>
1150
  constexpr tuple<CTypes...> tuple_cat(Tuples&&...);
1151
 
1152
  // [tuple.apply], calling a function with a tuple of arguments
1153
  template<class F, exposition onlyconceptnc{tuple-like} Tuple>
1154
- constexpr decltype(auto) apply(F&& f, Tuple&& t) noexcept(see below);
 
1155
 
1156
  template<class T, exposition onlyconceptnc{tuple-like} Tuple>
1157
  constexpr T make_from_tuple(Tuple&& t);
1158
 
1159
  // [tuple.helper], tuple helper classes
@@ -1167,11 +1203,11 @@ namespace std {
1167
 
1168
  template<size_t I, class... Types>
1169
  struct tuple_element<I, tuple<Types...>>;
1170
 
1171
  template<size_t I, class T>
1172
- using tuple_element_t = typename tuple_element<I, T>::type;
1173
 
1174
  // [tuple.elem], element access
1175
  template<size_t I, class... Types>
1176
  constexpr tuple_element_t<I, tuple<Types...>>& get(tuple<Types...>&) noexcept;
1177
  template<size_t I, class... Types>
@@ -1222,15 +1258,17 @@ namespace std {
1222
  template<class T>
1223
  concept tuple-like = see belownc; // exposition only
1224
  ```
1225
 
1226
  A type `T` models and satisfies the exposition-only concept `tuple-like`
1227
- if `remove_cvref_t<T>` is a specialization of `array`, `pair`, `tuple`,
1228
- or `ranges::subrange`.
1229
 
1230
  ### Class template `tuple` <a id="tuple.tuple">[[tuple.tuple]]</a>
1231
 
 
 
1232
  ``` cpp
1233
  namespace std {
1234
  template<class... Types>
1235
  class tuple {
1236
  public:
@@ -1352,10 +1390,13 @@ namespace std {
1352
  template<class Alloc, class... UTypes>
1353
  tuple(allocator_arg_t, Alloc, tuple<UTypes...>) -> tuple<UTypes...>;
1354
  }
1355
  ```
1356
 
 
 
 
1357
  #### Construction <a id="tuple.cnstr">[[tuple.cnstr]]</a>
1358
 
1359
  In the descriptions that follow, let i be in the range \[`0`,
1360
  `sizeof...(Types)`) in order, `Tᵢ` be the iᵗʰ type in `Types`, and `Uᵢ`
1361
  be the iᵗʰ type in a template parameter pack named `UTypes`, where
@@ -1466,11 +1507,11 @@ template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&
1466
  template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>& u);
1467
  template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&& u);
1468
  template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>&& u);
1469
  ```
1470
 
1471
- Let `I` be the pack `0, 1, ..., (sizeof...(Types) - 1)`. Let
1472
  *`FWD`*`(u)` be `static_cast<decltype(u)>(u)`.
1473
 
1474
  *Constraints:*
1475
 
1476
  - `sizeof...(Types)` equals `sizeof...(UTypes)`, and
@@ -1537,21 +1578,21 @@ is `true`.
1537
  ``` cpp
1538
  template<tuple-like UTuple>
1539
  constexpr explicit(see below) tuple(UTuple&& u);
1540
  ```
1541
 
1542
- Let `I` be the pack `0, 1, …, (sizeof...(Types) - 1)`.
1543
 
1544
  *Constraints:*
1545
 
1546
  - `different-from<UTuple, tuple>` [[range.utility.helpers]] is `true`,
1547
  - `remove_cvref_t<UTuple>` is not a specialization of
1548
  `ranges::subrange`,
1549
  - `sizeof...(Types)` equals `tuple_size_v<remove_cvref_t<UTuple>>`,
1550
  - `(is_constructible_v<Types, decltype(get<I>(std::forward<UTuple>(u)))> && ...)`
1551
  is `true`, and
1552
- - either `sizeof...(Types)` is not `1`, or (when `Types...` expands to
1553
  `T`) `is_convertible_v<UTuple, T>` and `is_constructible_v<T, UTuple>`
1554
  are both `false`.
1555
 
1556
  *Effects:* For all i, initializes the iᵗʰ element of `*this` with
1557
  `get<`i`>(std::forward<UTuple>(u))`.
@@ -1560,10 +1601,19 @@ Let `I` be the pack `0, 1, …, (sizeof...(Types) - 1)`.
1560
 
1561
  ``` cpp
1562
  !(is_convertible_v<decltype(get<I>(std::forward<UTuple>(u))), Types> && ...)
1563
  ```
1564
 
 
 
 
 
 
 
 
 
 
1565
  ``` cpp
1566
  template<class Alloc>
1567
  constexpr explicit(see below)
1568
  tuple(allocator_arg_t, const Alloc& a);
1569
  template<class Alloc>
@@ -1802,11 +1852,11 @@ template<tuple-like UTuple>
1802
  *Constraints:*
1803
 
1804
  - `different-from<UTuple, tuple>` [[range.utility.helpers]] is `true`,
1805
  - `remove_cvref_t<UTuple>` is not a specialization of
1806
  `ranges::subrange`,
1807
- - `sizeof...(Types)` equals `tuple_size_v<remove_cvref_t<UTuple>>`, and,
1808
  - `is_assignable_v<``Tᵢ``&, decltype(get<`i`>(std::forward<UTuple>(u)))>`
1809
  is `true` for all i.
1810
 
1811
  *Effects:* For all i, assigns `get<`i`>(std::forward<UTuple>(u))` to
1812
  `get<`i`>(*this)`.
@@ -1821,11 +1871,11 @@ template<tuple-like UTuple>
1821
  *Constraints:*
1822
 
1823
  - `different-from<UTuple, tuple>` [[range.utility.helpers]] is `true`,
1824
  - `remove_cvref_t<UTuple>` is not a specialization of
1825
  `ranges::subrange`,
1826
- - `sizeof...(Types)` equals `tuple_size_v<remove_cvref_t<UTuple>>`, and,
1827
  - `is_assignable_v<const ``Tᵢ``&, decltype(get<`i`>(std::forward<UTuple>(u)))>`
1828
  is `true` for all i.
1829
 
1830
  *Effects:* For all i, assigns `get<`i`>(std::forward<UTuple>(u))` to
1831
  `get<`i`>(*this)`.
@@ -1848,11 +1898,11 @@ Let i be in the range \[`0`, `sizeof...(Types)`) in order.
1848
  `true`.
1849
 
1850
  *Preconditions:* For all i, `get<`i`>(*this)` is swappable
1851
  with [[swappable.requirements]] `get<`i`>(rhs)`.
1852
 
1853
- *Effects:* For each i, calls `swap` for `get<`i`>(*this)` with
1854
  `get<`i`>(rhs)`.
1855
 
1856
  *Throws:* Nothing unless one of the element-wise `swap` calls throws an
1857
  exception.
1858
 
@@ -1900,13 +1950,11 @@ variable).
1900
  ``` cpp
1901
  template<class... TTypes>
1902
  constexpr tuple<TTypes&...> tie(TTypes&... t) noexcept;
1903
  ```
1904
 
1905
- *Returns:* `tuple<TTypes&...>(t...)`. When an argument in `t` is
1906
- `ignore`, assigning any value to the corresponding tuple element has no
1907
- effect.
1908
 
1909
  [*Example 2*:
1910
 
1911
  `tie` functions allow one to create tuples that unpack tuples into
1912
  variables. `ignore` can be used for elements that are not needed:
@@ -1948,14 +1996,15 @@ elems₀`...`, …, elemsₙ₋₁`...`.
1948
 
1949
  ### Calling a function with a `tuple` of arguments <a id="tuple.apply">[[tuple.apply]]</a>
1950
 
1951
  ``` cpp
1952
  template<class F, tuple-like Tuple>
1953
- constexpr decltype(auto) apply(F&& f, Tuple&& t) noexcept(see below);
 
1954
  ```
1955
 
1956
- *Effects:* Given the exposition-only function:
1957
 
1958
  ``` cpp
1959
  namespace std {
1960
  template<class F, tuple-like Tuple, size_t... I>
1961
  constexpr decltype(auto) apply-impl(F&& f, Tuple&& t, index_sequence<I...>) {
@@ -1970,28 +2019,20 @@ Equivalent to:
1970
  ``` cpp
1971
  return apply-impl(std::forward<F>(f), std::forward<Tuple>(t),
1972
  make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
1973
  ```
1974
 
1975
- *Remarks:* Let `I` be the pack
1976
- `0, 1, ..., (tuple_size_v<remove_reference_t<Tuple>> - 1)`. The
1977
- exception specification is equivalent to:
1978
-
1979
- ``` cpp
1980
- noexcept(invoke(std::forward<F>(f), get<I>(std::forward<Tuple>(t))...))
1981
- ```
1982
-
1983
  ``` cpp
1984
  template<class T, tuple-like Tuple>
1985
  constexpr T make_from_tuple(Tuple&& t);
1986
  ```
1987
 
1988
  *Mandates:* If `tuple_size_v<remove_reference_t<Tuple>>` is 1, then
1989
  `reference_constructs_from_temporary_v<T, decltype(get<0>(declval<Tuple>()))>`
1990
  is `false`.
1991
 
1992
- *Effects:* Given the exposition-only function:
1993
 
1994
  ``` cpp
1995
  namespace std {
1996
  template<class T, tuple-like Tuple, size_t... I>
1997
  requires is_constructible_v<T, decltype(get<I>(declval<Tuple>()))...>
@@ -2017,17 +2058,17 @@ list. — *end note*]
2017
 
2018
  ``` cpp
2019
  template<class T> struct tuple_size;
2020
  ```
2021
 
2022
- All specializations of `tuple_size` meet the *Cpp17UnaryTypeTrait*
2023
- requirements [[meta.rqmts]] with a base characteristic of
2024
- `integral_constant<size_t, N>` for some `N`.
2025
 
2026
  ``` cpp
2027
  template<class... Types>
2028
- struct tuple_size<tuple<Types...>> : public integral_constant<size_t, sizeof...(Types)> { };
2029
  ```
2030
 
2031
  ``` cpp
2032
  template<size_t I, class... Types>
2033
  struct tuple_element<I, tuple<Types...>> {
@@ -2035,12 +2076,12 @@ template<size_t I, class... Types>
2035
  };
2036
  ```
2037
 
2038
  *Mandates:* `I` < `sizeof...(Types)`.
2039
 
2040
- *Type:* `TI` is the type of the `I`ᵗʰ element of `Types`, where indexing
2041
- is zero-based.
2042
 
2043
  ``` cpp
2044
  template<class T> struct tuple_size<const T>;
2045
  ```
2046
 
@@ -2075,11 +2116,11 @@ template<size_t I, class T> struct tuple_element<I, const T>;
2075
  ```
2076
 
2077
  Let `TE` denote `tuple_element_t<I, T>` of the cv-unqualified type `T`.
2078
  Then each specialization of the template meets the
2079
  *Cpp17TransformationTrait* requirements [[meta.rqmts]] with a member
2080
- typedef `type` that names the type `add_const_t<TE>`.
2081
 
2082
  In addition to being available via inclusion of the `<tuple>` header,
2083
  the template is available when any of the headers `<array>`, `<ranges>`,
2084
  or `<utility>` are included.
2085
 
@@ -2089,32 +2130,34 @@ or `<utility>` are included.
2089
  template<size_t I, class... Types>
2090
  constexpr tuple_element_t<I, tuple<Types...>>&
2091
  get(tuple<Types...>& t) noexcept;
2092
  template<size_t I, class... Types>
2093
  constexpr tuple_element_t<I, tuple<Types...>>&&
2094
- get(tuple<Types...>&& t) noexcept; // Note A
2095
  template<size_t I, class... Types>
2096
  constexpr const tuple_element_t<I, tuple<Types...>>&
2097
- get(const tuple<Types...>& t) noexcept; // Note B
2098
  template<size_t I, class... Types>
2099
  constexpr const tuple_element_t<I, tuple<Types...>>&& get(const tuple<Types...>&& t) noexcept;
2100
  ```
2101
 
2102
  *Mandates:* `I` < `sizeof...(Types)`.
2103
 
2104
  *Returns:* A reference to the `I`ᵗʰ element of `t`, where indexing is
2105
  zero-based.
2106
 
2107
- [*Note 1*: \[Note A\]If a type `T` in `Types` is some reference type
2108
- `X&`, the return type is `X&`, not `X&&`. However, if the element type
2109
- is a non-reference type `T`, the return type is `T&&`. — *end note*]
 
2110
 
2111
- [*Note 2*: \[Note B\]Constness is shallow. If a type `T` in `Types` is
2112
- some reference type `X&`, the return type is `X&`, not `const X&`.
2113
- However, if the element type is a non-reference type `T`, the return
2114
- type is `const T&`. This is consistent with how constness is defined to
2115
- work for non-static data members of reference type. — *end note*]
 
2116
 
2117
  ``` cpp
2118
  template<class T, class... Types>
2119
  constexpr T& get(tuple<Types...>& t) noexcept;
2120
  template<class T, class... Types>
@@ -2155,16 +2198,14 @@ template<class... TTypes, tuple-like UTuple>
2155
  constexpr bool operator==(const tuple<TTypes...>& t, const UTuple& u);
2156
  ```
2157
 
2158
  For the first overload let `UTuple` be `tuple<UTypes...>`.
2159
 
2160
- *Mandates:* For all `i`, where 0 ≤ `i` < `sizeof...(TTypes)`,
2161
- `get<i>(t) == get<i>(u)` is a valid expression. `sizeof...(TTypes)`
2162
- equals `tuple_size_v<UTuple>`.
2163
-
2164
- *Preconditions:* For all `i`, `decltype(get<i>(t) == get<i>(u))` models
2165
- `boolean-testable`.
2166
 
2167
  *Returns:* `true` if `get<i>(t) == get<i>(u)` for all `i`, otherwise
2168
  `false`.
2169
 
2170
  [*Note 1*: If `sizeof...(TTypes)` equals zero, returns
@@ -2208,11 +2249,11 @@ lookup [[basic.lookup.argdep]] only.
2208
 
2209
  [*Note 1*: The above definition does not require `tₜₐᵢₗ` (or `uₜₐᵢₗ`)
2210
  to be constructed. It might not even be possible, as `t` and `u` are not
2211
  required to be copy constructible. Also, all comparison operator
2212
  functions are short circuited; they do not perform element accesses
2213
- beyond what is required to determine the result of the
2214
  comparison. — *end note*]
2215
 
2216
  ### `common_reference` related specializations <a id="tuple.common.ref">[[tuple.common.ref]]</a>
2217
 
2218
  In the descriptions that follow:
@@ -2240,11 +2281,11 @@ struct basic_common_reference<TTuple, UTuple, TQual, UQual> {
2240
  - `is_same_v<UTuple, decay_t<UTuple>>` is `true`.
2241
  - `tuple_size_v<TTuple>` equals `tuple_size_v<UTuple>`.
2242
  - `tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...>` denotes a
2243
  type.
2244
 
2245
- The member *typedef-name* `type` denotes the type
2246
  `tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...>`.
2247
 
2248
  ``` cpp
2249
  template<tuple-like TTuple, tuple-like UTuple>
2250
  struct common_type<TTuple, UTuple> {
@@ -2259,11 +2300,11 @@ struct common_type<TTuple, UTuple> {
2259
  - `is_same_v<TTuple, decay_t<TTuple>>` is `true`.
2260
  - `is_same_v<UTuple, decay_t<UTuple>>` is `true`.
2261
  - `tuple_size_v<TTuple>` equals `tuple_size_v<UTuple>`.
2262
  - `tuple<common_type_t<TTypes, UTypes>...>` denotes a type.
2263
 
2264
- The member *typedef-name* `type` denotes the type
2265
  `tuple<common_type_t<TTypes, UTypes>...>`.
2266
 
2267
  ### Tuple traits <a id="tuple.traits">[[tuple.traits]]</a>
2268
 
2269
  ``` cpp
@@ -2301,11 +2342,11 @@ template<class... Types>
2301
  noexcept(x.swap(y))
2302
  ```
2303
 
2304
  ## Optional objects <a id="optional">[[optional]]</a>
2305
 
2306
- ### In general <a id="optional.general">[[optional.general]]</a>
2307
 
2308
  Subclause  [[optional]] describes class template `optional` that
2309
  represents optional objects. An *optional object* is an object that
2310
  contains the storage for another object and manages the lifetime of this
2311
  contained object, if any. The contained object may be initialized after
@@ -2314,16 +2355,28 @@ the optional object has been destroyed. The initialization state of the
2314
  contained object is tracked by the optional object.
2315
 
2316
  ### Header `<optional>` synopsis <a id="optional.syn">[[optional.syn]]</a>
2317
 
2318
  ``` cpp
 
2319
  #include <compare> // see [compare.syn]
2320
 
2321
  namespace std {
2322
  // [optional.optional], class template optional
2323
  template<class T>
2324
- class optional;
 
 
 
 
 
 
 
 
 
 
 
2325
 
2326
  template<class T>
2327
  concept is-derived-from-optional = requires(const T& t) { // exposition only
2328
  []<class U>(const optional<U>&){ }(t);
2329
  };
@@ -2378,11 +2431,11 @@ namespace std {
2378
  // [optional.specalg], specialized algorithms
2379
  template<class T>
2380
  constexpr void swap(optional<T>&, optional<T>&) noexcept(see below);
2381
 
2382
  template<class T>
2383
- constexpr optional<see below> make_optional(T&&);
2384
  template<class T, class... Args>
2385
  constexpr optional<T> make_optional(Args&&... args);
2386
  template<class T, class U, class... Args>
2387
  constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args);
2388
 
@@ -2400,21 +2453,23 @@ namespace std {
2400
  namespace std {
2401
  template<class T>
2402
  class optional {
2403
  public:
2404
  using value_type = T;
 
 
2405
 
2406
  // [optional.ctor], constructors
2407
  constexpr optional() noexcept;
2408
  constexpr optional(nullopt_t) noexcept;
2409
  constexpr optional(const optional&);
2410
  constexpr optional(optional&&) noexcept(see below);
2411
  template<class... Args>
2412
  constexpr explicit optional(in_place_t, Args&&...);
2413
  template<class U, class... Args>
2414
  constexpr explicit optional(in_place_t, initializer_list<U>, Args&&...);
2415
- template<class U = T>
2416
  constexpr explicit(see below) optional(U&&);
2417
  template<class U>
2418
  constexpr explicit(see below) optional(const optional<U>&);
2419
  template<class U>
2420
  constexpr explicit(see below) optional(optional<U>&&);
@@ -2424,34 +2479,40 @@ namespace std {
2424
 
2425
  // [optional.assign], assignment
2426
  constexpr optional& operator=(nullopt_t) noexcept;
2427
  constexpr optional& operator=(const optional&);
2428
  constexpr optional& operator=(optional&&) noexcept(see below);
2429
- template<class U = T> constexpr optional& operator=(U&&);
2430
  template<class U> constexpr optional& operator=(const optional<U>&);
2431
  template<class U> constexpr optional& operator=(optional<U>&&);
2432
  template<class... Args> constexpr T& emplace(Args&&...);
2433
  template<class U, class... Args> constexpr T& emplace(initializer_list<U>, Args&&...);
2434
 
2435
  // [optional.swap], swap
2436
  constexpr void swap(optional&) noexcept(see below);
2437
 
 
 
 
 
 
 
2438
  // [optional.observe], observers
2439
  constexpr const T* operator->() const noexcept;
2440
  constexpr T* operator->() noexcept;
2441
  constexpr const T& operator*() const & noexcept;
2442
  constexpr T& operator*() & noexcept;
2443
  constexpr T&& operator*() && noexcept;
2444
  constexpr const T&& operator*() const && noexcept;
2445
  constexpr explicit operator bool() const noexcept;
2446
  constexpr bool has_value() const noexcept;
2447
- constexpr const T& value() const &;
2448
- constexpr T& value() &;
2449
- constexpr T&& value() &&;
2450
- constexpr const T&& value() const &&;
2451
- template<class U> constexpr T value_or(U&&) const &;
2452
- template<class U> constexpr T value_or(U&&) &&;
2453
 
2454
  // [optional.monadic], monadic operations
2455
  template<class F> constexpr auto and_then(F&& f) &;
2456
  template<class F> constexpr auto and_then(F&& f) &&;
2457
  template<class F> constexpr auto and_then(F&& f) const &;
@@ -2473,25 +2534,29 @@ namespace std {
2473
  template<class T>
2474
  optional(T) -> optional<T>;
2475
  }
2476
  ```
2477
 
2478
- Any instance of `optional<T>` at any given time either contains a value
2479
- or does not contain a value. When an instance of `optional<T>` *contains
2480
- a value*, it means that an object of type `T`, referred to as the
2481
- optional object’s *contained value*, is allocated within the storage of
2482
- the optional object. Implementations are not permitted to use additional
2483
- storage, such as dynamic memory, to allocate its contained value. When
2484
- an object of type `optional<T>` is contextually converted to `bool`, the
2485
- conversion returns `true` if the object contains a value; otherwise the
2486
- conversion returns `false`.
2487
 
2488
- When an `optional<T>` object contains a value, member `val` points to
2489
- the contained value.
2490
 
2491
- `T` shall be a type other than cv `in_place_t` or cv `nullopt_t` that
2492
- meets the *Cpp17Destructible* requirements ([[cpp17.destructible]]).
 
 
 
 
 
2493
 
2494
  #### Constructors <a id="optional.ctor">[[optional.ctor]]</a>
2495
 
2496
  The exposition-only variable template *`converts-from-any-cvref`* is
2497
  used by some constructors for `optional`.
@@ -2536,11 +2601,11 @@ constexpr optional(optional&& rhs) noexcept(see below);
2536
  ```
2537
 
2538
  *Constraints:* `is_move_constructible_v<T>` is `true`.
2539
 
2540
  *Effects:* If `rhs` contains a value, direct-non-list-initializes the
2541
- contained value with `std::move(*rhs)`. `rhs.has_value()` is unchanged.
2542
 
2543
  *Ensures:* `rhs.has_value() == this->has_value()`.
2544
 
2545
  *Throws:* Any exception thrown by the selected constructor of `T`.
2546
 
@@ -2582,11 +2647,11 @@ template<class U, class... Args>
2582
 
2583
  *Remarks:* If `T`’s constructor selected for the initialization is a
2584
  constexpr constructor, this constructor is a constexpr constructor.
2585
 
2586
  ``` cpp
2587
- template<class U = T> constexpr explicit(see below) optional(U&& v);
2588
  ```
2589
 
2590
  *Constraints:*
2591
 
2592
  - `is_constructible_v<T, U>` is `true`,
@@ -2642,11 +2707,11 @@ template<class U> constexpr explicit(see below) optional(optional<U>&& rhs);
2642
  - `is_constructible_v<T, U>` is `true`, and
2643
  - if `T` is not cv `bool`, *`converts-from-any-cvref`*`<T, optional<U>>`
2644
  is `false`.
2645
 
2646
  *Effects:* If `rhs` contains a value, direct-non-list-initializes the
2647
- contained value with `std::move(*rhs)`. `rhs.has_value()` is unchanged.
2648
 
2649
  *Ensures:* `rhs.has_value() == this->has_value()`.
2650
 
2651
  *Throws:* Any exception thrown by the selected constructor of `T`.
2652
 
@@ -2726,11 +2791,11 @@ constexpr optional& operator=(optional&& rhs) noexcept(see below);
2726
 
2727
  **Table: `optional::operator=(optional&&)` effects** <a id="optional.assign.move">[optional.assign.move]</a>
2728
 
2729
  | | `*this` contains a value | `*this` does not contain a value |
2730
  | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------- |
2731
- | `rhs` contains a value | assigns `std::move(*rhs)` to the contained value | direct-non-list-initializes the contained value with `std::move(*rhs)` |
2732
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2733
 
2734
 
2735
  *Ensures:* `rhs.has_value() == this->has_value()`.
2736
 
@@ -2752,17 +2817,19 @@ guarantee of `T`’s move assignment. If
2752
  `is_trivially_move_constructible_v<T> &&`
2753
  `is_trivially_move_assignable_v<T> &&` `is_trivially_destructible_v<T>`
2754
  is `true`, this assignment operator is trivial.
2755
 
2756
  ``` cpp
2757
- template<class U = T> constexpr optional<T>& operator=(U&& v);
2758
  ```
2759
 
2760
- *Constraints:* `is_same_v<remove_cvref_t<U>, optional>` is `false`,
2761
- `conjunction_v<is_scalar<T>, is_same<T, decay_t<U>>>` is `false`,
2762
- `is_constructible_v<T, U>` is `true`, and `is_assignable_v<T&, U>` is
2763
- `true`.
 
 
2764
 
2765
  *Effects:* If `*this` contains a value, assigns `std::forward<U>(v)` to
2766
  the contained value; otherwise direct-non-list-initializes the contained
2767
  value with `std::forward<U>(v)`.
2768
 
@@ -2832,11 +2899,11 @@ expression `rhs.has_value()` remains unchanged.
2832
 
2833
  **Table: `optional::operator=(optional<U>&&)` effects** <a id="optional.assign.move.templ">[optional.assign.move.templ]</a>
2834
 
2835
  | | `*this` contains a value | `*this` does not contain a value |
2836
  | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------- |
2837
- | `rhs` contains a value | assigns `std::move(*rhs)` to the contained value | direct-non-list-initializes the contained value with `std::move(*rhs)` |
2838
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2839
 
2840
 
2841
  *Ensures:* `rhs.has_value() == this->has_value()`.
2842
 
@@ -2925,40 +2992,75 @@ exception is thrown during the call to function `swap`, the state of
2925
  `*val` and `*rhs.val` is determined by the exception safety guarantee of
2926
  `swap` for lvalues of `T`. If an exception is thrown during the call to
2927
  `T`’s move constructor, the state of `*val` and `*rhs.val` is determined
2928
  by the exception safety guarantee of `T`’s move constructor.
2929
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2930
  #### Observers <a id="optional.observe">[[optional.observe]]</a>
2931
 
2932
  ``` cpp
2933
  constexpr const T* operator->() const noexcept;
2934
  constexpr T* operator->() noexcept;
2935
  ```
2936
 
2937
- *Preconditions:* `*this` contains a value.
2938
 
2939
  *Returns:* `val`.
2940
 
2941
  *Remarks:* These functions are constexpr functions.
2942
 
2943
  ``` cpp
2944
  constexpr const T& operator*() const & noexcept;
2945
  constexpr T& operator*() & noexcept;
2946
  ```
2947
 
2948
- *Preconditions:* `*this` contains a value.
2949
 
2950
  *Returns:* `*val`.
2951
 
2952
  *Remarks:* These functions are constexpr functions.
2953
 
2954
  ``` cpp
2955
  constexpr T&& operator*() && noexcept;
2956
  constexpr const T&& operator*() const && noexcept;
2957
  ```
2958
 
2959
- *Preconditions:* `*this` contains a value.
2960
 
2961
  *Effects:* Equivalent to: `return std::move(*val);`
2962
 
2963
  ``` cpp
2964
  constexpr explicit operator bool() const noexcept;
@@ -2997,11 +3099,11 @@ constexpr const T&& value() const &&;
2997
  ``` cpp
2998
  return has_value() ? std::move(*val) : throw bad_optional_access();
2999
  ```
3000
 
3001
  ``` cpp
3002
- template<class U> constexpr T value_or(U&& v) const &;
3003
  ```
3004
 
3005
  *Mandates:* `is_copy_constructible_v<T> && is_convertible_v<U&&, T>` is
3006
  `true`.
3007
 
@@ -3010,11 +3112,11 @@ template<class U> constexpr T value_or(U&& v) const &;
3010
  ``` cpp
3011
  return has_value() ? **this : static_cast<T>(std::forward<U>(v));
3012
  ```
3013
 
3014
  ``` cpp
3015
- template<class U> constexpr T value_or(U&& v) &&;
3016
  ```
3017
 
3018
  *Mandates:* `is_move_constructible_v<T> && is_convertible_v<U&&, T>` is
3019
  `true`.
3020
 
@@ -3029,96 +3131,96 @@ return has_value() ? std::move(**this) : static_cast<T>(std::forward<U>(v));
3029
  ``` cpp
3030
  template<class F> constexpr auto and_then(F&& f) &;
3031
  template<class F> constexpr auto and_then(F&& f) const &;
3032
  ```
3033
 
3034
- Let `U` be `invoke_result_t<F, decltype(value())>`.
3035
 
3036
  *Mandates:* `remove_cvref_t<U>` is a specialization of `optional`.
3037
 
3038
  *Effects:* Equivalent to:
3039
 
3040
  ``` cpp
3041
  if (*this) {
3042
- return invoke(std::forward<F>(f), value());
3043
  } else {
3044
  return remove_cvref_t<U>();
3045
  }
3046
  ```
3047
 
3048
  ``` cpp
3049
  template<class F> constexpr auto and_then(F&& f) &&;
3050
  template<class F> constexpr auto and_then(F&& f) const &&;
3051
  ```
3052
 
3053
- Let `U` be `invoke_result_t<F, decltype(std::move(value()))>`.
3054
 
3055
  *Mandates:* `remove_cvref_t<U>` is a specialization of `optional`.
3056
 
3057
  *Effects:* Equivalent to:
3058
 
3059
  ``` cpp
3060
  if (*this) {
3061
- return invoke(std::forward<F>(f), std::move(value()));
3062
  } else {
3063
  return remove_cvref_t<U>();
3064
  }
3065
  ```
3066
 
3067
  ``` cpp
3068
  template<class F> constexpr auto transform(F&& f) &;
3069
  template<class F> constexpr auto transform(F&& f) const &;
3070
  ```
3071
 
3072
- Let `U` be `remove_cv_t<invoke_result_t<F, decltype(value())>>`.
3073
 
3074
- *Mandates:* `U` is a non-array object type other than `in_place_t` or
3075
- `nullopt_t`. The declaration
3076
 
3077
  ``` cpp
3078
- U u(invoke(std::forward<F>(f), value()));
3079
  ```
3080
 
3081
  is well-formed for some invented variable `u`.
3082
 
3083
  [*Note 1*: There is no requirement that `U` is
3084
  movable [[dcl.init.general]]. — *end note*]
3085
 
3086
  *Returns:* If `*this` contains a value, an `optional<U>` object whose
3087
  contained value is direct-non-list-initialized with
3088
- `invoke(std::forward<F>(f), value())`; otherwise, `optional<U>()`.
3089
 
3090
  ``` cpp
3091
  template<class F> constexpr auto transform(F&& f) &&;
3092
  template<class F> constexpr auto transform(F&& f) const &&;
3093
  ```
3094
 
3095
  Let `U` be
3096
- `remove_cv_t<invoke_result_t<F, decltype(std::move(value()))>>`.
3097
 
3098
- *Mandates:* `U` is a non-array object type other than `in_place_t` or
3099
- `nullopt_t`. The declaration
3100
 
3101
  ``` cpp
3102
- U u(invoke(std::forward<F>(f), std::move(value())));
3103
  ```
3104
 
3105
  is well-formed for some invented variable `u`.
3106
 
3107
  [*Note 2*: There is no requirement that `U` is
3108
  movable [[dcl.init.general]]. — *end note*]
3109
 
3110
  *Returns:* If `*this` contains a value, an `optional<U>` object whose
3111
  contained value is direct-non-list-initialized with
3112
- `invoke(std::forward<F>(f), std::move(value()))`; otherwise,
3113
  `optional<U>()`.
3114
 
3115
  ``` cpp
3116
  template<class F> constexpr optional or_else(F&& f) const &;
3117
  ```
3118
 
3119
- *Constraints:* `F` models `invocable<>` and `T` models
3120
  `copy_constructible`.
3121
 
3122
  *Mandates:* `is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>` is
3123
  `true`.
3124
 
@@ -3134,11 +3236,11 @@ if (*this) {
3134
 
3135
  ``` cpp
3136
  template<class F> constexpr optional or_else(F&& f) &&;
3137
  ```
3138
 
3139
- *Constraints:* `F` models `invocable<>` and `T` models
3140
  `move_constructible`.
3141
 
3142
  *Mandates:* `is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>` is
3143
  `true`.
3144
 
@@ -3161,10 +3263,432 @@ constexpr void reset() noexcept;
3161
  *Effects:* If `*this` contains a value, calls `val->T::T̃()` to destroy
3162
  the contained value; otherwise no effect.
3163
 
3164
  *Ensures:* `*this` does not contain a value.
3165
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3166
  ### No-value state indicator <a id="optional.nullopt">[[optional.nullopt]]</a>
3167
 
3168
  ``` cpp
3169
  struct nullopt_t{see below};
3170
  inline constexpr nullopt_t nullopt(unspecified);
@@ -3184,33 +3708,34 @@ initializer-list constructor, and shall not be an aggregate.
3184
  ``` cpp
3185
  namespace std {
3186
  class bad_optional_access : public exception {
3187
  public:
3188
  // see [exception] for the specification of the special member functions
3189
- const char* what() const noexcept override;
3190
  };
3191
  }
3192
  ```
3193
 
3194
  The class `bad_optional_access` defines the type of objects thrown as
3195
  exceptions to report the situation where an attempt is made to access
3196
  the value of an optional object that does not contain a value.
3197
 
3198
  ``` cpp
3199
- const char* what() const noexcept override;
3200
  ```
3201
 
3202
- *Returns:* An *implementation-defined* NTBS.
 
3203
 
3204
  ### Relational operators <a id="optional.relops">[[optional.relops]]</a>
3205
 
3206
  ``` cpp
3207
  template<class T, class U> constexpr bool operator==(const optional<T>& x, const optional<U>& y);
3208
  ```
3209
 
3210
- *Mandates:* The expression `*x == *y` is well-formed and its result is
3211
- convertible to `bool`.
3212
 
3213
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
3214
 
3215
  *Returns:* If `x.has_value() != y.has_value()`, `false`; otherwise if
3216
  `x.has_value() == false`, `true`; otherwise `*x == *y`.
@@ -3220,12 +3745,12 @@ convertible to `bool`.
3220
 
3221
  ``` cpp
3222
  template<class T, class U> constexpr bool operator!=(const optional<T>& x, const optional<U>& y);
3223
  ```
3224
 
3225
- *Mandates:* The expression `*x != *y` is well-formed and its result is
3226
- convertible to `bool`.
3227
 
3228
  *Returns:* If `x.has_value() != y.has_value()`, `true`; otherwise, if
3229
  `x.has_value() == false`, `false`; otherwise `*x != *y`.
3230
 
3231
  *Remarks:* Specializations of this function template for which
@@ -3233,11 +3758,11 @@ convertible to `bool`.
3233
 
3234
  ``` cpp
3235
  template<class T, class U> constexpr bool operator<(const optional<T>& x, const optional<U>& y);
3236
  ```
3237
 
3238
- *Mandates:* `*x < *y` is well-formed and its result is convertible to
3239
  `bool`.
3240
 
3241
  *Returns:* If `!y`, `false`; otherwise, if `!x`, `true`; otherwise
3242
  `*x < *y`.
3243
 
@@ -3246,11 +3771,11 @@ is a core constant expression are constexpr functions.
3246
 
3247
  ``` cpp
3248
  template<class T, class U> constexpr bool operator>(const optional<T>& x, const optional<U>& y);
3249
  ```
3250
 
3251
- *Mandates:* The expression `*x > *y` is well-formed and its result is
3252
  convertible to `bool`.
3253
 
3254
  *Returns:* If `!x`, `false`; otherwise, if `!y`, `true`; otherwise
3255
  `*x > *y`.
3256
 
@@ -3259,12 +3784,12 @@ is a core constant expression are constexpr functions.
3259
 
3260
  ``` cpp
3261
  template<class T, class U> constexpr bool operator<=(const optional<T>& x, const optional<U>& y);
3262
  ```
3263
 
3264
- *Mandates:* The expression `*x <= *y` is well-formed and its result is
3265
- convertible to `bool`.
3266
 
3267
  *Returns:* If `!x`, `true`; otherwise, if `!y`, `false`; otherwise
3268
  `*x <= *y`.
3269
 
3270
  *Remarks:* Specializations of this function template for which
@@ -3272,12 +3797,12 @@ convertible to `bool`.
3272
 
3273
  ``` cpp
3274
  template<class T, class U> constexpr bool operator>=(const optional<T>& x, const optional<U>& y);
3275
  ```
3276
 
3277
- *Mandates:* The expression `*x >= *y` is well-formed and its result is
3278
- convertible to `bool`.
3279
 
3280
  *Returns:* If `!y`, `true`; otherwise, if `!x`, `false`; otherwise
3281
  `*x >= *y`.
3282
 
3283
  *Remarks:* Specializations of this function template for which
@@ -3313,113 +3838,113 @@ template<class T> constexpr strong_ordering operator<=>(const optional<T>& x, nu
3313
 
3314
  ``` cpp
3315
  template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
3316
  ```
3317
 
3318
- *Mandates:* The expression `*x == v` is well-formed and its result is
3319
- convertible to `bool`.
3320
 
3321
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
3322
 
3323
  *Effects:* Equivalent to: `return x.has_value() ? *x == v : false;`
3324
 
3325
  ``` cpp
3326
  template<class T, class U> constexpr bool operator==(const T& v, const optional<U>& x);
3327
  ```
3328
 
3329
- *Mandates:* The expression `v == *x` is well-formed and its result is
3330
- convertible to `bool`.
3331
 
3332
  *Effects:* Equivalent to: `return x.has_value() ? v == *x : false;`
3333
 
3334
  ``` cpp
3335
  template<class T, class U> constexpr bool operator!=(const optional<T>& x, const U& v);
3336
  ```
3337
 
3338
- *Mandates:* The expression `*x != v` is well-formed and its result is
3339
- convertible to `bool`.
3340
 
3341
  *Effects:* Equivalent to: `return x.has_value() ? *x != v : true;`
3342
 
3343
  ``` cpp
3344
  template<class T, class U> constexpr bool operator!=(const T& v, const optional<U>& x);
3345
  ```
3346
 
3347
- *Mandates:* The expression `v != *x` is well-formed and its result is
3348
- convertible to `bool`.
3349
 
3350
  *Effects:* Equivalent to: `return x.has_value() ? v != *x : true;`
3351
 
3352
  ``` cpp
3353
  template<class T, class U> constexpr bool operator<(const optional<T>& x, const U& v);
3354
  ```
3355
 
3356
- *Mandates:* The expression `*x < v` is well-formed and its result is
3357
- convertible to `bool`.
3358
 
3359
  *Effects:* Equivalent to: `return x.has_value() ? *x < v : true;`
3360
 
3361
  ``` cpp
3362
  template<class T, class U> constexpr bool operator<(const T& v, const optional<U>& x);
3363
  ```
3364
 
3365
- *Mandates:* The expression `v < *x` is well-formed and its result is
3366
- convertible to `bool`.
3367
 
3368
  *Effects:* Equivalent to: `return x.has_value() ? v < *x : false;`
3369
 
3370
  ``` cpp
3371
  template<class T, class U> constexpr bool operator>(const optional<T>& x, const U& v);
3372
  ```
3373
 
3374
- *Mandates:* The expression `*x > v` is well-formed and its result is
3375
- convertible to `bool`.
3376
 
3377
  *Effects:* Equivalent to: `return x.has_value() ? *x > v : false;`
3378
 
3379
  ``` cpp
3380
  template<class T, class U> constexpr bool operator>(const T& v, const optional<U>& x);
3381
  ```
3382
 
3383
- *Mandates:* The expression `v > *x` is well-formed and its result is
3384
- convertible to `bool`.
3385
 
3386
  *Effects:* Equivalent to: `return x.has_value() ? v > *x : true;`
3387
 
3388
  ``` cpp
3389
  template<class T, class U> constexpr bool operator<=(const optional<T>& x, const U& v);
3390
  ```
3391
 
3392
- *Mandates:* The expression `*x <= v` is well-formed and its result is
3393
- convertible to `bool`.
3394
 
3395
  *Effects:* Equivalent to: `return x.has_value() ? *x <= v : true;`
3396
 
3397
  ``` cpp
3398
  template<class T, class U> constexpr bool operator<=(const T& v, const optional<U>& x);
3399
  ```
3400
 
3401
- *Mandates:* The expression `v <= *x` is well-formed and its result is
3402
- convertible to `bool`.
3403
 
3404
  *Effects:* Equivalent to: `return x.has_value() ? v <= *x : false;`
3405
 
3406
  ``` cpp
3407
  template<class T, class U> constexpr bool operator>=(const optional<T>& x, const U& v);
3408
  ```
3409
 
3410
- *Mandates:* The expression `*x >= v` is well-formed and its result is
3411
- convertible to `bool`.
3412
 
3413
  *Effects:* Equivalent to: `return x.has_value() ? *x >= v : false;`
3414
 
3415
  ``` cpp
3416
  template<class T, class U> constexpr bool operator>=(const T& v, const optional<U>& x);
3417
  ```
3418
 
3419
- *Mandates:* The expression `v >= *x` is well-formed and its result is
3420
- convertible to `bool`.
3421
 
3422
  *Effects:* Equivalent to: `return x.has_value() ? v >= *x : true;`
3423
 
3424
  ``` cpp
3425
  template<class T, class U>
@@ -3436,19 +3961,27 @@ template<class T, class U>
3436
  ``` cpp
3437
  template<class T>
3438
  constexpr void swap(optional<T>& x, optional<T>& y) noexcept(noexcept(x.swap(y)));
3439
  ```
3440
 
3441
- *Constraints:* `is_move_constructible_v<T>` is `true` and
3442
- `is_swappable_v<T>` is `true`.
 
 
 
 
 
3443
 
3444
  *Effects:* Calls `x.swap(y)`.
3445
 
3446
  ``` cpp
3447
  template<class T> constexpr optional<decay_t<T>> make_optional(T&& v);
3448
  ```
3449
 
 
 
 
3450
  *Returns:* `optional<decay_t<T>>(std::forward<T>(v))`.
3451
 
3452
  ``` cpp
3453
  template<class T, class...Args>
3454
  constexpr optional<T> make_optional(Args&&... args);
@@ -3479,20 +4012,24 @@ object `o` of type `optional<T>`, if `o.has_value() == true`, then
3479
  unspecified value. The member functions are not guaranteed to be
3480
  `noexcept`.
3481
 
3482
  ## Variants <a id="variant">[[variant]]</a>
3483
 
3484
- ### In general <a id="variant.general">[[variant.general]]</a>
3485
 
3486
  A variant object holds and manages the lifetime of a value. If the
3487
  `variant` holds a value, that value’s type has to be one of the template
3488
  argument types given to `variant`. These template arguments are called
3489
  alternatives.
3490
 
 
 
 
3491
  ### Header `<variant>` synopsis <a id="variant.syn">[[variant.syn]]</a>
3492
 
3493
  ``` cpp
 
3494
  #include <compare> // see [compare.syn]
3495
 
3496
  namespace std {
3497
  // [variant.variant], class template variant
3498
  template<class... Types>
@@ -3508,11 +4045,11 @@ namespace std {
3508
  struct variant_size<variant<Types...>>;
3509
 
3510
  template<size_t I, class T> struct variant_alternative; // not defined
3511
  template<size_t I, class T> struct variant_alternative<I, const T>;
3512
  template<size_t I, class T>
3513
- using variant_alternative_t = typename variant_alternative<I, T>::type;
3514
 
3515
  template<size_t I, class... Types>
3516
  struct variant_alternative<I, variant<Types...>>;
3517
 
3518
  inline constexpr size_t variant_npos = -1;
@@ -3520,26 +4057,30 @@ namespace std {
3520
  // [variant.get], value access
3521
  template<class T, class... Types>
3522
  constexpr bool holds_alternative(const variant<Types...>&) noexcept;
3523
 
3524
  template<size_t I, class... Types>
3525
- constexpr variant_alternative_t<I, variant<Types...>>& get(variant<Types...>&);
 
3526
  template<size_t I, class... Types>
3527
- constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&&);
 
3528
  template<size_t I, class... Types>
3529
- constexpr const variant_alternative_t<I, variant<Types...>>& get(const variant<Types...>&);
 
3530
  template<size_t I, class... Types>
3531
- constexpr const variant_alternative_t<I, variant<Types...>>&& get(const variant<Types...>&&);
 
3532
 
3533
  template<class T, class... Types>
3534
- constexpr T& get(variant<Types...>&);
3535
  template<class T, class... Types>
3536
- constexpr T&& get(variant<Types...>&&);
3537
  template<class T, class... Types>
3538
- constexpr const T& get(const variant<Types...>&);
3539
  template<class T, class... Types>
3540
- constexpr const T&& get(const variant<Types...>&&);
3541
 
3542
  template<size_t I, class... Types>
3543
  constexpr add_pointer_t<variant_alternative_t<I, variant<Types...>>>
3544
  get_if(variant<Types...>*) noexcept;
3545
  template<size_t I, class... Types>
@@ -3648,28 +4189,35 @@ namespace std {
3648
  constexpr bool valueless_by_exception() const noexcept;
3649
  constexpr size_t index() const noexcept;
3650
 
3651
  // [variant.swap], swap
3652
  constexpr void swap(variant&) noexcept(see below);
 
 
 
 
 
 
3653
  };
3654
  }
3655
  ```
3656
 
3657
  Any instance of `variant` at any given time either holds a value of one
3658
  of its alternative types or holds no value. When an instance of
3659
  `variant` holds a value of alternative type `T`, it means that a value
3660
  of type `T`, referred to as the `variant` object’s *contained value*, is
3661
- allocated within the storage of the `variant` object. Implementations
3662
- are not permitted to use additional storage, such as dynamic memory, to
3663
- allocate the contained value.
3664
 
3665
  All types in `Types` shall meet the *Cpp17Destructible* requirements (
3666
  [[cpp17.destructible]]).
3667
 
3668
  A program that instantiates the definition of `variant` with no template
3669
  arguments is ill-formed.
3670
 
 
 
 
3671
  #### Constructors <a id="variant.ctor">[[variant.ctor]]</a>
3672
 
3673
  In the descriptions that follow, let i be in the range \[`0`,
3674
  `sizeof...(Types)`), and `Tᵢ` be the iᵗʰ type in `Types`.
3675
 
@@ -3697,11 +4245,11 @@ equivalent to `is_nothrow_default_constructible_v<``T₀``>`.
3697
  constexpr variant(const variant& w);
3698
  ```
3699
 
3700
  *Effects:* If `w` holds a value, initializes the `variant` to hold the
3701
  same alternative as `w` and direct-initializes the contained value with
3702
- `get<j>(w)`, where `j` is `w.index()`. Otherwise, initializes the
3703
  `variant` to not hold a value.
3704
 
3705
  *Throws:* Any exception thrown by direct-initializing any `Tᵢ` for all
3706
  i.
3707
 
@@ -3716,12 +4264,12 @@ constexpr variant(variant&& w) noexcept(see below);
3716
 
3717
  *Constraints:* `is_move_constructible_v<``Tᵢ``>` is `true` for all i.
3718
 
3719
  *Effects:* If `w` holds a value, initializes the `variant` to hold the
3720
  same alternative as `w` and direct-initializes the contained value with
3721
- `get<j>(std::move(w))`, where `j` is `w.index()`. Otherwise, initializes
3722
- the `variant` to not hold a value.
3723
 
3724
  *Throws:* Any exception thrown by move-constructing any `Tᵢ` for all i.
3725
 
3726
  *Remarks:* The exception specification is equivalent to the logical of
3727
  `is_nothrow_move_constructible_v<``Tᵢ``>` for all i. If
@@ -3875,11 +4423,11 @@ Let j be `rhs.index()`.
3875
  value contained in `*this` and sets `*this` to not hold a value.
3876
  - Otherwise, if `index() == `j, assigns the value contained in `rhs` to
3877
  the value contained in `*this`.
3878
  - Otherwise, if either `is_nothrow_copy_constructible_v<``Tⱼ``>` is
3879
  `true` or `is_nothrow_move_constructible_v<``Tⱼ``>` is `false`,
3880
- equivalent to `emplace<`j`>(get<`j`>(rhs))`.
3881
  - Otherwise, equivalent to `operator=(variant(rhs))`.
3882
 
3883
  *Ensures:* `index() == rhs.index()`.
3884
 
3885
  *Returns:* `*this`.
@@ -3903,13 +4451,14 @@ Let j be `rhs.index()`.
3903
  *Effects:*
3904
 
3905
  - If neither `*this` nor `rhs` holds a value, there is no effect.
3906
  - Otherwise, if `*this` holds a value but `rhs` does not, destroys the
3907
  value contained in `*this` and sets `*this` to not hold a value.
3908
- - Otherwise, if `index() == `j, assigns `get<`j`>(std::move(rhs))` to
3909
- the value contained in `*this`.
3910
- - Otherwise, equivalent to `emplace<`j`>(get<`j`>(std::move(rhs)))`.
 
3911
 
3912
  *Returns:* `*this`.
3913
 
3914
  *Remarks:* If `is_trivially_move_constructible_v<``Tᵢ``> &&`
3915
  `is_trivially_move_assignable_v<``Tᵢ``> &&`
@@ -4107,26 +4656,27 @@ requirements [[swappable.requirements]].
4107
  *Effects:*
4108
 
4109
  - If `valueless_by_exception() && rhs.valueless_by_exception()` no
4110
  effect.
4111
  - Otherwise, if `index() == rhs.index()`, calls
4112
- `swap(get<`i`>(*this), get<`i`>(rhs))` where i is `index()`.
 
4113
  - Otherwise, exchanges values of `rhs` and `*this`.
4114
 
4115
  *Throws:* If `index() == rhs.index()`, any exception thrown by
4116
- `swap(get<`i`>(*this), get<`i`>(rhs))` with i being `index()`.
4117
- Otherwise, any exception thrown by the move constructor of `Tᵢ` or `Tⱼ`
4118
- with i being `index()` and j being `rhs.index()`.
4119
 
4120
  *Remarks:* If an exception is thrown during the call to function
4121
- `swap(get<`i`>(*this), get<`i`>(rhs))`, the states of the contained
4122
- values of `*this` and of `rhs` are determined by the exception safety
4123
- guarantee of `swap` for lvalues of `Tᵢ` with i being `index()`. If an
4124
- exception is thrown during the exchange of the values of `*this` and
4125
- `rhs`, the states of the values of `*this` and of `rhs` are determined
4126
- by the exception safety guarantee of `variant`’s move constructor. The
4127
- exception specification is equivalent to the logical of
4128
  `is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_swappable_v<``Tᵢ``>`
4129
  for all i.
4130
 
4131
  ### `variant` helper classes <a id="variant.helper">[[variant.helper]]</a>
4132
 
@@ -4157,19 +4707,19 @@ template<size_t I, class T> struct variant_alternative<I, const T>;
4157
  ```
4158
 
4159
  Let `VA` denote `variant_alternative<I, T>` of the cv-unqualified type
4160
  `T`. Then each specialization of the template meets the
4161
  *Cpp17TransformationTrait* requirements [[meta.rqmts]] with a member
4162
- typedef `type` that names the type `add_const_t<VA::type>`.
4163
 
4164
  ``` cpp
4165
  variant_alternative<I, variant<Types...>>::type
4166
  ```
4167
 
4168
  *Mandates:* `I` < `sizeof...(Types)`.
4169
 
4170
- *Type:* The type `T_I`.
4171
 
4172
  ### Value access <a id="variant.get">[[variant.get]]</a>
4173
 
4174
  ``` cpp
4175
  template<class T, class... Types>
@@ -4179,10 +4729,31 @@ template<class T, class... Types>
4179
  *Mandates:* The type `T` occurs exactly once in `Types`.
4180
 
4181
  *Returns:* `true` if `index()` is equal to the zero-based index of `T`
4182
  in `Types`.
4183
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4184
  ``` cpp
4185
  template<size_t I, class... Types>
4186
  constexpr variant_alternative_t<I, variant<Types...>>& get(variant<Types...>& v);
4187
  template<size_t I, class... Types>
4188
  constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&& v);
@@ -4243,81 +4814,83 @@ zero-based index of `T` in `Types`.
4243
  ``` cpp
4244
  template<class... Types>
4245
  constexpr bool operator==(const variant<Types...>& v, const variant<Types...>& w);
4246
  ```
4247
 
4248
- *Mandates:* `get<`i`>(v) == get<`i`>(w)` is a valid expression that is
4249
- convertible to `bool`, for all i.
4250
 
4251
  *Returns:* If `v.index() != w.index()`, `false`; otherwise if
4252
  `v.valueless_by_exception()`, `true`; otherwise
4253
- `get<`i`>(v) == get<`i`>(w)` with i being `v.index()`.
4254
 
4255
  ``` cpp
4256
  template<class... Types>
4257
  constexpr bool operator!=(const variant<Types...>& v, const variant<Types...>& w);
4258
  ```
4259
 
4260
- *Mandates:* `get<`i`>(v) != get<`i`>(w)` is a valid expression that is
4261
- convertible to `bool`, for all i.
4262
 
4263
  *Returns:* If `v.index() != w.index()`, `true`; otherwise if
4264
  `v.valueless_by_exception()`, `false`; otherwise
4265
- `get<`i`>(v) != get<`i`>(w)` with i being `v.index()`.
4266
 
4267
  ``` cpp
4268
  template<class... Types>
4269
  constexpr bool operator<(const variant<Types...>& v, const variant<Types...>& w);
4270
  ```
4271
 
4272
- *Mandates:* `get<`i`>(v) < get<`i`>(w)` is a valid expression that is
4273
- convertible to `bool`, for all i.
4274
 
4275
  *Returns:* If `w.valueless_by_exception()`, `false`; otherwise if
4276
  `v.valueless_by_exception()`, `true`; otherwise, if
4277
  `v.index() < w.index()`, `true`; otherwise if `v.index() > w.index()`,
4278
- `false`; otherwise `get<`i`>(v) < get<`i`>(w)` with i being `v.index()`.
 
4279
 
4280
  ``` cpp
4281
  template<class... Types>
4282
  constexpr bool operator>(const variant<Types...>& v, const variant<Types...>& w);
4283
  ```
4284
 
4285
- *Mandates:* `get<`i`>(v) > get<`i`>(w)` is a valid expression that is
4286
- convertible to `bool`, for all i.
4287
 
4288
  *Returns:* If `v.valueless_by_exception()`, `false`; otherwise if
4289
  `w.valueless_by_exception()`, `true`; otherwise, if
4290
  `v.index() > w.index()`, `true`; otherwise if `v.index() < w.index()`,
4291
- `false`; otherwise `get<`i`>(v) > get<`i`>(w)` with i being `v.index()`.
 
4292
 
4293
  ``` cpp
4294
  template<class... Types>
4295
  constexpr bool operator<=(const variant<Types...>& v, const variant<Types...>& w);
4296
  ```
4297
 
4298
- *Mandates:* `get<`i`>(v) <= get<`i`>(w)` is a valid expression that is
4299
- convertible to `bool`, for all i.
4300
 
4301
  *Returns:* If `v.valueless_by_exception()`, `true`; otherwise if
4302
  `w.valueless_by_exception()`, `false`; otherwise, if
4303
  `v.index() < w.index()`, `true`; otherwise if `v.index() > w.index()`,
4304
- `false`; otherwise `get<`i`>(v) <= get<`i`>(w)` with i being
4305
  `v.index()`.
4306
 
4307
  ``` cpp
4308
  template<class... Types>
4309
  constexpr bool operator>=(const variant<Types...>& v, const variant<Types...>& w);
4310
  ```
4311
 
4312
- *Mandates:* `get<`i`>(v) >= get<`i`>(w)` is a valid expression that is
4313
- convertible to `bool`, for all i.
4314
 
4315
  *Returns:* If `w.valueless_by_exception()`, `true`; otherwise if
4316
  `v.valueless_by_exception()`, `false`; otherwise, if
4317
  `v.index() > w.index()`, `true`; otherwise if `v.index() < w.index()`,
4318
- `false`; otherwise `get<`i`>(v) >= get<`i`>(w)` with i being
4319
  `v.index()`.
4320
 
4321
  ``` cpp
4322
  template<class... Types> requires (three_way_comparable<Types> && ...)
4323
  constexpr common_comparison_category_t<compare_three_way_result_t<Types>...>
@@ -4330,11 +4903,11 @@ template<class... Types> requires (three_way_comparable<Types> && ...)
4330
  if (v.valueless_by_exception() && w.valueless_by_exception())
4331
  return strong_ordering::equal;
4332
  if (v.valueless_by_exception()) return strong_ordering::less;
4333
  if (w.valueless_by_exception()) return strong_ordering::greater;
4334
  if (auto c = v.index() <=> w.index(); c != 0) return c;
4335
- return get<i>(v) <=> get<i>(w);
4336
  ```
4337
 
4338
  with i being `v.index()`.
4339
 
4340
  ### Visitation <a id="variant.visit">[[variant.visit]]</a>
@@ -4349,17 +4922,17 @@ template<class R, class Visitor, class... Variants>
4349
  Let *as-variant* denote the following exposition-only function
4350
  templates:
4351
 
4352
  ``` cpp
4353
  template<class... Ts>
4354
- auto&& as-variant(variant<Ts...>& var) { return var; }
4355
  template<class... Ts>
4356
- auto&& as-variant(const variant<Ts...>& var) { return var; }
4357
  template<class... Ts>
4358
- auto&& as-variant(variant<Ts...>&& var) { return std::move(var); }
4359
  template<class... Ts>
4360
- auto&& as-variant(const variant<Ts...>&& var) { return std::move(var); }
4361
  ```
4362
 
4363
  Let n be `sizeof...(Variants)`. For each 0 ≤ i < n, let `Vᵢ` denote the
4364
  type
4365
  `decltype(`*`as-variant`*`(``std::forward<``Variantsᵢ``>(``varsᵢ``)``))`.
@@ -4371,17 +4944,17 @@ Let `V` denote the pack of types `Vᵢ`.
4371
  Let m be a pack of n values of type `size_t`. Such a pack is valid if
4372
  0 ≤ mᵢ < `variant_size_v<remove_reference_t<Vᵢ``>>` for all 0 ≤ i < n.
4373
  For each valid pack m, let e(m) denote the expression:
4374
 
4375
  ``` cpp
4376
- INVOKE(std::forward<Visitor>(vis), get<m>(std::forward<V>(vars))...) // see [func.require]
4377
  ```
4378
 
4379
  for the first form and
4380
 
4381
  ``` cpp
4382
- INVOKE<R>(std::forward<Visitor>(vis), get<m>(std::forward<V>(vars))...) // see [func.require]
4383
  ```
4384
 
4385
  for the second form.
4386
 
4387
  *Mandates:* For each valid pack m, e(m) is a valid expression. All such
@@ -4397,10 +4970,37 @@ expressions are of the same type and value category.
4397
  *Complexity:* For n ≤ 1, the invocation of the callable object is
4398
  implemented in constant time, i.e., for n = 1, it does not depend on the
4399
  number of alternative types of `V₀`. For n > 1, the invocation of the
4400
  callable object has no complexity requirements.
4401
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4402
  ### Class `monostate` <a id="variant.monostate">[[variant.monostate]]</a>
4403
 
4404
  ``` cpp
4405
  struct monostate{};
4406
  ```
@@ -4440,23 +5040,24 @@ for all i.
4440
  ``` cpp
4441
  namespace std {
4442
  class bad_variant_access : public exception {
4443
  public:
4444
  // see [exception] for the specification of the special member functions
4445
- const char* what() const noexcept override;
4446
  };
4447
  }
4448
  ```
4449
 
4450
  Objects of type `bad_variant_access` are thrown to report invalid
4451
  accesses to the value of a `variant` object.
4452
 
4453
  ``` cpp
4454
- const char* what() const noexcept override;
4455
  ```
4456
 
4457
- *Returns:* An *implementation-defined* NTBS.
 
4458
 
4459
  ### Hash support <a id="variant.hash">[[variant.hash]]</a>
4460
 
4461
  ``` cpp
4462
  template<class... Types> struct hash<variant<Types...>>;
@@ -4904,12 +5505,15 @@ template<class T>
4904
  const T* any_cast(const any* operand) noexcept;
4905
  template<class T>
4906
  T* any_cast(any* operand) noexcept;
4907
  ```
4908
 
4909
- *Returns:* If `operand != nullptr && operand->type() == typeid(T)`, a
4910
- pointer to the object contained by `operand`; otherwise, `nullptr`.
 
 
 
4911
 
4912
  [*Example 2*:
4913
 
4914
  ``` cpp
4915
  bool is_string(const any& operand) {
@@ -4919,20 +5523,21 @@ bool is_string(const any& operand) {
4919
 
4920
  — *end example*]
4921
 
4922
  ## Expected objects <a id="expected">[[expected]]</a>
4923
 
4924
- ### In general <a id="expected.general">[[expected.general]]</a>
4925
 
4926
  Subclause [[expected]] describes the class template `expected` that
4927
  represents expected objects. An `expected<T, E>` object holds an object
4928
- of type `T` or an object of type `unexpected<E>` and manages the
4929
- lifetime of the contained objects.
4930
 
4931
  ### Header `<expected>` synopsis <a id="expected.syn">[[expected.syn]]</a>
4932
 
4933
  ``` cpp
 
4934
  namespace std {
4935
  // [expected.unexpected], class template unexpected
4936
  template<class E> class unexpected;
4937
 
4938
  // [expected.bad], class template bad_expected_access
@@ -4946,14 +5551,14 @@ namespace std {
4946
  explicit unexpect_t() = default;
4947
  };
4948
  inline constexpr unexpect_t unexpect{};
4949
 
4950
  // [expected.expected], class template expected
4951
- template<class T, class E> class expected;
4952
 
4953
  // [expected.void], partial specialization of expected for void types
4954
- template<class T, class E> requires is_void_v<T> class expected<T, E>;
4955
  }
4956
  ```
4957
 
4958
  ### Class template `unexpected` <a id="expected.unexpected">[[expected.unexpected]]</a>
4959
 
@@ -5100,16 +5705,16 @@ its result is convertible to `bool`.
5100
  ``` cpp
5101
  namespace std {
5102
  template<class E>
5103
  class bad_expected_access : public bad_expected_access<void> {
5104
  public:
5105
- explicit bad_expected_access(E);
5106
- const char* what() const noexcept override;
5107
- E& error() & noexcept;
5108
- const E& error() const & noexcept;
5109
- E&& error() && noexcept;
5110
- const E&& error() const && noexcept;
5111
 
5112
  private:
5113
  E unex; // exposition only
5114
  };
5115
  }
@@ -5119,60 +5724,62 @@ The class template `bad_expected_access` defines the type of objects
5119
  thrown as exceptions to report the situation where an attempt is made to
5120
  access the value of an `expected<T, E>` object for which `has_value()`
5121
  is `false`.
5122
 
5123
  ``` cpp
5124
- explicit bad_expected_access(E e);
5125
  ```
5126
 
5127
  *Effects:* Initializes *unex* with `std::move(e)`.
5128
 
5129
  ``` cpp
5130
- const E& error() const & noexcept;
5131
- E& error() & noexcept;
5132
  ```
5133
 
5134
  *Returns:* *unex*.
5135
 
5136
  ``` cpp
5137
- E&& error() && noexcept;
5138
- const E&& error() const && noexcept;
5139
  ```
5140
 
5141
  *Returns:* `std::move(`*`unex`*`)`.
5142
 
5143
  ``` cpp
5144
- const char* what() const noexcept override;
5145
  ```
5146
 
5147
- *Returns:* An implementation-defined NTBS.
 
5148
 
5149
  ### Class template specialization `bad_expected_access<void>` <a id="expected.bad.void">[[expected.bad.void]]</a>
5150
 
5151
  ``` cpp
5152
  namespace std {
5153
  template<>
5154
  class bad_expected_access<void> : public exception {
5155
  protected:
5156
- bad_expected_access() noexcept;
5157
- bad_expected_access(const bad_expected_access&);
5158
- bad_expected_access(bad_expected_access&&);
5159
- bad_expected_access& operator=(const bad_expected_access&);
5160
- bad_expected_access& operator=(bad_expected_access&&);
5161
- ~bad_expected_access();
5162
 
5163
  public:
5164
- const char* what() const noexcept override;
5165
  };
5166
  }
5167
  ```
5168
 
5169
  ``` cpp
5170
- const char* what() const noexcept override;
5171
  ```
5172
 
5173
- *Returns:* An implementation-defined NTBS.
 
5174
 
5175
  ### Class template `expected` <a id="expected.expected">[[expected.expected]]</a>
5176
 
5177
  #### General <a id="expected.object.general">[[expected.object.general]]</a>
5178
 
@@ -5195,11 +5802,11 @@ namespace std {
5195
  template<class U, class G>
5196
  constexpr explicit(see below) expected(const expected<U, G>&);
5197
  template<class U, class G>
5198
  constexpr explicit(see below) expected(expected<U, G>&&);
5199
 
5200
- template<class U = T>
5201
  constexpr explicit(see below) expected(U&& v);
5202
 
5203
  template<class G>
5204
  constexpr explicit(see below) expected(const unexpected<G>&);
5205
  template<class G>
@@ -5218,11 +5825,11 @@ namespace std {
5218
  constexpr ~expected();
5219
 
5220
  // [expected.object.assign], assignment
5221
  constexpr expected& operator=(const expected&);
5222
  constexpr expected& operator=(expected&&) noexcept(see below);
5223
- template<class U = T> constexpr expected& operator=(U&&);
5224
  template<class G>
5225
  constexpr expected& operator=(const unexpected<G>&);
5226
  template<class G>
5227
  constexpr expected& operator=(unexpected<G>&&);
5228
 
@@ -5242,20 +5849,20 @@ namespace std {
5242
  constexpr T& operator*() & noexcept;
5243
  constexpr const T&& operator*() const && noexcept;
5244
  constexpr T&& operator*() && noexcept;
5245
  constexpr explicit operator bool() const noexcept;
5246
  constexpr bool has_value() const noexcept;
5247
- constexpr const T& value() const &;
5248
- constexpr T& value() &;
5249
- constexpr const T&& value() const &&;
5250
- constexpr T&& value() &&;
5251
  constexpr const E& error() const & noexcept;
5252
  constexpr E& error() & noexcept;
5253
  constexpr const E&& error() const && noexcept;
5254
  constexpr E&& error() && noexcept;
5255
- template<class U> constexpr T value_or(U&&) const &;
5256
- template<class U> constexpr T value_or(U&&) &&;
5257
  template<class G = E> constexpr E error_or(G&&) const &;
5258
  template<class G = E> constexpr E error_or(G&&) &&;
5259
 
5260
  // [expected.object.monadic], monadic operations
5261
  template<class F> constexpr auto and_then(F&& f) &;
@@ -5292,15 +5899,13 @@ namespace std {
5292
  };
5293
  }
5294
  ```
5295
 
5296
  Any object of type `expected<T, E>` either contains a value of type `T`
5297
- or a value of type `E` within its own storage. Implementations are not
5298
- permitted to use additional storage, such as dynamic memory, to allocate
5299
- the object of type `T` or the object of type `E`. Member *`has_val`*
5300
- indicates whether the `expected<T, E>` object contains an object of type
5301
- `T`.
5302
 
5303
  A type `T` is a *valid value type for `expected`*, if `remove_cv_t<T>`
5304
  is `void` or a complete non-array object type that is not `in_place_t`,
5305
  `unexpect_t`, or a specialization of `unexpected`. A program which
5306
  instantiates class template `expected<T, E>` with an argument `T` that
@@ -5416,18 +6021,19 @@ with `std::forward<GF>(rhs.error())`.
5416
 
5417
  *Remarks:* The expression inside `explicit` is equivalent to
5418
  `!is_convertible_v<UF, T> || !is_convertible_v<GF, E>`.
5419
 
5420
  ``` cpp
5421
- template<class U = T>
5422
  constexpr explicit(!is_convertible_v<U, T>) expected(U&& v);
5423
  ```
5424
 
5425
  *Constraints:*
5426
 
5427
  - `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`; and
5428
- - `is_same_v<expected, remove_cvref_t<U>>` is `false`; and
 
5429
  - `remove_cvref_t<U>` is not a specialization of `unexpected`; and
5430
  - `is_constructible_v<T, U>` is `true`; and
5431
  - if `T` is cv `bool`, `remove_cvref_t<U>` is not a specialization of
5432
  `expected`.
5433
 
@@ -5527,11 +6133,12 @@ destroys *unex*.
5527
  `is_trivially_destructible_v<E>` is `true`, then this destructor is a
5528
  trivial destructor.
5529
 
5530
  #### Assignment <a id="expected.object.assign">[[expected.object.assign]]</a>
5531
 
5532
- This subclause makes use of the following exposition-only function:
 
5533
 
5534
  ``` cpp
5535
  template<class T, class U, class... Args>
5536
  constexpr void reinit-expected(T& newval, U& oldval, Args&&... args) { // exposition only
5537
  if constexpr (is_nothrow_constructible_v<T, Args...>) {
@@ -5624,11 +6231,11 @@ Then, if no exception was thrown, equivalent to:
5624
  is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T> &&
5625
  is_nothrow_move_assignable_v<E> && is_nothrow_move_constructible_v<E>
5626
  ```
5627
 
5628
  ``` cpp
5629
- template<class U = T>
5630
  constexpr expected& operator=(U&& v);
5631
  ```
5632
 
5633
  *Constraints:*
5634
 
@@ -5740,12 +6347,12 @@ constexpr void swap(expected& rhs) noexcept(see below);
5740
 
5741
  | \topline | `this->has_value()` | `!this->has_value()` |
5742
  | -------- | ------------------- | -------------------- |
5743
 
5744
 
5745
- For the case where `rhs.value()` is `false` and `this->has_value()` is
5746
- `true`, equivalent to:
5747
 
5748
  ``` cpp
5749
  if constexpr (is_nothrow_move_constructible_v<E>) {
5750
  E tmp(std::move(rhs.unex));
5751
  destroy_at(addressof(rhs.unex));
@@ -5793,29 +6400,29 @@ friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)
5793
  ``` cpp
5794
  constexpr const T* operator->() const noexcept;
5795
  constexpr T* operator->() noexcept;
5796
  ```
5797
 
5798
- *Preconditions:* `has_value()` is `true`.
5799
 
5800
  *Returns:* `addressof(`*`val`*`)`.
5801
 
5802
  ``` cpp
5803
  constexpr const T& operator*() const & noexcept;
5804
  constexpr T& operator*() & noexcept;
5805
  ```
5806
 
5807
- *Preconditions:* `has_value()` is `true`.
5808
 
5809
  *Returns:* *val*.
5810
 
5811
  ``` cpp
5812
  constexpr T&& operator*() && noexcept;
5813
  constexpr const T&& operator*() const && noexcept;
5814
  ```
5815
 
5816
- *Preconditions:* `has_value()` is `true`.
5817
 
5818
  *Returns:* `std::move(`*`val`*`)`.
5819
 
5820
  ``` cpp
5821
  constexpr explicit operator bool() const noexcept;
@@ -5852,34 +6459,34 @@ constexpr const T&& value() const &&;
5852
  ``` cpp
5853
  constexpr const E& error() const & noexcept;
5854
  constexpr E& error() & noexcept;
5855
  ```
5856
 
5857
- *Preconditions:* `has_value()` is `false`.
5858
 
5859
  *Returns:* *unex*.
5860
 
5861
  ``` cpp
5862
  constexpr E&& error() && noexcept;
5863
  constexpr const E&& error() const && noexcept;
5864
  ```
5865
 
5866
- *Preconditions:* `has_value()` is `false`.
5867
 
5868
  *Returns:* `std::move(`*`unex`*`)`.
5869
 
5870
  ``` cpp
5871
- template<class U> constexpr T value_or(U&& v) const &;
5872
  ```
5873
 
5874
  *Mandates:* `is_copy_constructible_v<T>` is `true` and
5875
  `is_convertible_v<U, T>` is `true`.
5876
 
5877
  *Returns:* `has_value() ? **this : static_cast<T>(std::forward<U>(v))`.
5878
 
5879
  ``` cpp
5880
- template<class U> constexpr T value_or(U&& v) &&;
5881
  ```
5882
 
5883
  *Mandates:* `is_move_constructible_v<T>` is `true` and
5884
  `is_convertible_v<U, T>` is `true`.
5885
 
@@ -5911,45 +6518,45 @@ template<class G = E> constexpr E error_or(G&& e) &&;
5911
  ``` cpp
5912
  template<class F> constexpr auto and_then(F&& f) &;
5913
  template<class F> constexpr auto and_then(F&& f) const &;
5914
  ```
5915
 
5916
- Let `U` be `remove_cvref_t<invoke_result_t<F, decltype(value())>>`.
5917
 
5918
  *Constraints:* `is_constructible_v<E, decltype(error())>` is `true`.
5919
 
5920
  *Mandates:* `U` is a specialization of `expected` and
5921
- `is_same_v<U::error_type, E>` is `true`.
5922
 
5923
  *Effects:* Equivalent to:
5924
 
5925
  ``` cpp
5926
  if (has_value())
5927
- return invoke(std::forward<F>(f), value());
5928
  else
5929
  return U(unexpect, error());
5930
  ```
5931
 
5932
  ``` cpp
5933
  template<class F> constexpr auto and_then(F&& f) &&;
5934
  template<class F> constexpr auto and_then(F&& f) const &&;
5935
  ```
5936
 
5937
  Let `U` be
5938
- `remove_cvref_t<invoke_result_t<F, decltype(std::move(value()))>>`.
5939
 
5940
  *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
5941
  `true`.
5942
 
5943
  *Mandates:* `U` is a specialization of `expected` and
5944
- `is_same_v<U::error_type, E>` is `true`.
5945
 
5946
  *Effects:* Equivalent to:
5947
 
5948
  ``` cpp
5949
  if (has_value())
5950
- return invoke(std::forward<F>(f), std::move(value()));
5951
  else
5952
  return U(unexpect, std::move(error()));
5953
  ```
5954
 
5955
  ``` cpp
@@ -5957,20 +6564,20 @@ template<class F> constexpr auto or_else(F&& f) &;
5957
  template<class F> constexpr auto or_else(F&& f) const &;
5958
  ```
5959
 
5960
  Let `G` be `remove_cvref_t<invoke_result_t<F, decltype(error())>>`.
5961
 
5962
- *Constraints:* `is_constructible_v<T, decltype(value())>` is `true`.
5963
 
5964
  *Mandates:* `G` is a specialization of `expected` and
5965
- `is_same_v<G::value_type, T>` is `true`.
5966
 
5967
  *Effects:* Equivalent to:
5968
 
5969
  ``` cpp
5970
  if (has_value())
5971
- return G(in_place, value());
5972
  else
5973
  return invoke(std::forward<F>(f), error());
5974
  ```
5975
 
5976
  ``` cpp
@@ -5979,39 +6586,39 @@ template<class F> constexpr auto or_else(F&& f) const &&;
5979
  ```
5980
 
5981
  Let `G` be
5982
  `remove_cvref_t<invoke_result_t<F, decltype(std::move(error()))>>`.
5983
 
5984
- *Constraints:* `is_constructible_v<T, decltype(std::move(value()))>` is
5985
- `true`.
5986
 
5987
  *Mandates:* `G` is a specialization of `expected` and
5988
- `is_same_v<G::value_type, T>` is `true`.
5989
 
5990
  *Effects:* Equivalent to:
5991
 
5992
  ``` cpp
5993
  if (has_value())
5994
- return G(in_place, std::move(value()));
5995
  else
5996
  return invoke(std::forward<F>(f), std::move(error()));
5997
  ```
5998
 
5999
  ``` cpp
6000
  template<class F> constexpr auto transform(F&& f) &;
6001
  template<class F> constexpr auto transform(F&& f) const &;
6002
  ```
6003
 
6004
- Let `U` be `remove_cv_t<invoke_result_t<F, decltype(value())>>`.
6005
 
6006
  *Constraints:* `is_constructible_v<E, decltype(error())>` is `true`.
6007
 
6008
  *Mandates:* `U` is a valid value type for `expected`. If `is_void_v<U>`
6009
  is `false`, the declaration
6010
 
6011
  ``` cpp
6012
- U u(invoke(std::forward<F>(f), value()));
6013
  ```
6014
 
6015
  is well-formed.
6016
 
6017
  *Effects:*
@@ -6019,53 +6626,54 @@ is well-formed.
6019
  - If `has_value()` is `false`, returns
6020
  `expected<U, E>(unexpect, error())`.
6021
  - Otherwise, if `is_void_v<U>` is `false`, returns an `expected<U, E>`
6022
  object whose *has_val* member is `true` and *val* member is
6023
  direct-non-list-initialized with
6024
- `invoke(std::forward<F>(f), value())`.
6025
- - Otherwise, evaluates `invoke(std::forward<F>(f), value())` and then
6026
  returns `expected<U, E>()`.
6027
 
6028
  ``` cpp
6029
  template<class F> constexpr auto transform(F&& f) &&;
6030
  template<class F> constexpr auto transform(F&& f) const &&;
6031
  ```
6032
 
6033
  Let `U` be
6034
- `remove_cv_t<invoke_result_t<F, decltype(std::move(value()))>>`.
6035
 
6036
  *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
6037
  `true`.
6038
 
6039
  *Mandates:* `U` is a valid value type for `expected`. If `is_void_v<U>`
6040
  is `false`, the declaration
6041
 
6042
  ``` cpp
6043
- U u(invoke(std::forward<F>(f), std::move(value())));
6044
  ```
6045
 
6046
- is well-formed for some invented variable `u`.
6047
 
6048
  *Effects:*
6049
 
6050
  - If `has_value()` is `false`, returns
6051
  `expected<U, E>(unexpect, std::move(error()))`.
6052
  - Otherwise, if `is_void_v<U>` is `false`, returns an `expected<U, E>`
6053
  object whose *has_val* member is `true` and *val* member is
6054
  direct-non-list-initialized with
6055
- `invoke(std::forward<F>(f), std::move(value()))`.
6056
- - Otherwise, evaluates `invoke(std::forward<F>(f), std::move(value()))`
6057
- and then returns `expected<U, E>()`.
 
6058
 
6059
  ``` cpp
6060
  template<class F> constexpr auto transform_error(F&& f) &;
6061
  template<class F> constexpr auto transform_error(F&& f) const &;
6062
  ```
6063
 
6064
  Let `G` be `remove_cv_t<invoke_result_t<F, decltype(error())>>`.
6065
 
6066
- *Constraints:* `is_constructible_v<T, decltype(value())>` is `true`.
6067
 
6068
  *Mandates:* `G` is a valid template argument for `unexpected`
6069
  [[expected.un.general]] and the declaration
6070
 
6071
  ``` cpp
@@ -6073,11 +6681,11 @@ G g(invoke(std::forward<F>(f), error()));
6073
  ```
6074
 
6075
  is well-formed.
6076
 
6077
  *Returns:* If `has_value()` is `true`,
6078
- `expected<T, G>(in_place, value())`; otherwise, an `expected<T, G>`
6079
  object whose *has_val* member is `false` and *unex* member is
6080
  direct-non-list-initialized with `invoke(std::forward<F>(f), error())`.
6081
 
6082
  ``` cpp
6083
  template<class F> constexpr auto transform_error(F&& f) &&;
@@ -6085,12 +6693,12 @@ template<class F> constexpr auto transform_error(F&& f) const &&;
6085
  ```
6086
 
6087
  Let `G` be
6088
  `remove_cv_t<invoke_result_t<F, decltype(std::move(error()))>>`.
6089
 
6090
- *Constraints:* `is_constructible_v<T, decltype(std::move(value()))>` is
6091
- `true`.
6092
 
6093
  *Mandates:* `G` is a valid template argument for `unexpected`
6094
  [[expected.un.general]] and the declaration
6095
 
6096
  ``` cpp
@@ -6098,11 +6706,11 @@ G g(invoke(std::forward<F>(f), std::move(error())));
6098
  ```
6099
 
6100
  is well-formed.
6101
 
6102
  *Returns:* If `has_value()` is `true`,
6103
- `expected<T, G>(in_place, std::move(value()))`; otherwise, an
6104
  `expected<T, G>` object whose *has_val* member is `false` and *unex*
6105
  member is direct-non-list-initialized with
6106
  `invoke(std::forward<F>(f), std::move(error()))`.
6107
 
6108
  #### Equality operators <a id="expected.object.eq">[[expected.object.eq]]</a>
@@ -6110,34 +6718,35 @@ member is direct-non-list-initialized with
6110
  ``` cpp
6111
  template<class T2, class E2> requires (!is_void_v<T2>)
6112
  friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
6113
  ```
6114
 
6115
- *Mandates:* The expressions `*x == *y` and `x.error() == y.error()` are
6116
- well-formed and their results are convertible to `bool`.
6117
 
6118
  *Returns:* If `x.has_value()` does not equal `y.has_value()`, `false`;
6119
  otherwise if `x.has_value()` is `true`, `*x == *y`; otherwise
6120
  `x.error() == y.error()`.
6121
 
6122
  ``` cpp
6123
  template<class T2> friend constexpr bool operator==(const expected& x, const T2& v);
6124
  ```
6125
 
6126
- *Mandates:* The expression `*x == v` is well-formed and its result is
6127
- convertible to `bool`.
 
6128
 
6129
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
6130
 
6131
  *Returns:* `x.has_value() && static_cast<bool>(*x == v)`.
6132
 
6133
  ``` cpp
6134
  template<class E2> friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
6135
  ```
6136
 
6137
- *Mandates:* The expression `x.error() == e.error()` is well-formed and
6138
- its result is convertible to `bool`.
6139
 
6140
  *Returns:*
6141
  `!x.has_value() && static_cast<bool>(x.error() == e.error())`.
6142
 
6143
  ### Partial specialization of `expected` for `void` types <a id="expected.void">[[expected.void]]</a>
@@ -6194,12 +6803,12 @@ public:
6194
 
6195
  // [expected.void.obs], observers
6196
  constexpr explicit operator bool() const noexcept;
6197
  constexpr bool has_value() const noexcept;
6198
  constexpr void operator*() const noexcept;
6199
- constexpr void value() const &;
6200
- constexpr void value() &&;
6201
  constexpr const E& error() const & noexcept;
6202
  constexpr E& error() & noexcept;
6203
  constexpr const E&& error() const && noexcept;
6204
  constexpr E&& error() && noexcept;
6205
  template<class G = E> constexpr E error_or(G&&) const &;
@@ -6236,15 +6845,13 @@ private:
6236
  };
6237
  };
6238
  ```
6239
 
6240
  Any object of type `expected<T, E>` either represents a value of type
6241
- `T`, or contains a value of type `E` within its own storage.
6242
- Implementations are not permitted to use additional storage, such as
6243
- dynamic memory, to allocate the object of type `E`. Member *`has_val`*
6244
- indicates whether the `expected<T, E>` object represents a value of type
6245
- `T`.
6246
 
6247
  A program that instantiates the definition of the template
6248
  `expected<T, E>` with a type for the `E` parameter that is not a valid
6249
  template argument for `unexpected` is ill-formed.
6250
 
@@ -6409,10 +7016,13 @@ constexpr expected& operator=(const expected& rhs);
6409
 
6410
  ``` cpp
6411
  constexpr expected& operator=(expected&& rhs) noexcept(see below);
6412
  ```
6413
 
 
 
 
6414
  *Effects:*
6415
 
6416
  - If `this->has_value() && rhs.has_value()` is `true`, no effects.
6417
  - Otherwise, if `this->has_value()` is `true`, equivalent to:
6418
  ``` cpp
@@ -6426,13 +7036,10 @@ constexpr expected& operator=(expected&& rhs) noexcept(see below);
6426
  *Returns:* `*this`.
6427
 
6428
  *Remarks:* The exception specification is equivalent to
6429
  `is_nothrow_move_constructible_v<E> && is_nothrow_move_assignable_v<E>`.
6430
 
6431
- This operator is defined as deleted unless `is_move_constructible_v<E>`
6432
- is `true` and `is_move_assignable_v<E>` is `true`.
6433
-
6434
  ``` cpp
6435
  template<class G>
6436
  constexpr expected& operator=(const unexpected<G>& e);
6437
  template<class G>
6438
  constexpr expected& operator=(unexpected<G>&& e);
@@ -6477,12 +7084,12 @@ constexpr void swap(expected& rhs) noexcept(see below);
6477
 
6478
  | \topline | `this->has_value()` | `!this->has_value()` |
6479
  | -------- | ------------------- | -------------------- |
6480
 
6481
 
6482
- For the case where `rhs.value()` is `false` and `this->has_value()` is
6483
- `true`, equivalent to:
6484
 
6485
  ``` cpp
6486
  construct_at(addressof(unex), std::move(rhs.unex));
6487
  destroy_at(addressof(rhs.unex));
6488
  has_val = false;
@@ -6511,40 +7118,45 @@ constexpr bool has_value() const noexcept;
6511
 
6512
  ``` cpp
6513
  constexpr void operator*() const noexcept;
6514
  ```
6515
 
6516
- *Preconditions:* `has_value()` is `true`.
6517
 
6518
  ``` cpp
6519
  constexpr void value() const &;
6520
  ```
6521
 
 
 
6522
  *Throws:* `bad_expected_access(error())` if `has_value()` is `false`.
6523
 
6524
  ``` cpp
6525
  constexpr void value() &&;
6526
  ```
6527
 
 
 
 
6528
  *Throws:* `bad_expected_access(std::move(error()))` if `has_value()` is
6529
  `false`.
6530
 
6531
  ``` cpp
6532
  constexpr const E& error() const & noexcept;
6533
  constexpr E& error() & noexcept;
6534
  ```
6535
 
6536
- *Preconditions:* `has_value()` is `false`.
6537
 
6538
  *Returns:* *unex*.
6539
 
6540
  ``` cpp
6541
  constexpr E&& error() && noexcept;
6542
  constexpr const E&& error() const && noexcept;
6543
  ```
6544
 
6545
- *Preconditions:* `has_value()` is `false`.
6546
 
6547
  *Returns:* `std::move(`*`unex`*`)`.
6548
 
6549
  ``` cpp
6550
  template<class G = E> constexpr E error_or(G&& e) const &;
@@ -6576,11 +7188,11 @@ template<class F> constexpr auto and_then(F&& f) const &;
6576
  Let `U` be `remove_cvref_t<invoke_result_t<F>>`.
6577
 
6578
  *Constraints:* `is_constructible_v<E, decltype(error())>>` is `true`.
6579
 
6580
  *Mandates:* `U` is a specialization of `expected` and
6581
- `is_same_v<U::error_type, E>` is `true`.
6582
 
6583
  *Effects:* Equivalent to:
6584
 
6585
  ``` cpp
6586
  if (has_value())
@@ -6598,11 +7210,11 @@ Let `U` be `remove_cvref_t<invoke_result_t<F>>`.
6598
 
6599
  *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
6600
  `true`.
6601
 
6602
  *Mandates:* `U` is a specialization of `expected` and
6603
- `is_same_v<U::error_type, E>` is `true`.
6604
 
6605
  *Effects:* Equivalent to:
6606
 
6607
  ``` cpp
6608
  if (has_value())
@@ -6617,11 +7229,11 @@ template<class F> constexpr auto or_else(F&& f) const &;
6617
  ```
6618
 
6619
  Let `G` be `remove_cvref_t<invoke_result_t<F, decltype(error())>>`.
6620
 
6621
  *Mandates:* `G` is a specialization of `expected` and
6622
- `is_same_v<G::value_type, T>` is `true`.
6623
 
6624
  *Effects:* Equivalent to:
6625
 
6626
  ``` cpp
6627
  if (has_value())
@@ -6637,11 +7249,11 @@ template<class F> constexpr auto or_else(F&& f) const &&;
6637
 
6638
  Let `G` be
6639
  `remove_cvref_t<invoke_result_t<F, decltype(std::move(error()))>>`.
6640
 
6641
  *Mandates:* `G` is a specialization of `expected` and
6642
- `is_same_v<G::value_type, T>` is `true`.
6643
 
6644
  *Effects:* Equivalent to:
6645
 
6646
  ``` cpp
6647
  if (has_value())
@@ -6755,23 +7367,23 @@ member is direct-non-list-initialized with
6755
  ``` cpp
6756
  template<class T2, class E2> requires is_void_v<T2>
6757
  friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
6758
  ```
6759
 
6760
- *Mandates:* The expression `x.error() == y.error()` is well-formed and
6761
- its result is convertible to `bool`.
6762
 
6763
  *Returns:* If `x.has_value()` does not equal `y.has_value()`, `false`;
6764
  otherwise `x.has_value() || static_cast<bool>(x.error() == y.error())`.
6765
 
6766
  ``` cpp
6767
  template<class E2>
6768
  friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
6769
  ```
6770
 
6771
- *Mandates:* The expression `x.error() == e.error()` is well-formed and
6772
- its result is convertible to `bool`.
6773
 
6774
  *Returns:*
6775
  `!x.has_value() && static_cast<bool>(x.error() == e.error())`.
6776
 
6777
  ## Bitsets <a id="bitset">[[bitset]]</a>
@@ -6813,13 +7425,10 @@ namespace std {
6813
  namespace std {
6814
  template<size_t N> class bitset {
6815
  public:
6816
  // bit reference
6817
  class reference {
6818
- friend class bitset;
6819
- constexpr reference() noexcept;
6820
-
6821
  public:
6822
  constexpr reference(const reference&) = default;
6823
  constexpr ~reference();
6824
  constexpr reference& operator=(bool x) noexcept; // for b[i] = x;
6825
  constexpr reference& operator=(const reference&) noexcept; // for b[i] = b[j];
@@ -6837,14 +7446,22 @@ namespace std {
6837
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
6838
  typename basic_string<charT, traits, Allocator>::size_type n
6839
  = basic_string<charT, traits, Allocator>::npos,
6840
  charT zero = charT('0'),
6841
  charT one = charT('1'));
 
 
 
 
 
 
 
 
6842
  template<class charT>
6843
  constexpr explicit bitset(
6844
  const charT* str,
6845
- typename basic_string<charT>::size_type n = basic_string<charT>::npos,
6846
  charT zero = charT('0'),
6847
  charT one = charT('1'));
6848
 
6849
  // [bitset.members], bitset operations
6850
  constexpr bitset& operator&=(const bitset& rhs) noexcept;
@@ -6936,10 +7553,18 @@ template<class charT, class traits, class Allocator>
6936
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
6937
  typename basic_string<charT, traits, Allocator>::size_type n
6938
  = basic_string<charT, traits, Allocator>::npos,
6939
  charT zero = charT('0'),
6940
  charT one = charT('1'));
 
 
 
 
 
 
 
 
6941
  ```
6942
 
6943
  *Effects:* Determines the effective length `rlen` of the initializing
6944
  string as the smaller of `n` and `str.size() - pos`. Initializes the
6945
  first `M` bit positions to values determined from the corresponding
@@ -6961,21 +7586,21 @@ other than `zero` or `one`.
6961
 
6962
  ``` cpp
6963
  template<class charT>
6964
  constexpr explicit bitset(
6965
  const charT* str,
6966
- typename basic_string<charT>::size_type n = basic_string<charT>::npos,
6967
  charT zero = charT('0'),
6968
  charT one = charT('1'));
6969
  ```
6970
 
6971
  *Effects:* As if by:
6972
 
6973
  ``` cpp
6974
- bitset(n == basic_string<charT>::npos
6975
- ? basic_string<charT>(str)
6976
- : basic_string<charT>(str, n),
6977
  0, n, zero, one)
6978
  ```
6979
 
6980
  #### Members <a id="bitset.members">[[bitset.members]]</a>
6981
 
@@ -7113,22 +7738,22 @@ position.
7113
 
7114
  ``` cpp
7115
  constexpr bool operator[](size_t pos) const;
7116
  ```
7117
 
7118
- *Preconditions:* `pos` is valid.
7119
 
7120
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
7121
  one, otherwise `false`.
7122
 
7123
  *Throws:* Nothing.
7124
 
7125
  ``` cpp
7126
  constexpr bitset::reference operator[](size_t pos);
7127
  ```
7128
 
7129
- *Preconditions:* `pos` is valid.
7130
 
7131
  *Returns:* An object of type `bitset::reference` such that
7132
  `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
7133
  equivalent to `this->set(pos, val)`.
7134
 
@@ -7396,16 +8021,21 @@ namespace std {
7396
  // [func.identity], identity
7397
  struct identity; // freestanding
7398
 
7399
  // [func.not.fn], function template not_fn
7400
  template<class F> constexpr unspecified not_fn(F&& f); // freestanding
 
7401
 
7402
  // [func.bind.partial], function templates bind_front and bind_back
7403
  template<class F, class... Args>
7404
  constexpr unspecified bind_front(F&&, Args&&...); // freestanding
 
 
7405
  template<class F, class... Args>
7406
  constexpr unspecified bind_back(F&&, Args&&...); // freestanding
 
 
7407
 
7408
  // [func.bind], bind
7409
  template<class T> struct is_bind_expression; // freestanding
7410
  template<class T>
7411
  constexpr bool is_bind_expression_v = // freestanding
@@ -7422,39 +8052,49 @@ namespace std {
7422
 
7423
  namespace placeholders {
7424
  // M is the implementation-defined number of placeholders
7425
  see belownc _1; // freestanding
7426
  see belownc _2; // freestanding
7427
- .
7428
- .
7429
- .
7430
  see belownc _M; // freestanding
7431
  }
7432
 
7433
  // [func.memfn], member function adaptors
7434
  template<class R, class T>
7435
  constexpr unspecified mem_fn(R T::*) noexcept; // freestanding
7436
 
7437
  // [func.wrap], polymorphic function wrappers
 
7438
  class bad_function_call;
7439
 
 
7440
  template<class> class function; // not defined
7441
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;
7442
 
7443
- // [func.wrap.func.alg], specialized algorithms
7444
  template<class R, class... ArgTypes>
7445
  void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
7446
 
7447
- // [func.wrap.func.nullptr], null pointer comparison operator functions
7448
  template<class R, class... ArgTypes>
7449
  bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
7450
 
7451
- // [func.wrap.move], move only wrapper
7452
  template<class... S> class move_only_function; // not defined
7453
  template<class R, class... ArgTypes>
7454
  class move_only_function<R(ArgTypes...) cv ref noexcept(noex)>; // see below
7455
 
 
 
 
 
 
 
 
 
 
 
7456
  // [func.search], searchers
7457
  template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
7458
  class default_searcher; // freestanding
7459
 
7460
  template<class RandomAccessIterator,
@@ -7478,10 +8118,29 @@ namespace std {
7478
  struct greater; // freestanding
7479
  struct less; // freestanding
7480
  struct greater_equal; // freestanding
7481
  struct less_equal; // freestanding
7482
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7483
  }
7484
  ```
7485
 
7486
  [*Example 1*:
7487
 
@@ -7533,19 +8192,19 @@ collectively referred to as *state entities*.
7533
  ### Requirements <a id="func.require">[[func.require]]</a>
7534
 
7535
  Define `INVOKE(f, t₁, t₂, …, t_N)` as follows:
7536
 
7537
  - `(t₁.*f)(t₂, …, t_N)` when `f` is a pointer to a member function of a
7538
- class `T` and `is_same_v<T, remove_cvref_t<decltype(t1)>> ||`
7539
  `is_base_of_v<T, remove_cvref_t<decltype(t₁)>>` is `true`;
7540
  - `(t₁.get().*f)(t₂, …, t_N)` when `f` is a pointer to a member function
7541
  of a class `T` and `remove_cvref_t<decltype(t₁)>` is a specialization
7542
  of `reference_wrapper`;
7543
  - `((*t₁).*f)(t₂, …, t_N)` when `f` is a pointer to a member function of
7544
  a class `T` and `t₁` does not satisfy the previous two items;
7545
  - `t₁.*f` when N = 1 and `f` is a pointer to data member of a class `T`
7546
- and `is_same_v<T, remove_cvref_t<decltype(t1)>> ||`
7547
  `is_base_of_v<T, remove_cvref_t<decltype(t₁)>>` is `true`;
7548
  - `t₁.get().*f` when N = 1 and `f` is a pointer to data member of a
7549
  class `T` and `remove_cvref_t<decltype(t₁)>` is a specialization of
7550
  `reference_wrapper`;
7551
  - `(*t₁).*f` when N = 1 and `f` is a pointer to data member of a class
@@ -7659,10 +8318,19 @@ namespace std {
7659
 
7660
  // [refwrap.invoke], invocation
7661
  template<class... ArgTypes>
7662
  constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) const
7663
  noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);
 
 
 
 
 
 
 
 
 
7664
  };
7665
 
7666
  template<class T>
7667
  reference_wrapper(T&) -> reference_wrapper<T>;
7668
  }
@@ -7676,10 +8344,15 @@ function of type `T`.
7676
  [[term.trivially.copyable.type]].
7677
 
7678
  The template parameter `T` of `reference_wrapper` may be an incomplete
7679
  type.
7680
 
 
 
 
 
 
7681
  #### Constructors <a id="refwrap.const">[[refwrap.const]]</a>
7682
 
7683
  ``` cpp
7684
  template<class U>
7685
  constexpr reference_wrapper(U&& u) noexcept(see below);
@@ -7740,11 +8413,68 @@ template<class... ArgTypes>
7740
  ```
7741
 
7742
  *Mandates:* `T` is a complete type.
7743
 
7744
  *Returns:* *INVOKE*(get(),
7745
- std::forward\<ArgTypes\>(args)...). [[func.require]]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7746
 
7747
  #### Helper functions <a id="refwrap.helpers">[[refwrap.helpers]]</a>
7748
 
7749
  The template parameter `T` of the following `ref` and `cref` function
7750
  templates may be an incomplete type.
@@ -8657,10 +9387,28 @@ is `true`.
8657
  wrapper [[term.perfect.forwarding.call.wrapper]] `g` with call pattern
8658
  `!invoke(fd, call_args...)`.
8659
 
8660
  *Throws:* Any exception thrown by the initialization of `fd`.
8661
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8662
  ### Function templates `bind_front` and `bind_back` <a id="func.bind.partial">[[func.bind.partial]]</a>
8663
 
8664
  ``` cpp
8665
  template<class F, class... Args>
8666
  constexpr unspecified bind_front(F&& f, Args&&... args);
@@ -8706,10 +9454,48 @@ wrapper [[term.perfect.forwarding.call.wrapper]] `g` with call pattern:
8706
  invocation.
8707
 
8708
  *Throws:* Any exception thrown by the initialization of the state
8709
  entities of `g` [[func.def]].
8710
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8711
  ### Function object binders <a id="func.bind">[[func.bind]]</a>
8712
 
8713
  #### General <a id="func.bind.general">[[func.bind.general]]</a>
8714
 
8715
  Subclause [[func.bind]] describes a uniform mechanism for binding
@@ -8844,13 +9630,11 @@ type `V`_`fd` is `cv FD&`.
8844
  ``` cpp
8845
  namespace std::placeholders {
8846
  // M is the number of placeholders
8847
  see below _1;
8848
  see below _2;
8849
- .
8850
- .
8851
- .
8852
  see below _M;
8853
  }
8854
  ```
8855
 
8856
  The number `M` of placeholders is *implementation-defined*.
@@ -8894,10 +9678,31 @@ expression [[expr.call]] of `fn`.
8894
  #### General <a id="func.wrap.general">[[func.wrap.general]]</a>
8895
 
8896
  Subclause [[func.wrap]] describes polymorphic wrapper classes that
8897
  encapsulate arbitrary callable objects.
8898
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8899
  #### Class `bad_function_call` <a id="func.wrap.badcall">[[func.wrap.badcall]]</a>
8900
 
8901
  An exception of type `bad_function_call` is thrown by
8902
  `function::operator()` [[func.wrap.func.inv]] when the function wrapper
8903
  object has no target.
@@ -8922,12 +9727,10 @@ const char* what() const noexcept override;
8922
 
8923
  ##### General <a id="func.wrap.func.general">[[func.wrap.func.general]]</a>
8924
 
8925
  ``` cpp
8926
  namespace std {
8927
- template<class> class function; // not defined
8928
-
8929
  template<class R, class... ArgTypes>
8930
  class function<R(ArgTypes...)> {
8931
  public:
8932
  using result_type = R;
8933
 
@@ -8971,16 +9774,10 @@ namespace std {
8971
  The `function` class template provides polymorphic wrappers that
8972
  generalize the notion of a function pointer. Wrappers can store, copy,
8973
  and call arbitrary callable objects [[func.def]], given a call signature
8974
  [[func.def]].
8975
 
8976
- A callable type [[func.def]] `F` is *Lvalue-Callable* for argument types
8977
- `ArgTypes` and return type `R` if the expression
8978
- `INVOKE<R>(declval<F&>(), declval<ArgTypes>()...)`, considered as an
8979
- unevaluated operand [[term.unevaluated.operand]], is well-formed
8980
- [[func.require]].
8981
-
8982
  The `function` class template is a call wrapper [[func.def]] whose call
8983
  signature [[func.def]] is `R(ArgTypes...)`.
8984
 
8985
  [*Note 1*: The types deduced by the deduction guides for `function`
8986
  might change in future revisions of C++. — *end note*]
@@ -9002,11 +9799,11 @@ function(nullptr_t) noexcept;
9002
  ``` cpp
9003
  function(const function& f);
9004
  ```
9005
 
9006
  *Ensures:* `!*this` if `!f`; otherwise, the target object of `*this` is
9007
- a copy of `f.target()`.
9008
 
9009
  *Throws:* Nothing if `f`’s target is a specialization of
9010
  `reference_wrapper` or a function pointer. Otherwise, may throw
9011
  `bad_alloc` or any exception thrown by the copy constructor of the
9012
  stored callable object.
@@ -9036,12 +9833,11 @@ template<class F> function(F&& f);
9036
  Let `FD` be `decay_t<F>`.
9037
 
9038
  *Constraints:*
9039
 
9040
  - `is_same_v<remove_cvref_t<F>, function>` is `false`, and
9041
- - `FD` is Lvalue-Callable [[func.wrap.func]] for argument types
9042
- `ArgTypes...` and return type `R`.
9043
 
9044
  *Mandates:*
9045
 
9046
  - `is_copy_constructible_v<FD>` is `true`, and
9047
  - `is_constructible_v<FD, F>` is `true`.
@@ -9122,12 +9918,12 @@ function& operator=(nullptr_t) noexcept;
9122
 
9123
  ``` cpp
9124
  template<class F> function& operator=(F&& f);
9125
  ```
9126
 
9127
- *Constraints:* `decay_t<F>` is Lvalue-Callable [[func.wrap.func]] for
9128
- argument types `ArgTypes...` and return type `R`.
9129
 
9130
  *Effects:* As if by: `function(std::forward<F>(f)).swap(*this);`
9131
 
9132
  *Returns:* `*this`.
9133
 
@@ -9207,11 +10003,11 @@ template<class R, class... ArgTypes>
9207
  void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
9208
  ```
9209
 
9210
  *Effects:* As if by: `f1.swap(f2);`
9211
 
9212
- #### Move only wrapper <a id="func.wrap.move">[[func.wrap.move]]</a>
9213
 
9214
  ##### General <a id="func.wrap.move.general">[[func.wrap.move.general]]</a>
9215
 
9216
  The header provides partial specializations of `move_only_function` for
9217
  each combination of the possible replacements of the placeholders cv,
@@ -9229,18 +10025,16 @@ above, there is a placeholder *inv-quals* defined as follows:
9229
 
9230
  ##### Class template `move_only_function` <a id="func.wrap.move.class">[[func.wrap.move.class]]</a>
9231
 
9232
  ``` cpp
9233
  namespace std {
9234
- template<class... S> class move_only_function; // not defined
9235
-
9236
  template<class R, class... ArgTypes>
9237
  class move_only_function<R(ArgTypes...) cv ref noexcept(noex)> {
9238
  public:
9239
  using result_type = R;
9240
 
9241
- // [func.wrap.move.ctor], constructors, assignment, and destructor
9242
  move_only_function() noexcept;
9243
  move_only_function(nullptr_t) noexcept;
9244
  move_only_function(move_only_function&&) noexcept;
9245
  template<class F> move_only_function(F&&);
9246
  template<class T, class... Args>
@@ -9280,11 +10074,11 @@ dynamically allocated memory for a small contained value.
9280
 
9281
  [*Note 1*: Such small-object optimization can only be applied to a type
9282
  `T` for which `is_nothrow_move_constructible_v<T>` is
9283
  `true`. — *end note*]
9284
 
9285
- ##### Constructors, assignment, and destructor <a id="func.wrap.move.ctor">[[func.wrap.move.ctor]]</a>
9286
 
9287
  ``` cpp
9288
  template<class VT>
9289
  static constexpr bool is-callable-from = see below;
9290
  ```
@@ -9473,10 +10267,540 @@ friend void swap(move_only_function& f1, move_only_function& f2) noexcept;
9473
  friend bool operator==(const move_only_function& f, nullptr_t) noexcept;
9474
  ```
9475
 
9476
  *Returns:* `true` if `f` has no target object, otherwise `false`.
9477
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9478
  ### Searchers <a id="func.search">[[func.search]]</a>
9479
 
9480
  #### General <a id="func.search.general">[[func.search.general]]</a>
9481
 
9482
  Subclause [[func.search]] provides function object types
@@ -9588,11 +10912,11 @@ boyer_moore_searcher(RandomAccessIterator1 pat_first,
9588
  Hash hf = Hash(),
9589
  BinaryPredicate pred = BinaryPredicate());
9590
  ```
9591
 
9592
  *Preconditions:* The value type of `RandomAccessIterator1` meets the
9593
- *Cpp17DefaultConstructible*, the *Cpp17CopyConstructible*, and the
9594
  *Cpp17CopyAssignable* requirements.
9595
 
9596
  Let `V` be `iterator_traits<RandomAccessIterator1>::value_type`. For any
9597
  two values `A` and `B` of type `V`, if `pred(A, B) == true`, then
9598
  `hf(A) == hf(B)` is `true`.
@@ -9755,2651 +11079,10 @@ An enabled specialization `hash<Key>` will:
9755
  - meet the requirement that the expression `h(k)`, where `h` is an
9756
  object of type `hash<Key>` and `k` is an object of type `Key`, shall
9757
  not throw an exception unless `hash<Key>` is a program-defined
9758
  specialization.
9759
 
9760
- ## Class `type_index` <a id="type.index">[[type.index]]</a>
9761
-
9762
- ### Header `<typeindex>` synopsis <a id="type.index.synopsis">[[type.index.synopsis]]</a>
9763
-
9764
- ``` cpp
9765
- #include <compare> // see [compare.syn]
9766
-
9767
- namespace std {
9768
- class type_index;
9769
- template<class T> struct hash;
9770
- template<> struct hash<type_index>;
9771
- }
9772
- ```
9773
-
9774
- ### `type_index` overview <a id="type.index.overview">[[type.index.overview]]</a>
9775
-
9776
- ``` cpp
9777
- namespace std {
9778
- class type_index {
9779
- public:
9780
- type_index(const type_info& rhs) noexcept;
9781
- bool operator==(const type_index& rhs) const noexcept;
9782
- bool operator< (const type_index& rhs) const noexcept;
9783
- bool operator> (const type_index& rhs) const noexcept;
9784
- bool operator<=(const type_index& rhs) const noexcept;
9785
- bool operator>=(const type_index& rhs) const noexcept;
9786
- strong_ordering operator<=>(const type_index& rhs) const noexcept;
9787
- size_t hash_code() const noexcept;
9788
- const char* name() const noexcept;
9789
-
9790
- private:
9791
- const type_info* target; // exposition only
9792
- // Note that the use of a pointer here, rather than a reference,
9793
- // means that the default copy/move constructor and assignment
9794
- // operators will be provided and work as expected.
9795
- };
9796
- }
9797
- ```
9798
-
9799
- The class `type_index` provides a simple wrapper for `type_info` which
9800
- can be used as an index type in associative containers [[associative]]
9801
- and in unordered associative containers [[unord]].
9802
-
9803
- ### `type_index` members <a id="type.index.members">[[type.index.members]]</a>
9804
-
9805
- ``` cpp
9806
- type_index(const type_info& rhs) noexcept;
9807
- ```
9808
-
9809
- *Effects:* Constructs a `type_index` object, the equivalent of
9810
- `target = &rhs`.
9811
-
9812
- ``` cpp
9813
- bool operator==(const type_index& rhs) const noexcept;
9814
- ```
9815
-
9816
- *Returns:* `*target == *rhs.target`.
9817
-
9818
- ``` cpp
9819
- bool operator<(const type_index& rhs) const noexcept;
9820
- ```
9821
-
9822
- *Returns:* `target->before(*rhs.target)`.
9823
-
9824
- ``` cpp
9825
- bool operator>(const type_index& rhs) const noexcept;
9826
- ```
9827
-
9828
- *Returns:* `rhs.target->before(*target)`.
9829
-
9830
- ``` cpp
9831
- bool operator<=(const type_index& rhs) const noexcept;
9832
- ```
9833
-
9834
- *Returns:* `!rhs.target->before(*target)`.
9835
-
9836
- ``` cpp
9837
- bool operator>=(const type_index& rhs) const noexcept;
9838
- ```
9839
-
9840
- *Returns:* `!target->before(*rhs.target)`.
9841
-
9842
- ``` cpp
9843
- strong_ordering operator<=>(const type_index& rhs) const noexcept;
9844
- ```
9845
-
9846
- *Effects:* Equivalent to:
9847
-
9848
- ``` cpp
9849
- if (*target == *rhs.target) return strong_ordering::equal;
9850
- if (target->before(*rhs.target)) return strong_ordering::less;
9851
- return strong_ordering::greater;
9852
- ```
9853
-
9854
- ``` cpp
9855
- size_t hash_code() const noexcept;
9856
- ```
9857
-
9858
- *Returns:* `target->hash_code()`.
9859
-
9860
- ``` cpp
9861
- const char* name() const noexcept;
9862
- ```
9863
-
9864
- *Returns:* `target->name()`.
9865
-
9866
- ### Hash support <a id="type.index.hash">[[type.index.hash]]</a>
9867
-
9868
- ``` cpp
9869
- template<> struct hash<type_index>;
9870
- ```
9871
-
9872
- For an object `index` of type `type_index`, `hash<type_index>()(index)`
9873
- shall evaluate to the same result as `index.hash_code()`.
9874
-
9875
- ## Execution policies <a id="execpol">[[execpol]]</a>
9876
-
9877
- ### In general <a id="execpol.general">[[execpol.general]]</a>
9878
-
9879
- Subclause  [[execpol]] describes classes that are *execution policy*
9880
- types. An object of an execution policy type indicates the kinds of
9881
- parallelism allowed in the execution of an algorithm and expresses the
9882
- consequent requirements on the element access functions.
9883
-
9884
- [*Example 1*:
9885
-
9886
- ``` cpp
9887
- using namespace std;
9888
- vector<int> v = ...;
9889
-
9890
- // standard sequential sort
9891
- sort(v.begin(), v.end());
9892
-
9893
- // explicitly sequential sort
9894
- sort(execution::seq, v.begin(), v.end());
9895
-
9896
- // permitting parallel execution
9897
- sort(execution::par, v.begin(), v.end());
9898
-
9899
- // permitting vectorization as well
9900
- sort(execution::par_unseq, v.begin(), v.end());
9901
- ```
9902
-
9903
- — *end example*]
9904
-
9905
- [*Note 1*: Implementations can provide additional execution policies to
9906
- those described in this standard as extensions to address parallel
9907
- architectures that require idiosyncratic parameters for efficient
9908
- execution. — *end note*]
9909
-
9910
- ### Header `<execution>` synopsis <a id="execution.syn">[[execution.syn]]</a>
9911
-
9912
- ``` cpp
9913
- namespace std {
9914
- // [execpol.type], execution policy type trait
9915
- template<class T> struct is_execution_policy;
9916
- template<class T> constexpr bool is_execution_policy_v = is_execution_policy<T>::value;
9917
- }
9918
-
9919
- namespace std::execution {
9920
- // [execpol.seq], sequenced execution policy
9921
- class sequenced_policy;
9922
-
9923
- // [execpol.par], parallel execution policy
9924
- class parallel_policy;
9925
-
9926
- // [execpol.parunseq], parallel and unsequenced execution policy
9927
- class parallel_unsequenced_policy;
9928
-
9929
- // [execpol.unseq], unsequenced execution policy
9930
- class unsequenced_policy;
9931
-
9932
- // [execpol.objects], execution policy objects
9933
- inline constexpr sequenced_policy seq{ unspecified };
9934
- inline constexpr parallel_policy par{ unspecified };
9935
- inline constexpr parallel_unsequenced_policy par_unseq{ unspecified };
9936
- inline constexpr unsequenced_policy unseq{ unspecified };
9937
- }
9938
- ```
9939
-
9940
- ### Execution policy type trait <a id="execpol.type">[[execpol.type]]</a>
9941
-
9942
- ``` cpp
9943
- template<class T> struct is_execution_policy { see below };
9944
- ```
9945
-
9946
- `is_execution_policy` can be used to detect execution policies for the
9947
- purpose of excluding function signatures from otherwise ambiguous
9948
- overload resolution participation.
9949
-
9950
- `is_execution_policy<T>` is a *Cpp17UnaryTypeTrait* with a base
9951
- characteristic of `true_type` if `T` is the type of a standard or
9952
- *implementation-defined* execution policy, otherwise `false_type`.
9953
-
9954
- [*Note 1*: This provision reserves the privilege of creating
9955
- non-standard execution policies to the library
9956
- implementation. — *end note*]
9957
-
9958
- The behavior of a program that adds specializations for
9959
- `is_execution_policy` is undefined.
9960
-
9961
- ### Sequenced execution policy <a id="execpol.seq">[[execpol.seq]]</a>
9962
-
9963
- ``` cpp
9964
- class execution::sequenced_policy { unspecified };
9965
- ```
9966
-
9967
- The class `execution::sequenced_policy` is an execution policy type used
9968
- as a unique type to disambiguate parallel algorithm overloading and
9969
- require that a parallel algorithm’s execution may not be parallelized.
9970
-
9971
- During the execution of a parallel algorithm with the
9972
- `execution::sequenced_policy` policy, if the invocation of an element
9973
- access function exits via an exception, `terminate` is
9974
- invoked [[except.terminate]].
9975
-
9976
- ### Parallel execution policy <a id="execpol.par">[[execpol.par]]</a>
9977
-
9978
- ``` cpp
9979
- class execution::parallel_policy { unspecified };
9980
- ```
9981
-
9982
- The class `execution::parallel_policy` is an execution policy type used
9983
- as a unique type to disambiguate parallel algorithm overloading and
9984
- indicate that a parallel algorithm’s execution may be parallelized.
9985
-
9986
- During the execution of a parallel algorithm with the
9987
- `execution::parallel_policy` policy, if the invocation of an element
9988
- access function exits via an exception, `terminate` is
9989
- invoked [[except.terminate]].
9990
-
9991
- ### Parallel and unsequenced execution policy <a id="execpol.parunseq">[[execpol.parunseq]]</a>
9992
-
9993
- ``` cpp
9994
- class execution::parallel_unsequenced_policy { unspecified };
9995
- ```
9996
-
9997
- The class `execution::parallel_unsequenced_policy` is an execution
9998
- policy type used as a unique type to disambiguate parallel algorithm
9999
- overloading and indicate that a parallel algorithm’s execution may be
10000
- parallelized and vectorized.
10001
-
10002
- During the execution of a parallel algorithm with the
10003
- `execution::parallel_unsequenced_policy` policy, if the invocation of an
10004
- element access function exits via an exception, `terminate` is
10005
- invoked [[except.terminate]].
10006
-
10007
- ### Unsequenced execution policy <a id="execpol.unseq">[[execpol.unseq]]</a>
10008
-
10009
- ``` cpp
10010
- class execution::unsequenced_policy { unspecified };
10011
- ```
10012
-
10013
- The class `unsequenced_policy` is an execution policy type used as a
10014
- unique type to disambiguate parallel algorithm overloading and indicate
10015
- that a parallel algorithm’s execution may be vectorized, e.g., executed
10016
- on a single thread using instructions that operate on multiple data
10017
- items.
10018
-
10019
- During the execution of a parallel algorithm with the
10020
- `execution::unsequenced_policy` policy, if the invocation of an element
10021
- access function exits via an exception, `terminate` is invoked
10022
- [[except.terminate]].
10023
-
10024
- ### Execution policy objects <a id="execpol.objects">[[execpol.objects]]</a>
10025
-
10026
- ``` cpp
10027
- inline constexpr execution::sequenced_policy execution::seq{ unspecified };
10028
- inline constexpr execution::parallel_policy execution::par{ unspecified };
10029
- inline constexpr execution::parallel_unsequenced_policy execution::par_unseq{ unspecified };
10030
- inline constexpr execution::unsequenced_policy execution::unseq{ unspecified };
10031
- ```
10032
-
10033
- The header `<execution>` declares global objects associated with each
10034
- type of execution policy.
10035
-
10036
- ## Primitive numeric conversions <a id="charconv">[[charconv]]</a>
10037
-
10038
- ### Header `<charconv>` synopsis <a id="charconv.syn">[[charconv.syn]]</a>
10039
-
10040
- When a function is specified with a type placeholder of `integer-type`,
10041
- the implementation provides overloads for all cv-unqualified signed and
10042
- unsigned integer types and `char` in lieu of `integer-type`. When a
10043
- function is specified with a type placeholder of `floating-point-type`,
10044
- the implementation provides overloads for all cv-unqualified
10045
- floating-point types [[basic.fundamental]] in lieu of
10046
- `floating-point-type`.
10047
-
10048
- ``` cpp
10049
- %
10050
- %
10051
- {chars_format{chars_format{chars_format{chars_formatnamespace std {
10052
- // floating-point format for primitive numerical conversion
10053
- enum class chars_format {
10054
- scientific = unspecified,
10055
- fixed = unspecified,
10056
- hex = unspecified,
10057
- general = fixed | scientific
10058
- };
10059
- %
10060
- %
10061
- {to_chars_result{to_chars_result}
10062
-
10063
- // [charconv.to.chars], primitive numerical output conversion
10064
- struct to_chars_result {
10065
- char* ptr;
10066
- errc ec;
10067
- friend bool operator==(const to_chars_result&, const to_chars_result&) = default;
10068
- };
10069
-
10070
- constexpr to_chars_result to_chars(char* first, char* last, integer-type value, int base = 10);
10071
- to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;
10072
-
10073
- to_chars_result to_chars(char* first, char* last, floating-point-type value);
10074
- to_chars_result to_chars(char* first, char* last, floating-point-type value, chars_format fmt);
10075
- to_chars_result to_chars(char* first, char* last, floating-point-type value,
10076
- chars_format fmt, int precision);
10077
- %
10078
- %
10079
- {from_chars_result{from_chars_result}
10080
-
10081
- // [charconv.from.chars], primitive numerical input conversion
10082
- struct from_chars_result {
10083
- const char* ptr;
10084
- errc ec;
10085
- friend bool operator==(const from_chars_result&, const from_chars_result&) = default;
10086
- };
10087
-
10088
- constexpr from_chars_result from_chars(const char* first, const char* last,
10089
- integer-type& value, int base = 10);
10090
-
10091
- from_chars_result from_chars(const char* first, const char* last, floating-point-type& value,
10092
- chars_format fmt = chars_format::general);
10093
- }
10094
- ```
10095
-
10096
- The type `chars_format` is a bitmask type [[bitmask.types]] with
10097
- elements `scientific`, `fixed`, and `hex`.
10098
-
10099
- The types `to_chars_result` and `from_chars_result` have the data
10100
- members and special members specified above. They have no base classes
10101
- or members other than those specified.
10102
-
10103
- ### Primitive numeric output conversion <a id="charconv.to.chars">[[charconv.to.chars]]</a>
10104
-
10105
- All functions named `to_chars` convert `value` into a character string
10106
- by successively filling the range \[`first`, `last`), where \[`first`,
10107
- `last`) is required to be a valid range. If the member `ec` of the
10108
- return value is such that the value is equal to the value of a
10109
- value-initialized `errc`, the conversion was successful and the member
10110
- `ptr` is the one-past-the-end pointer of the characters written.
10111
- Otherwise, the member `ec` has the value `errc::value_too_large`, the
10112
- member `ptr` has the value `last`, and the contents of the range
10113
- \[`first`, `last`) are unspecified.
10114
-
10115
- The functions that take a floating-point `value` but not a `precision`
10116
- parameter ensure that the string representation consists of the smallest
10117
- number of characters such that there is at least one digit before the
10118
- radix point (if present) and parsing the representation using the
10119
- corresponding `from_chars` function recovers `value` exactly.
10120
-
10121
- [*Note 1*: This guarantee applies only if `to_chars` and `from_chars`
10122
- are executed on the same implementation. — *end note*]
10123
-
10124
- If there are several such representations, the representation with the
10125
- smallest difference from the floating-point argument value is chosen,
10126
- resolving any remaining ties using rounding according to
10127
- `round_to_nearest` [[round.style]].
10128
-
10129
- The functions taking a `chars_format` parameter determine the conversion
10130
- specifier for `printf` as follows: The conversion specifier is `f` if
10131
- `fmt` is `chars_format::fixed`, `e` if `fmt` is
10132
- `chars_format::scientific`, `a` (without leading `"0x"` in the result)
10133
- if `fmt` is `chars_format::hex`, and `g` if `fmt` is
10134
- `chars_format::general`.
10135
-
10136
- ``` cpp
10137
- constexpr to_chars_result to_chars(char* first, char* last, integer-type value, int base = 10);
10138
- ```
10139
-
10140
- *Preconditions:* `base` has a value between 2 and 36 (inclusive).
10141
-
10142
- *Effects:* The value of `value` is converted to a string of digits in
10143
- the given base (with no redundant leading zeroes). Digits in the range
10144
- 10..35 (inclusive) are represented as lowercase characters `a`..`z`. If
10145
- `value` is less than zero, the representation starts with `’-’`.
10146
-
10147
- *Throws:* Nothing.
10148
-
10149
- ``` cpp
10150
- to_chars_result to_chars(char* first, char* last, floating-point-type value);
10151
- ```
10152
-
10153
- *Effects:* `value` is converted to a string in the style of `printf` in
10154
- the `"C"` locale. The conversion specifier is `f` or `e`, chosen
10155
- according to the requirement for a shortest representation (see above);
10156
- a tie is resolved in favor of `f`.
10157
-
10158
- *Throws:* Nothing.
10159
-
10160
- ``` cpp
10161
- to_chars_result to_chars(char* first, char* last, floating-point-type value, chars_format fmt);
10162
- ```
10163
-
10164
- *Preconditions:* `fmt` has the value of one of the enumerators of
10165
- `chars_format`.
10166
-
10167
- *Effects:* `value` is converted to a string in the style of `printf` in
10168
- the `"C"` locale.
10169
-
10170
- *Throws:* Nothing.
10171
-
10172
- ``` cpp
10173
- to_chars_result to_chars(char* first, char* last, floating-point-type value,
10174
- chars_format fmt, int precision);
10175
- ```
10176
-
10177
- *Preconditions:* `fmt` has the value of one of the enumerators of
10178
- `chars_format`.
10179
-
10180
- *Effects:* `value` is converted to a string in the style of `printf` in
10181
- the `"C"` locale with the given precision.
10182
-
10183
- *Throws:* Nothing.
10184
-
10185
- See also: ISO C 7.21.6.1
10186
-
10187
- ### Primitive numeric input conversion <a id="charconv.from.chars">[[charconv.from.chars]]</a>
10188
-
10189
- All functions named `from_chars` analyze the string \[`first`, `last`)
10190
- for a pattern, where \[`first`, `last`) is required to be a valid range.
10191
- If no characters match the pattern, `value` is unmodified, the member
10192
- `ptr` of the return value is `first` and the member `ec` is equal to
10193
- `errc::invalid_argument`.
10194
-
10195
- [*Note 1*: If the pattern allows for an optional sign, but the string
10196
- has no digit characters following the sign, no characters match the
10197
- pattern. — *end note*]
10198
-
10199
- Otherwise, the characters matching the pattern are interpreted as a
10200
- representation of a value of the type of `value`. The member `ptr` of
10201
- the return value points to the first character not matching the pattern,
10202
- or has the value `last` if all characters match. If the parsed value is
10203
- not in the range representable by the type of `value`, `value` is
10204
- unmodified and the member `ec` of the return value is equal to
10205
- `errc::result_out_of_range`. Otherwise, `value` is set to the parsed
10206
- value, after rounding according to `round_to_nearest` [[round.style]],
10207
- and the member `ec` is value-initialized.
10208
-
10209
- ``` cpp
10210
- constexpr from_chars_result from_chars(const char* first, const char* last,
10211
- integer-type& value, int base = 10);
10212
- ```
10213
-
10214
- *Preconditions:* `base` has a value between 2 and 36 (inclusive).
10215
-
10216
- *Effects:* The pattern is the expected form of the subject sequence in
10217
- the `"C"` locale for the given nonzero base, as described for `strtol`,
10218
- except that no `"0x"` or `"0X"` prefix shall appear if the value of
10219
- `base` is 16, and except that `’-’` is the only sign that may appear,
10220
- and only if `value` has a signed type.
10221
-
10222
- *Throws:* Nothing.
10223
-
10224
- ``` cpp
10225
- from_chars_result from_chars(const char* first, const char* last, floating-point-type& value,
10226
- chars_format fmt = chars_format::general);
10227
- ```
10228
-
10229
- *Preconditions:* `fmt` has the value of one of the enumerators of
10230
- `chars_format`.
10231
-
10232
- *Effects:* The pattern is the expected form of the subject sequence in
10233
- the `"C"` locale, as described for `strtod`, except that
10234
-
10235
- - the sign `’+’` may only appear in the exponent part;
10236
- - if `fmt` has `chars_format::scientific` set but not
10237
- `chars_format::fixed`, the otherwise optional exponent part shall
10238
- appear;
10239
- - if `fmt` has `chars_format::fixed` set but not
10240
- `chars_format::scientific`, the optional exponent part shall not
10241
- appear; and
10242
- - if `fmt` is `chars_format::hex`, the prefix `"0x"` or `"0X"` is
10243
- assumed. \[*Example 1*: The string `0x123` is parsed to have the value
10244
- `0` with remaining characters `x123`. — *end example*]
10245
-
10246
- In any case, the resulting `value` is one of at most two floating-point
10247
- values closest to the value of the string matching the pattern.
10248
-
10249
- *Throws:* Nothing.
10250
-
10251
- See also: ISO C 7.22.1.3, 7.22.1.4
10252
-
10253
- ## Formatting <a id="format">[[format]]</a>
10254
-
10255
- ### Header `<format>` synopsis <a id="format.syn">[[format.syn]]</a>
10256
-
10257
- ``` cpp
10258
- namespace std {
10259
- // [format.context], class template basic_format_context
10260
- template<class Out, class charT> class basic_format_context;
10261
- using format_context = basic_format_context<unspecified, char>;
10262
- using wformat_context = basic_format_context<unspecified, wchar_t>;
10263
-
10264
- // [format.args], class template basic_format_args
10265
- template<class Context> class basic_format_args;
10266
- using format_args = basic_format_args<format_context>;
10267
- using wformat_args = basic_format_args<wformat_context>;
10268
-
10269
- // [format.fmt.string], class template basic_format_string
10270
- template<class charT, class... Args>
10271
- struct basic_format_string;
10272
-
10273
- template<class... Args>
10274
- using format_string = basic_format_string<char, type_identity_t<Args>...>;
10275
- template<class... Args>
10276
- using wformat_string = basic_format_string<wchar_t, type_identity_t<Args>...>;
10277
-
10278
- // [format.functions], formatting functions
10279
- template<class... Args>
10280
- string format(format_string<Args...> fmt, Args&&... args);
10281
- template<class... Args>
10282
- wstring format(wformat_string<Args...> fmt, Args&&... args);
10283
- template<class... Args>
10284
- string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
10285
- template<class... Args>
10286
- wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
10287
-
10288
- string vformat(string_view fmt, format_args args);
10289
- wstring vformat(wstring_view fmt, wformat_args args);
10290
- string vformat(const locale& loc, string_view fmt, format_args args);
10291
- wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
10292
-
10293
- template<class Out, class... Args>
10294
- Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
10295
- template<class Out, class... Args>
10296
- Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
10297
- template<class Out, class... Args>
10298
- Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
10299
- template<class Out, class... Args>
10300
- Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
10301
-
10302
- template<class Out>
10303
- Out vformat_to(Out out, string_view fmt, format_args args);
10304
- template<class Out>
10305
- Out vformat_to(Out out, wstring_view fmt, wformat_args args);
10306
- template<class Out>
10307
- Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
10308
- template<class Out>
10309
- Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
10310
-
10311
- template<class Out> struct format_to_n_result {
10312
- Out out;
10313
- iter_difference_t<Out> size;
10314
- };
10315
- template<class Out, class... Args>
10316
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
10317
- format_string<Args...> fmt, Args&&... args);
10318
- template<class Out, class... Args>
10319
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
10320
- wformat_string<Args...> fmt, Args&&... args);
10321
- template<class Out, class... Args>
10322
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
10323
- const locale& loc, format_string<Args...> fmt,
10324
- Args&&... args);
10325
- template<class Out, class... Args>
10326
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
10327
- const locale& loc, wformat_string<Args...> fmt,
10328
- Args&&... args);
10329
-
10330
- template<class... Args>
10331
- size_t formatted_size(format_string<Args...> fmt, Args&&... args);
10332
- template<class... Args>
10333
- size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
10334
- template<class... Args>
10335
- size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
10336
- template<class... Args>
10337
- size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
10338
-
10339
- // [format.formatter], formatter
10340
- template<class T, class charT = char> struct formatter;
10341
-
10342
- // [format.formattable], concept formattable
10343
- template<class T, class charT>
10344
- concept formattable = see below;
10345
-
10346
- template<class R, class charT>
10347
- concept const-formattable-range = // exposition only
10348
- ranges::input_range<const R> &&
10349
- formattable<ranges::range_reference_t<const R>, charT>;
10350
-
10351
- template<class R, class charT>
10352
- using fmt-maybe-const = // exposition only
10353
- conditional_t<const-formattable-range<R, charT>, const R, R>;
10354
-
10355
- // [format.parse.ctx], class template basic_format_parse_context
10356
- template<class charT> class basic_format_parse_context;
10357
- using format_parse_context = basic_format_parse_context<char>;
10358
- using wformat_parse_context = basic_format_parse_context<wchar_t>;
10359
-
10360
- // [format.range], formatting of ranges
10361
- // [format.range.fmtkind], variable template format_kind
10362
- enum class range_format {
10363
- disabled,
10364
- map,
10365
- set,
10366
- sequence,
10367
- string,
10368
- debug_string
10369
- };
10370
-
10371
- template<class R>
10372
- constexpr unspecified format_kind = unspecified;
10373
-
10374
- template<ranges::input_range R>
10375
- requires same_as<R, remove_cvref_t<R>>
10376
- constexpr range_format format_kind<R> = see below;
10377
-
10378
- // [format.range.formatter], class template range_formatter
10379
- template<class T, class charT = char>
10380
- requires same_as<remove_cvref_t<T>, T> && formattable<T, charT>
10381
- class range_formatter;
10382
-
10383
- // [format.range.fmtdef], class template range-default-formatter
10384
- template<range_format K, ranges::input_range R, class charT>
10385
- struct range-default-formatter; // exposition only
10386
-
10387
- // [format.range.fmtmap], [format.range.fmtset], [format.range.fmtstr], specializations for maps, sets, and strings
10388
- template<ranges::input_range R, class charT>
10389
- requires (format_kind<R> != range_format::disabled) &&
10390
- formattable<ranges::range_reference_t<R>, charT>
10391
- struct formatter<R, charT> : range-default-formatter<format_kind<R>, R, charT> { };
10392
-
10393
- // [format.arguments], arguments
10394
- // [format.arg], class template basic_format_arg
10395
- template<class Context> class basic_format_arg;
10396
-
10397
- template<class Visitor, class Context>
10398
- decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
10399
-
10400
- // [format.arg.store], class template format-arg-store
10401
- template<class Context, class... Args> class format-arg-store; // exposition only
10402
-
10403
- template<class Context = format_context, class... Args>
10404
- format-arg-store<Context, Args...>
10405
- make_format_args(Args&&... fmt_args);
10406
- template<class... Args>
10407
- format-arg-store<wformat_context, Args...>
10408
- make_wformat_args(Args&&... args);
10409
-
10410
- // [format.error], class format_error
10411
- class format_error;
10412
- }
10413
- ```
10414
-
10415
- The class template `format_to_n_result` has the template parameters,
10416
- data members, and special members specified above. It has no base
10417
- classes or members other than those specified.
10418
-
10419
- ### Format string <a id="format.string">[[format.string]]</a>
10420
-
10421
- #### In general <a id="format.string.general">[[format.string.general]]</a>
10422
-
10423
- A *format string* for arguments `args` is a (possibly empty) sequence of
10424
- *replacement fields*, *escape sequences*, and characters other than `{`
10425
- and `}`. Let `charT` be the character type of the format string. Each
10426
- character that is not part of a replacement field or an escape sequence
10427
- is copied unchanged to the output. An escape sequence is one of `{{` or
10428
- `}}`. It is replaced with `{` or `}`, respectively, in the output. The
10429
- syntax of replacement fields is as follows:
10430
-
10431
- ``` bnf
10432
- replacement-field
10433
- '{' arg-idₒₚₜ format-specifierₒₚₜ '}'
10434
- ```
10435
-
10436
- ``` bnf
10437
- arg-id
10438
- '0'
10439
- positive-integer
10440
- ```
10441
-
10442
- ``` bnf
10443
- positive-integer
10444
- nonzero-digit
10445
- positive-integer digit
10446
- ```
10447
-
10448
- ``` bnf
10449
- nonnegative-integer
10450
- digit
10451
- nonnegative-integer digit
10452
- ```
10453
-
10454
- ``` bnf
10455
- nonzero-digit one of
10456
- '1 2 3 4 5 6 7 8 9'
10457
- ```
10458
-
10459
- ``` bnf
10460
- digit one of
10461
- '0 1 2 3 4 5 6 7 8 9'
10462
- ```
10463
-
10464
- ``` bnf
10465
- format-specifier
10466
- ':' format-spec
10467
- ```
10468
-
10469
- ``` bnf
10470
- format-spec
10471
- as specified by the formatter specialization for the argument type
10472
- ```
10473
-
10474
- The *arg-id* field specifies the index of the argument in `args` whose
10475
- value is to be formatted and inserted into the output instead of the
10476
- replacement field. If there is no argument with the index *arg-id* in
10477
- `args`, the string is not a format string for `args`. The optional
10478
- *format-specifier* field explicitly specifies a format for the
10479
- replacement value.
10480
-
10481
- [*Example 1*:
10482
-
10483
- ``` cpp
10484
- string s = format("{0}-{{", 8); // value of s is "8-{"
10485
- ```
10486
-
10487
- — *end example*]
10488
-
10489
- If all *arg-id*s in a format string are omitted (including those in the
10490
- *format-spec*, as interpreted by the corresponding `formatter`
10491
- specialization), argument indices 0, 1, 2, … will automatically be used
10492
- in that order. If some *arg-id*s are omitted and some are present, the
10493
- string is not a format string.
10494
-
10495
- [*Note 1*: A format string cannot contain a mixture of automatic and
10496
- manual indexing. — *end note*]
10497
-
10498
- [*Example 2*:
10499
-
10500
- ``` cpp
10501
- string s0 = format("{} to {}", "a", "b"); // OK, automatic indexing
10502
- string s1 = format("{1} to {0}", "a", "b"); // OK, manual indexing
10503
- string s2 = format("{0} to {}", "a", "b"); // not a format string (mixing automatic and manual indexing),
10504
- // ill-formed
10505
- string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing),
10506
- // ill-formed
10507
- ```
10508
-
10509
- — *end example*]
10510
-
10511
- The *format-spec* field contains *format specifications* that define how
10512
- the value should be presented. Each type can define its own
10513
- interpretation of the *format-spec* field. If *format-spec* does not
10514
- conform to the format specifications for the argument type referred to
10515
- by *arg-id*, the string is not a format string for `args`.
10516
-
10517
- [*Example 3*:
10518
-
10519
- - For arithmetic, pointer, and string types the *format-spec* is
10520
- interpreted as a *std-format-spec* as described in
10521
- [[format.string.std]].
10522
- - For chrono types the *format-spec* is interpreted as a
10523
- *chrono-format-spec* as described in [[time.format]].
10524
- - For user-defined `formatter` specializations, the behavior of the
10525
- `parse` member function determines how the *format-spec* is
10526
- interpreted.
10527
-
10528
- — *end example*]
10529
-
10530
- #### Standard format specifiers <a id="format.string.std">[[format.string.std]]</a>
10531
-
10532
- Each `formatter` specialization described in [[format.formatter.spec]]
10533
- for fundamental and string types interprets *format-spec* as a
10534
- *std-format-spec*.
10535
-
10536
- [*Note 1*: The format specification can be used to specify such details
10537
- as minimum field width, alignment, padding, and decimal precision. Some
10538
- of the formatting options are only supported for arithmetic
10539
- types. — *end note*]
10540
-
10541
- The syntax of format specifications is as follows:
10542
-
10543
- ``` bnf
10544
- std-format-spec
10545
- fill-and-alignₒₚₜ signₒₚₜ '#'ₒₚₜ '0'ₒₚₜ widthₒₚₜ precisionₒₚₜ 'L'ₒₚₜ typeₒₚₜ
10546
- ```
10547
-
10548
- ``` bnf
10549
- fill-and-align
10550
- fillₒₚₜ align
10551
- ```
10552
-
10553
- ``` bnf
10554
- fill
10555
- any character other than \{ or \}
10556
- ```
10557
-
10558
- ``` bnf
10559
- align one of
10560
- '< > ^'
10561
- ```
10562
-
10563
- ``` bnf
10564
- sign one of
10565
- '+ -' space
10566
- ```
10567
-
10568
- ``` bnf
10569
- width
10570
- positive-integer
10571
- '{' arg-idₒₚₜ '}'
10572
- ```
10573
-
10574
- ``` bnf
10575
- precision
10576
- '.' nonnegative-integer
10577
- '.' '{' arg-idₒₚₜ '}'
10578
- ```
10579
-
10580
- ``` bnf
10581
- type one of
10582
- 'a A b B c d e E f F g G o p s x X ?'
10583
- ```
10584
-
10585
- Field widths are specified in *field width units*; the number of column
10586
- positions required to display a sequence of characters in a terminal.
10587
- The *minimum field width* is the number of field width units a
10588
- replacement field minimally requires of the formatted sequence of
10589
- characters produced for a format argument. The *estimated field width*
10590
- is the number of field width units that are required for the formatted
10591
- sequence of characters produced for a format argument independent of the
10592
- effects of the *width* option. The *padding width* is the greater of `0`
10593
- and the difference of the minimum field width and the estimated field
10594
- width.
10595
-
10596
- [*Note 2*: The POSIX `wcswidth` function is an example of a function
10597
- that, given a string, returns the number of column positions required by
10598
- a terminal to display the string. — *end note*]
10599
-
10600
- The *fill character* is the character denoted by the *fill* option or,
10601
- if the *fill* option is absent, the space character. For a format
10602
- specification in UTF-8, UTF-16, or UTF-32, the fill character
10603
- corresponds to a single Unicode scalar value.
10604
-
10605
- [*Note 3*: The presence of a *fill* option is signaled by the character
10606
- following it, which must be one of the alignment options. If the second
10607
- character of *std-format-spec* is not a valid alignment option, then it
10608
- is assumed that the *fill* and *align* options are both
10609
- absent. — *end note*]
10610
-
10611
- The *align* option applies to all argument types. The meaning of the
10612
- various alignment options is as specified in [[format.align]].
10613
-
10614
- [*Example 1*:
10615
-
10616
- ``` cpp
10617
- char c = 120;
10618
- string s0 = format("{:6}", 42); // value of s0 is "\ \ \ \ 42"
10619
- string s1 = format("{:6}", 'x'); // value of s1 is "x\ \ \ \ \ "
10620
- string s2 = format("{:*<6}", 'x'); // value of s2 is "x*****"
10621
- string s3 = format("{:*>6}", 'x'); // value of s3 is "*****x"
10622
- string s4 = format("{:*^6}", 'x'); // value of s4 is "**x***"
10623
- string s5 = format("{:6d}", c); // value of s5 is "\ \ \ 120"
10624
- string s6 = format("{:6}", true); // value of s6 is "true\ \ "
10625
- string s7 = format("{:*<6.3}", "123456"); // value of s7 is "123***"
10626
- string s8 = format("{:02}", 1234); // value of s8 is "1234"
10627
- string s9 = format("{:*<}", "12"); // value of s9 is "12"
10628
- string sA = format("{:*<6}", "12345678"); // value of sA is "12345678"
10629
- ```
10630
-
10631
- — *end example*]
10632
-
10633
- [*Note 4*: The *fill*, *align*, and `0` options have no effect when the
10634
- minimum field width is not greater than the estimated field width
10635
- because padding width is `0` in that case. Since fill characters are
10636
- assumed to have a field width of `1`, use of a character with a
10637
- different field width can produce misaligned output. The
10638
- U+1f921 (clown face) character has a field width of `2`. The examples
10639
- above that include that character illustrate the effect of the field
10640
- width when that character is used as a fill character as opposed to when
10641
- it is used as a formatting argument. — *end note*]
10642
-
10643
- **Table: Meaning of align options** <a id="format.align">[format.align]</a>
10644
-
10645
- | Option | Meaning |
10646
- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
10647
- | `<` | Forces the formatted argument to be aligned to the start of the field by inserting $n$ fill characters after the formatted argument where $n$ is the padding width. This is the default for non-arithmetic non-pointer types, `charT`, and `bool`, unless an integer presentation type is specified. |
10648
- | % `>` | Forces the formatted argument to be aligned to the end of the field by inserting $n$ fill characters before the formatted argument where $n$ is the padding width. This is the default for arithmetic types other than `charT` and `bool`, pointer types, or when an integer presentation type is specified. |
10649
- | % `^` | Forces the formatted argument to be centered within the field by inserting $\bigl\lfloor \frac{n}{2} \bigr\rfloor$ fill characters before and $\bigl\lceil \frac{n}{2} \bigr\rceil$ fill characters after the formatted argument, where $n$ is the padding width. |
10650
-
10651
-
10652
- The *sign* option is only valid for arithmetic types other than `charT`
10653
- and `bool` or when an integer presentation type is specified. The
10654
- meaning of the various options is as specified in [[format.sign]].
10655
-
10656
- **Table: Meaning of sign options** <a id="format.sign">[format.sign]</a>
10657
-
10658
- | Option | Meaning |
10659
- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
10660
- | `+` | Indicates that a sign should be used for both non-negative and negative numbers. The `+` sign is inserted before the output of `to_chars` for non-negative numbers other than negative zero. *For negative numbers and negative zero the output of `to_chars` will already contain the sign so no additional transformation is performed.* |
10661
- | % `-` | Indicates that a sign should be used for negative numbers and negative zero only (this is the default behavior). |
10662
- | % space | Indicates that a leading space should be used for non-negative numbers other than negative zero, and a minus sign for negative numbers and negative zero. |
10663
-
10664
-
10665
- The *sign* option applies to floating-point infinity and NaN.
10666
-
10667
- [*Example 2*:
10668
-
10669
- ``` cpp
10670
- double inf = numeric_limits<double>::infinity();
10671
- double nan = numeric_limits<double>::quiet_NaN();
10672
- string s0 = format("{0:},{0:+},{0:-},{0: }", 1); // value of s0 is "1,+1,1, 1"
10673
- string s1 = format("{0:},{0:+},{0:-},{0: }", -1); // value of s1 is "-1,-1,-1,-1"
10674
- string s2 = format("{0:},{0:+},{0:-},{0: }", inf); // value of s2 is "inf,+inf,inf, inf"
10675
- string s3 = format("{0:},{0:+},{0:-},{0: }", nan); // value of s3 is "nan,+nan,nan, nan"
10676
- ```
10677
-
10678
- — *end example*]
10679
-
10680
- The `#` option causes the *alternate form* to be used for the
10681
- conversion. This option is valid for arithmetic types other than `charT`
10682
- and `bool` or when an integer presentation type is specified, and not
10683
- otherwise. For integral types, the alternate form inserts the base
10684
- prefix (if any) specified in [[format.type.int]] into the output after
10685
- the sign character (possibly space) if there is one, or before the
10686
- output of `to_chars` otherwise. For floating-point types, the alternate
10687
- form causes the result of the conversion of finite values to always
10688
- contain a decimal-point character, even if no digits follow it.
10689
- Normally, a decimal-point character appears in the result of these
10690
- conversions only if a digit follows it. In addition, for `g` and `G`
10691
- conversions, trailing zeros are not removed from the result.
10692
-
10693
- The `0` option is valid for arithmetic types other than `charT` and
10694
- `bool` or when an integer presentation type is specified. For formatting
10695
- arguments that have a value other than an infinity or a NaN, this option
10696
- pads the formatted argument by inserting the `0` character n times
10697
- following the sign or base prefix indicators (if any) where n is `0` if
10698
- the *align* option is present and is the padding width otherwise.
10699
-
10700
- [*Example 3*:
10701
-
10702
- ``` cpp
10703
- char c = 120;
10704
- string s1 = format("{:+06d}", c); // value of s1 is "+00120"
10705
- string s2 = format("{:#06x}", 0xa); // value of s2 is "0x000a"
10706
- string s3 = format("{:<06}", -42); // value of s3 is "-42\ \ \ " (0 has no effect)
10707
- string s4 = format("{:06}", inf); // value of s4 is "\ \ \ inf" (0 has no effect)
10708
- ```
10709
-
10710
- — *end example*]
10711
-
10712
- The *width* option specifies the minimum field width. If the *width*
10713
- option is absent, the minimum field width is `0`.
10714
-
10715
- If `{ \opt{arg-id} }` is used in a *width* or *precision* option, the
10716
- value of the corresponding formatting argument is used as the value of
10717
- the option. If the corresponding formatting argument is not of standard
10718
- signed or unsigned integer type, or its value is negative, an exception
10719
- of type `format_error` is thrown.
10720
-
10721
- If *positive-integer* is used in a *width* option, the value of the
10722
- *positive-integer* is interpreted as a decimal integer and used as the
10723
- value of the option.
10724
-
10725
- For the purposes of width computation, a string is assumed to be in a
10726
- locale-independent, *implementation-defined* encoding. Implementations
10727
- should use either UTF-8, UTF-16, or UTF-32, on platforms capable of
10728
- displaying Unicode text in a terminal.
10729
-
10730
- [*Note 5*:
10731
-
10732
- This is the case for Windows[^2]
10733
-
10734
- -based and many POSIX-based operating systems.
10735
-
10736
- — *end note*]
10737
-
10738
- For a sequence of characters in UTF-8, UTF-16, or UTF-32, an
10739
- implementation should use as its field width the sum of the field widths
10740
- of the first code point of each extended grapheme cluster. Extended
10741
- grapheme clusters are defined by UAX \#29 of the Unicode Standard. The
10742
- following code points have a field width of 2:
10743
-
10744
- - any code point with the `East_Asian_Width="W"` or
10745
- `East_Asian_Width="F"` Derived Extracted Property as described by UAX
10746
- \#44 of the Unicode Standard
10747
- - `U+4dc0` – `U+4dff` (Yijing Hexagram Symbols)
10748
- - `U+1f300` – `U+1f5ff` (Miscellaneous Symbols and Pictographs)
10749
- - `U+1f900` – `U+1f9ff` (Supplemental Symbols and Pictographs)
10750
-
10751
- The field width of all other code points is 1.
10752
-
10753
- For a sequence of characters in neither UTF-8, UTF-16, nor UTF-32, the
10754
- field width is unspecified.
10755
-
10756
- The *precision* option is valid for floating-point and string types. For
10757
- floating-point types, the value of this option specifies the precision
10758
- to be used for the floating-point presentation type. For string types,
10759
- this option specifies the longest prefix of the formatted argument to be
10760
- included in the replacement field such that the field width of the
10761
- prefix is no greater than the value of this option.
10762
-
10763
- If *nonnegative-integer* is used in a *precision* option, the value of
10764
- the decimal integer is used as the value of the option.
10765
-
10766
- When the `L` option is used, the form used for the conversion is called
10767
- the *locale-specific form*. The `L` option is only valid for arithmetic
10768
- types, and its effect depends upon the type.
10769
-
10770
- - For integral types, the locale-specific form causes the context’s
10771
- locale to be used to insert the appropriate digit group separator
10772
- characters.
10773
- - For floating-point types, the locale-specific form causes the
10774
- context’s locale to be used to insert the appropriate digit group and
10775
- radix separator characters.
10776
- - For the textual representation of `bool`, the locale-specific form
10777
- causes the context’s locale to be used to insert the appropriate
10778
- string as if obtained with `numpunct::truename` or
10779
- `numpunct::falsename`.
10780
-
10781
- The *type* determines how the data should be presented.
10782
-
10783
- The available string presentation types are specified in
10784
- [[format.type.string]].
10785
-
10786
- **Table: Meaning of type options for strings** <a id="format.type.string">[format.type.string]</a>
10787
-
10788
- | Type | Meaning |
10789
- | --------- | ------------------------------------------------------------------ |
10790
- | none, `s` | Copies the string to the output. |
10791
- | % `?` | Copies the escaped string [[format.string.escaped]] to the output. |
10792
-
10793
-
10794
- The meaning of some non-string presentation types is defined in terms of
10795
- a call to `to_chars`. In such cases, let \[`first`, `last`) be a range
10796
- large enough to hold the `to_chars` output and `value` be the formatting
10797
- argument value. Formatting is done as if by calling `to_chars` as
10798
- specified and copying the output through the output iterator of the
10799
- format context.
10800
-
10801
- [*Note 6*: Additional padding and adjustments are performed prior to
10802
- copying the output through the output iterator as specified by the
10803
- format specifiers. — *end note*]
10804
-
10805
- The available integer presentation types for integral types other than
10806
- `bool` and `charT` are specified in [[format.type.int]].
10807
-
10808
- [*Example 4*:
10809
-
10810
- ``` cpp
10811
- string s0 = format("{}", 42); // value of s0 is "42"
10812
- string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); // value of s1 is "101010 42 52 2a"
10813
- string s2 = format("{0:#x} {0:#X}", 42); // value of s2 is "0x2a 0X2A"
10814
- string s3 = format("{:L}", 1234); // value of s3 can be "1,234"
10815
- // (depending on the locale)
10816
- ```
10817
-
10818
- — *end example*]
10819
-
10820
- **Table: Meaning of type options for integer types** <a id="format.type.int">[format.type.int]</a>
10821
-
10822
- | Type | Meaning |
10823
- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
10824
- | `b` | `to_chars(first, last, value, 2)`; \indextext{base prefix}% the base prefix is `0b`. |
10825
- | % `B` | The same as `b`, except that \indextext{base prefix}% the base prefix is `0B`. |
10826
- | % `c` | Copies the character `static_cast<charT>(value)` to the output. Throws `format_error` if `value` is not in the range of representable values for `charT`. |
10827
- | % `d` | `to_chars(first, last, value)`. |
10828
- | % `o` | `to_chars(first, last, value, 8)`; \indextext{base prefix}% the base prefix is `0` if `value` is nonzero and is empty otherwise. |
10829
- | % `x` | `to_chars(first, last, value, 16)`; \indextext{base prefix}% the base prefix is `0x`. |
10830
- | % `X` | The same as `x`, except that it uses uppercase letters for digits above 9 and \indextext{base prefix}% the base prefix is `0X`. |
10831
- | % none | The same as `d`. *If the formatting argument type is `charT` or `bool`, the default is instead `c` or `s`, respectively.* |
10832
-
10833
-
10834
- The available `charT` presentation types are specified in
10835
- [[format.type.char]].
10836
-
10837
- **Table: Meaning of type options for `charT`** <a id="format.type.char">[format.type.char]</a>
10838
-
10839
- | Type | Meaning |
10840
- | ------------------------------ | --------------------------------------------------------------------- |
10841
- | none, `c` | Copies the character to the output. |
10842
- | % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]]. |
10843
- | % `?` | Copies the escaped character [[format.string.escaped]] to the output. |
10844
-
10845
-
10846
- The available `bool` presentation types are specified in
10847
- [[format.type.bool]].
10848
-
10849
- **Table: Meaning of type options for `bool`** <a id="format.type.bool">[format.type.bool]</a>
10850
-
10851
- | Type | Meaning |
10852
- | ------------------------------ | -------------------------------------------------------------------------------------- |
10853
- | none, `s` | Copies textual representation, either `true` or `false`, to the output. |
10854
- | % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]] for the value `static_cast<unsigned char>(value)`. |
10855
-
10856
-
10857
- The available floating-point presentation types and their meanings for
10858
- values other than infinity and NaN are specified in
10859
- [[format.type.float]]. For lower-case presentation types, infinity and
10860
- NaN are formatted as `inf` and `nan`, respectively. For upper-case
10861
- presentation types, infinity and NaN are formatted as `INF` and `NAN`,
10862
- respectively.
10863
-
10864
- [*Note 7*: In either case, a sign is included if indicated by the
10865
- *sign* option. — *end note*]
10866
-
10867
- **Table: Meaning of type options for floating-point types** <a id="format.type.float">[format.type.float]</a>
10868
-
10869
- | Type | Meaning |
10870
- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10871
- | `a` | If precision is specified, equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::hex, precision) \end{codeblock} where `precision` is the specified formatting precision; equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::hex) \end{codeblock} otherwise. |
10872
- | % `A` | The same as `a`, except that it uses uppercase letters for digits above 9 and `P` to indicate the exponent. |
10873
- | % `e` | Equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::scientific, precision) \end{codeblock} where `precision` is the specified formatting precision, or `6` if precision is not specified. |
10874
- | % `E` | The same as `e`, except that it uses `E` to indicate exponent. |
10875
- | % `f`, `F` | Equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::fixed, precision) \end{codeblock} where `precision` is the specified formatting precision, or `6` if precision is not specified. |
10876
- | % `g` | Equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::general, precision) \end{codeblock} where `precision` is the specified formatting precision, or `6` if precision is not specified. |
10877
- | % `G` | The same as `g`, except that it uses `E` to indicate exponent. |
10878
- | % none | If precision is specified, equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::general, precision) \end{codeblock} where `precision` is the specified formatting precision; equivalent to \begin{codeblock} to_chars(first, last, value) \end{codeblock} otherwise. |
10879
-
10880
-
10881
- The available pointer presentation types and their mapping to `to_chars`
10882
- are specified in [[format.type.ptr]].
10883
-
10884
- [*Note 8*: Pointer presentation types also apply to
10885
- `nullptr_t`. — *end note*]
10886
-
10887
- **Table: Meaning of type options for pointer types** <a id="format.type.ptr">[format.type.ptr]</a>
10888
-
10889
- | Type | Meaning |
10890
- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10891
- | none, `p` | If `uintptr_t` is defined, \begin{codeblock} to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16) \end{codeblock} with the prefix `0x` inserted immediately before the output of `to_chars`; otherwise, implementation-defined. |
10892
-
10893
-
10894
- ### Error reporting <a id="format.err.report">[[format.err.report]]</a>
10895
-
10896
- Formatting functions throw `format_error` if an argument `fmt` is passed
10897
- that is not a format string for `args`. They propagate exceptions thrown
10898
- by operations of `formatter` specializations and iterators. Failure to
10899
- allocate storage is reported by throwing an exception as described in 
10900
- [[res.on.exception.handling]].
10901
-
10902
- ### Class template `basic_format_string` <a id="format.fmt.string">[[format.fmt.string]]</a>
10903
-
10904
- ``` cpp
10905
- namespace std {
10906
- template<class charT, class... Args>
10907
- struct basic_format_string {
10908
- private:
10909
- basic_string_view<charT> str; // exposition only
10910
-
10911
- public:
10912
- template<class T> consteval basic_format_string(const T& s);
10913
-
10914
- constexpr basic_string_view<charT> get() const noexcept { return str; }
10915
- };
10916
- }
10917
- ```
10918
-
10919
- ``` cpp
10920
- template<class T> consteval basic_format_string(const T& s);
10921
- ```
10922
-
10923
- *Constraints:* `const T&` models
10924
- `convertible_to<basic_string_view<charT>>`.
10925
-
10926
- *Effects:* Direct-non-list-initializes *str* with `s`.
10927
-
10928
- *Remarks:* A call to this function is not a core constant
10929
- expression [[expr.const]] unless there exist `args` of types `Args` such
10930
- that *str* is a format string for `args`.
10931
-
10932
- ### Formatting functions <a id="format.functions">[[format.functions]]</a>
10933
-
10934
- In the description of the functions, operator `+` is used for some of
10935
- the iterator categories for which it does not have to be defined. In
10936
- these cases the semantics of `a + n` are the same as in
10937
- [[algorithms.requirements]].
10938
-
10939
- ``` cpp
10940
- template<class... Args>
10941
- string format(format_string<Args...> fmt, Args&&... args);
10942
- ```
10943
-
10944
- *Effects:* Equivalent to:
10945
-
10946
- ``` cpp
10947
- return vformat(fmt.str, make_format_args(args...));
10948
- ```
10949
-
10950
- ``` cpp
10951
- template<class... Args>
10952
- wstring format(wformat_string<Args...> fmt, Args&&... args);
10953
- ```
10954
-
10955
- *Effects:* Equivalent to:
10956
-
10957
- ``` cpp
10958
- return vformat(fmt.str, make_wformat_args(args...));
10959
- ```
10960
-
10961
- ``` cpp
10962
- template<class... Args>
10963
- string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
10964
- ```
10965
-
10966
- *Effects:* Equivalent to:
10967
-
10968
- ``` cpp
10969
- return vformat(loc, fmt.str, make_format_args(args...));
10970
- ```
10971
-
10972
- ``` cpp
10973
- template<class... Args>
10974
- wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
10975
- ```
10976
-
10977
- *Effects:* Equivalent to:
10978
-
10979
- ``` cpp
10980
- return vformat(loc, fmt.str, make_wformat_args(args...));
10981
- ```
10982
-
10983
- ``` cpp
10984
- string vformat(string_view fmt, format_args args);
10985
- wstring vformat(wstring_view fmt, wformat_args args);
10986
- string vformat(const locale& loc, string_view fmt, format_args args);
10987
- wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
10988
- ```
10989
-
10990
- *Returns:* A string object holding the character representation of
10991
- formatting arguments provided by `args` formatted according to
10992
- specifications given in `fmt`. If present, `loc` is used for
10993
- locale-specific formatting.
10994
-
10995
- *Throws:* As specified in  [[format.err.report]].
10996
-
10997
- ``` cpp
10998
- template<class Out, class... Args>
10999
- Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
11000
- ```
11001
-
11002
- *Effects:* Equivalent to:
11003
-
11004
- ``` cpp
11005
- return vformat_to(std::move(out), fmt.str, make_format_args(args...));
11006
- ```
11007
-
11008
- ``` cpp
11009
- template<class Out, class... Args>
11010
- Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
11011
- ```
11012
-
11013
- *Effects:* Equivalent to:
11014
-
11015
- ``` cpp
11016
- return vformat_to(std::move(out), fmt.str, make_wformat_args(args...));
11017
- ```
11018
-
11019
- ``` cpp
11020
- template<class Out, class... Args>
11021
- Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
11022
- ```
11023
-
11024
- *Effects:* Equivalent to:
11025
-
11026
- ``` cpp
11027
- return vformat_to(std::move(out), loc, fmt.str, make_format_args(args...));
11028
- ```
11029
-
11030
- ``` cpp
11031
- template<class Out, class... Args>
11032
- Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
11033
- ```
11034
-
11035
- *Effects:* Equivalent to:
11036
-
11037
- ``` cpp
11038
- return vformat_to(std::move(out), loc, fmt.str, make_wformat_args(args...));
11039
- ```
11040
-
11041
- ``` cpp
11042
- template<class Out>
11043
- Out vformat_to(Out out, string_view fmt, format_args args);
11044
- template<class Out>
11045
- Out vformat_to(Out out, wstring_view fmt, wformat_args args);
11046
- template<class Out>
11047
- Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
11048
- template<class Out>
11049
- Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
11050
- ```
11051
-
11052
- Let `charT` be `decltype(fmt)::value_type`.
11053
-
11054
- *Constraints:* `Out` satisfies `output_iterator<const charT&>`.
11055
-
11056
- *Preconditions:* `Out` models `output_iterator<const charT&>`.
11057
-
11058
- *Effects:* Places the character representation of formatting the
11059
- arguments provided by `args`, formatted according to the specifications
11060
- given in `fmt`, into the range \[`out`, `out + N`), where `N` is the
11061
- number of characters in that character representation. If present, `loc`
11062
- is used for locale-specific formatting.
11063
-
11064
- *Returns:* `out + N`.
11065
-
11066
- *Throws:* As specified in  [[format.err.report]].
11067
-
11068
- ``` cpp
11069
- template<class Out, class... Args>
11070
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
11071
- format_string<Args...> fmt, Args&&... args);
11072
- template<class Out, class... Args>
11073
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
11074
- wformat_string<Args...> fmt, Args&&... args);
11075
- template<class Out, class... Args>
11076
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
11077
- const locale& loc, format_string<Args...> fmt,
11078
- Args&&... args);
11079
- template<class Out, class... Args>
11080
- format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
11081
- const locale& loc, wformat_string<Args...> fmt,
11082
- Args&&... args);
11083
- ```
11084
-
11085
- Let
11086
-
11087
- - `charT` be `decltype(fmt.`*`str`*`)::value_type`,
11088
- - `N` be `formatted_size(fmt, args...)` for the functions without a
11089
- `loc` parameter and `formatted_size(loc, fmt, args...)` for the
11090
- functions with a `loc` parameter, and
11091
- - `M` be `clamp(n, 0, N)`.
11092
-
11093
- *Constraints:* `Out` satisfies `output_iterator<const charT&>`.
11094
-
11095
- *Preconditions:* `Out` models `output_iterator<const charT&>`, and
11096
- `formatter<``remove_cvref_t<Tᵢ``>, charT>` meets the
11097
- requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
11098
-
11099
- *Effects:* Places the first `M` characters of the character
11100
- representation of formatting the arguments provided by `args`, formatted
11101
- according to the specifications given in `fmt`, into the range \[`out`,
11102
- `out + M`). If present, `loc` is used for locale-specific formatting.
11103
-
11104
- *Returns:* `{out + M, N}`.
11105
-
11106
- *Throws:* As specified in  [[format.err.report]].
11107
-
11108
- ``` cpp
11109
- template<class... Args>
11110
- size_t formatted_size(format_string<Args...> fmt, Args&&... args);
11111
- template<class... Args>
11112
- size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
11113
- template<class... Args>
11114
- size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
11115
- template<class... Args>
11116
- size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
11117
- ```
11118
-
11119
- Let `charT` be `decltype(fmt.`*`str`*`)::value_type`.
11120
-
11121
- *Preconditions:* `formatter<``remove_cvref_t<Tᵢ``>, charT>` meets the
11122
- requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
11123
-
11124
- *Returns:* The number of characters in the character representation of
11125
- formatting arguments `args` formatted according to specifications given
11126
- in `fmt`. If present, `loc` is used for locale-specific formatting.
11127
-
11128
- *Throws:* As specified in  [[format.err.report]].
11129
-
11130
- ### Formatter <a id="format.formatter">[[format.formatter]]</a>
11131
-
11132
- #### Formatter requirements <a id="formatter.requirements">[[formatter.requirements]]</a>
11133
-
11134
- A type `F` meets the requirements if it meets the
11135
-
11136
- - *Cpp17DefaultConstructible* ([[cpp17.defaultconstructible]]),
11137
- - *Cpp17CopyConstructible* ([[cpp17.copyconstructible]]),
11138
- - *Cpp17CopyAssignable* ([[cpp17.copyassignable]]),
11139
- - *Cpp17Swappable* [[swappable.requirements]], and
11140
- - *Cpp17Destructible* ([[cpp17.destructible]])
11141
-
11142
- requirements, and the expressions shown in [[formatter.basic]] are valid
11143
- and have the indicated semantics.
11144
-
11145
- A type `F` meets the requirements if it meets the requirements and the
11146
- expressions shown in [[formatter]] are valid and have the indicated
11147
- semantics.
11148
-
11149
- Given character type `charT`, output iterator type `Out`, and formatting
11150
- argument type `T`, in [[formatter.basic]] and [[formatter]]:
11151
-
11152
- - `f` is a value of type (possibly const) `F`,
11153
- - `g` is an lvalue of type `F`,
11154
- - `u` is an lvalue of type `T`,
11155
- - `t` is a value of a type convertible to (possibly const) `T`,
11156
- - `PC` is `basic_format_parse_context<charT>`,
11157
- - `FC` is `basic_format_context<Out, charT>`,
11158
- - `pc` is an lvalue of type `PC`, and
11159
- - `fc` is an lvalue of type `FC`.
11160
-
11161
- `pc.begin()` points to the beginning of the *format-spec*
11162
- [[format.string]] of the replacement field being formatted in the format
11163
- string. If *format-spec* is empty then either `pc.begin() == pc.end()`
11164
- or `*pc.begin() == '}'`.
11165
-
11166
- [*Note 1*: This allows formatters to emit meaningful error
11167
- messages. — *end note*]
11168
-
11169
- **Table: \newoldconcept{Formatter} requirements** <a id="formatter">[formatter]</a>
11170
-
11171
- | Expression | Return type | Requirement |
11172
- | ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11173
- | `f.format(t, fc)` | `FC::iterator` | Formats `t` according to the specifiers stored in `*this`, writes the output to `fc.out()`, and returns an iterator past the end of the output range. The output shall only depend on `t`, `fc.locale()`, `fc.arg(n)` for any value `n` of type `size_t`, and the range {[}`pc.begin()`, `pc.end()`{)} from the last call to `f.parse(pc)`. |
11174
- | `f.format(u, fc)` | `FC::iterator` | As above, but does not modify `u`. |
11175
-
11176
-
11177
- #### Concept <a id="format.formattable">[[format.formattable]]</a>
11178
-
11179
- Let `fmt-iter-for<charT>` be an unspecified type that models
11180
- `output_iterator<const charT&>` [[iterator.concept.output]].
11181
-
11182
- ``` cpp
11183
- template<class T, class Context,
11184
- class Formatter = typename Context::template formatter_type<remove_const_t<T>>>
11185
- concept formattable-with = // exposition only
11186
- semiregular<Formatter> &&
11187
- requires(Formatter& f, const Formatter& cf, T&& t, Context fc,
11188
- basic_format_parse_context<typename Context::char_type> pc)
11189
- {
11190
- { f.parse(pc) } -> same_as<typename decltype(pc)::iterator>;
11191
- { cf.format(t, fc) } -> same_as<typename Context::iterator>;
11192
- };
11193
-
11194
- template<class T, class charT>
11195
- concept formattable =
11196
- formattable-with<remove_reference_t<T>, basic_format_context<fmt-iter-for<charT>>>;
11197
- ```
11198
-
11199
- A type `T` and a character type `charT` model `formattable` if
11200
- `formatter<remove_cvref_t<T>, charT>` meets the requirements
11201
- [[formatter.requirements]] and, if `remove_reference_t<T>` is
11202
- const-qualified, the requirements.
11203
-
11204
- #### Formatter specializations <a id="format.formatter.spec">[[format.formatter.spec]]</a>
11205
-
11206
- The functions defined in [[format.functions]] use specializations of the
11207
- class template `formatter` to format individual arguments.
11208
-
11209
- Let `charT` be either `char` or `wchar_t`. Each specialization of
11210
- `formatter` is either enabled or disabled, as described below. A
11211
- *debug-enabled* specialization of `formatter` additionally provides a
11212
- public, constexpr, non-static member function `set_debug_format()` which
11213
- modifies the state of the `formatter` to be as if the type of the
11214
- *std-format-spec* parsed by the last call to `parse` were `?`. Each
11215
- header that declares the template `formatter` provides the following
11216
- enabled specializations:
11217
-
11218
- - The debug-enabled specializations
11219
- ``` cpp
11220
- template<> struct formatter<char, char>;
11221
- template<> struct formatter<char, wchar_t>;
11222
- template<> struct formatter<wchar_t, wchar_t>;
11223
- ```
11224
- - For each `charT`, the debug-enabled string type specializations
11225
- ``` cpp
11226
- template<> struct formatter<charT*, charT>;
11227
- template<> struct formatter<const charT*, charT>;
11228
- template<size_t N> struct formatter<charT[N], charT>;
11229
- template<class traits, class Allocator>
11230
- struct formatter<basic_string<charT, traits, Allocator>, charT>;
11231
- template<class traits>
11232
- struct formatter<basic_string_view<charT, traits>, charT>;
11233
- ```
11234
- - For each `charT`, for each cv-unqualified arithmetic type
11235
- `ArithmeticT` other than `char`, `wchar_t`, `char8_t`, `char16_t`, or
11236
- `char32_t`, a specialization
11237
- ``` cpp
11238
- template<> struct formatter<ArithmeticT, charT>;
11239
- ```
11240
- - For each `charT`, the pointer type specializations
11241
- ``` cpp
11242
- template<> struct formatter<nullptr_t, charT>;
11243
- template<> struct formatter<void*, charT>;
11244
- template<> struct formatter<const void*, charT>;
11245
- ```
11246
-
11247
- The `parse` member functions of these formatters interpret the format
11248
- specification as a *std-format-spec* as described in
11249
- [[format.string.std]].
11250
-
11251
- [*Note 1*: Specializations such as `formatter<wchar_t, char>` and
11252
- `formatter<const char*, wchar_t>` that would require implicit multibyte
11253
- / wide string or character conversion are disabled. — *end note*]
11254
-
11255
- For any types `T` and `charT` for which neither the library nor the user
11256
- provides an explicit or partial specialization of the class template
11257
- `formatter`, `formatter<T, charT>` is disabled.
11258
-
11259
- If the library provides an explicit or partial specialization of
11260
- `formatter<T, charT>`, that specialization is enabled and meets the
11261
- requirements except as noted otherwise.
11262
-
11263
- If `F` is a disabled specialization of `formatter`, these values are
11264
- `false`:
11265
-
11266
- - `is_default_constructible_v<F>`,
11267
- - `is_copy_constructible_v<F>`,
11268
- - `is_move_constructible_v<F>`,
11269
- - `is_copy_assignable_v<F>`, and
11270
- - `is_move_assignable_v<F>`.
11271
-
11272
- An enabled specialization `formatter<T, charT>` meets the requirements
11273
- [[formatter.requirements]].
11274
-
11275
- [*Example 1*:
11276
-
11277
- ``` cpp
11278
- #include <format>
11279
-
11280
- enum color { red, green, blue };
11281
- const char* color_names[] = { "red", "green", "blue" };
11282
-
11283
- template<> struct std::formatter<color> : std::formatter<const char*> {
11284
- auto format(color c, format_context& ctx) const {
11285
- return formatter<const char*>::format(color_names[c], ctx);
11286
- }
11287
- };
11288
-
11289
- struct err {};
11290
-
11291
- std::string s0 = std::format("{}", 42); // OK, library-provided formatter
11292
- std::string s1 = std::format("{}", L"foo"); // error: disabled formatter
11293
- std::string s2 = std::format("{}", red); // OK, user-provided formatter
11294
- std::string s3 = std::format("{}", err{}); // error: disabled formatter
11295
- ```
11296
-
11297
- — *end example*]
11298
-
11299
- #### Formatting escaped characters and strings <a id="format.string.escaped">[[format.string.escaped]]</a>
11300
-
11301
- A character or string can be formatted as *escaped* to make it more
11302
- suitable for debugging or for logging.
11303
-
11304
- The escaped string *E* representation of a string *S* is constructed by
11305
- encoding a sequence of characters as follows. The associated character
11306
- encoding *CE* for `charT` ([[lex.string.literal]]) is used to both
11307
- interpret *S* and construct *E*.
11308
-
11309
- - U+0022 (quotation mark) (`"`) is appended to *E*.
11310
- - For each code unit sequence *X* in *S* that either encodes a single
11311
- character, is a shift sequence, or is a sequence of ill-formed code
11312
- units, processing is in order as follows:
11313
- - If *X* encodes a single character *C*, then:
11314
- - If *C* is one of the characters in [[format.escape.sequences]],
11315
- then the two characters shown as the corresponding escape sequence
11316
- are appended to *E*.
11317
- - Otherwise, if *C* is not U+0020 (space) and
11318
- - *CE* is UTF-8, UTF-16, or UTF-32 and *C* corresponds to a
11319
- Unicode scalar value whose Unicode property `General_Category`
11320
- has a value in the groups `Separator` (`Z`) or `Other` (`C`), as
11321
- described by UAX \#44 of the Unicode Standard, or
11322
- - *CE* is UTF-8, UTF-16, or UTF-32 and *C* corresponds to a
11323
- Unicode scalar value with the Unicode property
11324
- `Grapheme_Extend=Yes` as described by UAX \#44 of the Unicode
11325
- Standard and *C* is not immediately preceded in *S* by a
11326
- character *P* appended to *E* without translation to an escape
11327
- sequence, or
11328
- - *CE* is neither UTF-8, UTF-16, nor UTF-32 and *C* is one of an
11329
- implementation-defined set of separator or non-printable
11330
- characters
11331
-
11332
- then the sequence `\u{hex-digit-sequence}` is appended to *E*,
11333
- where `hex-digit-sequence` is the shortest hexadecimal
11334
- representation of *C* using lower-case hexadecimal digits.
11335
- - Otherwise, *C* is appended to *E*.
11336
- - Otherwise, if *X* is a shift sequence, the effect on *E* and further
11337
- decoding of *S* is unspecified. *Recommended practice:* A shift
11338
- sequence should be represented in *E* such that the original code
11339
- unit sequence of *S* can be reconstructed.
11340
- - Otherwise (*X* is a sequence of ill-formed code units), each code
11341
- unit *U* is appended to *E* in order as the sequence
11342
- `\x{hex-digit-sequence}`, where `hex-digit-sequence` is the shortest
11343
- hexadecimal representation of *U* using lower-case hexadecimal
11344
- digits.
11345
- - Finally, U+0022 (quotation mark) (`"`) is appended to *E*.
11346
-
11347
- **Table: Mapping of characters to escape sequences** <a id="format.escape.sequences">[format.escape.sequences]</a>
11348
-
11349
- | Character | Escape sequence |
11350
- | ----------------------------- | --------------- |
11351
- | U+0009 (character tabulation) | `\t` |
11352
- | % U+000a (line feed) | `\n` |
11353
- | % U+000d (carriage return) | `\r` |
11354
- | % U+0022 (quotation mark) | `\"` |
11355
- | % U+005c (reverse solidus) | `` |
11356
-
11357
-
11358
- The escaped string representation of a character *C* is equivalent to
11359
- the escaped string representation of a string of *C*, except that:
11360
-
11361
- - the result starts and ends with U+0027 (apostrophe) (`'`) instead of
11362
- U+0022 (quotation mark) (`"`), and
11363
- - if *C* is U+0027 (apostrophe), the two characters `\'` are appended to
11364
- *E*, and
11365
- - if *C* is U+0022 (quotation mark), then *C* is appended unchanged.
11366
-
11367
- [*Example 1*:
11368
-
11369
- ``` cpp
11370
- string s0 = format("[{}]", "h\tllo"); // s0 has value: [h\ \ \ \ llo]
11371
- string s1 = format("[{:?}]", "h\tllo"); // s1 has value: ["h\ tllo"]
11372
- string s3 = format("[{:?}, {:?}]", '\'', '"'); // s3 has value: ['\ '', '"']
11373
-
11374
- // The following examples assume use of the UTF-8 encoding
11375
- string s4 = format("[{:?}]", string("\0 \n \t \x02 \x1b", 9));
11376
- // s4 has value: ["\ u{0\ \ n \ t \ u{2} \ u{1b}"]}
11377
- string s5 = format("[{:?}]", "\xc3\x28"); // invalid UTF-8, s5 has value: ["\ x{c3\("]}
11378
- string s7 = format("[{:?}]", "\u0301"); // s7 has value: ["\ u{301"]}
11379
- string s8 = format("[{:?}]", "\\\u0301"); // s8 has value: ["\ \ \ u{301"]}
11380
- ```
11381
-
11382
- — *end example*]
11383
-
11384
- #### Class template `basic_format_parse_context` <a id="format.parse.ctx">[[format.parse.ctx]]</a>
11385
-
11386
- ``` cpp
11387
- namespace std {
11388
- template<class charT>
11389
- class basic_format_parse_context {
11390
- public:
11391
- using char_type = charT;
11392
- using const_iterator = typename basic_string_view<charT>::const_iterator;
11393
- using iterator = const_iterator;
11394
-
11395
- private:
11396
- iterator begin_; // exposition only
11397
- iterator end_; // exposition only
11398
- enum indexing { unknown, manual, automatic }; // exposition only
11399
- indexing indexing_; // exposition only
11400
- size_t next_arg_id_; // exposition only
11401
- size_t num_args_; // exposition only
11402
-
11403
- public:
11404
- constexpr explicit basic_format_parse_context(basic_string_view<charT> fmt,
11405
- size_t num_args = 0) noexcept;
11406
- basic_format_parse_context(const basic_format_parse_context&) = delete;
11407
- basic_format_parse_context& operator=(const basic_format_parse_context&) = delete;
11408
-
11409
- constexpr const_iterator begin() const noexcept;
11410
- constexpr const_iterator end() const noexcept;
11411
- constexpr void advance_to(const_iterator it);
11412
-
11413
- constexpr size_t next_arg_id();
11414
- constexpr void check_arg_id(size_t id);
11415
- };
11416
- }
11417
- ```
11418
-
11419
- An instance of `basic_format_parse_context` holds the format string
11420
- parsing state consisting of the format string range being parsed and the
11421
- argument counter for automatic indexing.
11422
-
11423
- ``` cpp
11424
- constexpr explicit basic_format_parse_context(basic_string_view<charT> fmt,
11425
- size_t num_args = 0) noexcept;
11426
- ```
11427
-
11428
- *Effects:* Initializes `begin_` with `fmt.begin()`, `end_` with
11429
- `fmt.end()`, `indexing_` with `unknown`, `next_arg_id_` with `0`, and
11430
- `num_args_` with `num_args`.
11431
-
11432
- ``` cpp
11433
- constexpr const_iterator begin() const noexcept;
11434
- ```
11435
-
11436
- *Returns:* `begin_`.
11437
-
11438
- ``` cpp
11439
- constexpr const_iterator end() const noexcept;
11440
- ```
11441
-
11442
- *Returns:* `end_`.
11443
-
11444
- ``` cpp
11445
- constexpr void advance_to(const_iterator it);
11446
- ```
11447
-
11448
- *Preconditions:* `end()` is reachable from `it`.
11449
-
11450
- *Effects:* Equivalent to: `begin_ = it;`
11451
-
11452
- ``` cpp
11453
- constexpr size_t next_arg_id();
11454
- ```
11455
-
11456
- *Effects:* If `indexing_ != manual` is `true`, equivalent to:
11457
-
11458
- ``` cpp
11459
- if (indexing_ == unknown)
11460
- indexing_ = automatic;
11461
- return next_arg_id_++;
11462
- ```
11463
-
11464
- *Throws:* `format_error` if `indexing_ == manual` is `true` which
11465
- indicates mixing of automatic and manual argument indexing.
11466
-
11467
- *Remarks:* Let *`cur-arg-id`* be the value of `next_arg_id_` prior to
11468
- this call. Call expressions where *`cur-arg-id`*` >= num_args_` is
11469
- `true` are not core constant expressions [[expr.const]].
11470
-
11471
- ``` cpp
11472
- constexpr void check_arg_id(size_t id);
11473
- ```
11474
-
11475
- *Effects:* If `indexing_ != automatic` is `true`, equivalent to:
11476
-
11477
- ``` cpp
11478
- if (indexing_ == unknown)
11479
- indexing_ = manual;
11480
- ```
11481
-
11482
- *Throws:* `format_error` if `indexing_ == automatic` is `true` which
11483
- indicates mixing of automatic and manual argument indexing.
11484
-
11485
- *Remarks:* Call expressions where `id >= num_args_` is `true` are not
11486
- core constant expressions [[expr.const]].
11487
-
11488
- #### Class template `basic_format_context` <a id="format.context">[[format.context]]</a>
11489
-
11490
- ``` cpp
11491
- namespace std {
11492
- template<class Out, class charT>
11493
- class basic_format_context {
11494
- basic_format_args<basic_format_context> args_; // exposition only
11495
- Out out_; // exposition only
11496
-
11497
- public:
11498
- using iterator = Out;
11499
- using char_type = charT;
11500
- template<class T> using formatter_type = formatter<T, charT>;
11501
-
11502
- basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
11503
- std::locale locale();
11504
-
11505
- iterator out();
11506
- void advance_to(iterator it);
11507
- };
11508
- }
11509
- ```
11510
-
11511
- An instance of `basic_format_context` holds formatting state consisting
11512
- of the formatting arguments and the output iterator.
11513
-
11514
- `Out` shall model `output_iterator<const charT&>`.
11515
-
11516
- `format_context` is an alias for a specialization of
11517
- `basic_format_context` with an output iterator that appends to `string`,
11518
- such as `back_insert_iterator<string>`. Similarly, `wformat_context` is
11519
- an alias for a specialization of `basic_format_context` with an output
11520
- iterator that appends to `wstring`.
11521
-
11522
- *Recommended practice:* For a given type `charT`, implementations should
11523
- provide a single instantiation of `basic_format_context` for appending
11524
- to `basic_string<charT>`, `vector<charT>`, or any other container with
11525
- contiguous storage by wrapping those in temporary objects with a uniform
11526
- interface (such as a `span<charT>`) and polymorphic reallocation.
11527
-
11528
- ``` cpp
11529
- basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
11530
- ```
11531
-
11532
- *Returns:* `args_.get(id)`.
11533
-
11534
- ``` cpp
11535
- std::locale locale();
11536
- ```
11537
-
11538
- *Returns:* The locale passed to the formatting function if the latter
11539
- takes one, and `std::locale()` otherwise.
11540
-
11541
- ``` cpp
11542
- iterator out();
11543
- ```
11544
-
11545
- *Effects:* Equivalent to: `return std::move(out_);`
11546
-
11547
- ``` cpp
11548
- void advance_to(iterator it);
11549
- ```
11550
-
11551
- *Effects:* Equivalent to: `out_ = std::move(it);`
11552
-
11553
- [*Example 1*:
11554
-
11555
- ``` cpp
11556
- struct S { int value; };
11557
-
11558
- template<> struct std::formatter<S> {
11559
- size_t width_arg_id = 0;
11560
-
11561
- // Parses a width argument id in the format { digit }.
11562
- constexpr auto parse(format_parse_context& ctx) {
11563
- auto iter = ctx.begin();
11564
- auto get_char = [&]() { return iter != ctx.end() ? *iter : 0; };
11565
- if (get_char() != '{')
11566
- return iter;
11567
- ++iter;
11568
- char c = get_char();
11569
- if (!isdigit(c) || (++iter, get_char()) != '}')
11570
- throw format_error("invalid format");
11571
- width_arg_id = c - '0';
11572
- ctx.check_arg_id(width_arg_id);
11573
- return ++iter;
11574
- }
11575
-
11576
- // Formats an S with width given by the argument width_arg_id.
11577
- auto format(S s, format_context& ctx) const {
11578
- int width = visit_format_arg([](auto value) -> int {
11579
- if constexpr (!is_integral_v<decltype(value)>)
11580
- throw format_error("width is not integral");
11581
- else if (value < 0 || value > numeric_limits<int>::max())
11582
- throw format_error("invalid width");
11583
- else
11584
- return value;
11585
- }, ctx.arg(width_arg_id));
11586
- return format_to(ctx.out(), "{0:x<{1}}", s.value, width);
11587
- }
11588
- };
11589
-
11590
- std::string s = std::format("{0:{1}}", S{42}, 10); // value of s is "xxxxxxxx42"
11591
- ```
11592
-
11593
- — *end example*]
11594
-
11595
- ### Formatting of ranges <a id="format.range">[[format.range]]</a>
11596
-
11597
- #### Variable template `format_kind` <a id="format.range.fmtkind">[[format.range.fmtkind]]</a>
11598
-
11599
- ``` cpp
11600
- template<ranges::input_range R>
11601
- requires same_as<R, remove_cvref_t<R>>
11602
- constexpr range_format format_kind<R> = see below;
11603
- ```
11604
-
11605
- A program that instantiates the primary template of `format_kind` is
11606
- ill-formed.
11607
-
11608
- For a type `R`, `format_kind<R>` is defined as follows:
11609
-
11610
- - If `same_as<remove_cvref_t<ranges::range_reference_t<R>>, R>` is
11611
- `true`, `format_kind<R>` is `range_format::disabled`. \[*Note 1*: This
11612
- prevents constraint recursion for ranges whose reference type is the
11613
- same range type. For example, `std::filesystem::path` is a range of
11614
- `std::filesystem::path`. — *end note*]
11615
- - Otherwise, if the *qualified-id* `R::key_type` is valid and denotes a
11616
- type:
11617
- - If the *qualified-id* `R::mapped_type` is valid and denotes a type,
11618
- let `U` be `remove_cvref_t<ranges::range_reference_t<R>>`. If either
11619
- `U` is a specialization of `pair` or `U` is a specialization of
11620
- `tuple` and `tuple_size_v<U> == 2`, `format_kind<R>` is
11621
- `range_format::map`.
11622
- - Otherwise, `format_kind<R>` is `range_format::set`.
11623
- - Otherwise, `format_kind<R>` is `range_format::sequence`.
11624
-
11625
- *Remarks:* Pursuant to [[namespace.std]], users may specialize
11626
- `format_kind` for cv-unqualified program-defined types that model
11627
- `ranges::input_range`. Such specializations shall be usable in constant
11628
- expressions [[expr.const]] and have type `const range_format`.
11629
-
11630
- #### Class template `range_formatter` <a id="format.range.formatter">[[format.range.formatter]]</a>
11631
-
11632
- ``` cpp
11633
- namespace std {
11634
- template<class T, class charT = char>
11635
- requires same_as<remove_cvref_t<T>, T> && formattable<T, charT>
11636
- class range_formatter {
11637
- formatter<T, charT> underlying_; // exposition only
11638
- basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only
11639
- basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("["); // exposition only
11640
- basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>("]"); // exposition only
11641
-
11642
- public:
11643
- constexpr void set_separator(basic_string_view<charT> sep) noexcept;
11644
- constexpr void set_brackets(basic_string_view<charT> opening,
11645
- basic_string_view<charT> closing) noexcept;
11646
- constexpr formatter<T, charT>& underlying() noexcept { return underlying_; }
11647
- constexpr const formatter<T, charT>& underlying() const noexcept { return underlying_; }
11648
-
11649
- template<class ParseContext>
11650
- constexpr typename ParseContext::iterator
11651
- parse(ParseContext& ctx);
11652
-
11653
- template<ranges::input_range R, class FormatContext>
11654
- requires formattable<ranges::range_reference_t<R>, charT> &&
11655
- same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
11656
- typename FormatContext::iterator
11657
- format(R&& r, FormatContext& ctx) const;
11658
- };
11659
- }
11660
- ```
11661
-
11662
- The class template `range_formatter` is a utility for implementing
11663
- `formatter` specializations for range types.
11664
-
11665
- `range_formatter` interprets *format-spec* as a *range-format-spec*. The
11666
- syntax of format specifications is as follows:
11667
-
11668
- ``` bnf
11669
- range-format-spec
11670
- range-fill-and-alignₒₚₜ widthₒₚₜ 'n'ₒₚₜ range-typeₒₚₜ range-underlying-specₒₚₜ
11671
- ```
11672
-
11673
- ``` bnf
11674
- range-fill-and-align
11675
- range-fillₒₚₜ align
11676
- ```
11677
-
11678
- ``` bnf
11679
- range-fill
11680
- any character other than '{' or '}' or ':'
11681
- ```
11682
-
11683
- ``` bnf
11684
- range-type
11685
- 'm'
11686
- 's'
11687
- '?s'
11688
- ```
11689
-
11690
- ``` bnf
11691
- range-underlying-spec
11692
- ':' format-spec
11693
- ```
11694
-
11695
- For `range_formatter<T, charT>`, the *format-spec* in a
11696
- *range-underlying-spec*, if any, is interpreted by
11697
- `formatter<T, charT>`.
11698
-
11699
- The *range-fill-and-align* is interpreted the same way as a
11700
- *fill-and-align* [[format.string.std]]. The productions *align* and
11701
- *width* are described in [[format.string]].
11702
-
11703
- The `n` option causes the range to be formatted without the opening and
11704
- closing brackets.
11705
-
11706
- [*Note 1*: This is equivalent to invoking
11707
- `set_brackets({}, {})`. — *end note*]
11708
-
11709
- The *range-type* specifier changes the way a range is formatted, with
11710
- certain options only valid with certain argument types. The meaning of
11711
- the various type options is as specified in [[formatter.range.type]].
11712
-
11713
- **Table: Meaning of range-type options** <a id="formatter.range.type">[formatter.range.type]</a>
11714
-
11715
- | Option | Requirements | Meaning |
11716
- | ------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11717
- | % `m` | `T` shall be either a specialization of `pair` or a specialization of `tuple` such that `tuple_size_v<T>` is `2`. | Indicates that the opening bracket should be `"{"`, the closing bracket should be `"}"`, the separator should be `", "`, and each range element should be formatted as if `m` were specified for its tuple-type. *If the `n` option is provided in addition to the `m` option, both the opening and closing brackets are still empty.* |
11718
- | % `s` | `T` shall be `charT`. | Indicates that the range should be formatted as a `string`. |
11719
- | % `?s` | `T` shall be `charT`. | Indicates that the range should be formatted as an escaped string [[format.string.escaped]]. |
11720
-
11721
-
11722
- If the *range-type* is `s` or `?s`, then there shall be no `n` option
11723
- and no *range-underlying-spec*.
11724
-
11725
- ``` cpp
11726
- constexpr void set_separator(basic_string_view<charT> sep) noexcept;
11727
- ```
11728
-
11729
- *Effects:* Equivalent to: *`separator_`*` = sep;`
11730
-
11731
- ``` cpp
11732
- constexpr void set_brackets(basic_string_view<charT> opening,
11733
- basic_string_view<charT> closing) noexcept;
11734
- ```
11735
-
11736
- *Effects:* Equivalent to:
11737
-
11738
- ``` cpp
11739
- opening-bracket_ = opening;
11740
- closing-bracket_ = closing;
11741
- ```
11742
-
11743
- ``` cpp
11744
- template<class ParseContext>
11745
- constexpr typename ParseContext::iterator
11746
- parse(ParseContext& ctx);
11747
- ```
11748
-
11749
- *Effects:* Parses the format specifier as a *range-format-spec* and
11750
- stores the parsed specifiers in `*this`. The values of
11751
- *opening-bracket\_*, *closing-bracket\_*, and *separator\_* are modified
11752
- if and only if required by the *range-type* or the `n` option, if
11753
- present. If:
11754
-
11755
- - the *range-type* is neither `s` nor `?s`,
11756
- - *`underlying_`*`.set_debug_format()` is a valid expression, and
11757
- - there is no *range-underlying-spec*,
11758
-
11759
- then calls *`underlying_`*`.set_debug_format()`.
11760
-
11761
- *Returns:* An iterator past the end of the *range-format-spec*.
11762
-
11763
- ``` cpp
11764
- template<ranges::input_range R, class FormatContext>
11765
- requires formattable<ranges::range_reference_t<R>, charT> &&
11766
- same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
11767
- typename FormatContext::iterator
11768
- format(R&& r, FormatContext& ctx) const;
11769
- ```
11770
-
11771
- *Effects:* Writes the following into `ctx.out()`, adjusted according to
11772
- the *range-format-spec*:
11773
-
11774
- - If the *range-type* was `s`, then as if by formatting
11775
- `basic_string<charT>(from_range, r)`.
11776
- - Otherwise, if the *range-type* was `?s`, then as if by formatting
11777
- `basic_string<charT>(from_range, r)` as an escaped
11778
- string [[format.string.escaped]].
11779
- - Otherwise,
11780
- - *opening-bracket\_*,
11781
- - for each element `e` of the range `r`:
11782
- - the result of writing `e` via *underlying\_* and
11783
- - *separator\_*, unless `e` is the last element of `r`, and
11784
- - *closing-bracket\_*.
11785
-
11786
- *Returns:* An iterator past the end of the output range.
11787
-
11788
- #### Class template *`range-default-formatter`* <a id="format.range.fmtdef">[[format.range.fmtdef]]</a>
11789
-
11790
- ``` cpp
11791
- namespace std {
11792
- template<ranges::input_range R, class charT>
11793
- struct range-default-formatter<range_format::sequence, R, charT> { // exposition only
11794
- private:
11795
- using maybe-const-r = fmt-maybe-const<R, charT>; // exposition only
11796
- range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-r>>,
11797
- charT> underlying_; // exposition only
11798
-
11799
- public:
11800
- constexpr void set_separator(basic_string_view<charT> sep) noexcept;
11801
- constexpr void set_brackets(basic_string_view<charT> opening,
11802
- basic_string_view<charT> closing) noexcept;
11803
-
11804
- template<class ParseContext>
11805
- constexpr typename ParseContext::iterator
11806
- parse(ParseContext& ctx);
11807
-
11808
- template<class FormatContext>
11809
- typename FormatContext::iterator
11810
- format(maybe-const-r& elems, FormatContext& ctx) const;
11811
- };
11812
- }
11813
- ```
11814
-
11815
- ``` cpp
11816
- constexpr void set_separator(basic_string_view<charT> sep) noexcept;
11817
- ```
11818
-
11819
- *Effects:* Equivalent to: *`underlying_`*`.set_separator(sep);`
11820
-
11821
- ``` cpp
11822
- constexpr void set_brackets(basic_string_view<charT> opening,
11823
- basic_string_view<charT> closing) noexcept;
11824
- ```
11825
-
11826
- *Effects:* Equivalent to:
11827
- *`underlying_`*`.set_brackets(opening, closing);`
11828
-
11829
- ``` cpp
11830
- template<class ParseContext>
11831
- constexpr typename ParseContext::iterator
11832
- parse(ParseContext& ctx);
11833
- ```
11834
-
11835
- *Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
11836
-
11837
- ``` cpp
11838
- template<class FormatContext>
11839
- typename FormatContext::iterator
11840
- format(maybe-const-r& elems, FormatContext& ctx) const;
11841
- ```
11842
-
11843
- *Effects:* Equivalent to: `return `*`underlying_`*`.format(elems, ctx);`
11844
-
11845
- #### Specialization of *`range-default-formatter`* for maps <a id="format.range.fmtmap">[[format.range.fmtmap]]</a>
11846
-
11847
- ``` cpp
11848
- namespace std {
11849
- template<ranges::input_range R, class charT>
11850
- struct range-default-formatter<range_format::map, R, charT> {
11851
- private:
11852
- using maybe-const-map = fmt-maybe-const<R, charT>; // exposition only
11853
- using element-type = // exposition only
11854
- remove_cvref_t<ranges::range_reference_t<maybe-const-map>>;
11855
- range_formatter<element-type, charT> underlying_; // exposition only
11856
-
11857
- public:
11858
- constexpr range-default-formatter();
11859
-
11860
- template<class ParseContext>
11861
- constexpr typename ParseContext::iterator
11862
- parse(ParseContext& ctx);
11863
-
11864
- template<class FormatContext>
11865
- typename FormatContext::iterator
11866
- format(maybe-const-map& r, FormatContext& ctx) const;
11867
- };
11868
- }
11869
- ```
11870
-
11871
- ``` cpp
11872
- constexpr range-default-formatter();
11873
- ```
11874
-
11875
- *Mandates:* Either:
11876
-
11877
- - *element-type* is a specialization of `pair`, or
11878
- - *element-type* is a specialization of `tuple` and
11879
- `tuple_size_v<`*`element-type`*`> == 2`.
11880
-
11881
- *Effects:* Equivalent to:
11882
-
11883
- ``` cpp
11884
- underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
11885
- underlying_.underlying().set_brackets({}, {});
11886
- underlying_.underlying().set_separator(STATICALLY-WIDEN<charT>(": "));
11887
- ```
11888
-
11889
- ``` cpp
11890
- template<class ParseContext>
11891
- constexpr typename ParseContext::iterator
11892
- parse(ParseContext& ctx);
11893
- ```
11894
-
11895
- *Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
11896
-
11897
- ``` cpp
11898
- template<class FormatContext>
11899
- typename FormatContext::iterator
11900
- format(maybe-const-map& r, FormatContext& ctx) const;
11901
- ```
11902
-
11903
- *Effects:* Equivalent to: `return `*`underlying_`*`.format(r, ctx);`
11904
-
11905
- #### Specialization of *`range-default-formatter`* for sets <a id="format.range.fmtset">[[format.range.fmtset]]</a>
11906
-
11907
- ``` cpp
11908
- namespace std {
11909
- template<ranges::input_range R, class charT>
11910
- struct range-default-formatter<range_format::set, R, charT> {
11911
- private:
11912
- using maybe-const-set = fmt-maybe-const<R, charT>; // exposition only
11913
- range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-set>>,
11914
- charT> underlying_; // exposition only
11915
-
11916
- public:
11917
- constexpr range-default-formatter();
11918
-
11919
- template<class ParseContext>
11920
- constexpr typename ParseContext::iterator
11921
- parse(ParseContext& ctx);
11922
-
11923
- template<class FormatContext>
11924
- typename FormatContext::iterator
11925
- format(maybe-const-set& r, FormatContext& ctx) const;
11926
- };
11927
- }
11928
- ```
11929
-
11930
- ``` cpp
11931
- constexpr range-default-formatter();
11932
- ```
11933
-
11934
- *Effects:* Equivalent to:
11935
-
11936
- ``` cpp
11937
- underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
11938
- ```
11939
-
11940
- ``` cpp
11941
- template<class ParseContext>
11942
- constexpr typename ParseContext::iterator
11943
- parse(ParseContext& ctx);
11944
- ```
11945
-
11946
- *Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
11947
-
11948
- ``` cpp
11949
- template<class FormatContext>
11950
- typename FormatContext::iterator
11951
- format(maybe-const-set& r, FormatContext& ctx) const;
11952
- ```
11953
-
11954
- *Effects:* Equivalent to: `return `*`underlying_`*`.format(r, ctx);`
11955
-
11956
- #### Specialization of *`range-default-formatter`* for strings <a id="format.range.fmtstr">[[format.range.fmtstr]]</a>
11957
-
11958
- ``` cpp
11959
- namespace std {
11960
- template<range_format K, ranges::input_range R, class charT>
11961
- requires (K == range_format::string || K == range_format::debug_string)
11962
- struct range-default-formatter<K, R, charT> {
11963
- private:
11964
- formatter<basic_string<charT>, charT> underlying_; // exposition only
11965
-
11966
- public:
11967
- template<class ParseContext>
11968
- constexpr typename ParseContext::iterator
11969
- parse(ParseContext& ctx);
11970
-
11971
- template<class FormatContext>
11972
- typename FormatContext::iterator
11973
- format(see below& str, FormatContext& ctx) const;
11974
- };
11975
- }
11976
- ```
11977
-
11978
- *Mandates:* `same_as<remove_cvref_t<range_reference_t<R>>, charT>` is
11979
- `true`.
11980
-
11981
- ``` cpp
11982
- template<class ParseContext>
11983
- constexpr typename ParseContext::iterator
11984
- parse(ParseContext& ctx);
11985
- ```
11986
-
11987
- *Effects:* Equivalent to:
11988
-
11989
- ``` cpp
11990
- auto i = underlying_.parse(ctx);
11991
- if constexpr (K == range_format::debug_string) {
11992
- underlying_.set_debug_format();
11993
- }
11994
- return i;
11995
- ```
11996
-
11997
- ``` cpp
11998
- template<class FormatContext>
11999
- typename FormatContext::iterator
12000
- format(see below& r, FormatContext& ctx) const;
12001
- ```
12002
-
12003
- The type of `r` is `const R&` if `ranges::input_range<const R>` is
12004
- `true` and `R&` otherwise.
12005
-
12006
- *Effects:* Let *`s`* be a `basic_string<charT>` such that
12007
- `ranges::equal(`*`s`*`, r)` is `true`. Equivalent to:
12008
- `return `*`underlying_`*`.format(`*`s`*`, ctx);`
12009
-
12010
- ### Arguments <a id="format.arguments">[[format.arguments]]</a>
12011
-
12012
- #### Class template `basic_format_arg` <a id="format.arg">[[format.arg]]</a>
12013
-
12014
- ``` cpp
12015
- namespace std {
12016
- template<class Context>
12017
- class basic_format_arg {
12018
- public:
12019
- class handle;
12020
-
12021
- private:
12022
- using char_type = typename Context::char_type; // exposition only
12023
-
12024
- variant<monostate, bool, char_type,
12025
- int, unsigned int, long long int, unsigned long long int,
12026
- float, double, long double,
12027
- const char_type*, basic_string_view<char_type>,
12028
- const void*, handle> value; // exposition only
12029
-
12030
- template<class T> explicit basic_format_arg(T& v) noexcept; // exposition only
12031
-
12032
- public:
12033
- basic_format_arg() noexcept;
12034
-
12035
- explicit operator bool() const noexcept;
12036
- };
12037
- }
12038
- ```
12039
-
12040
- An instance of `basic_format_arg` provides access to a formatting
12041
- argument for user-defined formatters.
12042
-
12043
- The behavior of a program that adds specializations of
12044
- `basic_format_arg` is undefined.
12045
-
12046
- ``` cpp
12047
- basic_format_arg() noexcept;
12048
- ```
12049
-
12050
- *Ensures:* `!(*this)`.
12051
-
12052
- ``` cpp
12053
- template<class T> explicit basic_format_arg(T& v) noexcept;
12054
- ```
12055
-
12056
- *Constraints:* `T` satisfies `formattable-with<Context>`.
12057
-
12058
- *Preconditions:* If `decay_t<T>` is `char_type*` or `const char_type*`,
12059
- `static_cast<const char_type*>(v)` points to a NTCTS [[defns.ntcts]].
12060
-
12061
- *Effects:* Let `TD` be `remove_const_t<T>`.
12062
-
12063
- - If `TD` is `bool` or `char_type`, initializes `value` with `v`;
12064
- - otherwise, if `TD` is `char` and `char_type` is `wchar_t`, initializes
12065
- `value` with `static_cast<wchar_t>(v)`;
12066
- - otherwise, if `TD` is a signed integer type [[basic.fundamental]] and
12067
- `sizeof(TD) <= sizeof(int)`, initializes `value` with
12068
- `static_cast<int>(v)`;
12069
- - otherwise, if `TD` is an unsigned integer type and
12070
- `sizeof(TD) <= sizeof(unsigned int)`, initializes `value` with
12071
- `static_cast<unsigned int>(v)`;
12072
- - otherwise, if `TD` is a signed integer type and
12073
- `sizeof(TD) <= sizeof(long long int)`, initializes `value` with
12074
- `static_cast<long long int>(v)`;
12075
- - otherwise, if `TD` is an unsigned integer type and
12076
- `sizeof(TD) <= sizeof(unsigned long long int)`, initializes `value`
12077
- with `static_cast<unsigned long long int>(v)`;
12078
- - otherwise, if `TD` is a standard floating-point type, initializes
12079
- `value` with `v`;
12080
- - otherwise, if `TD` is a specialization of `basic_string_view` or
12081
- `basic_string` and `TD::value_type` is `char_type`, initializes
12082
- `value` with `basic_string_view<char_type>(v.data(), v.size())`;
12083
- - otherwise, if `decay_t<TD>` is `char_type*` or `const char_type*`,
12084
- initializes `value` with `static_cast<const char_type*>(v)`;
12085
- - otherwise, if `is_void_v<remove_pointer_t<TD>>` is `true` or
12086
- `is_null_pointer_v<TD>` is `true`, initializes `value` with
12087
- `static_cast<const void*>(v)`;
12088
- - otherwise, initializes `value` with `handle(v)`.
12089
-
12090
- [*Note 1*: Constructing `basic_format_arg` from a pointer to a member
12091
- is ill-formed unless the user provides an enabled specialization of
12092
- `formatter` for that pointer to member type. — *end note*]
12093
-
12094
- ``` cpp
12095
- explicit operator bool() const noexcept;
12096
- ```
12097
-
12098
- *Returns:* `!holds_alternative<monostate>(value)`.
12099
-
12100
- The class `handle` allows formatting an object of a user-defined type.
12101
-
12102
- ``` cpp
12103
- namespace std {
12104
- template<class Context>
12105
- class basic_format_arg<Context>::handle {
12106
- const void* ptr_; // exposition only
12107
- void (*format_)(basic_format_parse_context<char_type>&,
12108
- Context&, const void*); // exposition only
12109
-
12110
- template<class T> explicit handle(T& val) noexcept; // exposition only
12111
-
12112
- friend class basic_format_arg<Context>; // exposition only
12113
-
12114
- public:
12115
- void format(basic_format_parse_context<char_type>&, Context& ctx) const;
12116
- };
12117
- }
12118
- ```
12119
-
12120
- ``` cpp
12121
- template<class T> explicit handle(T& val) noexcept;
12122
- ```
12123
-
12124
- Let
12125
-
12126
- - `TD` be `remove_const_t<T>`,
12127
- - `TQ` be `const TD` if `const TD` satisfies `formattable-with<Context>`
12128
- and `TD` otherwise.
12129
-
12130
- *Mandates:* `TQ` satisfies `formattable-with<Context>`.
12131
-
12132
- *Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
12133
-
12134
- ``` cpp
12135
- [](basic_format_parse_context<char_type>& parse_ctx,
12136
- Context& format_ctx, const void* ptr) {
12137
- typename Context::template formatter_type<TD> f;
12138
- parse_ctx.advance_to(f.parse(parse_ctx));
12139
- format_ctx.advance_to(f.format(*const_cast<TQ*>(static_cast<const TD*>(ptr)),
12140
- format_ctx));
12141
- }
12142
- ```
12143
-
12144
- ``` cpp
12145
- void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
12146
- ```
12147
-
12148
- *Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
12149
-
12150
- ``` cpp
12151
- template<class Visitor, class Context>
12152
- decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
12153
- ```
12154
-
12155
- *Effects:* Equivalent to:
12156
- `return visit(std::forward<Visitor>(vis), arg.value);`
12157
-
12158
- #### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
12159
-
12160
- ``` cpp
12161
- namespace std {
12162
- template<class Context, class... Args>
12163
- class format-arg-store { // exposition only
12164
- array<basic_format_arg<Context>, sizeof...(Args)> args; // exposition only
12165
- };
12166
- }
12167
- ```
12168
-
12169
- An instance of *`format-arg-store`* stores formatting arguments.
12170
-
12171
- ``` cpp
12172
- template<class Context = format_context, class... Args>
12173
- format-arg-store<Context, Args...> make_format_args(Args&&... fmt_args);
12174
- ```
12175
-
12176
- *Preconditions:* The type
12177
- `typename Context::template formatter_type<remove_cvref_t<``Tᵢ``>>`
12178
- meets the requirements [[formatter.requirements]] for each `Tᵢ` in
12179
- `Args`.
12180
-
12181
- *Returns:* An object of type *`format-arg-store`*`<Context, Args...>`
12182
- whose *args* data member is initialized with
12183
- `{basic_format_arg<Context>(fmt_args)...}`.
12184
-
12185
- ``` cpp
12186
- template<class... Args>
12187
- format-arg-store<wformat_context, Args...> make_wformat_args(Args&&... args);
12188
- ```
12189
-
12190
- *Effects:* Equivalent to:
12191
- `return make_format_args<wformat_context>(args...);`
12192
-
12193
- #### Class template `basic_format_args` <a id="format.args">[[format.args]]</a>
12194
-
12195
- ``` cpp
12196
- namespace std {
12197
- template<class Context>
12198
- class basic_format_args {
12199
- size_t size_; // exposition only
12200
- const basic_format_arg<Context>* data_; // exposition only
12201
-
12202
- public:
12203
- basic_format_args() noexcept;
12204
-
12205
- template<class... Args>
12206
- basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
12207
-
12208
- basic_format_arg<Context> get(size_t i) const noexcept;
12209
- };
12210
-
12211
- template<class Context, class... Args>
12212
- basic_format_args(format-arg-store<Context, Args...>) -> basic_format_args<Context>;
12213
- }
12214
- ```
12215
-
12216
- An instance of `basic_format_args` provides access to formatting
12217
- arguments. Implementations should optimize the representation of
12218
- `basic_format_args` for a small number of formatting arguments.
12219
-
12220
- [*Note 1*: For example, by storing indices of type alternatives
12221
- separately from values and packing the former. — *end note*]
12222
-
12223
- ``` cpp
12224
- basic_format_args() noexcept;
12225
- ```
12226
-
12227
- *Effects:* Initializes `size_` with `0`.
12228
-
12229
- ``` cpp
12230
- template<class... Args>
12231
- basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
12232
- ```
12233
-
12234
- *Effects:* Initializes `size_` with `sizeof...(Args)` and `data_` with
12235
- `store.args.data()`.
12236
-
12237
- ``` cpp
12238
- basic_format_arg<Context> get(size_t i) const noexcept;
12239
- ```
12240
-
12241
- *Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
12242
-
12243
- ### Tuple formatter <a id="format.tuple">[[format.tuple]]</a>
12244
-
12245
- For each of `pair` and `tuple`, the library provides the following
12246
- formatter specialization where `pair-or-tuple` is the name of the
12247
- template:
12248
-
12249
- ``` cpp
12250
- namespace std {
12251
- template<class charT, formattable<charT>... Ts>
12252
- struct formatter<pair-or-tuple<Ts...>, charT> {
12253
- private:
12254
- tuple<formatter<remove_cvref_t<Ts>, charT>...> underlying_; // exposition only
12255
- basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only
12256
- basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("("); // exposition only
12257
- basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>(")"); // exposition only
12258
-
12259
- public:
12260
- constexpr void set_separator(basic_string_view<charT> sep) noexcept;
12261
- constexpr void set_brackets(basic_string_view<charT> opening,
12262
- basic_string_view<charT> closing) noexcept;
12263
-
12264
- template<class ParseContext>
12265
- constexpr typename ParseContext::iterator
12266
- parse(ParseContext& ctx);
12267
-
12268
- template<class FormatContext>
12269
- typename FormatContext::iterator
12270
- format(see below& elems, FormatContext& ctx) const;
12271
- };
12272
- }
12273
- ```
12274
-
12275
- The `parse` member functions of these formatters interpret the format
12276
- specification as a *tuple-format-spec* according to the following
12277
- syntax:
12278
-
12279
- ``` bnf
12280
- tuple-format-spec
12281
- tuple-fill-and-alignₒₚₜ widthₒₚₜ tuple-typeₒₚₜ
12282
- ```
12283
-
12284
- ``` bnf
12285
- tuple-fill-and-align
12286
- tuple-fillₒₚₜ align
12287
- ```
12288
-
12289
- ``` bnf
12290
- tuple-fill
12291
- any character other than '{' or '}' or ':'
12292
- ```
12293
-
12294
- ``` bnf
12295
- tuple-type
12296
- 'm'
12297
- 'n'
12298
- ```
12299
-
12300
- The *tuple-fill-and-align* is interpreted the same way as a
12301
- *fill-and-align* [[format.string.std]]. The productions *align* and
12302
- *width* are described in [[format.string]].
12303
-
12304
- The *tuple-type* specifier changes the way a `pair` or `tuple` is
12305
- formatted, with certain options only valid with certain argument types.
12306
- The meaning of the various type options is as specified in
12307
- [[formatter.tuple.type]].
12308
-
12309
- **Table: Meaning of tuple-type options** <a id="formatter.tuple.type">[formatter.tuple.type]</a>
12310
-
12311
- | Option | Requirements | Meaning |
12312
- | ------ | ------------ | -------------------------------------- |
12313
- | <charT>(": ")); set_brackets({}, {}); \end{codeblock}% |
12314
- | % `n` | none | Equivalent to: `set_brackets({}, {});` |
12315
- | % none | none | No effects |
12316
-
12317
- ``` cpp
12318
- constexpr void set_separator(basic_string_view<charT> sep) noexcept;
12319
- ```
12320
-
12321
- *Effects:* Equivalent to: *`separator_`*` = sep;`
12322
-
12323
- ``` cpp
12324
- constexpr void set_brackets(basic_string_view<charT> opening,
12325
- basic_string_view<charT> closing) noexcept;
12326
- ```
12327
-
12328
- *Effects:* Equivalent to:
12329
-
12330
- ``` cpp
12331
- opening-bracket_ = opening;
12332
- closing-bracket_ = closing;
12333
- ```
12334
-
12335
- ``` cpp
12336
- template<class ParseContext>
12337
- constexpr typename ParseContext::iterator
12338
- parse(ParseContext& ctx);
12339
- ```
12340
-
12341
- *Effects:* Parses the format specifier as a *tuple-format-spec* and
12342
- stores the parsed specifiers in `*this`. The values of
12343
- *opening-bracket\_*, *closing-bracket\_*, and *separator\_* are modified
12344
- if and only if required by the *tuple-type*, if present. For each
12345
- element *`e`* in *underlying\_*, if *`e`*`.set_debug_format()` is a
12346
- valid expression, calls *`e`*`.set_debug_format()`.
12347
-
12348
- *Returns:* An iterator past the end of the *tuple-format-spec*.
12349
-
12350
- ``` cpp
12351
- template<class FormatContext>
12352
- typename FormatContext::iterator
12353
- format(see below& elems, FormatContext& ctx) const;
12354
- ```
12355
-
12356
- The type of `elems` is:
12357
-
12358
- - If `(formattable<const Ts, charT> && ...)` is `true`,
12359
- `const `*`pair-or-tuple`*`<Ts...>&`.
12360
- - Otherwise *`pair-or-tuple`*`<Ts...>&`.
12361
-
12362
- *Effects:* Writes the following into `ctx.out()`, adjusted according to
12363
- the *tuple-format-spec*:
12364
-
12365
- - *opening-bracket\_*,
12366
- - for each index `I` in the \[`0`, `sizeof...(Ts)`):
12367
- - if `I != 0`, *separator\_*,
12368
- - the result of writing `get<I>(elems)` via
12369
- `get<I>(`*`underlying_`*`)`, and
12370
- - *closing-bracket\_*.
12371
-
12372
- *Returns:* An iterator past the end of the output range.
12373
-
12374
- ### Class `format_error` <a id="format.error">[[format.error]]</a>
12375
-
12376
- ``` cpp
12377
- namespace std {
12378
- class format_error : public runtime_error {
12379
- public:
12380
- explicit format_error(const string& what_arg);
12381
- explicit format_error(const char* what_arg);
12382
- };
12383
- }
12384
- ```
12385
-
12386
- The class `format_error` defines the type of objects thrown as
12387
- exceptions to report errors from the formatting library.
12388
-
12389
- ``` cpp
12390
- format_error(const string& what_arg);
12391
- ```
12392
-
12393
- *Ensures:* `strcmp(what(), what_arg.c_str()) == 0`.
12394
-
12395
- ``` cpp
12396
- format_error(const char* what_arg);
12397
- ```
12398
-
12399
- *Ensures:* `strcmp(what(), what_arg) == 0`.
12400
-
12401
  ## Bit manipulation <a id="bit">[[bit]]</a>
12402
 
12403
  ### General <a id="bit.general">[[bit.general]]</a>
12404
 
12405
  The header `<bit>` provides components to access, manipulate and process
@@ -12428,13 +11111,13 @@ namespace std {
12428
  template<class T>
12429
  constexpr int bit_width(T x) noexcept;
12430
 
12431
  // [bit.rotate], rotating
12432
  template<class T>
12433
- [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
12434
  template<class T>
12435
- [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
12436
 
12437
  // [bit.count], counting
12438
  template<class T>
12439
  constexpr int countl_zero(T x) noexcept;
12440
  template<class T>
@@ -12466,35 +11149,48 @@ template<class To, class From>
12466
 
12467
  - `sizeof(To) == sizeof(From)` is `true`;
12468
  - `is_trivially_copyable_v<To>` is `true`; and
12469
  - `is_trivially_copyable_v<From>` is `true`.
12470
 
 
 
 
 
 
 
 
 
 
 
 
 
12471
  *Returns:* An object of type `To`. Implicitly creates objects nested
12472
  within the result [[intro.object]]. Each bit of the value representation
12473
  of the result is equal to the corresponding bit in the object
12474
  representation of `from`. Padding bits of the result are unspecified.
12475
  For the result and each object created within it, if there is no value
12476
  of the object’s type corresponding to the value representation produced,
12477
  the behavior is undefined. If there are multiple such values, which
12478
  value is produced is unspecified. A bit in the value representation of
12479
  the result is indeterminate if it does not correspond to a bit in the
12480
- value representation of `from` or corresponds to a bit of an object that
12481
- is not within its lifetime or has an indeterminate
12482
- value [[basic.indet]]. For each bit in the value representation of the
12483
- result that is indeterminate, the smallest object containing that bit
12484
- has an indeterminate value; the behavior is undefined unless that object
12485
- is of unsigned ordinary character type or `std::byte` type. The result
12486
- does not otherwise contain any indeterminate values.
12487
 
12488
- *Remarks:* This function is `constexpr` if and only if `To`, `From`, and
12489
- the types of all subobjects of `To` and `From` are types `T` such that:
 
 
 
 
12490
 
12491
- - `is_union_v<T>` is `false`;
12492
- - `is_pointer_v<T>` is `false`;
12493
- - `is_member_pointer_v<T>` is `false`;
12494
- - `is_volatile_v<T>` is `false`; and
12495
- - `T` has no non-static data members of reference type.
12496
 
12497
  ### `byteswap` <a id="bit.byteswap">[[bit.byteswap]]</a>
12498
 
12499
  ``` cpp
12500
  template<class T>
@@ -12567,11 +11263,11 @@ template<class T>
12567
  In the following descriptions, let `N` denote
12568
  `numeric_limits<T>::digits`.
12569
 
12570
  ``` cpp
12571
  template<class T>
12572
- [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
12573
  ```
12574
 
12575
  *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12576
 
12577
  Let `r` be `s % N`.
@@ -12579,11 +11275,11 @@ Let `r` be `s % N`.
12579
  *Returns:* If `r` is `0`, `x`; if `r` is positive,
12580
  `(x << r) | (x >> (N - r))`; if `r` is negative, `rotr(x, -r)`.
12581
 
12582
  ``` cpp
12583
  template<class T>
12584
- [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
12585
  ```
12586
 
12587
  *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12588
 
12589
  Let `r` be `s % N`.
@@ -12679,14 +11375,136 @@ If all scalar types have size 1 byte, then all of `endian::little`,
12679
  big-endian, `endian::native` is equal to `endian::big`. If all scalar
12680
  types are little-endian, `endian::native` is equal to `endian::little`.
12681
  Otherwise, `endian::native` is not equal to either `endian::big` or
12682
  `endian::little`.
12683
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12684
  <!-- Link reference definitions -->
12685
  [algorithms]: algorithms.md#algorithms
12686
  [algorithms.general]: algorithms.md#algorithms.general
12687
- [algorithms.requirements]: algorithms.md#algorithms.requirements
12688
  [allocator.requirements.general]: library.md#allocator.requirements.general
12689
  [allocator.uses.construction]: mem.md#allocator.uses.construction
12690
  [any]: #any
12691
  [any.assign]: #any.assign
12692
  [any.bad.any.cast]: #any.bad.any.cast
@@ -12704,11 +11522,10 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12704
  [arithmetic.operations.minus]: #arithmetic.operations.minus
12705
  [arithmetic.operations.modulus]: #arithmetic.operations.modulus
12706
  [arithmetic.operations.multiplies]: #arithmetic.operations.multiplies
12707
  [arithmetic.operations.negate]: #arithmetic.operations.negate
12708
  [arithmetic.operations.plus]: #arithmetic.operations.plus
12709
- [associative]: containers.md#associative
12710
  [basic.fundamental]: basic.md#basic.fundamental
12711
  [basic.indet]: basic.md#basic.indet
12712
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
12713
  [basic.types.general]: basic.md#basic.types.general
12714
  [bit]: #bit
@@ -12718,11 +11535,10 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12718
  [bit.endian]: #bit.endian
12719
  [bit.general]: #bit.general
12720
  [bit.pow.two]: #bit.pow.two
12721
  [bit.rotate]: #bit.rotate
12722
  [bit.syn]: #bit.syn
12723
- [bitmask.types]: library.md#bitmask.types
12724
  [bitset]: #bitset
12725
  [bitset.cons]: #bitset.cons
12726
  [bitset.hash]: #bitset.hash
12727
  [bitset.members]: #bitset.members
12728
  [bitset.operators]: #bitset.operators
@@ -12731,14 +11547,10 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12731
  [bitwise.operations.and]: #bitwise.operations.and
12732
  [bitwise.operations.general]: #bitwise.operations.general
12733
  [bitwise.operations.not]: #bitwise.operations.not
12734
  [bitwise.operations.or]: #bitwise.operations.or
12735
  [bitwise.operations.xor]: #bitwise.operations.xor
12736
- [charconv]: #charconv
12737
- [charconv.from.chars]: #charconv.from.chars
12738
- [charconv.syn]: #charconv.syn
12739
- [charconv.to.chars]: #charconv.to.chars
12740
  [class.base.init]: class.md#class.base.init
12741
  [class.copy.ctor]: class.md#class.copy.ctor
12742
  [comparisons]: #comparisons
12743
  [comparisons.equal.to]: #comparisons.equal.to
12744
  [comparisons.general]: #comparisons.general
@@ -12747,34 +11559,23 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12747
  [comparisons.less]: #comparisons.less
12748
  [comparisons.less.equal]: #comparisons.less.equal
12749
  [comparisons.not.equal.to]: #comparisons.not.equal.to
12750
  [comparisons.three.way]: #comparisons.three.way
12751
  [concepts.equality]: concepts.md#concepts.equality
 
12752
  [cpp17.copyassignable]: #cpp17.copyassignable
12753
- [cpp17.copyconstructible]: #cpp17.copyconstructible
12754
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
12755
  [cpp17.destructible]: #cpp17.destructible
12756
  [cpp17.hash]: #cpp17.hash
12757
  [cpp17.moveassignable]: #cpp17.moveassignable
12758
  [cpp17.moveconstructible]: #cpp17.moveconstructible
12759
  [dcl.constexpr]: dcl.md#dcl.constexpr
12760
  [dcl.init.general]: dcl.md#dcl.init.general
12761
  [declval]: #declval
12762
  [defns.expression.equivalent]: intro.md#defns.expression.equivalent
12763
- [defns.ntcts]: intro.md#defns.ntcts
12764
  [defns.order.ptr]: #defns.order.ptr
12765
  [defns.referenceable]: intro.md#defns.referenceable
12766
- [except.terminate]: except.md#except.terminate
12767
- [execpol]: #execpol
12768
- [execpol.general]: #execpol.general
12769
- [execpol.objects]: #execpol.objects
12770
- [execpol.par]: #execpol.par
12771
- [execpol.parunseq]: #execpol.parunseq
12772
- [execpol.seq]: #execpol.seq
12773
- [execpol.type]: #execpol.type
12774
- [execpol.unseq]: #execpol.unseq
12775
- [execution.syn]: #execution.syn
12776
  [expected]: #expected
12777
  [expected.bad]: #expected.bad
12778
  [expected.bad.void]: #expected.bad.void
12779
  [expected.expected]: #expected.expected
12780
  [expected.general]: #expected.general
@@ -12812,51 +11613,10 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12812
  [expr.mul]: expr.md#expr.mul
12813
  [expr.or]: expr.md#expr.or
12814
  [expr.rel]: expr.md#expr.rel
12815
  [expr.unary.op]: expr.md#expr.unary.op
12816
  [expr.xor]: expr.md#expr.xor
12817
- [format]: #format
12818
- [format.align]: #format.align
12819
- [format.arg]: #format.arg
12820
- [format.arg.store]: #format.arg.store
12821
- [format.args]: #format.args
12822
- [format.arguments]: #format.arguments
12823
- [format.context]: #format.context
12824
- [format.err.report]: #format.err.report
12825
- [format.error]: #format.error
12826
- [format.escape.sequences]: #format.escape.sequences
12827
- [format.fmt.string]: #format.fmt.string
12828
- [format.formattable]: #format.formattable
12829
- [format.formatter]: #format.formatter
12830
- [format.formatter.spec]: #format.formatter.spec
12831
- [format.functions]: #format.functions
12832
- [format.parse.ctx]: #format.parse.ctx
12833
- [format.range]: #format.range
12834
- [format.range.fmtdef]: #format.range.fmtdef
12835
- [format.range.fmtkind]: #format.range.fmtkind
12836
- [format.range.fmtmap]: #format.range.fmtmap
12837
- [format.range.fmtset]: #format.range.fmtset
12838
- [format.range.fmtstr]: #format.range.fmtstr
12839
- [format.range.formatter]: #format.range.formatter
12840
- [format.sign]: #format.sign
12841
- [format.string]: #format.string
12842
- [format.string.escaped]: #format.string.escaped
12843
- [format.string.general]: #format.string.general
12844
- [format.string.std]: #format.string.std
12845
- [format.syn]: #format.syn
12846
- [format.tuple]: #format.tuple
12847
- [format.type.bool]: #format.type.bool
12848
- [format.type.char]: #format.type.char
12849
- [format.type.float]: #format.type.float
12850
- [format.type.int]: #format.type.int
12851
- [format.type.ptr]: #format.type.ptr
12852
- [format.type.string]: #format.type.string
12853
- [formatter]: #formatter
12854
- [formatter.basic]: #formatter.basic
12855
- [formatter.range.type]: #formatter.range.type
12856
- [formatter.requirements]: #formatter.requirements
12857
- [formatter.tuple.type]: #formatter.tuple.type
12858
  [forward]: #forward
12859
  [freestanding.item]: library.md#freestanding.item
12860
  [func.bind]: #func.bind
12861
  [func.bind.bind]: #func.bind.bind
12862
  [func.bind.general]: #func.bind.general
@@ -12875,10 +11635,16 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12875
  [func.search.bmh]: #func.search.bmh
12876
  [func.search.default]: #func.search.default
12877
  [func.search.general]: #func.search.general
12878
  [func.wrap]: #func.wrap
12879
  [func.wrap.badcall]: #func.wrap.badcall
 
 
 
 
 
 
12880
  [func.wrap.func]: #func.wrap.func
12881
  [func.wrap.func.alg]: #func.wrap.func.alg
12882
  [func.wrap.func.cap]: #func.wrap.func.cap
12883
  [func.wrap.func.con]: #func.wrap.func.con
12884
  [func.wrap.func.general]: #func.wrap.func.general
@@ -12891,27 +11657,34 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12891
  [func.wrap.move.class]: #func.wrap.move.class
12892
  [func.wrap.move.ctor]: #func.wrap.move.ctor
12893
  [func.wrap.move.general]: #func.wrap.move.general
12894
  [func.wrap.move.inv]: #func.wrap.move.inv
12895
  [func.wrap.move.util]: #func.wrap.move.util
 
 
 
 
 
 
12896
  [function.objects]: #function.objects
12897
  [function.objects.general]: #function.objects.general
12898
  [functional.syn]: #functional.syn
 
12899
  [intro.multithread]: basic.md#intro.multithread
12900
  [intro.object]: basic.md#intro.object
12901
  [invalid.argument]: diagnostics.md#invalid.argument
12902
  [istream.formatted]: input.md#istream.formatted
12903
- [iterator.concept.output]: iterators.md#iterator.concept.output
12904
- [lex.string.literal]: lex.md#lex.string.literal
 
12905
  [logical.operations]: #logical.operations
12906
  [logical.operations.and]: #logical.operations.and
12907
  [logical.operations.general]: #logical.operations.general
12908
  [logical.operations.not]: #logical.operations.not
12909
  [logical.operations.or]: #logical.operations.or
12910
  [meta.rqmts]: meta.md#meta.rqmts
12911
  [meta.trans.other]: meta.md#meta.trans.other
12912
- [namespace.std]: library.md#namespace.std
12913
  [optional]: #optional
12914
  [optional.assign]: #optional.assign
12915
  [optional.assign.copy]: #optional.assign.copy
12916
  [optional.assign.copy.templ]: #optional.assign.copy.templ
12917
  [optional.assign.move]: #optional.assign.move
@@ -12920,17 +11693,28 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12920
  [optional.comp.with.t]: #optional.comp.with.t
12921
  [optional.ctor]: #optional.ctor
12922
  [optional.dtor]: #optional.dtor
12923
  [optional.general]: #optional.general
12924
  [optional.hash]: #optional.hash
 
12925
  [optional.mod]: #optional.mod
12926
  [optional.monadic]: #optional.monadic
12927
  [optional.nullops]: #optional.nullops
12928
  [optional.nullopt]: #optional.nullopt
12929
  [optional.observe]: #optional.observe
12930
  [optional.optional]: #optional.optional
12931
  [optional.optional.general]: #optional.optional.general
 
 
 
 
 
 
 
 
 
 
12932
  [optional.relops]: #optional.relops
12933
  [optional.specalg]: #optional.specalg
12934
  [optional.swap]: #optional.swap
12935
  [optional.syn]: #optional.syn
12936
  [ostream.formatted]: input.md#ostream.formatted
@@ -12941,36 +11725,38 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12941
  [pair.piecewise]: #pair.piecewise
12942
  [pairs]: #pairs
12943
  [pairs.general]: #pairs.general
12944
  [pairs.pair]: #pairs.pair
12945
  [pairs.spec]: #pairs.spec
 
12946
  [range.cmp]: #range.cmp
12947
  [range.utility.helpers]: ranges.md#range.utility.helpers
12948
  [refwrap]: #refwrap
12949
  [refwrap.access]: #refwrap.access
12950
  [refwrap.assign]: #refwrap.assign
12951
  [refwrap.common.ref]: #refwrap.common.ref
 
12952
  [refwrap.const]: #refwrap.const
12953
  [refwrap.general]: #refwrap.general
12954
  [refwrap.helpers]: #refwrap.helpers
12955
  [refwrap.invoke]: #refwrap.invoke
12956
- [res.on.exception.handling]: library.md#res.on.exception.handling
12957
- [round.style]: support.md#round.style
12958
  [support.signal]: support.md#support.signal
12959
  [swappable.requirements]: library.md#swappable.requirements
12960
- [temp.param]: temp.md#temp.param
 
12961
  [temp.type]: temp.md#temp.type
12962
  [template.bitset]: #template.bitset
12963
  [template.bitset.general]: #template.bitset.general
12964
  [term.object.representation]: basic.md#term.object.representation
12965
  [term.object.type]: basic.md#term.object.type
12966
  [term.odr.use]: basic.md#term.odr.use
12967
  [term.perfect.forwarding.call.wrapper]: #term.perfect.forwarding.call.wrapper
12968
  [term.simple.call.wrapper]: #term.simple.call.wrapper
 
12969
  [term.trivially.copyable.type]: basic.md#term.trivially.copyable.type
12970
  [term.unevaluated.operand]: expr.md#term.unevaluated.operand
12971
- [time.format]: time.md#time.format
12972
  [tuple]: #tuple
12973
  [tuple.apply]: #tuple.apply
12974
  [tuple.assign]: #tuple.assign
12975
  [tuple.cnstr]: #tuple.cnstr
12976
  [tuple.common.ref]: #tuple.common.ref
@@ -12983,15 +11769,11 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12983
  [tuple.special]: #tuple.special
12984
  [tuple.swap]: #tuple.swap
12985
  [tuple.syn]: #tuple.syn
12986
  [tuple.traits]: #tuple.traits
12987
  [tuple.tuple]: #tuple.tuple
12988
- [type.index]: #type.index
12989
- [type.index.hash]: #type.index.hash
12990
- [type.index.members]: #type.index.members
12991
- [type.index.overview]: #type.index.overview
12992
- [type.index.synopsis]: #type.index.synopsis
12993
  [unord]: containers.md#unord
12994
  [unord.hash]: #unord.hash
12995
  [utilities]: #utilities
12996
  [utilities.general]: #utilities.general
12997
  [utilities.summary]: #utilities.summary
@@ -12999,12 +11781,12 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
12999
  [utility.as.const]: #utility.as.const
13000
  [utility.exchange]: #utility.exchange
13001
  [utility.intcmp]: #utility.intcmp
13002
  [utility.swap]: #utility.swap
13003
  [utility.syn]: #utility.syn
 
13004
  [utility.underlying]: #utility.underlying
13005
- [utility.unreachable]: #utility.unreachable
13006
  [variant]: #variant
13007
  [variant.assign]: #variant.assign
13008
  [variant.bad.access]: #variant.bad.access
13009
  [variant.ctor]: #variant.ctor
13010
  [variant.dtor]: #variant.dtor
@@ -13025,10 +11807,5 @@ Otherwise, `endian::native` is not equal to either `endian::big` or
13025
  [variant.visit]: #variant.visit
13026
 
13027
  [^1]: Such a type is a function pointer or a class type which has a
13028
  member `operator()` or a class type which has a conversion to a
13029
  pointer to function.
13030
-
13031
- [^2]: Windows® is a registered trademark of Microsoft Corporation. This
13032
- information is given for the convenience of users of this document
13033
- and does not constitute an endorsement by ISO or IEC of this
13034
- product.
 
8
  [[utilities.summary]].
9
 
10
  **Table: General utilities library summary** <a id="utilities.summary">[utilities.summary]</a>
11
 
12
  | Subclause | | Header |
13
+ | -------------------- | ---------------------------- | -------------- |
14
  | [[utility]] | Utility components | `<utility>` |
15
  | [[pairs]] | Pairs | |
16
  | [[tuple]] | Tuples | `<tuple>` |
17
  | [[optional]] | Optional objects | `<optional>` |
18
  | [[variant]] | Variants | `<variant>` |
19
  | [[any]] | Storage for any type | `<any>` |
20
  | [[expected]] | Expected objects | `<expected>` |
21
  | [[bitset]] | Fixed-size sequences of bits | `<bitset>` |
22
  | [[function.objects]] | Function objects | `<functional>` |
 
 
 
 
23
  | [[bit]] | Bit manipulation | `<bit>` |
24
 
25
 
26
  ## Utility components <a id="utility">[[utility]]</a>
27
 
 
50
  template<class T>
51
  constexpr T&& forward(remove_reference_t<T>& t) noexcept;
52
  template<class T>
53
  constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
54
  template<class T, class U>
55
+ constexpr auto forward_like(U&& x) noexcept -> see below;
56
  template<class T>
57
  constexpr remove_reference_t<T>&& move(T&&) noexcept;
58
  template<class T>
59
  constexpr conditional_t<
60
  !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>
 
90
 
91
  // [utility.underlying], to_underlying
92
  template<class T>
93
  constexpr underlying_type_t<T> to_underlying(T value) noexcept;
94
 
95
+ // [utility.undefined], undefined behavior
96
  [[noreturn]] void unreachable();
97
+ void observable_checkpoint() noexcept;
98
 
99
  // [intseq], compile-time integer sequences%
100
  %
101
  %
102
 
 
209
  template<size_t I>
210
  struct in_place_index_t {
211
  explicit in_place_index_t() = default;
212
  };
213
  template<size_t I> constexpr in_place_index_t<I> in_place_index{};
214
+
215
+ // nontype argument tag%
216
+ %
217
+
218
+ template<auto V>
219
+ struct nontype_t {
220
+ explicit nontype_t() = default;
221
+ };
222
+ template<auto V> constexpr nontype_t<V> nontype{};
223
+
224
+ // [variant.monostate], class monostate%
225
+
226
+ struct monostate;
227
+
228
+ // [variant.monostate.relops], monostate relational operators%
229
+ {monostate{monostate}
230
+ constexpr bool operator==(monostate, monostate) noexcept;
231
+ constexpr strong_ordering operator<=>(monostate, monostate) noexcept;
232
+
233
+ // [variant.hash], hash support%
234
+ {monostate}
235
+ template<class T> struct hash;
236
+ template<> struct hash<monostate>;
237
  }
238
  ```
239
 
240
  ### `swap` <a id="utility.swap">[[utility.swap]]</a>
241
 
 
336
 
337
  — *end example*]
338
 
339
  ``` cpp
340
  template<class T, class U>
341
+ constexpr auto forward_like(U&& x) noexcept -> see below;
342
  ```
343
 
344
  *Mandates:* `T` is a referenceable type [[defns.referenceable]].
345
 
346
  - Let *`COPY_CONST`*`(A, B)` be `const B` if `A` is a const type,
 
555
  constexpr underlying_type_t<T> to_underlying(T value) noexcept;
556
  ```
557
 
558
  *Returns:* `static_cast<underlying_type_t<T>>(value)`.
559
 
560
+ ### Undefined behavior <a id="utility.undefined">[[utility.undefined]]</a>
561
 
562
  ``` cpp
563
  [[noreturn]] void unreachable();
564
  ```
565
 
 
584
  int b = f(3); // undefined behavior
585
  ```
586
 
587
  — *end example*]
588
 
589
+ ``` cpp
590
+ void observable_checkpoint() noexcept;
591
+ ```
592
+
593
+ *Effects:* Establishes an observable checkpoint [[intro.abstract]].
594
+
595
  ## Pairs <a id="pairs">[[pairs]]</a>
596
 
597
+ ### General <a id="pairs.general">[[pairs.general]]</a>
598
 
599
  The library provides a template for heterogeneous pairs of values. The
600
  library also provides a matching function template to simplify their
601
  construction and several templates that provide access to `pair` objects
602
  as if they were `tuple` objects (see  [[tuple.helper]] and 
 
658
  template<class T1, class T2>
659
  pair(T1, T2) -> pair<T1, T2>;
660
  }
661
  ```
662
 
663
+ Member functions of `pair` do not throw exceptions unless one of the
664
+ element-wise operations specified to be called for that operation throws
665
+ an exception.
666
 
667
  The defaulted move and copy constructor, respectively, of `pair` is a
668
  constexpr function if and only if all required element-wise
669
  initializations for move and copy, respectively, would be
670
  constexpr-suitable [[dcl.constexpr]].
671
 
672
  If
673
  `(is_trivially_destructible_v<T1> && is_trivially_destructible_v<T2>)`
674
  is `true`, then the destructor of `pair` is trivial.
675
 
676
+ `pair<T, U>` is a structural type [[term.structural.type]] if `T` and
677
+ `U` are both structural types. Two values `p1` and `p2` of type
678
+ `pair<T, U>` are template-argument-equivalent [[temp.type]] if and only
679
+ if `p1.first` and `p2.first` are template-argument-equivalent and
680
+ `p1.second` and `p2.second` are template-argument-equivalent.
681
 
682
  ``` cpp
683
  constexpr explicit(see below) pair();
684
  ```
685
 
 
855
  *Constraints:*
856
 
857
  - `is_move_assignable_v<T1>` is `true` and
858
  - `is_move_assignable_v<T2>` is `true`.
859
 
860
+ *Effects:* Assigns `std::forward<T1>(p.first)` to `first` and
861
+ `std::forward<T2>(p.second)` to `second`.
862
 
863
  *Returns:* `*this`.
864
 
865
  *Remarks:* The exception specification is equivalent to:
866
 
 
889
  *Constraints:*
890
 
891
  - `is_assignable_v<T1&, U1>` is `true` and
892
  - `is_assignable_v<T2&, U2>` is `true`.
893
 
894
+ *Effects:* Assigns `std::forward<U1>(p.first)` `first` and
895
+ `std::forward<U2>(p.second)` to `second`.
 
896
 
897
  *Returns:* `*this`.
898
 
899
  ``` cpp
900
  template<pair-like P> constexpr pair& operator=(P&& p);
 
975
  ``` cpp
976
  template<class T1, class T2, class U1, class U2>
977
  constexpr bool operator==(const pair<T1, T2>& x, const pair<U1, U2>& y);
978
  ```
979
 
980
+ *Constraints:* `x.first == y.first` and `x.second == y.second` are valid
981
+ expressions and each of `decltype(x.first == y.first)` and
982
+ `decltype(x.second == y.second)` models *`boolean- testable`*.
983
 
984
  *Returns:* `x.first == y.first && x.second == y.second`.
985
 
986
  ``` cpp
987
  template<class T1, class T2, class U1, class U2>
 
1055
  };
1056
  ```
1057
 
1058
  *Mandates:* `I` < 2.
1059
 
1060
+ *Result:* The type `T1` if `I` is 0, otherwise the type `T2`.
1061
 
1062
  ``` cpp
1063
  template<size_t I, class T1, class T2>
1064
  constexpr tuple_element_t<I, pair<T1, T2>>& get(pair<T1, T2>& p) noexcept;
1065
  template<size_t I, class T1, class T2>
 
1123
  arguments used for piecewise construction of the elements of the `pair`
1124
  object.
1125
 
1126
  ## Tuples <a id="tuple">[[tuple]]</a>
1127
 
1128
+ ### General <a id="tuple.general">[[tuple.general]]</a>
1129
 
1130
  Subclause  [[tuple]] describes the tuple library that provides a tuple
1131
  type as the class template `tuple` that can be instantiated with any
1132
  number of arguments. Each template argument specifies the type of an
1133
  element in the `tuple`. Consequently, tuples are heterogeneous,
1134
  fixed-size collections of values. An instantiation of `tuple` with two
1135
  arguments is similar to an instantiation of `pair` with the same two
1136
  arguments. See  [[pairs]].
1137
 
1138
+ In addition to being available via inclusion of the `<tuple>` header,
1139
+ `ignore` [[tuple.syn]] is available when `<utility>` [[utility]] is
1140
+ included.
1141
+
1142
  ### Header `<tuple>` synopsis <a id="tuple.syn">[[tuple.syn]]</a>
1143
 
1144
  ``` cpp
1145
  // all freestanding
1146
  #include <compare> // see [compare.syn]
 
1162
  template<class> class TQual, template<class> class UQual>
1163
  struct basic_common_reference<TTuple, UTuple, TQual, UQual>;
1164
  template<exposition onlyconceptnc{tuple-like} TTuple, exposition onlyconceptnc{tuple-like} UTuple>
1165
  struct common_type<TTuple, UTuple>;
1166
 
1167
+ // ignore
1168
+ struct ignore-type { // exposition only
1169
+ constexpr const ignore-type&
1170
+ operator=(const auto &) const noexcept { return *this; }
1171
+ };
1172
+ inline constexpr ignore-type ignore;
1173
+
1174
  // [tuple.creation], tuple creation functions
 
 
1175
  template<class... TTypes>
1176
  constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&...);
1177
 
1178
  template<class... TTypes>
1179
  constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&...) noexcept;
 
1184
  template<exposition onlyconceptnc{tuple-like}... Tuples>
1185
  constexpr tuple<CTypes...> tuple_cat(Tuples&&...);
1186
 
1187
  // [tuple.apply], calling a function with a tuple of arguments
1188
  template<class F, exposition onlyconceptnc{tuple-like} Tuple>
1189
+ constexpr apply_result_t<F, Tuple> apply(F&& f, Tuple&& t)
1190
+ noexcept(is_nothrow_applicable_v<F, Tuple>);
1191
 
1192
  template<class T, exposition onlyconceptnc{tuple-like} Tuple>
1193
  constexpr T make_from_tuple(Tuple&& t);
1194
 
1195
  // [tuple.helper], tuple helper classes
 
1203
 
1204
  template<size_t I, class... Types>
1205
  struct tuple_element<I, tuple<Types...>>;
1206
 
1207
  template<size_t I, class T>
1208
+ using tuple_element_t = tuple_element<I, T>::type;
1209
 
1210
  // [tuple.elem], element access
1211
  template<size_t I, class... Types>
1212
  constexpr tuple_element_t<I, tuple<Types...>>& get(tuple<Types...>&) noexcept;
1213
  template<size_t I, class... Types>
 
1258
  template<class T>
1259
  concept tuple-like = see belownc; // exposition only
1260
  ```
1261
 
1262
  A type `T` models and satisfies the exposition-only concept `tuple-like`
1263
+ if `remove_cvref_t<T>` is a specialization of `array`, `complex`,
1264
+ `pair`, `tuple`, or `ranges::subrange`.
1265
 
1266
  ### Class template `tuple` <a id="tuple.tuple">[[tuple.tuple]]</a>
1267
 
1268
+ #### General <a id="tuple.tuple.general">[[tuple.tuple.general]]</a>
1269
+
1270
  ``` cpp
1271
  namespace std {
1272
  template<class... Types>
1273
  class tuple {
1274
  public:
 
1390
  template<class Alloc, class... UTypes>
1391
  tuple(allocator_arg_t, Alloc, tuple<UTypes...>) -> tuple<UTypes...>;
1392
  }
1393
  ```
1394
 
1395
+ If a program declares an explicit or partial specialization of `tuple`,
1396
+ the program is ill-formed, no diagnostic required.
1397
+
1398
  #### Construction <a id="tuple.cnstr">[[tuple.cnstr]]</a>
1399
 
1400
  In the descriptions that follow, let i be in the range \[`0`,
1401
  `sizeof...(Types)`) in order, `Tᵢ` be the iᵗʰ type in `Types`, and `Uᵢ`
1402
  be the iᵗʰ type in a template parameter pack named `UTypes`, where
 
1507
  template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>& u);
1508
  template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&& u);
1509
  template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>&& u);
1510
  ```
1511
 
1512
+ Let `I` be the pack `0, 1, `…`, (sizeof...(Types) - 1)`. Let
1513
  *`FWD`*`(u)` be `static_cast<decltype(u)>(u)`.
1514
 
1515
  *Constraints:*
1516
 
1517
  - `sizeof...(Types)` equals `sizeof...(UTypes)`, and
 
1578
  ``` cpp
1579
  template<tuple-like UTuple>
1580
  constexpr explicit(see below) tuple(UTuple&& u);
1581
  ```
1582
 
1583
+ Let `I` be the pack `0, 1, ``, (sizeof...(Types) - 1)`.
1584
 
1585
  *Constraints:*
1586
 
1587
  - `different-from<UTuple, tuple>` [[range.utility.helpers]] is `true`,
1588
  - `remove_cvref_t<UTuple>` is not a specialization of
1589
  `ranges::subrange`,
1590
  - `sizeof...(Types)` equals `tuple_size_v<remove_cvref_t<UTuple>>`,
1591
  - `(is_constructible_v<Types, decltype(get<I>(std::forward<UTuple>(u)))> && ...)`
1592
  is `true`, and
1593
+ - either `sizeof...(Types)` is not 1, or (when `Types...` expands to
1594
  `T`) `is_convertible_v<UTuple, T>` and `is_constructible_v<T, UTuple>`
1595
  are both `false`.
1596
 
1597
  *Effects:* For all i, initializes the iᵗʰ element of `*this` with
1598
  `get<`i`>(std::forward<UTuple>(u))`.
 
1601
 
1602
  ``` cpp
1603
  !(is_convertible_v<decltype(get<I>(std::forward<UTuple>(u))), Types> && ...)
1604
  ```
1605
 
1606
+ The constructor is defined as deleted if
1607
+
1608
+ ``` cpp
1609
+ (reference_constructs_from_temporary_v<Types, decltype(get<I>(std::forward<UTuple>(u)))>
1610
+ || ...)
1611
+ ```
1612
+
1613
+ is `true`.
1614
+
1615
  ``` cpp
1616
  template<class Alloc>
1617
  constexpr explicit(see below)
1618
  tuple(allocator_arg_t, const Alloc& a);
1619
  template<class Alloc>
 
1852
  *Constraints:*
1853
 
1854
  - `different-from<UTuple, tuple>` [[range.utility.helpers]] is `true`,
1855
  - `remove_cvref_t<UTuple>` is not a specialization of
1856
  `ranges::subrange`,
1857
+ - `sizeof...(Types)` equals `tuple_size_v<remove_cvref_t<UTuple>>`, and
1858
  - `is_assignable_v<``Tᵢ``&, decltype(get<`i`>(std::forward<UTuple>(u)))>`
1859
  is `true` for all i.
1860
 
1861
  *Effects:* For all i, assigns `get<`i`>(std::forward<UTuple>(u))` to
1862
  `get<`i`>(*this)`.
 
1871
  *Constraints:*
1872
 
1873
  - `different-from<UTuple, tuple>` [[range.utility.helpers]] is `true`,
1874
  - `remove_cvref_t<UTuple>` is not a specialization of
1875
  `ranges::subrange`,
1876
+ - `sizeof...(Types)` equals `tuple_size_v<remove_cvref_t<UTuple>>`, and
1877
  - `is_assignable_v<const ``Tᵢ``&, decltype(get<`i`>(std::forward<UTuple>(u)))>`
1878
  is `true` for all i.
1879
 
1880
  *Effects:* For all i, assigns `get<`i`>(std::forward<UTuple>(u))` to
1881
  `get<`i`>(*this)`.
 
1898
  `true`.
1899
 
1900
  *Preconditions:* For all i, `get<`i`>(*this)` is swappable
1901
  with [[swappable.requirements]] `get<`i`>(rhs)`.
1902
 
1903
+ *Effects:* For each i, calls `swap` for `get<`i`>(*this)` and
1904
  `get<`i`>(rhs)`.
1905
 
1906
  *Throws:* Nothing unless one of the element-wise `swap` calls throws an
1907
  exception.
1908
 
 
1950
  ``` cpp
1951
  template<class... TTypes>
1952
  constexpr tuple<TTypes&...> tie(TTypes&... t) noexcept;
1953
  ```
1954
 
1955
+ *Returns:* `tuple<TTypes&...>(t...)`.
 
 
1956
 
1957
  [*Example 2*:
1958
 
1959
  `tie` functions allow one to create tuples that unpack tuples into
1960
  variables. `ignore` can be used for elements that are not needed:
 
1996
 
1997
  ### Calling a function with a `tuple` of arguments <a id="tuple.apply">[[tuple.apply]]</a>
1998
 
1999
  ``` cpp
2000
  template<class F, tuple-like Tuple>
2001
+ constexpr apply_result_t<F, Tuple> apply(F&& f, Tuple&& t)
2002
+ noexcept(is_nothrow_applicable_v<F, Tuple>);
2003
  ```
2004
 
2005
+ *Effects:* Given the exposition-only function template:
2006
 
2007
  ``` cpp
2008
  namespace std {
2009
  template<class F, tuple-like Tuple, size_t... I>
2010
  constexpr decltype(auto) apply-impl(F&& f, Tuple&& t, index_sequence<I...>) {
 
2019
  ``` cpp
2020
  return apply-impl(std::forward<F>(f), std::forward<Tuple>(t),
2021
  make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
2022
  ```
2023
 
 
 
 
 
 
 
 
 
2024
  ``` cpp
2025
  template<class T, tuple-like Tuple>
2026
  constexpr T make_from_tuple(Tuple&& t);
2027
  ```
2028
 
2029
  *Mandates:* If `tuple_size_v<remove_reference_t<Tuple>>` is 1, then
2030
  `reference_constructs_from_temporary_v<T, decltype(get<0>(declval<Tuple>()))>`
2031
  is `false`.
2032
 
2033
+ *Effects:* Given the exposition-only function template:
2034
 
2035
  ``` cpp
2036
  namespace std {
2037
  template<class T, tuple-like Tuple, size_t... I>
2038
  requires is_constructible_v<T, decltype(get<I>(declval<Tuple>()))...>
 
2058
 
2059
  ``` cpp
2060
  template<class T> struct tuple_size;
2061
  ```
2062
 
2063
+ Except where specified otherwise, all specializations of `tuple_size`
2064
+ meet the *Cpp17UnaryTypeTrait* requirements [[meta.rqmts]] with a base
2065
+ characteristic of `integral_constant<size_t, N>` for some `N`.
2066
 
2067
  ``` cpp
2068
  template<class... Types>
2069
+ struct tuple_size<tuple<Types...>> : integral_constant<size_t, sizeof...(Types)> { };
2070
  ```
2071
 
2072
  ``` cpp
2073
  template<size_t I, class... Types>
2074
  struct tuple_element<I, tuple<Types...>> {
 
2076
  };
2077
  ```
2078
 
2079
  *Mandates:* `I` < `sizeof...(Types)`.
2080
 
2081
+ *Result:* `TI` is the type of the `I`ᵗʰ element of `Types`, where
2082
+ indexing is zero-based.
2083
 
2084
  ``` cpp
2085
  template<class T> struct tuple_size<const T>;
2086
  ```
2087
 
 
2116
  ```
2117
 
2118
  Let `TE` denote `tuple_element_t<I, T>` of the cv-unqualified type `T`.
2119
  Then each specialization of the template meets the
2120
  *Cpp17TransformationTrait* requirements [[meta.rqmts]] with a member
2121
+ typedef `type` that names the type `const TE`.
2122
 
2123
  In addition to being available via inclusion of the `<tuple>` header,
2124
  the template is available when any of the headers `<array>`, `<ranges>`,
2125
  or `<utility>` are included.
2126
 
 
2130
  template<size_t I, class... Types>
2131
  constexpr tuple_element_t<I, tuple<Types...>>&
2132
  get(tuple<Types...>& t) noexcept;
2133
  template<size_t I, class... Types>
2134
  constexpr tuple_element_t<I, tuple<Types...>>&&
2135
+ get(tuple<Types...>&& t) noexcept; // #1
2136
  template<size_t I, class... Types>
2137
  constexpr const tuple_element_t<I, tuple<Types...>>&
2138
+ get(const tuple<Types...>& t) noexcept; // #2
2139
  template<size_t I, class... Types>
2140
  constexpr const tuple_element_t<I, tuple<Types...>>&& get(const tuple<Types...>&& t) noexcept;
2141
  ```
2142
 
2143
  *Mandates:* `I` < `sizeof...(Types)`.
2144
 
2145
  *Returns:* A reference to the `I`ᵗʰ element of `t`, where indexing is
2146
  zero-based.
2147
 
2148
+ [*Note 1*: For the overload marked \#1, if a type `T` in `Types` is
2149
+ some reference type `X&`, the return type is `X&`, not `X&&`. However,
2150
+ if the element type is a non-reference type `T`, the return type is
2151
+ `T&&`. — *end note*]
2152
 
2153
+ [*Note 2*: Constness is shallow. For the overload marked \#2, if a type
2154
+ `T` in `Types` is some reference type `X&`, the return type is `X&`, not
2155
+ `const X&`. However, if the element type is a non-reference type `T`,
2156
+ the return type is `const T&`. This is consistent with how constness is
2157
+ defined to work for non-static data members of reference
2158
+ type. — *end note*]
2159
 
2160
  ``` cpp
2161
  template<class T, class... Types>
2162
  constexpr T& get(tuple<Types...>& t) noexcept;
2163
  template<class T, class... Types>
 
2198
  constexpr bool operator==(const tuple<TTypes...>& t, const UTuple& u);
2199
  ```
2200
 
2201
  For the first overload let `UTuple` be `tuple<UTypes...>`.
2202
 
2203
+ *Constraints:* For all `i`, where 0 ≤ `i` < `sizeof...(TTypes)`,
2204
+ `get<i>(t) == get<i>(u)` is a valid expression and
2205
+ `decltype(get<i>(t) == get<i>(u))` models `boolean-testable`.
2206
+ `sizeof...(TTypes)` equals `tuple_size_v<UTuple>`.
 
 
2207
 
2208
  *Returns:* `true` if `get<i>(t) == get<i>(u)` for all `i`, otherwise
2209
  `false`.
2210
 
2211
  [*Note 1*: If `sizeof...(TTypes)` equals zero, returns
 
2249
 
2250
  [*Note 1*: The above definition does not require `tₜₐᵢₗ` (or `uₜₐᵢₗ`)
2251
  to be constructed. It might not even be possible, as `t` and `u` are not
2252
  required to be copy constructible. Also, all comparison operator
2253
  functions are short circuited; they do not perform element accesses
2254
+ beyond what is needed to determine the result of the
2255
  comparison. — *end note*]
2256
 
2257
  ### `common_reference` related specializations <a id="tuple.common.ref">[[tuple.common.ref]]</a>
2258
 
2259
  In the descriptions that follow:
 
2281
  - `is_same_v<UTuple, decay_t<UTuple>>` is `true`.
2282
  - `tuple_size_v<TTuple>` equals `tuple_size_v<UTuple>`.
2283
  - `tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...>` denotes a
2284
  type.
2285
 
2286
+ *Result:* The member *typedef-name* `type` denotes the type
2287
  `tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...>`.
2288
 
2289
  ``` cpp
2290
  template<tuple-like TTuple, tuple-like UTuple>
2291
  struct common_type<TTuple, UTuple> {
 
2300
  - `is_same_v<TTuple, decay_t<TTuple>>` is `true`.
2301
  - `is_same_v<UTuple, decay_t<UTuple>>` is `true`.
2302
  - `tuple_size_v<TTuple>` equals `tuple_size_v<UTuple>`.
2303
  - `tuple<common_type_t<TTypes, UTypes>...>` denotes a type.
2304
 
2305
+ *Result:* The member *typedef-name* `type` denotes the type
2306
  `tuple<common_type_t<TTypes, UTypes>...>`.
2307
 
2308
  ### Tuple traits <a id="tuple.traits">[[tuple.traits]]</a>
2309
 
2310
  ``` cpp
 
2342
  noexcept(x.swap(y))
2343
  ```
2344
 
2345
  ## Optional objects <a id="optional">[[optional]]</a>
2346
 
2347
+ ### General <a id="optional.general">[[optional.general]]</a>
2348
 
2349
  Subclause  [[optional]] describes class template `optional` that
2350
  represents optional objects. An *optional object* is an object that
2351
  contains the storage for another object and manages the lifetime of this
2352
  contained object, if any. The contained object may be initialized after
 
2355
  contained object is tracked by the optional object.
2356
 
2357
  ### Header `<optional>` synopsis <a id="optional.syn">[[optional.syn]]</a>
2358
 
2359
  ``` cpp
2360
+ // mostly freestanding
2361
  #include <compare> // see [compare.syn]
2362
 
2363
  namespace std {
2364
  // [optional.optional], class template optional
2365
  template<class T>
2366
+ class optional; // partially freestanding
2367
+
2368
+ // [optional.optional.ref], partial specialization of optional for lvalue reference types
2369
+ template<class T>
2370
+ class optional<T&>; // partially freestanding
2371
+
2372
+ template<class T>
2373
+ constexpr bool ranges::enable_view<optional<T>> = true;
2374
+ template<class T>
2375
+ constexpr auto format_kind<optional<T>> = range_format::disabled;
2376
+ template<class T>
2377
+ constexpr bool ranges::enable_borrowed_range<optional<T&>> = true;
2378
 
2379
  template<class T>
2380
  concept is-derived-from-optional = requires(const T& t) { // exposition only
2381
  []<class U>(const optional<U>&){ }(t);
2382
  };
 
2431
  // [optional.specalg], specialized algorithms
2432
  template<class T>
2433
  constexpr void swap(optional<T>&, optional<T>&) noexcept(see below);
2434
 
2435
  template<class T>
2436
+ constexpr optional<decay_t<T>> make_optional(T&&);
2437
  template<class T, class... Args>
2438
  constexpr optional<T> make_optional(Args&&... args);
2439
  template<class T, class U, class... Args>
2440
  constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args);
2441
 
 
2453
  namespace std {
2454
  template<class T>
2455
  class optional {
2456
  public:
2457
  using value_type = T;
2458
+ using iterator = implementation-defined; // see~[optional.iterators]
2459
+ using const_iterator = implementation-defined; // see~[optional.iterators]
2460
 
2461
  // [optional.ctor], constructors
2462
  constexpr optional() noexcept;
2463
  constexpr optional(nullopt_t) noexcept;
2464
  constexpr optional(const optional&);
2465
  constexpr optional(optional&&) noexcept(see below);
2466
  template<class... Args>
2467
  constexpr explicit optional(in_place_t, Args&&...);
2468
  template<class U, class... Args>
2469
  constexpr explicit optional(in_place_t, initializer_list<U>, Args&&...);
2470
+ template<class U = remove_cv_t<T>>
2471
  constexpr explicit(see below) optional(U&&);
2472
  template<class U>
2473
  constexpr explicit(see below) optional(const optional<U>&);
2474
  template<class U>
2475
  constexpr explicit(see below) optional(optional<U>&&);
 
2479
 
2480
  // [optional.assign], assignment
2481
  constexpr optional& operator=(nullopt_t) noexcept;
2482
  constexpr optional& operator=(const optional&);
2483
  constexpr optional& operator=(optional&&) noexcept(see below);
2484
+ template<class U = remove_cv_t<T>> constexpr optional& operator=(U&&);
2485
  template<class U> constexpr optional& operator=(const optional<U>&);
2486
  template<class U> constexpr optional& operator=(optional<U>&&);
2487
  template<class... Args> constexpr T& emplace(Args&&...);
2488
  template<class U, class... Args> constexpr T& emplace(initializer_list<U>, Args&&...);
2489
 
2490
  // [optional.swap], swap
2491
  constexpr void swap(optional&) noexcept(see below);
2492
 
2493
+ // [optional.iterators], iterator support
2494
+ constexpr iterator begin() noexcept;
2495
+ constexpr const_iterator begin() const noexcept;
2496
+ constexpr iterator end() noexcept;
2497
+ constexpr const_iterator end() const noexcept;
2498
+
2499
  // [optional.observe], observers
2500
  constexpr const T* operator->() const noexcept;
2501
  constexpr T* operator->() noexcept;
2502
  constexpr const T& operator*() const & noexcept;
2503
  constexpr T& operator*() & noexcept;
2504
  constexpr T&& operator*() && noexcept;
2505
  constexpr const T&& operator*() const && noexcept;
2506
  constexpr explicit operator bool() const noexcept;
2507
  constexpr bool has_value() const noexcept;
2508
+ constexpr const T& value() const &; // freestanding-deleted
2509
+ constexpr T& value() &; // freestanding-deleted
2510
+ constexpr T&& value() &&; // freestanding-deleted
2511
+ constexpr const T&& value() const &&; // freestanding-deleted
2512
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&&) const &;
2513
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&&) &&;
2514
 
2515
  // [optional.monadic], monadic operations
2516
  template<class F> constexpr auto and_then(F&& f) &;
2517
  template<class F> constexpr auto and_then(F&& f) &&;
2518
  template<class F> constexpr auto and_then(F&& f) const &;
 
2534
  template<class T>
2535
  optional(T) -> optional<T>;
2536
  }
2537
  ```
2538
 
2539
+ An object of type `optional<T>` at any given time either contains a
2540
+ value or does not contain a value. When an object of type `optional<T>`
2541
+ *contains a value*, it means that an object of type `T`, referred to as
2542
+ the optional object’s *contained value*, is nested within
2543
+ [[intro.object]] the optional object. When an object of type
2544
+ `optional<T>` is contextually converted to `bool`, the conversion
2545
+ returns `true` if the object contains a value; otherwise the conversion
2546
+ returns `false`.
 
2547
 
2548
+ When an object of type `optional<T>` contains a value, member `val`
2549
+ points to the contained value.
2550
 
2551
+ A type `X` is a *valid contained type* for `optional` if `X` is an
2552
+ lvalue reference type or a complete non-array object type, and
2553
+ `remove_cvref_t<X>` is a type other than `in_place_t` or `nullopt_t`. If
2554
+ a specialization of `optional` is instantiated with a type `T` that is
2555
+ not a valid contained type for `optional`, the program is ill-formed. If
2556
+ `T` is an object type, `T` shall meet the *Cpp17Destructible*
2557
+ requirements ([[cpp17.destructible]]).
2558
 
2559
  #### Constructors <a id="optional.ctor">[[optional.ctor]]</a>
2560
 
2561
  The exposition-only variable template *`converts-from-any-cvref`* is
2562
  used by some constructors for `optional`.
 
2601
  ```
2602
 
2603
  *Constraints:* `is_move_constructible_v<T>` is `true`.
2604
 
2605
  *Effects:* If `rhs` contains a value, direct-non-list-initializes the
2606
+ contained value with `*std::move(rhs)`. `rhs.has_value()` is unchanged.
2607
 
2608
  *Ensures:* `rhs.has_value() == this->has_value()`.
2609
 
2610
  *Throws:* Any exception thrown by the selected constructor of `T`.
2611
 
 
2647
 
2648
  *Remarks:* If `T`’s constructor selected for the initialization is a
2649
  constexpr constructor, this constructor is a constexpr constructor.
2650
 
2651
  ``` cpp
2652
+ template<class U = remove_cv_t<T>> constexpr explicit(see below) optional(U&& v);
2653
  ```
2654
 
2655
  *Constraints:*
2656
 
2657
  - `is_constructible_v<T, U>` is `true`,
 
2707
  - `is_constructible_v<T, U>` is `true`, and
2708
  - if `T` is not cv `bool`, *`converts-from-any-cvref`*`<T, optional<U>>`
2709
  is `false`.
2710
 
2711
  *Effects:* If `rhs` contains a value, direct-non-list-initializes the
2712
+ contained value with `*std::move(rhs)`. `rhs.has_value()` is unchanged.
2713
 
2714
  *Ensures:* `rhs.has_value() == this->has_value()`.
2715
 
2716
  *Throws:* Any exception thrown by the selected constructor of `T`.
2717
 
 
2791
 
2792
  **Table: `optional::operator=(optional&&)` effects** <a id="optional.assign.move">[optional.assign.move]</a>
2793
 
2794
  | | `*this` contains a value | `*this` does not contain a value |
2795
  | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------- |
2796
+ | `rhs` contains a value | assigns `*std::move(rhs)` to the contained value | direct-non-list-initializes the contained value with `*std::move(rhs)` |
2797
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2798
 
2799
 
2800
  *Ensures:* `rhs.has_value() == this->has_value()`.
2801
 
 
2817
  `is_trivially_move_constructible_v<T> &&`
2818
  `is_trivially_move_assignable_v<T> &&` `is_trivially_destructible_v<T>`
2819
  is `true`, this assignment operator is trivial.
2820
 
2821
  ``` cpp
2822
+ template<class U = remove_cv_t<T>> constexpr optional& operator=(U&& v);
2823
  ```
2824
 
2825
+ *Constraints:*
2826
+
2827
+ - `is_same_v<remove_cvref_t<U>, optional>` is `false`,
2828
+ - `conjunction_v<is_scalar<T>, is_same<T, decay_t<U>>>` is `false`,
2829
+ - `is_constructible_v<T, U>` is `true`, and
2830
+ - `is_assignable_v<T&, U>` is `true`.
2831
 
2832
  *Effects:* If `*this` contains a value, assigns `std::forward<U>(v)` to
2833
  the contained value; otherwise direct-non-list-initializes the contained
2834
  value with `std::forward<U>(v)`.
2835
 
 
2899
 
2900
  **Table: `optional::operator=(optional<U>&&)` effects** <a id="optional.assign.move.templ">[optional.assign.move.templ]</a>
2901
 
2902
  | | `*this` contains a value | `*this` does not contain a value |
2903
  | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------- |
2904
+ | `rhs` contains a value | assigns `*std::move(rhs)` to the contained value | direct-non-list-initializes the contained value with `*std::move(rhs)` |
2905
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2906
 
2907
 
2908
  *Ensures:* `rhs.has_value() == this->has_value()`.
2909
 
 
2992
  `*val` and `*rhs.val` is determined by the exception safety guarantee of
2993
  `swap` for lvalues of `T`. If an exception is thrown during the call to
2994
  `T`’s move constructor, the state of `*val` and `*rhs.val` is determined
2995
  by the exception safety guarantee of `T`’s move constructor.
2996
 
2997
+ #### Iterator support <a id="optional.iterators">[[optional.iterators]]</a>
2998
+
2999
+ ``` cpp
3000
+ using iterator = implementation-defined;
3001
+ using const_iterator = implementation-defined;
3002
+ ```
3003
+
3004
+ These types model `contiguous_iterator` [[iterator.concept.contiguous]],
3005
+ meet the *Cpp17RandomAccessIterator*
3006
+ requirements [[random.access.iterators]], and meet the requirements for
3007
+ constexpr iterators [[iterator.requirements.general]], with value type
3008
+ `remove_cv_t<T>`. The reference type is `T&` for `iterator` and
3009
+ `const T&` for `const_iterator`.
3010
+
3011
+ All requirements on container iterators [[container.reqmts]] apply to
3012
+ `optional::iterator` and `optional::const_iterator` as well.
3013
+
3014
+ Any operation that initializes or destroys the contained value of an
3015
+ optional object invalidates all iterators into that object.
3016
+
3017
+ ``` cpp
3018
+ constexpr iterator begin() noexcept;
3019
+ constexpr const_iterator begin() const noexcept;
3020
+ ```
3021
+
3022
+ *Returns:* If `has_value()` is `true`, an iterator referring to the
3023
+ contained value. Otherwise, a past-the-end iterator value.
3024
+
3025
+ ``` cpp
3026
+ constexpr iterator end() noexcept;
3027
+ constexpr const_iterator end() const noexcept;
3028
+ ```
3029
+
3030
+ *Returns:* `begin() + has_value()`.
3031
+
3032
  #### Observers <a id="optional.observe">[[optional.observe]]</a>
3033
 
3034
  ``` cpp
3035
  constexpr const T* operator->() const noexcept;
3036
  constexpr T* operator->() noexcept;
3037
  ```
3038
 
3039
+ `has_value()` is `true`.
3040
 
3041
  *Returns:* `val`.
3042
 
3043
  *Remarks:* These functions are constexpr functions.
3044
 
3045
  ``` cpp
3046
  constexpr const T& operator*() const & noexcept;
3047
  constexpr T& operator*() & noexcept;
3048
  ```
3049
 
3050
+ `has_value()` is `true`.
3051
 
3052
  *Returns:* `*val`.
3053
 
3054
  *Remarks:* These functions are constexpr functions.
3055
 
3056
  ``` cpp
3057
  constexpr T&& operator*() && noexcept;
3058
  constexpr const T&& operator*() const && noexcept;
3059
  ```
3060
 
3061
+ `has_value()` is `true`.
3062
 
3063
  *Effects:* Equivalent to: `return std::move(*val);`
3064
 
3065
  ``` cpp
3066
  constexpr explicit operator bool() const noexcept;
 
3099
  ``` cpp
3100
  return has_value() ? std::move(*val) : throw bad_optional_access();
3101
  ```
3102
 
3103
  ``` cpp
3104
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) const &;
3105
  ```
3106
 
3107
  *Mandates:* `is_copy_constructible_v<T> && is_convertible_v<U&&, T>` is
3108
  `true`.
3109
 
 
3112
  ``` cpp
3113
  return has_value() ? **this : static_cast<T>(std::forward<U>(v));
3114
  ```
3115
 
3116
  ``` cpp
3117
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) &&;
3118
  ```
3119
 
3120
  *Mandates:* `is_move_constructible_v<T> && is_convertible_v<U&&, T>` is
3121
  `true`.
3122
 
 
3131
  ``` cpp
3132
  template<class F> constexpr auto and_then(F&& f) &;
3133
  template<class F> constexpr auto and_then(F&& f) const &;
3134
  ```
3135
 
3136
+ Let `U` be `invoke_result_t<F, decltype(*`*`val`*`)>`.
3137
 
3138
  *Mandates:* `remove_cvref_t<U>` is a specialization of `optional`.
3139
 
3140
  *Effects:* Equivalent to:
3141
 
3142
  ``` cpp
3143
  if (*this) {
3144
+ return invoke(std::forward<F>(f), *val);
3145
  } else {
3146
  return remove_cvref_t<U>();
3147
  }
3148
  ```
3149
 
3150
  ``` cpp
3151
  template<class F> constexpr auto and_then(F&& f) &&;
3152
  template<class F> constexpr auto and_then(F&& f) const &&;
3153
  ```
3154
 
3155
+ Let `U` be `invoke_result_t<F, decltype(std::move(*`*`val`*`))>`.
3156
 
3157
  *Mandates:* `remove_cvref_t<U>` is a specialization of `optional`.
3158
 
3159
  *Effects:* Equivalent to:
3160
 
3161
  ``` cpp
3162
  if (*this) {
3163
+ return invoke(std::forward<F>(f), std::move(*val));
3164
  } else {
3165
  return remove_cvref_t<U>();
3166
  }
3167
  ```
3168
 
3169
  ``` cpp
3170
  template<class F> constexpr auto transform(F&& f) &;
3171
  template<class F> constexpr auto transform(F&& f) const &;
3172
  ```
3173
 
3174
+ Let `U` be `remove_cv_t<invoke_result_t<F, decltype(*`*`val`*`)>>`.
3175
 
3176
+ *Mandates:* `U` is a valid contained type for `optional`. The
3177
+ declaration
3178
 
3179
  ``` cpp
3180
+ U u(invoke(std::forward<F>(f), *val));
3181
  ```
3182
 
3183
  is well-formed for some invented variable `u`.
3184
 
3185
  [*Note 1*: There is no requirement that `U` is
3186
  movable [[dcl.init.general]]. — *end note*]
3187
 
3188
  *Returns:* If `*this` contains a value, an `optional<U>` object whose
3189
  contained value is direct-non-list-initialized with
3190
+ `invoke(std::forward<F>(f), *`*`val`*`)`; otherwise, `optional<U>()`.
3191
 
3192
  ``` cpp
3193
  template<class F> constexpr auto transform(F&& f) &&;
3194
  template<class F> constexpr auto transform(F&& f) const &&;
3195
  ```
3196
 
3197
  Let `U` be
3198
+ `remove_cv_t<invoke_result_t<F, decltype(std::move(*`*`val`*`))>>`.
3199
 
3200
+ *Mandates:* `U` is a valid contained type for `optional`. The
3201
+ declaration
3202
 
3203
  ``` cpp
3204
+ U u(invoke(std::forward<F>(f), std::move(*val)));
3205
  ```
3206
 
3207
  is well-formed for some invented variable `u`.
3208
 
3209
  [*Note 2*: There is no requirement that `U` is
3210
  movable [[dcl.init.general]]. — *end note*]
3211
 
3212
  *Returns:* If `*this` contains a value, an `optional<U>` object whose
3213
  contained value is direct-non-list-initialized with
3214
+ `invoke(std::forward<F>(f), std::move(*`*`val`*`))`; otherwise,
3215
  `optional<U>()`.
3216
 
3217
  ``` cpp
3218
  template<class F> constexpr optional or_else(F&& f) const &;
3219
  ```
3220
 
3221
+ *Constraints:* `F` models `invocable` and `T` models
3222
  `copy_constructible`.
3223
 
3224
  *Mandates:* `is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>` is
3225
  `true`.
3226
 
 
3236
 
3237
  ``` cpp
3238
  template<class F> constexpr optional or_else(F&& f) &&;
3239
  ```
3240
 
3241
+ *Constraints:* `F` models `invocable` and `T` models
3242
  `move_constructible`.
3243
 
3244
  *Mandates:* `is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>` is
3245
  `true`.
3246
 
 
3263
  *Effects:* If `*this` contains a value, calls `val->T::T̃()` to destroy
3264
  the contained value; otherwise no effect.
3265
 
3266
  *Ensures:* `*this` does not contain a value.
3267
 
3268
+ ### Partial specialization of `optional` for reference types <a id="optional.optional.ref">[[optional.optional.ref]]</a>
3269
+
3270
+ #### General <a id="optional.optional.ref.general">[[optional.optional.ref.general]]</a>
3271
+
3272
+ ``` cpp
3273
+ namespace std {
3274
+ template<class T>
3275
+ class optional<T&> {
3276
+ public:
3277
+ using value_type = T;
3278
+ using iterator = implementation-defined; // see~[optional.ref.iterators]
3279
+
3280
+ public:
3281
+ // [optional.ref.ctor], constructors
3282
+ constexpr optional() noexcept = default;
3283
+ constexpr optional(nullopt_t) noexcept : optional() {}
3284
+ constexpr optional(const optional& rhs) noexcept = default;
3285
+
3286
+ template<class Arg>
3287
+ constexpr explicit optional(in_place_t, Arg&& arg);
3288
+ template<class U>
3289
+ constexpr explicit(see below) optional(U&& u) noexcept(see below);
3290
+ template<class U>
3291
+ constexpr explicit(see below) optional(optional<U>& rhs) noexcept(see below);
3292
+ template<class U>
3293
+ constexpr explicit(see below) optional(const optional<U>& rhs) noexcept(see below);
3294
+ template<class U>
3295
+ constexpr explicit(see below) optional(optional<U>&& rhs) noexcept(see below);
3296
+ template<class U>
3297
+ constexpr explicit(see below) optional(const optional<U>&& rhs) noexcept(see below);
3298
+
3299
+ constexpr ~optional() = default;
3300
+
3301
+ // [optional.ref.assign], assignment
3302
+ constexpr optional& operator=(nullopt_t) noexcept;
3303
+ constexpr optional& operator=(const optional& rhs) noexcept = default;
3304
+
3305
+ template<class U> constexpr T& emplace(U&& u) noexcept(see below);
3306
+
3307
+ // [optional.ref.swap], swap
3308
+ constexpr void swap(optional& rhs) noexcept;
3309
+
3310
+ // [optional.ref.iterators], iterator support
3311
+ constexpr iterator begin() const noexcept;
3312
+ constexpr iterator end() const noexcept;
3313
+
3314
+ // [optional.ref.observe], observers
3315
+ constexpr T* operator->() const noexcept;
3316
+ constexpr T& operator*() const noexcept;
3317
+ constexpr explicit operator bool() const noexcept;
3318
+ constexpr bool has_value() const noexcept;
3319
+ constexpr T& value() const; // freestanding-deleted
3320
+ template<class U = remove_cv_t<T>>
3321
+ constexpr remove_cv_t<T> value_or(U&& u) const;
3322
+
3323
+ // [optional.ref.monadic], monadic operations
3324
+ template<class F> constexpr auto and_then(F&& f) const;
3325
+ template<class F> constexpr optional<invoke_result_t<F, T&>> transform(F&& f) const;
3326
+ template<class F> constexpr optional or_else(F&& f) const;
3327
+
3328
+ // [optional.ref.mod], modifiers
3329
+ constexpr void reset() noexcept;
3330
+
3331
+ private:
3332
+ T* val = nullptr; // exposition only
3333
+
3334
+ // [optional.ref.expos], exposition only helper functions
3335
+ template<class U>
3336
+ constexpr void convert-ref-init-val(U&& u); // exposition only
3337
+ };
3338
+ }
3339
+ ```
3340
+
3341
+ An object of type `optional<T&>` *contains a value* if and only if
3342
+ `val != nullptr` is `true`. When an `optional<T&>` contains a value, the
3343
+ *contained value* is a reference to `*val`.
3344
+
3345
+ #### Constructors <a id="optional.ref.ctor">[[optional.ref.ctor]]</a>
3346
+
3347
+ ``` cpp
3348
+ template<class Arg>
3349
+ constexpr explicit optional(in_place_t, Arg&& arg);
3350
+ ```
3351
+
3352
+ *Constraints:*
3353
+
3354
+ - `is_constructible_v<T&, Arg>` is `true`, and
3355
+ - `reference_constructs_from_temporary_v<T&, Arg>` is `false`.
3356
+
3357
+ *Effects:* Equivalent to:
3358
+ *`convert-ref-init-val`*`(std::forward<Arg>(arg))`.
3359
+
3360
+ *Ensures:* `*this` contains a value.
3361
+
3362
+ ``` cpp
3363
+ template<class U>
3364
+ constexpr explicit(!is_convertible_v<U, T&>)
3365
+ optional(U&& u) noexcept(is_nothrow_constructible_v<T&, U>);
3366
+ ```
3367
+
3368
+ *Constraints:*
3369
+
3370
+ - `is_same_v<remove_cvref_t<U>, optional>` is `false`,
3371
+ - `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`, and
3372
+ - `is_constructible_v<T&, U>` is `true`.
3373
+
3374
+ *Effects:* Equivalent to:
3375
+ *`convert-ref-init-val`*`(std::forward<U>(u))`.
3376
+
3377
+ *Ensures:* `*this` contains a value.
3378
+
3379
+ *Remarks:* This constructor is defined as deleted if
3380
+
3381
+ ``` cpp
3382
+ reference_constructs_from_temporary_v<T&, U>
3383
+ ```
3384
+
3385
+ is `true`.
3386
+
3387
+ ``` cpp
3388
+ template<class U>
3389
+ constexpr explicit(!is_convertible_v<U&, T&>)
3390
+ optional(optional<U>& rhs) noexcept(is_nothrow_constructible_v<T&, U&>);
3391
+ ```
3392
+
3393
+ *Constraints:*
3394
+
3395
+ - `is_same_v<remove_cv_t<T>, optional<U>>` is `false`,
3396
+ - `is_same_v<T&, U>` is `false`, and
3397
+ - `is_constructible_v<T&, U&>` is `true`.
3398
+
3399
+ *Effects:* Equivalent to:
3400
+
3401
+ ``` cpp
3402
+ if (rhs.has_value()) convert-ref-init-val(*rhs);
3403
+ ```
3404
+
3405
+ *Remarks:* This constructor is defined as deleted if
3406
+
3407
+ ``` cpp
3408
+ reference_constructs_from_temporary_v<T&, U&>
3409
+ ```
3410
+
3411
+ is `true`.
3412
+
3413
+ ``` cpp
3414
+ template<class U>
3415
+ constexpr explicit(!is_convertible_v<const U&, T&>)
3416
+ optional(const optional<U>& rhs) noexcept(is_nothrow_constructible_v<T&, const U&>);
3417
+ ```
3418
+
3419
+ *Constraints:*
3420
+
3421
+ - `is_same_v<remove_cv_t<T>, optional<U>>` is `false`,
3422
+ - `is_same_v<T&, U>` is `false`, and
3423
+ - `is_constructible_v<T&, const U&>` is `true`.
3424
+
3425
+ *Effects:* Equivalent to:
3426
+
3427
+ ``` cpp
3428
+ if (rhs.has_value()) convert-ref-init-val(*rhs);
3429
+ ```
3430
+
3431
+ *Remarks:* This constructor is defined as deleted if
3432
+
3433
+ ``` cpp
3434
+ reference_constructs_from_temporary_v<T&, const U&>
3435
+ ```
3436
+
3437
+ is `true`.
3438
+
3439
+ ``` cpp
3440
+ template<class U>
3441
+ constexpr explicit(!is_convertible_v<U, T&>)
3442
+ optional(optional<U>&& rhs) noexcept(is_nothrow_constructible_v<T&, U>);
3443
+ ```
3444
+
3445
+ *Constraints:*
3446
+
3447
+ - `is_same_v<remove_cv_t<T>, optional<U>>` is `false`,
3448
+ - `is_same_v<T&, U>` is `false`, and
3449
+ - `is_constructible_v<T&, U>` is `true`.
3450
+
3451
+ *Effects:* Equivalent to:
3452
+
3453
+ ``` cpp
3454
+ if (rhs.has_value()) convert-ref-init-val(*std::move(rhs));
3455
+ ```
3456
+
3457
+ *Remarks:* This constructor is defined as deleted if
3458
+
3459
+ ``` cpp
3460
+ reference_constructs_from_temporary_v<T&, U>
3461
+ ```
3462
+
3463
+ is `true`.
3464
+
3465
+ ``` cpp
3466
+ template<class U>
3467
+ constexpr explicit(!is_convertible_v<const U, T&>)
3468
+ optional(const optional<U>&& rhs) noexcept(is_nothrow_constructible_v<T&, const U>);
3469
+ ```
3470
+
3471
+ *Constraints:*
3472
+
3473
+ - `is_same_v<remove_cv_t<T>, optional<U>>` is `false`,
3474
+ - `is_same_v<T&, U>` is `false`, and
3475
+ - `is_constructible_v<T&, const U>` is `true`.
3476
+
3477
+ *Effects:* Equivalent to:
3478
+
3479
+ ``` cpp
3480
+ if (rhs.has_value()) convert-ref-init-val(*std::move(rhs));
3481
+ ```
3482
+
3483
+ *Remarks:* This constructor is defined as deleted if
3484
+
3485
+ ``` cpp
3486
+ reference_constructs_from_temporary_v<T&, const U>
3487
+ ```
3488
+
3489
+ is `true`.
3490
+
3491
+ #### Assignment <a id="optional.ref.assign">[[optional.ref.assign]]</a>
3492
+
3493
+ ``` cpp
3494
+ constexpr optional& operator=(nullopt_t) noexcept;
3495
+ ```
3496
+
3497
+ *Effects:* Assigns `nullptr` to *val*.
3498
+
3499
+ *Ensures:* `*this` does not contain a value.
3500
+
3501
+ *Returns:* `*this`.
3502
+
3503
+ ``` cpp
3504
+ template<class U>
3505
+ constexpr T& emplace(U&& u) noexcept(is_nothrow_constructible_v<T&, U>);
3506
+ ```
3507
+
3508
+ *Constraints:*
3509
+
3510
+ - `is_constructible_v<T&, U>` is `true`, and
3511
+ - `reference_constructs_from_temporary_v<T&, U>` is `false`.
3512
+
3513
+ *Effects:* Equivalent to:
3514
+ *`convert-ref-init-val`*`(std::forward<U>(u))`.
3515
+
3516
+ *Returns:* `*`*`val`*.
3517
+
3518
+ #### Swap <a id="optional.ref.swap">[[optional.ref.swap]]</a>
3519
+
3520
+ ``` cpp
3521
+ constexpr void swap(optional& rhs) noexcept;
3522
+ ```
3523
+
3524
+ *Effects:* Equivalent to: `swap(`*`val`*`, rhs.`*`val`*`)`.
3525
+
3526
+ #### Iterator support <a id="optional.ref.iterators">[[optional.ref.iterators]]</a>
3527
+
3528
+ ``` cpp
3529
+ using iterator = implementation-defined;
3530
+ ```
3531
+
3532
+ This type models `contiguous_iterator` [[iterator.concept.contiguous]],
3533
+ meets the *Cpp17RandomAccessIterator*
3534
+ requirements [[random.access.iterators]], and meets the requirements for
3535
+ constexpr iterators [[iterator.requirements.general]], with value type
3536
+ `remove_cv_t<T>`. The reference type is `T&` for `iterator`.
3537
+
3538
+ All requirements on container iterators [[container.reqmts]] apply to
3539
+ `optional::iterator`.
3540
+
3541
+ ``` cpp
3542
+ constexpr iterator begin() const noexcept;
3543
+ ```
3544
+
3545
+ *Returns:* If `has_value()` is `true`, an iterator referring to
3546
+ `*`*`val`*. Otherwise, a past-the-end iterator value.
3547
+
3548
+ ``` cpp
3549
+ constexpr iterator end() const noexcept;
3550
+ ```
3551
+
3552
+ *Returns:* `begin() + has_value()`.
3553
+
3554
+ #### Observers <a id="optional.ref.observe">[[optional.ref.observe]]</a>
3555
+
3556
+ ``` cpp
3557
+ constexpr T* operator->() const noexcept;
3558
+ ```
3559
+
3560
+ `has_value()` is `true`.
3561
+
3562
+ *Returns:* *val*.
3563
+
3564
+ ``` cpp
3565
+ constexpr T& operator*() const noexcept;
3566
+ ```
3567
+
3568
+ `has_value()` is `true`.
3569
+
3570
+ *Returns:* `*`*`val`*.
3571
+
3572
+ ``` cpp
3573
+ constexpr explicit operator bool() const noexcept;
3574
+ ```
3575
+
3576
+ *Returns:* *`val`*` != nullptr`.
3577
+
3578
+ ``` cpp
3579
+ constexpr bool has_value() const noexcept;
3580
+ ```
3581
+
3582
+ *Returns:* *`val`*` != nullptr`.
3583
+
3584
+ ``` cpp
3585
+ constexpr T& value() const;
3586
+ ```
3587
+
3588
+ *Effects:* Equivalent to:
3589
+
3590
+ ``` cpp
3591
+ return has_value() ? *val : throw bad_optional_access();
3592
+ ```
3593
+
3594
+ ``` cpp
3595
+ template<class U = remove_cv_t<T>> constexpr remove_cv_t<T> value_or(U&& u) const;
3596
+ ```
3597
+
3598
+ Let `X` be `remove_cv_t<T>`.
3599
+
3600
+ *Mandates:* `is_constructible_v<X, T&> && is_convertible_v<U, X>` is
3601
+ `true`.
3602
+
3603
+ *Effects:* Equivalent to:
3604
+
3605
+ ``` cpp
3606
+ return has_value() ? *val : static_cast<X>(std::forward<U>(u));
3607
+ ```
3608
+
3609
+ #### Monadic operations <a id="optional.ref.monadic">[[optional.ref.monadic]]</a>
3610
+
3611
+ ``` cpp
3612
+ template<class F> constexpr auto and_then(F&& f) const;
3613
+ ```
3614
+
3615
+ Let `U` be `invoke_result_t<F, T&>`.
3616
+
3617
+ *Mandates:* `remove_cvref_t<U>` is a specialization of `optional`.
3618
+
3619
+ *Effects:* Equivalent to:
3620
+
3621
+ ``` cpp
3622
+ if (has_value()) {
3623
+ return invoke(std::forward<F>(f), *val);
3624
+ } else {
3625
+ return remove_cvref_t<U>();
3626
+ }
3627
+ ```
3628
+
3629
+ ``` cpp
3630
+ template<class F>
3631
+ constexpr optional<remove_cv_t<invoke_result_t<F, T&>>> transform(F&& f) const;
3632
+ ```
3633
+
3634
+ Let `U` be `remove_cv_t<invoke_result_t<F, T&>>`.
3635
+
3636
+ *Mandates:* The declaration
3637
+
3638
+ ``` cpp
3639
+ U u(invoke(std::forward<F>(f), *val));
3640
+ ```
3641
+
3642
+ is well-formed for some invented variable `u`.
3643
+
3644
+ [*Note 1*: There is no requirement that `U` is
3645
+ movable [[dcl.init.general]]. — *end note*]
3646
+
3647
+ *Returns:* If `*this` contains a value, an `optional<U>` object whose
3648
+ contained value is direct-non-list-initialized with
3649
+ `invoke(std::forward<F>(f), *`*`val`*`)`; otherwise, `optional<U>()`.
3650
+
3651
+ ``` cpp
3652
+ template<class F> constexpr optional or_else(F&& f) const;
3653
+ ```
3654
+
3655
+ *Constraints:* `F` models `invocable`.
3656
+
3657
+ *Mandates:* `is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>` is
3658
+ `true`.
3659
+
3660
+ *Effects:* Equivalent to:
3661
+
3662
+ ``` cpp
3663
+ if (has_value()) {
3664
+ return *val;
3665
+ } else {
3666
+ return std::forward<F>(f)();
3667
+ }
3668
+ ```
3669
+
3670
+ #### Modifiers <a id="optional.ref.mod">[[optional.ref.mod]]</a>
3671
+
3672
+ ``` cpp
3673
+ constexpr void reset() noexcept;
3674
+ ```
3675
+
3676
+ *Effects:* Assigns `nullptr` to *val*.
3677
+
3678
+ *Ensures:* `*this` does not contain a value.
3679
+
3680
+ #### Exposition only helper functions <a id="optional.ref.expos">[[optional.ref.expos]]</a>
3681
+
3682
+ ``` cpp
3683
+ template<class U>
3684
+ constexpr void convert-ref-init-val(U&& u); // exposition only
3685
+ ```
3686
+
3687
+ *Effects:* Creates a variable `r` as if by `T& r(std::forward<U>(u));`
3688
+ and then initializes *val* with `addressof(r)`.
3689
+
3690
  ### No-value state indicator <a id="optional.nullopt">[[optional.nullopt]]</a>
3691
 
3692
  ``` cpp
3693
  struct nullopt_t{see below};
3694
  inline constexpr nullopt_t nullopt(unspecified);
 
3708
  ``` cpp
3709
  namespace std {
3710
  class bad_optional_access : public exception {
3711
  public:
3712
  // see [exception] for the specification of the special member functions
3713
+ constexpr const char* what() const noexcept override;
3714
  };
3715
  }
3716
  ```
3717
 
3718
  The class `bad_optional_access` defines the type of objects thrown as
3719
  exceptions to report the situation where an attempt is made to access
3720
  the value of an optional object that does not contain a value.
3721
 
3722
  ``` cpp
3723
+ constexpr const char* what() const noexcept override;
3724
  ```
3725
 
3726
+ *Returns:* An *implementation-defined* NTBS, which during constant
3727
+ evaluation is encoded with the ordinary literal encoding [[lex.ccon]].
3728
 
3729
  ### Relational operators <a id="optional.relops">[[optional.relops]]</a>
3730
 
3731
  ``` cpp
3732
  template<class T, class U> constexpr bool operator==(const optional<T>& x, const optional<U>& y);
3733
  ```
3734
 
3735
+ *Constraints:* The expression `*x == *y` is well-formed and its result
3736
+ is convertible to `bool`.
3737
 
3738
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
3739
 
3740
  *Returns:* If `x.has_value() != y.has_value()`, `false`; otherwise if
3741
  `x.has_value() == false`, `true`; otherwise `*x == *y`.
 
3745
 
3746
  ``` cpp
3747
  template<class T, class U> constexpr bool operator!=(const optional<T>& x, const optional<U>& y);
3748
  ```
3749
 
3750
+ *Constraints:* The expression `*x != *y` is well-formed and its result
3751
+ is convertible to `bool`.
3752
 
3753
  *Returns:* If `x.has_value() != y.has_value()`, `true`; otherwise, if
3754
  `x.has_value() == false`, `false`; otherwise `*x != *y`.
3755
 
3756
  *Remarks:* Specializations of this function template for which
 
3758
 
3759
  ``` cpp
3760
  template<class T, class U> constexpr bool operator<(const optional<T>& x, const optional<U>& y);
3761
  ```
3762
 
3763
+ *Constraints:* `*x < *y` is well-formed and its result is convertible to
3764
  `bool`.
3765
 
3766
  *Returns:* If `!y`, `false`; otherwise, if `!x`, `true`; otherwise
3767
  `*x < *y`.
3768
 
 
3771
 
3772
  ``` cpp
3773
  template<class T, class U> constexpr bool operator>(const optional<T>& x, const optional<U>& y);
3774
  ```
3775
 
3776
+ *Constraints:* The expression `*x > *y` is well-formed and its result is
3777
  convertible to `bool`.
3778
 
3779
  *Returns:* If `!x`, `false`; otherwise, if `!y`, `true`; otherwise
3780
  `*x > *y`.
3781
 
 
3784
 
3785
  ``` cpp
3786
  template<class T, class U> constexpr bool operator<=(const optional<T>& x, const optional<U>& y);
3787
  ```
3788
 
3789
+ *Constraints:* The expression `*x <= *y` is well-formed and its result
3790
+ is convertible to `bool`.
3791
 
3792
  *Returns:* If `!x`, `true`; otherwise, if `!y`, `false`; otherwise
3793
  `*x <= *y`.
3794
 
3795
  *Remarks:* Specializations of this function template for which
 
3797
 
3798
  ``` cpp
3799
  template<class T, class U> constexpr bool operator>=(const optional<T>& x, const optional<U>& y);
3800
  ```
3801
 
3802
+ *Constraints:* The expression `*x >= *y` is well-formed and its result
3803
+ is convertible to `bool`.
3804
 
3805
  *Returns:* If `!y`, `true`; otherwise, if `!x`, `false`; otherwise
3806
  `*x >= *y`.
3807
 
3808
  *Remarks:* Specializations of this function template for which
 
3838
 
3839
  ``` cpp
3840
  template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
3841
  ```
3842
 
3843
+ *Constraints:* `U` is not a specialization of `optional`. The expression
3844
+ `*x == v` is well-formed and its result is convertible to `bool`.
3845
 
3846
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
3847
 
3848
  *Effects:* Equivalent to: `return x.has_value() ? *x == v : false;`
3849
 
3850
  ``` cpp
3851
  template<class T, class U> constexpr bool operator==(const T& v, const optional<U>& x);
3852
  ```
3853
 
3854
+ *Constraints:* `T` is not a specialization of `optional`. The expression
3855
+ `v == *x` is well-formed and its result is convertible to `bool`.
3856
 
3857
  *Effects:* Equivalent to: `return x.has_value() ? v == *x : false;`
3858
 
3859
  ``` cpp
3860
  template<class T, class U> constexpr bool operator!=(const optional<T>& x, const U& v);
3861
  ```
3862
 
3863
+ *Constraints:* `U` is not a specialization of `optional`. The expression
3864
+ `*x != v` is well-formed and its result is convertible to `bool`.
3865
 
3866
  *Effects:* Equivalent to: `return x.has_value() ? *x != v : true;`
3867
 
3868
  ``` cpp
3869
  template<class T, class U> constexpr bool operator!=(const T& v, const optional<U>& x);
3870
  ```
3871
 
3872
+ *Constraints:* `T` is not a specialization of `optional`. The expression
3873
+ `v != *x` is well-formed and its result is convertible to `bool`.
3874
 
3875
  *Effects:* Equivalent to: `return x.has_value() ? v != *x : true;`
3876
 
3877
  ``` cpp
3878
  template<class T, class U> constexpr bool operator<(const optional<T>& x, const U& v);
3879
  ```
3880
 
3881
+ *Constraints:* `U` is not a specialization of `optional`. The expression
3882
+ `*x < v` is well-formed and its result is convertible to `bool`.
3883
 
3884
  *Effects:* Equivalent to: `return x.has_value() ? *x < v : true;`
3885
 
3886
  ``` cpp
3887
  template<class T, class U> constexpr bool operator<(const T& v, const optional<U>& x);
3888
  ```
3889
 
3890
+ *Constraints:* `T` is not a specialization of `optional`. The expression
3891
+ `v < *x` is well-formed and its result is convertible to `bool`.
3892
 
3893
  *Effects:* Equivalent to: `return x.has_value() ? v < *x : false;`
3894
 
3895
  ``` cpp
3896
  template<class T, class U> constexpr bool operator>(const optional<T>& x, const U& v);
3897
  ```
3898
 
3899
+ *Constraints:* `U` is not a specialization of `optional`. The expression
3900
+ `*x > v` is well-formed and its result is convertible to `bool`.
3901
 
3902
  *Effects:* Equivalent to: `return x.has_value() ? *x > v : false;`
3903
 
3904
  ``` cpp
3905
  template<class T, class U> constexpr bool operator>(const T& v, const optional<U>& x);
3906
  ```
3907
 
3908
+ *Constraints:* `T` is not a specialization of `optional`. The expression
3909
+ `v > *x` is well-formed and its result is convertible to `bool`.
3910
 
3911
  *Effects:* Equivalent to: `return x.has_value() ? v > *x : true;`
3912
 
3913
  ``` cpp
3914
  template<class T, class U> constexpr bool operator<=(const optional<T>& x, const U& v);
3915
  ```
3916
 
3917
+ *Constraints:* `U` is not a specialization of `optional`. The expression
3918
+ `*x <= v` is well-formed and its result is convertible to `bool`.
3919
 
3920
  *Effects:* Equivalent to: `return x.has_value() ? *x <= v : true;`
3921
 
3922
  ``` cpp
3923
  template<class T, class U> constexpr bool operator<=(const T& v, const optional<U>& x);
3924
  ```
3925
 
3926
+ *Constraints:* `T` is not a specialization of `optional`. The expression
3927
+ `v <= *x` is well-formed and its result is convertible to `bool`.
3928
 
3929
  *Effects:* Equivalent to: `return x.has_value() ? v <= *x : false;`
3930
 
3931
  ``` cpp
3932
  template<class T, class U> constexpr bool operator>=(const optional<T>& x, const U& v);
3933
  ```
3934
 
3935
+ *Constraints:* `U` is not a specialization of `optional`. The expression
3936
+ `*x >= v` is well-formed and its result is convertible to `bool`.
3937
 
3938
  *Effects:* Equivalent to: `return x.has_value() ? *x >= v : false;`
3939
 
3940
  ``` cpp
3941
  template<class T, class U> constexpr bool operator>=(const T& v, const optional<U>& x);
3942
  ```
3943
 
3944
+ *Constraints:* `T` is not a specialization of `optional`. The expression
3945
+ `v >= *x` is well-formed and its result is convertible to `bool`.
3946
 
3947
  *Effects:* Equivalent to: `return x.has_value() ? v >= *x : true;`
3948
 
3949
  ``` cpp
3950
  template<class T, class U>
 
3961
  ``` cpp
3962
  template<class T>
3963
  constexpr void swap(optional<T>& x, optional<T>& y) noexcept(noexcept(x.swap(y)));
3964
  ```
3965
 
3966
+ *Constraints:*
3967
+
3968
+ ``` cpp
3969
+ is_reference_v<T> || (is_move_constructible_v<T> && is_swappable_v<T>)
3970
+ ```
3971
+
3972
+ is `true`.
3973
 
3974
  *Effects:* Calls `x.swap(y)`.
3975
 
3976
  ``` cpp
3977
  template<class T> constexpr optional<decay_t<T>> make_optional(T&& v);
3978
  ```
3979
 
3980
+ *Constraints:* The call to `make_optional` does not use an explicit
3981
+ *template-argument-list* that begins with a type *template-argument*.
3982
+
3983
  *Returns:* `optional<decay_t<T>>(std::forward<T>(v))`.
3984
 
3985
  ``` cpp
3986
  template<class T, class...Args>
3987
  constexpr optional<T> make_optional(Args&&... args);
 
4012
  unspecified value. The member functions are not guaranteed to be
4013
  `noexcept`.
4014
 
4015
  ## Variants <a id="variant">[[variant]]</a>
4016
 
4017
+ ### General <a id="variant.general">[[variant.general]]</a>
4018
 
4019
  A variant object holds and manages the lifetime of a value. If the
4020
  `variant` holds a value, that value’s type has to be one of the template
4021
  argument types given to `variant`. These template arguments are called
4022
  alternatives.
4023
 
4024
+ In [[variant]], *`GET`* denotes a set of exposition-only function
4025
+ templates [[variant.get]].
4026
+
4027
  ### Header `<variant>` synopsis <a id="variant.syn">[[variant.syn]]</a>
4028
 
4029
  ``` cpp
4030
+ // mostly freestanding
4031
  #include <compare> // see [compare.syn]
4032
 
4033
  namespace std {
4034
  // [variant.variant], class template variant
4035
  template<class... Types>
 
4045
  struct variant_size<variant<Types...>>;
4046
 
4047
  template<size_t I, class T> struct variant_alternative; // not defined
4048
  template<size_t I, class T> struct variant_alternative<I, const T>;
4049
  template<size_t I, class T>
4050
+ using variant_alternative_t = variant_alternative<I, T>::type;
4051
 
4052
  template<size_t I, class... Types>
4053
  struct variant_alternative<I, variant<Types...>>;
4054
 
4055
  inline constexpr size_t variant_npos = -1;
 
4057
  // [variant.get], value access
4058
  template<class T, class... Types>
4059
  constexpr bool holds_alternative(const variant<Types...>&) noexcept;
4060
 
4061
  template<size_t I, class... Types>
4062
+ constexpr variant_alternative_t<I, variant<Types...>>&
4063
+ get(variant<Types...>&); // freestanding-deleted
4064
  template<size_t I, class... Types>
4065
+ constexpr variant_alternative_t<I, variant<Types...>>&&
4066
+ get(variant<Types...>&&); // freestanding-deleted
4067
  template<size_t I, class... Types>
4068
+ constexpr const variant_alternative_t<I, variant<Types...>>&
4069
+ get(const variant<Types...>&); // freestanding-deleted
4070
  template<size_t I, class... Types>
4071
+ constexpr const variant_alternative_t<I, variant<Types...>>&&
4072
+ get(const variant<Types...>&&); // freestanding-deleted
4073
 
4074
  template<class T, class... Types>
4075
+ constexpr T& get(variant<Types...>&); // freestanding-deleted
4076
  template<class T, class... Types>
4077
+ constexpr T&& get(variant<Types...>&&); // freestanding-deleted
4078
  template<class T, class... Types>
4079
+ constexpr const T& get(const variant<Types...>&); // freestanding-deleted
4080
  template<class T, class... Types>
4081
+ constexpr const T&& get(const variant<Types...>&&); // freestanding-deleted
4082
 
4083
  template<size_t I, class... Types>
4084
  constexpr add_pointer_t<variant_alternative_t<I, variant<Types...>>>
4085
  get_if(variant<Types...>*) noexcept;
4086
  template<size_t I, class... Types>
 
4189
  constexpr bool valueless_by_exception() const noexcept;
4190
  constexpr size_t index() const noexcept;
4191
 
4192
  // [variant.swap], swap
4193
  constexpr void swap(variant&) noexcept(see below);
4194
+
4195
+ // [variant.visit], visitation
4196
+ template<class Self, class Visitor>
4197
+ constexpr decltype(auto) visit(this Self&&, Visitor&&);
4198
+ template<class R, class Self, class Visitor>
4199
+ constexpr R visit(this Self&&, Visitor&&);
4200
  };
4201
  }
4202
  ```
4203
 
4204
  Any instance of `variant` at any given time either holds a value of one
4205
  of its alternative types or holds no value. When an instance of
4206
  `variant` holds a value of alternative type `T`, it means that a value
4207
  of type `T`, referred to as the `variant` object’s *contained value*, is
4208
+ nested within [[intro.object]] the `variant` object.
 
 
4209
 
4210
  All types in `Types` shall meet the *Cpp17Destructible* requirements (
4211
  [[cpp17.destructible]]).
4212
 
4213
  A program that instantiates the definition of `variant` with no template
4214
  arguments is ill-formed.
4215
 
4216
+ If a program declares an explicit or partial specialization of
4217
+ `variant`, the program is ill-formed, no diagnostic required.
4218
+
4219
  #### Constructors <a id="variant.ctor">[[variant.ctor]]</a>
4220
 
4221
  In the descriptions that follow, let i be in the range \[`0`,
4222
  `sizeof...(Types)`), and `Tᵢ` be the iᵗʰ type in `Types`.
4223
 
 
4245
  constexpr variant(const variant& w);
4246
  ```
4247
 
4248
  *Effects:* If `w` holds a value, initializes the `variant` to hold the
4249
  same alternative as `w` and direct-initializes the contained value with
4250
+ *`GET`*`<j>(w)`, where `j` is `w.index()`. Otherwise, initializes the
4251
  `variant` to not hold a value.
4252
 
4253
  *Throws:* Any exception thrown by direct-initializing any `Tᵢ` for all
4254
  i.
4255
 
 
4264
 
4265
  *Constraints:* `is_move_constructible_v<``Tᵢ``>` is `true` for all i.
4266
 
4267
  *Effects:* If `w` holds a value, initializes the `variant` to hold the
4268
  same alternative as `w` and direct-initializes the contained value with
4269
+ *`GET`*`<j>(std::move(w))`, where `j` is `w.index()`. Otherwise,
4270
+ initializes the `variant` to not hold a value.
4271
 
4272
  *Throws:* Any exception thrown by move-constructing any `Tᵢ` for all i.
4273
 
4274
  *Remarks:* The exception specification is equivalent to the logical of
4275
  `is_nothrow_move_constructible_v<``Tᵢ``>` for all i. If
 
4423
  value contained in `*this` and sets `*this` to not hold a value.
4424
  - Otherwise, if `index() == `j, assigns the value contained in `rhs` to
4425
  the value contained in `*this`.
4426
  - Otherwise, if either `is_nothrow_copy_constructible_v<``Tⱼ``>` is
4427
  `true` or `is_nothrow_move_constructible_v<``Tⱼ``>` is `false`,
4428
+ equivalent to `emplace<`j`>(`*`GET`*`<`j`>(rhs))`.
4429
  - Otherwise, equivalent to `operator=(variant(rhs))`.
4430
 
4431
  *Ensures:* `index() == rhs.index()`.
4432
 
4433
  *Returns:* `*this`.
 
4451
  *Effects:*
4452
 
4453
  - If neither `*this` nor `rhs` holds a value, there is no effect.
4454
  - Otherwise, if `*this` holds a value but `rhs` does not, destroys the
4455
  value contained in `*this` and sets `*this` to not hold a value.
4456
+ - Otherwise, if `index() == `j, assigns *`GET`*`<`j`>(std::move(rhs))`
4457
+ to the value contained in `*this`.
4458
+ - Otherwise, equivalent to
4459
+ `emplace<`j`>(`*`GET`*`<`j`>(std::move(rhs)))`.
4460
 
4461
  *Returns:* `*this`.
4462
 
4463
  *Remarks:* If `is_trivially_move_constructible_v<``Tᵢ``> &&`
4464
  `is_trivially_move_assignable_v<``Tᵢ``> &&`
 
4656
  *Effects:*
4657
 
4658
  - If `valueless_by_exception() && rhs.valueless_by_exception()` no
4659
  effect.
4660
  - Otherwise, if `index() == rhs.index()`, calls
4661
+ `swap(`*`GET`*`<`i`>(*this), `*`GET`*`<`i`>(rhs))` where i is
4662
+ `index()`.
4663
  - Otherwise, exchanges values of `rhs` and `*this`.
4664
 
4665
  *Throws:* If `index() == rhs.index()`, any exception thrown by
4666
+ `swap(`*`GET`*`<`i`>(*this), `*`GET`*`<`i`>(rhs))` with i being
4667
+ `index()`. Otherwise, any exception thrown by the move constructor of
4668
+ `Tᵢ` or `Tⱼ` with i being `index()` and j being `rhs.index()`.
4669
 
4670
  *Remarks:* If an exception is thrown during the call to function
4671
+ `swap(`*`GET`*`<`i`>(*this), `*`GET`*`<`i`>(rhs))`, the states of the
4672
+ contained values of `*this` and of `rhs` are determined by the exception
4673
+ safety guarantee of `swap` for lvalues of `Tᵢ` with i being `index()`.
4674
+ If an exception is thrown during the exchange of the values of `*this`
4675
+ and `rhs`, the states of the values of `*this` and of `rhs` are
4676
+ determined by the exception safety guarantee of `variant`’s move
4677
+ constructor. The exception specification is equivalent to the logical of
4678
  `is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_swappable_v<``Tᵢ``>`
4679
  for all i.
4680
 
4681
  ### `variant` helper classes <a id="variant.helper">[[variant.helper]]</a>
4682
 
 
4707
  ```
4708
 
4709
  Let `VA` denote `variant_alternative<I, T>` of the cv-unqualified type
4710
  `T`. Then each specialization of the template meets the
4711
  *Cpp17TransformationTrait* requirements [[meta.rqmts]] with a member
4712
+ typedef `type` that names the type `const VA::type`.
4713
 
4714
  ``` cpp
4715
  variant_alternative<I, variant<Types...>>::type
4716
  ```
4717
 
4718
  *Mandates:* `I` < `sizeof...(Types)`.
4719
 
4720
+ *Result:* The type `T_I`.
4721
 
4722
  ### Value access <a id="variant.get">[[variant.get]]</a>
4723
 
4724
  ``` cpp
4725
  template<class T, class... Types>
 
4729
  *Mandates:* The type `T` occurs exactly once in `Types`.
4730
 
4731
  *Returns:* `true` if `index()` is equal to the zero-based index of `T`
4732
  in `Types`.
4733
 
4734
+ ``` cpp
4735
+ template<size_t I, class... Types>
4736
+ constexpr variant_alternative_t<I, variant<Types...>>&
4737
+ GET(variant<Types...>& v); // exposition only
4738
+ template<size_t I, class... Types>
4739
+ constexpr variant_alternative_t<I, variant<Types...>>&&
4740
+ GET(variant<Types...>&& v); // exposition only
4741
+ template<size_t I, class... Types>
4742
+ constexpr const variant_alternative_t<I, variant<Types...>>&
4743
+ GET(const variant<Types...>& v); // exposition only
4744
+ template<size_t I, class... Types>
4745
+ constexpr const variant_alternative_t<I, variant<Types...>>&&
4746
+ GET(const variant<Types...>&& v); // exposition only
4747
+ ```
4748
+
4749
+ *Mandates:* `I` < `sizeof...(Types)`.
4750
+
4751
+ *Preconditions:* `v.index()` is `I`.
4752
+
4753
+ *Returns:* A reference to the object stored in the `variant`.
4754
+
4755
  ``` cpp
4756
  template<size_t I, class... Types>
4757
  constexpr variant_alternative_t<I, variant<Types...>>& get(variant<Types...>& v);
4758
  template<size_t I, class... Types>
4759
  constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&& v);
 
4814
  ``` cpp
4815
  template<class... Types>
4816
  constexpr bool operator==(const variant<Types...>& v, const variant<Types...>& w);
4817
  ```
4818
 
4819
+ *Constraints:* *`GET`*`<`i`>(v) == `*`GET`*`<`i`>(w)` is a valid
4820
+ expression that is convertible to `bool`, for all i.
4821
 
4822
  *Returns:* If `v.index() != w.index()`, `false`; otherwise if
4823
  `v.valueless_by_exception()`, `true`; otherwise
4824
+ *`GET`*`<`i`>(v) == `*`GET`*`<`i`>(w)` with i being `v.index()`.
4825
 
4826
  ``` cpp
4827
  template<class... Types>
4828
  constexpr bool operator!=(const variant<Types...>& v, const variant<Types...>& w);
4829
  ```
4830
 
4831
+ *Constraints:* *`GET`*`<`i`>(v) != `*`GET`*`<`i`>(w)` is a valid
4832
+ expression that is convertible to `bool`, for all i.
4833
 
4834
  *Returns:* If `v.index() != w.index()`, `true`; otherwise if
4835
  `v.valueless_by_exception()`, `false`; otherwise
4836
+ *`GET`*`<`i`>(v) != `*`GET`*`<`i`>(w)` with i being `v.index()`.
4837
 
4838
  ``` cpp
4839
  template<class... Types>
4840
  constexpr bool operator<(const variant<Types...>& v, const variant<Types...>& w);
4841
  ```
4842
 
4843
+ *Constraints:* *`GET`*`<`i`>(v) < `*`GET`*`<`i`>(w)` is a valid
4844
+ expression that is convertible to `bool`, for all i.
4845
 
4846
  *Returns:* If `w.valueless_by_exception()`, `false`; otherwise if
4847
  `v.valueless_by_exception()`, `true`; otherwise, if
4848
  `v.index() < w.index()`, `true`; otherwise if `v.index() > w.index()`,
4849
+ `false`; otherwise *`GET`*`<`i`>(v) < `*`GET`*`<`i`>(w)` with i being
4850
+ `v.index()`.
4851
 
4852
  ``` cpp
4853
  template<class... Types>
4854
  constexpr bool operator>(const variant<Types...>& v, const variant<Types...>& w);
4855
  ```
4856
 
4857
+ *Constraints:* *`GET`*`<`i`>(v) > `*`GET`*`<`i`>(w)` is a valid
4858
+ expression that is convertible to `bool`, for all i.
4859
 
4860
  *Returns:* If `v.valueless_by_exception()`, `false`; otherwise if
4861
  `w.valueless_by_exception()`, `true`; otherwise, if
4862
  `v.index() > w.index()`, `true`; otherwise if `v.index() < w.index()`,
4863
+ `false`; otherwise *`GET`*`<`i`>(v) > `*`GET`*`<`i`>(w)` with i being
4864
+ `v.index()`.
4865
 
4866
  ``` cpp
4867
  template<class... Types>
4868
  constexpr bool operator<=(const variant<Types...>& v, const variant<Types...>& w);
4869
  ```
4870
 
4871
+ *Constraints:* *`GET`*`<`i`>(v) <= `*`GET`*`<`i`>(w)` is a valid
4872
+ expression that is convertible to `bool`, for all i.
4873
 
4874
  *Returns:* If `v.valueless_by_exception()`, `true`; otherwise if
4875
  `w.valueless_by_exception()`, `false`; otherwise, if
4876
  `v.index() < w.index()`, `true`; otherwise if `v.index() > w.index()`,
4877
+ `false`; otherwise *`GET`*`<`i`>(v) <= `*`GET`*`<`i`>(w)` with i being
4878
  `v.index()`.
4879
 
4880
  ``` cpp
4881
  template<class... Types>
4882
  constexpr bool operator>=(const variant<Types...>& v, const variant<Types...>& w);
4883
  ```
4884
 
4885
+ *Constraints:* *`GET`*`<`i`>(v) >= `*`GET`*`<`i`>(w)` is a valid
4886
+ expression that is convertible to `bool`, for all i.
4887
 
4888
  *Returns:* If `w.valueless_by_exception()`, `true`; otherwise if
4889
  `v.valueless_by_exception()`, `false`; otherwise, if
4890
  `v.index() > w.index()`, `true`; otherwise if `v.index() < w.index()`,
4891
+ `false`; otherwise *`GET`*`<`i`>(v) >= `*`GET`*`<`i`>(w)` with i being
4892
  `v.index()`.
4893
 
4894
  ``` cpp
4895
  template<class... Types> requires (three_way_comparable<Types> && ...)
4896
  constexpr common_comparison_category_t<compare_three_way_result_t<Types>...>
 
4903
  if (v.valueless_by_exception() && w.valueless_by_exception())
4904
  return strong_ordering::equal;
4905
  if (v.valueless_by_exception()) return strong_ordering::less;
4906
  if (w.valueless_by_exception()) return strong_ordering::greater;
4907
  if (auto c = v.index() <=> w.index(); c != 0) return c;
4908
+ return GET<i>(v) <=> GET<i>(w);
4909
  ```
4910
 
4911
  with i being `v.index()`.
4912
 
4913
  ### Visitation <a id="variant.visit">[[variant.visit]]</a>
 
4922
  Let *as-variant* denote the following exposition-only function
4923
  templates:
4924
 
4925
  ``` cpp
4926
  template<class... Ts>
4927
+ constexpr auto&& as-variant(variant<Ts...>& var) { return var; }
4928
  template<class... Ts>
4929
+ constexpr auto&& as-variant(const variant<Ts...>& var) { return var; }
4930
  template<class... Ts>
4931
+ constexpr auto&& as-variant(variant<Ts...>&& var) { return std::move(var); }
4932
  template<class... Ts>
4933
+ constexpr auto&& as-variant(const variant<Ts...>&& var) { return std::move(var); }
4934
  ```
4935
 
4936
  Let n be `sizeof...(Variants)`. For each 0 ≤ i < n, let `Vᵢ` denote the
4937
  type
4938
  `decltype(`*`as-variant`*`(``std::forward<``Variantsᵢ``>(``varsᵢ``)``))`.
 
4944
  Let m be a pack of n values of type `size_t`. Such a pack is valid if
4945
  0 ≤ mᵢ < `variant_size_v<remove_reference_t<Vᵢ``>>` for all 0 ≤ i < n.
4946
  For each valid pack m, let e(m) denote the expression:
4947
 
4948
  ``` cpp
4949
+ INVOKE(std::forward<Visitor>(vis), GET<m>(std::forward<V>(vars))...) // see [func.require]
4950
  ```
4951
 
4952
  for the first form and
4953
 
4954
  ``` cpp
4955
+ INVOKE<R>(std::forward<Visitor>(vis), GET<m>(std::forward<V>(vars))...) // see [func.require]
4956
  ```
4957
 
4958
  for the second form.
4959
 
4960
  *Mandates:* For each valid pack m, e(m) is a valid expression. All such
 
4970
  *Complexity:* For n ≤ 1, the invocation of the callable object is
4971
  implemented in constant time, i.e., for n = 1, it does not depend on the
4972
  number of alternative types of `V₀`. For n > 1, the invocation of the
4973
  callable object has no complexity requirements.
4974
 
4975
+ ``` cpp
4976
+ template<class Self, class Visitor>
4977
+ constexpr decltype(auto) visit(this Self&& self, Visitor&& vis);
4978
+ ```
4979
+
4980
+ Let `V` be
4981
+ *`OVERRIDE_REF`*`(Self&&, `*`COPY_CONST`*`(remove_reference_t<Self>, variant))`
4982
+ [[forward]].
4983
+
4984
+ *Constraints:* The call to `visit` does not use an explicit
4985
+ *template-argument-list* that begins with a type *template-argument*.
4986
+
4987
+ *Effects:* Equivalent to:
4988
+ `return std::visit(std::forward<Visitor>(vis), (V)self);`
4989
+
4990
+ ``` cpp
4991
+ template<class R, class Self, class Visitor>
4992
+ constexpr R visit(this Self&& self, Visitor&& vis);
4993
+ ```
4994
+
4995
+ Let `V` be
4996
+ *`OVERRIDE_REF`*`(Self&&, `*`COPY_CONST`*`(remove_reference_t<Self>, variant))`
4997
+ [[forward]].
4998
+
4999
+ *Effects:* Equivalent to:
5000
+ `return std::visit<R>(std::forward<Visitor>(vis), (V)self);`
5001
+
5002
  ### Class `monostate` <a id="variant.monostate">[[variant.monostate]]</a>
5003
 
5004
  ``` cpp
5005
  struct monostate{};
5006
  ```
 
5040
  ``` cpp
5041
  namespace std {
5042
  class bad_variant_access : public exception {
5043
  public:
5044
  // see [exception] for the specification of the special member functions
5045
+ constexpr const char* what() const noexcept override;
5046
  };
5047
  }
5048
  ```
5049
 
5050
  Objects of type `bad_variant_access` are thrown to report invalid
5051
  accesses to the value of a `variant` object.
5052
 
5053
  ``` cpp
5054
+ constexpr const char* what() const noexcept override;
5055
  ```
5056
 
5057
+ *Returns:* An *implementation-defined* NTBS, which during constant
5058
+ evaluation is encoded with the ordinary literal encoding [[lex.ccon]].
5059
 
5060
  ### Hash support <a id="variant.hash">[[variant.hash]]</a>
5061
 
5062
  ``` cpp
5063
  template<class... Types> struct hash<variant<Types...>>;
 
5505
  const T* any_cast(const any* operand) noexcept;
5506
  template<class T>
5507
  T* any_cast(any* operand) noexcept;
5508
  ```
5509
 
5510
+ *Mandates:* `is_void_v<T>` is `false`.
5511
+
5512
+ *Returns:* If `operand != nullptr && operand->type() == typeid(T)` is
5513
+ `true`, a pointer to the object contained by `operand`; otherwise,
5514
+ `nullptr`.
5515
 
5516
  [*Example 2*:
5517
 
5518
  ``` cpp
5519
  bool is_string(const any& operand) {
 
5523
 
5524
  — *end example*]
5525
 
5526
  ## Expected objects <a id="expected">[[expected]]</a>
5527
 
5528
+ ### General <a id="expected.general">[[expected.general]]</a>
5529
 
5530
  Subclause [[expected]] describes the class template `expected` that
5531
  represents expected objects. An `expected<T, E>` object holds an object
5532
+ of type `T` or an object of type `E` and manages the lifetime of the
5533
+ contained objects.
5534
 
5535
  ### Header `<expected>` synopsis <a id="expected.syn">[[expected.syn]]</a>
5536
 
5537
  ``` cpp
5538
+ // mostly freestanding
5539
  namespace std {
5540
  // [expected.unexpected], class template unexpected
5541
  template<class E> class unexpected;
5542
 
5543
  // [expected.bad], class template bad_expected_access
 
5551
  explicit unexpect_t() = default;
5552
  };
5553
  inline constexpr unexpect_t unexpect{};
5554
 
5555
  // [expected.expected], class template expected
5556
+ template<class T, class E> class expected; // partially freestanding
5557
 
5558
  // [expected.void], partial specialization of expected for void types
5559
+ template<class T, class E> requires is_void_v<T> class expected<T, E>; // partially freestanding
5560
  }
5561
  ```
5562
 
5563
  ### Class template `unexpected` <a id="expected.unexpected">[[expected.unexpected]]</a>
5564
 
 
5705
  ``` cpp
5706
  namespace std {
5707
  template<class E>
5708
  class bad_expected_access : public bad_expected_access<void> {
5709
  public:
5710
+ constexpr explicit bad_expected_access(E);
5711
+ constexpr const char* what() const noexcept override;
5712
+ constexpr E& error() & noexcept;
5713
+ constexpr const E& error() const & noexcept;
5714
+ constexpr E&& error() && noexcept;
5715
+ constexpr const E&& error() const && noexcept;
5716
 
5717
  private:
5718
  E unex; // exposition only
5719
  };
5720
  }
 
5724
  thrown as exceptions to report the situation where an attempt is made to
5725
  access the value of an `expected<T, E>` object for which `has_value()`
5726
  is `false`.
5727
 
5728
  ``` cpp
5729
+ constexpr explicit bad_expected_access(E e);
5730
  ```
5731
 
5732
  *Effects:* Initializes *unex* with `std::move(e)`.
5733
 
5734
  ``` cpp
5735
+ constexpr const E& error() const & noexcept;
5736
+ constexpr E& error() & noexcept;
5737
  ```
5738
 
5739
  *Returns:* *unex*.
5740
 
5741
  ``` cpp
5742
+ constexpr E&& error() && noexcept;
5743
+ constexpr const E&& error() const && noexcept;
5744
  ```
5745
 
5746
  *Returns:* `std::move(`*`unex`*`)`.
5747
 
5748
  ``` cpp
5749
+ constexpr const char* what() const noexcept override;
5750
  ```
5751
 
5752
+ *Returns:* An *implementation-defined* NTBS, which during constant
5753
+ evaluation is encoded with the ordinary literal encoding [[lex.ccon]].
5754
 
5755
  ### Class template specialization `bad_expected_access<void>` <a id="expected.bad.void">[[expected.bad.void]]</a>
5756
 
5757
  ``` cpp
5758
  namespace std {
5759
  template<>
5760
  class bad_expected_access<void> : public exception {
5761
  protected:
5762
+ constexpr bad_expected_access() noexcept;
5763
+ constexpr bad_expected_access(const bad_expected_access&) noexcept;
5764
+ constexpr bad_expected_access(bad_expected_access&&) noexcept;
5765
+ constexpr bad_expected_access& operator=(const bad_expected_access&) noexcept;
5766
+ constexpr bad_expected_access& operator=(bad_expected_access&&) noexcept;
5767
+ constexpr ~bad_expected_access();
5768
 
5769
  public:
5770
+ constexpr const char* what() const noexcept override;
5771
  };
5772
  }
5773
  ```
5774
 
5775
  ``` cpp
5776
+ constexpr const char* what() const noexcept override;
5777
  ```
5778
 
5779
+ *Returns:* An *implementation-defined* NTBS, which during constant
5780
+ evaluation is encoded with the ordinary literal encoding [[lex.ccon]].
5781
 
5782
  ### Class template `expected` <a id="expected.expected">[[expected.expected]]</a>
5783
 
5784
  #### General <a id="expected.object.general">[[expected.object.general]]</a>
5785
 
 
5802
  template<class U, class G>
5803
  constexpr explicit(see below) expected(const expected<U, G>&);
5804
  template<class U, class G>
5805
  constexpr explicit(see below) expected(expected<U, G>&&);
5806
 
5807
+ template<class U = remove_cv_t<T>>
5808
  constexpr explicit(see below) expected(U&& v);
5809
 
5810
  template<class G>
5811
  constexpr explicit(see below) expected(const unexpected<G>&);
5812
  template<class G>
 
5825
  constexpr ~expected();
5826
 
5827
  // [expected.object.assign], assignment
5828
  constexpr expected& operator=(const expected&);
5829
  constexpr expected& operator=(expected&&) noexcept(see below);
5830
+ template<class U = remove_cv_t<T>> constexpr expected& operator=(U&&);
5831
  template<class G>
5832
  constexpr expected& operator=(const unexpected<G>&);
5833
  template<class G>
5834
  constexpr expected& operator=(unexpected<G>&&);
5835
 
 
5849
  constexpr T& operator*() & noexcept;
5850
  constexpr const T&& operator*() const && noexcept;
5851
  constexpr T&& operator*() && noexcept;
5852
  constexpr explicit operator bool() const noexcept;
5853
  constexpr bool has_value() const noexcept;
5854
+ constexpr const T& value() const &; // freestanding-deleted
5855
+ constexpr T& value() &; // freestanding-deleted
5856
+ constexpr const T&& value() const &&; // freestanding-deleted
5857
+ constexpr T&& value() &&; // freestanding-deleted
5858
  constexpr const E& error() const & noexcept;
5859
  constexpr E& error() & noexcept;
5860
  constexpr const E&& error() const && noexcept;
5861
  constexpr E&& error() && noexcept;
5862
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&&) const &;
5863
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&&) &&;
5864
  template<class G = E> constexpr E error_or(G&&) const &;
5865
  template<class G = E> constexpr E error_or(G&&) &&;
5866
 
5867
  // [expected.object.monadic], monadic operations
5868
  template<class F> constexpr auto and_then(F&& f) &;
 
5899
  };
5900
  }
5901
  ```
5902
 
5903
  Any object of type `expected<T, E>` either contains a value of type `T`
5904
+ or a value of type `E` nested within [[intro.object]] it. Member
5905
+ *`has_val`* indicates whether the `expected<T, E>` object contains an
5906
+ object of type `T`.
 
 
5907
 
5908
  A type `T` is a *valid value type for `expected`*, if `remove_cv_t<T>`
5909
  is `void` or a complete non-array object type that is not `in_place_t`,
5910
  `unexpect_t`, or a specialization of `unexpected`. A program which
5911
  instantiates class template `expected<T, E>` with an argument `T` that
 
6021
 
6022
  *Remarks:* The expression inside `explicit` is equivalent to
6023
  `!is_convertible_v<UF, T> || !is_convertible_v<GF, E>`.
6024
 
6025
  ``` cpp
6026
+ template<class U = remove_cv_t<T>>
6027
  constexpr explicit(!is_convertible_v<U, T>) expected(U&& v);
6028
  ```
6029
 
6030
  *Constraints:*
6031
 
6032
  - `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`; and
6033
+ - `is_same_v<remove_cvref_t<U>, expected>` is `false`; and
6034
+ - `is_same_v<remove_cvref_t<U>, unexpect_t>` is `false`; and
6035
  - `remove_cvref_t<U>` is not a specialization of `unexpected`; and
6036
  - `is_constructible_v<T, U>` is `true`; and
6037
  - if `T` is cv `bool`, `remove_cvref_t<U>` is not a specialization of
6038
  `expected`.
6039
 
 
6133
  `is_trivially_destructible_v<E>` is `true`, then this destructor is a
6134
  trivial destructor.
6135
 
6136
  #### Assignment <a id="expected.object.assign">[[expected.object.assign]]</a>
6137
 
6138
+ This subclause makes use of the following exposition-only function
6139
+ template:
6140
 
6141
  ``` cpp
6142
  template<class T, class U, class... Args>
6143
  constexpr void reinit-expected(T& newval, U& oldval, Args&&... args) { // exposition only
6144
  if constexpr (is_nothrow_constructible_v<T, Args...>) {
 
6231
  is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T> &&
6232
  is_nothrow_move_assignable_v<E> && is_nothrow_move_constructible_v<E>
6233
  ```
6234
 
6235
  ``` cpp
6236
+ template<class U = remove_cv_t<T>>
6237
  constexpr expected& operator=(U&& v);
6238
  ```
6239
 
6240
  *Constraints:*
6241
 
 
6347
 
6348
  | \topline | `this->has_value()` | `!this->has_value()` |
6349
  | -------- | ------------------- | -------------------- |
6350
 
6351
 
6352
+ For the case where `rhs.has_value()` is `false` and `this->has_value()`
6353
+ is `true`, equivalent to:
6354
 
6355
  ``` cpp
6356
  if constexpr (is_nothrow_move_constructible_v<E>) {
6357
  E tmp(std::move(rhs.unex));
6358
  destroy_at(addressof(rhs.unex));
 
6400
  ``` cpp
6401
  constexpr const T* operator->() const noexcept;
6402
  constexpr T* operator->() noexcept;
6403
  ```
6404
 
6405
+ `has_value()` is `true`.
6406
 
6407
  *Returns:* `addressof(`*`val`*`)`.
6408
 
6409
  ``` cpp
6410
  constexpr const T& operator*() const & noexcept;
6411
  constexpr T& operator*() & noexcept;
6412
  ```
6413
 
6414
+ `has_value()` is `true`.
6415
 
6416
  *Returns:* *val*.
6417
 
6418
  ``` cpp
6419
  constexpr T&& operator*() && noexcept;
6420
  constexpr const T&& operator*() const && noexcept;
6421
  ```
6422
 
6423
+ `has_value()` is `true`.
6424
 
6425
  *Returns:* `std::move(`*`val`*`)`.
6426
 
6427
  ``` cpp
6428
  constexpr explicit operator bool() const noexcept;
 
6459
  ``` cpp
6460
  constexpr const E& error() const & noexcept;
6461
  constexpr E& error() & noexcept;
6462
  ```
6463
 
6464
+ `has_value()` is `false`.
6465
 
6466
  *Returns:* *unex*.
6467
 
6468
  ``` cpp
6469
  constexpr E&& error() && noexcept;
6470
  constexpr const E&& error() const && noexcept;
6471
  ```
6472
 
6473
+ `has_value()` is `false`.
6474
 
6475
  *Returns:* `std::move(`*`unex`*`)`.
6476
 
6477
  ``` cpp
6478
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) const &;
6479
  ```
6480
 
6481
  *Mandates:* `is_copy_constructible_v<T>` is `true` and
6482
  `is_convertible_v<U, T>` is `true`.
6483
 
6484
  *Returns:* `has_value() ? **this : static_cast<T>(std::forward<U>(v))`.
6485
 
6486
  ``` cpp
6487
+ template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) &&;
6488
  ```
6489
 
6490
  *Mandates:* `is_move_constructible_v<T>` is `true` and
6491
  `is_convertible_v<U, T>` is `true`.
6492
 
 
6518
  ``` cpp
6519
  template<class F> constexpr auto and_then(F&& f) &;
6520
  template<class F> constexpr auto and_then(F&& f) const &;
6521
  ```
6522
 
6523
+ Let `U` be `remove_cvref_t<invoke_result_t<F, decltype((`*`val`*`))>>`.
6524
 
6525
  *Constraints:* `is_constructible_v<E, decltype(error())>` is `true`.
6526
 
6527
  *Mandates:* `U` is a specialization of `expected` and
6528
+ `is_same_v<typename U::error_type, E>` is `true`.
6529
 
6530
  *Effects:* Equivalent to:
6531
 
6532
  ``` cpp
6533
  if (has_value())
6534
+ return invoke(std::forward<F>(f), val);
6535
  else
6536
  return U(unexpect, error());
6537
  ```
6538
 
6539
  ``` cpp
6540
  template<class F> constexpr auto and_then(F&& f) &&;
6541
  template<class F> constexpr auto and_then(F&& f) const &&;
6542
  ```
6543
 
6544
  Let `U` be
6545
+ `remove_cvref_t<invoke_result_t<F, decltype(std::move(`*`val`*`))>>`.
6546
 
6547
  *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
6548
  `true`.
6549
 
6550
  *Mandates:* `U` is a specialization of `expected` and
6551
+ `is_same_v<typename U::error_type, E>` is `true`.
6552
 
6553
  *Effects:* Equivalent to:
6554
 
6555
  ``` cpp
6556
  if (has_value())
6557
+ return invoke(std::forward<F>(f), std::move(val));
6558
  else
6559
  return U(unexpect, std::move(error()));
6560
  ```
6561
 
6562
  ``` cpp
 
6564
  template<class F> constexpr auto or_else(F&& f) const &;
6565
  ```
6566
 
6567
  Let `G` be `remove_cvref_t<invoke_result_t<F, decltype(error())>>`.
6568
 
6569
+ *Constraints:* `is_constructible_v<T, decltype((`*`val`*`))>` is `true`.
6570
 
6571
  *Mandates:* `G` is a specialization of `expected` and
6572
+ `is_same_v<typename G::value_type, T>` is `true`.
6573
 
6574
  *Effects:* Equivalent to:
6575
 
6576
  ``` cpp
6577
  if (has_value())
6578
+ return G(in_place, val);
6579
  else
6580
  return invoke(std::forward<F>(f), error());
6581
  ```
6582
 
6583
  ``` cpp
 
6586
  ```
6587
 
6588
  Let `G` be
6589
  `remove_cvref_t<invoke_result_t<F, decltype(std::move(error()))>>`.
6590
 
6591
+ *Constraints:* `is_constructible_v<T, decltype(std::move(`*`val`*`))>`
6592
+ is `true`.
6593
 
6594
  *Mandates:* `G` is a specialization of `expected` and
6595
+ `is_same_v<typename G::value_type, T>` is `true`.
6596
 
6597
  *Effects:* Equivalent to:
6598
 
6599
  ``` cpp
6600
  if (has_value())
6601
+ return G(in_place, std::move(val));
6602
  else
6603
  return invoke(std::forward<F>(f), std::move(error()));
6604
  ```
6605
 
6606
  ``` cpp
6607
  template<class F> constexpr auto transform(F&& f) &;
6608
  template<class F> constexpr auto transform(F&& f) const &;
6609
  ```
6610
 
6611
+ Let `U` be `remove_cv_t<invoke_result_t<F, decltype((`*`val`*`))>>`.
6612
 
6613
  *Constraints:* `is_constructible_v<E, decltype(error())>` is `true`.
6614
 
6615
  *Mandates:* `U` is a valid value type for `expected`. If `is_void_v<U>`
6616
  is `false`, the declaration
6617
 
6618
  ``` cpp
6619
+ U u(invoke(std::forward<F>(f), val));
6620
  ```
6621
 
6622
  is well-formed.
6623
 
6624
  *Effects:*
 
6626
  - If `has_value()` is `false`, returns
6627
  `expected<U, E>(unexpect, error())`.
6628
  - Otherwise, if `is_void_v<U>` is `false`, returns an `expected<U, E>`
6629
  object whose *has_val* member is `true` and *val* member is
6630
  direct-non-list-initialized with
6631
+ `invoke(std::forward<F>(f), `*`val`*`)`.
6632
+ - Otherwise, evaluates `invoke(std::forward<F>(f), `*`val`*`)` and then
6633
  returns `expected<U, E>()`.
6634
 
6635
  ``` cpp
6636
  template<class F> constexpr auto transform(F&& f) &&;
6637
  template<class F> constexpr auto transform(F&& f) const &&;
6638
  ```
6639
 
6640
  Let `U` be
6641
+ `remove_cv_t<invoke_result_t<F, decltype(std::move(`*`val`*`))>>`.
6642
 
6643
  *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
6644
  `true`.
6645
 
6646
  *Mandates:* `U` is a valid value type for `expected`. If `is_void_v<U>`
6647
  is `false`, the declaration
6648
 
6649
  ``` cpp
6650
+ U u(invoke(std::forward<F>(f), std::move(val)));
6651
  ```
6652
 
6653
+ is well-formed.
6654
 
6655
  *Effects:*
6656
 
6657
  - If `has_value()` is `false`, returns
6658
  `expected<U, E>(unexpect, std::move(error()))`.
6659
  - Otherwise, if `is_void_v<U>` is `false`, returns an `expected<U, E>`
6660
  object whose *has_val* member is `true` and *val* member is
6661
  direct-non-list-initialized with
6662
+ `invoke(std::forward<F>(f), std::move(`*`val`*`))`.
6663
+ - Otherwise, evaluates
6664
+ `invoke(std::forward<F>(f), std::move(`*`val`*`))` and then returns
6665
+ `expected<U, E>()`.
6666
 
6667
  ``` cpp
6668
  template<class F> constexpr auto transform_error(F&& f) &;
6669
  template<class F> constexpr auto transform_error(F&& f) const &;
6670
  ```
6671
 
6672
  Let `G` be `remove_cv_t<invoke_result_t<F, decltype(error())>>`.
6673
 
6674
+ *Constraints:* `is_constructible_v<T, decltype((`*`val`*`))>` is `true`.
6675
 
6676
  *Mandates:* `G` is a valid template argument for `unexpected`
6677
  [[expected.un.general]] and the declaration
6678
 
6679
  ``` cpp
 
6681
  ```
6682
 
6683
  is well-formed.
6684
 
6685
  *Returns:* If `has_value()` is `true`,
6686
+ `expected<T, G>(in_place, `*`val`*`)`; otherwise, an `expected<T, G>`
6687
  object whose *has_val* member is `false` and *unex* member is
6688
  direct-non-list-initialized with `invoke(std::forward<F>(f), error())`.
6689
 
6690
  ``` cpp
6691
  template<class F> constexpr auto transform_error(F&& f) &&;
 
6693
  ```
6694
 
6695
  Let `G` be
6696
  `remove_cv_t<invoke_result_t<F, decltype(std::move(error()))>>`.
6697
 
6698
+ *Constraints:* `is_constructible_v<T, decltype(std::move(`*`val`*`))>`
6699
+ is `true`.
6700
 
6701
  *Mandates:* `G` is a valid template argument for `unexpected`
6702
  [[expected.un.general]] and the declaration
6703
 
6704
  ``` cpp
 
6706
  ```
6707
 
6708
  is well-formed.
6709
 
6710
  *Returns:* If `has_value()` is `true`,
6711
+ `expected<T, G>(in_place, std::move(`*`val`*`))`; otherwise, an
6712
  `expected<T, G>` object whose *has_val* member is `false` and *unex*
6713
  member is direct-non-list-initialized with
6714
  `invoke(std::forward<F>(f), std::move(error()))`.
6715
 
6716
  #### Equality operators <a id="expected.object.eq">[[expected.object.eq]]</a>
 
6718
  ``` cpp
6719
  template<class T2, class E2> requires (!is_void_v<T2>)
6720
  friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
6721
  ```
6722
 
6723
+ *Constraints:* The expressions `*x == *y` and `x.error() == y.error()`
6724
+ are well-formed and their results are convertible to `bool`.
6725
 
6726
  *Returns:* If `x.has_value()` does not equal `y.has_value()`, `false`;
6727
  otherwise if `x.has_value()` is `true`, `*x == *y`; otherwise
6728
  `x.error() == y.error()`.
6729
 
6730
  ``` cpp
6731
  template<class T2> friend constexpr bool operator==(const expected& x, const T2& v);
6732
  ```
6733
 
6734
+ *Constraints:* `T2` is not a specialization of `expected`. The
6735
+ expression `*x == v` is well-formed and its result is convertible to
6736
+ `bool`.
6737
 
6738
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
6739
 
6740
  *Returns:* `x.has_value() && static_cast<bool>(*x == v)`.
6741
 
6742
  ``` cpp
6743
  template<class E2> friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
6744
  ```
6745
 
6746
+ *Constraints:* The expression `x.error() == e.error()` is well-formed
6747
+ and its result is convertible to `bool`.
6748
 
6749
  *Returns:*
6750
  `!x.has_value() && static_cast<bool>(x.error() == e.error())`.
6751
 
6752
  ### Partial specialization of `expected` for `void` types <a id="expected.void">[[expected.void]]</a>
 
6803
 
6804
  // [expected.void.obs], observers
6805
  constexpr explicit operator bool() const noexcept;
6806
  constexpr bool has_value() const noexcept;
6807
  constexpr void operator*() const noexcept;
6808
+ constexpr void value() const &; // freestanding-deleted
6809
+ constexpr void value() &&; // freestanding-deleted
6810
  constexpr const E& error() const & noexcept;
6811
  constexpr E& error() & noexcept;
6812
  constexpr const E&& error() const && noexcept;
6813
  constexpr E&& error() && noexcept;
6814
  template<class G = E> constexpr E error_or(G&&) const &;
 
6845
  };
6846
  };
6847
  ```
6848
 
6849
  Any object of type `expected<T, E>` either represents a value of type
6850
+ `T`, or contains a value of type `E` nested within [[intro.object]] it.
6851
+ Member *`has_val`* indicates whether the `expected<T, E>` object
6852
+ represents a value of type `T`.
 
 
6853
 
6854
  A program that instantiates the definition of the template
6855
  `expected<T, E>` with a type for the `E` parameter that is not a valid
6856
  template argument for `unexpected` is ill-formed.
6857
 
 
7016
 
7017
  ``` cpp
7018
  constexpr expected& operator=(expected&& rhs) noexcept(see below);
7019
  ```
7020
 
7021
+ *Constraints:* `is_move_constructible_v<E>` is `true` and
7022
+ `is_move_assignable_v<E>` is `true`.
7023
+
7024
  *Effects:*
7025
 
7026
  - If `this->has_value() && rhs.has_value()` is `true`, no effects.
7027
  - Otherwise, if `this->has_value()` is `true`, equivalent to:
7028
  ``` cpp
 
7036
  *Returns:* `*this`.
7037
 
7038
  *Remarks:* The exception specification is equivalent to
7039
  `is_nothrow_move_constructible_v<E> && is_nothrow_move_assignable_v<E>`.
7040
 
 
 
 
7041
  ``` cpp
7042
  template<class G>
7043
  constexpr expected& operator=(const unexpected<G>& e);
7044
  template<class G>
7045
  constexpr expected& operator=(unexpected<G>&& e);
 
7084
 
7085
  | \topline | `this->has_value()` | `!this->has_value()` |
7086
  | -------- | ------------------- | -------------------- |
7087
 
7088
 
7089
+ For the case where `rhs.has_value()` is `false` and `this->has_value()`
7090
+ is `true`, equivalent to:
7091
 
7092
  ``` cpp
7093
  construct_at(addressof(unex), std::move(rhs.unex));
7094
  destroy_at(addressof(rhs.unex));
7095
  has_val = false;
 
7118
 
7119
  ``` cpp
7120
  constexpr void operator*() const noexcept;
7121
  ```
7122
 
7123
+ `has_value()` is `true`.
7124
 
7125
  ``` cpp
7126
  constexpr void value() const &;
7127
  ```
7128
 
7129
+ *Mandates:* `is_copy_constructible_v<E>` is `true`.
7130
+
7131
  *Throws:* `bad_expected_access(error())` if `has_value()` is `false`.
7132
 
7133
  ``` cpp
7134
  constexpr void value() &&;
7135
  ```
7136
 
7137
+ *Mandates:* `is_copy_constructible_v<E>` is `true` and
7138
+ `is_move_constructible_v<E>` is `true`.
7139
+
7140
  *Throws:* `bad_expected_access(std::move(error()))` if `has_value()` is
7141
  `false`.
7142
 
7143
  ``` cpp
7144
  constexpr const E& error() const & noexcept;
7145
  constexpr E& error() & noexcept;
7146
  ```
7147
 
7148
+ `has_value()` is `false`.
7149
 
7150
  *Returns:* *unex*.
7151
 
7152
  ``` cpp
7153
  constexpr E&& error() && noexcept;
7154
  constexpr const E&& error() const && noexcept;
7155
  ```
7156
 
7157
+ `has_value()` is `false`.
7158
 
7159
  *Returns:* `std::move(`*`unex`*`)`.
7160
 
7161
  ``` cpp
7162
  template<class G = E> constexpr E error_or(G&& e) const &;
 
7188
  Let `U` be `remove_cvref_t<invoke_result_t<F>>`.
7189
 
7190
  *Constraints:* `is_constructible_v<E, decltype(error())>>` is `true`.
7191
 
7192
  *Mandates:* `U` is a specialization of `expected` and
7193
+ `is_same_v<typename U::error_type, E>` is `true`.
7194
 
7195
  *Effects:* Equivalent to:
7196
 
7197
  ``` cpp
7198
  if (has_value())
 
7210
 
7211
  *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
7212
  `true`.
7213
 
7214
  *Mandates:* `U` is a specialization of `expected` and
7215
+ `is_same_v<typename U::error_type, E>` is `true`.
7216
 
7217
  *Effects:* Equivalent to:
7218
 
7219
  ``` cpp
7220
  if (has_value())
 
7229
  ```
7230
 
7231
  Let `G` be `remove_cvref_t<invoke_result_t<F, decltype(error())>>`.
7232
 
7233
  *Mandates:* `G` is a specialization of `expected` and
7234
+ `is_same_v<typename G::value_type, T>` is `true`.
7235
 
7236
  *Effects:* Equivalent to:
7237
 
7238
  ``` cpp
7239
  if (has_value())
 
7249
 
7250
  Let `G` be
7251
  `remove_cvref_t<invoke_result_t<F, decltype(std::move(error()))>>`.
7252
 
7253
  *Mandates:* `G` is a specialization of `expected` and
7254
+ `is_same_v<typename G::value_type, T>` is `true`.
7255
 
7256
  *Effects:* Equivalent to:
7257
 
7258
  ``` cpp
7259
  if (has_value())
 
7367
  ``` cpp
7368
  template<class T2, class E2> requires is_void_v<T2>
7369
  friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
7370
  ```
7371
 
7372
+ *Constraints:* The expression `x.error() == y.error()` is well-formed
7373
+ and its result is convertible to `bool`.
7374
 
7375
  *Returns:* If `x.has_value()` does not equal `y.has_value()`, `false`;
7376
  otherwise `x.has_value() || static_cast<bool>(x.error() == y.error())`.
7377
 
7378
  ``` cpp
7379
  template<class E2>
7380
  friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
7381
  ```
7382
 
7383
+ *Constraints:* The expression `x.error() == e.error()` is well-formed
7384
+ and its result is convertible to `bool`.
7385
 
7386
  *Returns:*
7387
  `!x.has_value() && static_cast<bool>(x.error() == e.error())`.
7388
 
7389
  ## Bitsets <a id="bitset">[[bitset]]</a>
 
7425
  namespace std {
7426
  template<size_t N> class bitset {
7427
  public:
7428
  // bit reference
7429
  class reference {
 
 
 
7430
  public:
7431
  constexpr reference(const reference&) = default;
7432
  constexpr ~reference();
7433
  constexpr reference& operator=(bool x) noexcept; // for b[i] = x;
7434
  constexpr reference& operator=(const reference&) noexcept; // for b[i] = b[j];
 
7446
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
7447
  typename basic_string<charT, traits, Allocator>::size_type n
7448
  = basic_string<charT, traits, Allocator>::npos,
7449
  charT zero = charT('0'),
7450
  charT one = charT('1'));
7451
+ template<class charT, class traits>
7452
+ constexpr explicit bitset(
7453
+ basic_string_view<charT, traits> str,
7454
+ typename basic_string_view<charT, traits>::size_type pos = 0,
7455
+ typename basic_string_view<charT, traits>::size_type n
7456
+ = basic_string_view<charT, traits>::npos,
7457
+ charT zero = charT('0'),
7458
+ charT one = charT('1'));
7459
  template<class charT>
7460
  constexpr explicit bitset(
7461
  const charT* str,
7462
+ typename basic_string_view<charT>::size_type n = basic_string_view<charT>::npos,
7463
  charT zero = charT('0'),
7464
  charT one = charT('1'));
7465
 
7466
  // [bitset.members], bitset operations
7467
  constexpr bitset& operator&=(const bitset& rhs) noexcept;
 
7553
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
7554
  typename basic_string<charT, traits, Allocator>::size_type n
7555
  = basic_string<charT, traits, Allocator>::npos,
7556
  charT zero = charT('0'),
7557
  charT one = charT('1'));
7558
+ template<class charT, class traits>
7559
+ constexpr explicit bitset(
7560
+ basic_string_view<charT, traits> str,
7561
+ typename basic_string_view<charT, traits>::size_type pos = 0,
7562
+ typename basic_string_view<charT, traits>::size_type n
7563
+ = basic_string_view<charT, traits>::npos,
7564
+ charT zero = charT('0'),
7565
+ charT one = charT('1'));
7566
  ```
7567
 
7568
  *Effects:* Determines the effective length `rlen` of the initializing
7569
  string as the smaller of `n` and `str.size() - pos`. Initializes the
7570
  first `M` bit positions to values determined from the corresponding
 
7586
 
7587
  ``` cpp
7588
  template<class charT>
7589
  constexpr explicit bitset(
7590
  const charT* str,
7591
+ typename basic_string_view<charT>::size_type n = basic_string_view<charT>::npos,
7592
  charT zero = charT('0'),
7593
  charT one = charT('1'));
7594
  ```
7595
 
7596
  *Effects:* As if by:
7597
 
7598
  ``` cpp
7599
+ bitset(n == basic_string_view<charT>::npos
7600
+ ? basic_string_view<charT>(str)
7601
+ : basic_string_view<charT>(str, n),
7602
  0, n, zero, one)
7603
  ```
7604
 
7605
  #### Members <a id="bitset.members">[[bitset.members]]</a>
7606
 
 
7738
 
7739
  ``` cpp
7740
  constexpr bool operator[](size_t pos) const;
7741
  ```
7742
 
7743
+ `pos < size()` is `true`.
7744
 
7745
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
7746
  one, otherwise `false`.
7747
 
7748
  *Throws:* Nothing.
7749
 
7750
  ``` cpp
7751
  constexpr bitset::reference operator[](size_t pos);
7752
  ```
7753
 
7754
+ `pos < size()` is `true`.
7755
 
7756
  *Returns:* An object of type `bitset::reference` such that
7757
  `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
7758
  equivalent to `this->set(pos, val)`.
7759
 
 
8021
  // [func.identity], identity
8022
  struct identity; // freestanding
8023
 
8024
  // [func.not.fn], function template not_fn
8025
  template<class F> constexpr unspecified not_fn(F&& f); // freestanding
8026
+ template<auto f> constexpr unspecified not_fn() noexcept; // freestanding
8027
 
8028
  // [func.bind.partial], function templates bind_front and bind_back
8029
  template<class F, class... Args>
8030
  constexpr unspecified bind_front(F&&, Args&&...); // freestanding
8031
+ template<auto f, class... Args>
8032
+ constexpr unspecified bind_front(Args&&...); // freestanding
8033
  template<class F, class... Args>
8034
  constexpr unspecified bind_back(F&&, Args&&...); // freestanding
8035
+ template<auto f, class... Args>
8036
+ constexpr unspecified bind_back(Args&&...); // freestanding
8037
 
8038
  // [func.bind], bind
8039
  template<class T> struct is_bind_expression; // freestanding
8040
  template<class T>
8041
  constexpr bool is_bind_expression_v = // freestanding
 
8052
 
8053
  namespace placeholders {
8054
  // M is the implementation-defined number of placeholders
8055
  see belownc _1; // freestanding
8056
  see belownc _2; // freestanding
8057
+
 
 
8058
  see belownc _M; // freestanding
8059
  }
8060
 
8061
  // [func.memfn], member function adaptors
8062
  template<class R, class T>
8063
  constexpr unspecified mem_fn(R T::*) noexcept; // freestanding
8064
 
8065
  // [func.wrap], polymorphic function wrappers
8066
+ // [func.wrap.badcall], class bad_function_call
8067
  class bad_function_call;
8068
 
8069
+ // [func.wrap.func], class template function
8070
  template<class> class function; // not defined
8071
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;
8072
 
8073
+ // [func.wrap.func.alg], function specialized algorithms
8074
  template<class R, class... ArgTypes>
8075
  void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
8076
 
8077
+ // [func.wrap.func.nullptr], function null pointer comparison operator functions
8078
  template<class R, class... ArgTypes>
8079
  bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
8080
 
8081
+ // [func.wrap.move], move-only wrapper
8082
  template<class... S> class move_only_function; // not defined
8083
  template<class R, class... ArgTypes>
8084
  class move_only_function<R(ArgTypes...) cv ref noexcept(noex)>; // see below
8085
 
8086
+ // [func.wrap.copy], copyable wrapper
8087
+ template<class... S> class copyable_function; // not defined
8088
+ template<class R, class... ArgTypes>
8089
+ class copyable_function<R(ArgTypes...) cv ref noexcept(noex)>; // see below
8090
+
8091
+ // [func.wrap.ref], non-owning wrapper
8092
+ template<class... S> class function_ref; // freestanding, not defined
8093
+ template<class R, class... ArgTypes>
8094
+ class function_ref<R(ArgTypes...) cv noexcept(noex)>; // freestanding, see below
8095
+
8096
  // [func.search], searchers
8097
  template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
8098
  class default_searcher; // freestanding
8099
 
8100
  template<class RandomAccessIterator,
 
8118
  struct greater; // freestanding
8119
  struct less; // freestanding
8120
  struct greater_equal; // freestanding
8121
  struct less_equal; // freestanding
8122
  }
8123
+
8124
+ template<class Fn, class... Args>
8125
+ concept callable = // exposition only
8126
+ requires (Fn&& fn, Args&&... args) {
8127
+ std::forward<Fn>(fn)(std::forward<Args>(args)...);
8128
+ };
8129
+
8130
+ template<class Fn, class... Args>
8131
+ concept nothrow-callable = // exposition only
8132
+ callable<Fn, Args...> &&
8133
+ requires (Fn&& fn, Args&&... args) {
8134
+ { std::forward<Fn>(fn)(std::forward<Args>(args)...) } noexcept;
8135
+ };
8136
+
8137
+ template<class Fn, class... Args>
8138
+ using call-result-t = decltype(declval<Fn>()(declval<Args>()...)); // exposition only
8139
+
8140
+ template<const auto& T>
8141
+ using decayed-typeof = decltype(auto(T)); // exposition only
8142
  }
8143
  ```
8144
 
8145
  [*Example 1*:
8146
 
 
8192
  ### Requirements <a id="func.require">[[func.require]]</a>
8193
 
8194
  Define `INVOKE(f, t₁, t₂, …, t_N)` as follows:
8195
 
8196
  - `(t₁.*f)(t₂, …, t_N)` when `f` is a pointer to a member function of a
8197
+ class `T` and `is_same_v<T, remove_cvref_t<decltype(t₁)>> ||`
8198
  `is_base_of_v<T, remove_cvref_t<decltype(t₁)>>` is `true`;
8199
  - `(t₁.get().*f)(t₂, …, t_N)` when `f` is a pointer to a member function
8200
  of a class `T` and `remove_cvref_t<decltype(t₁)>` is a specialization
8201
  of `reference_wrapper`;
8202
  - `((*t₁).*f)(t₂, …, t_N)` when `f` is a pointer to a member function of
8203
  a class `T` and `t₁` does not satisfy the previous two items;
8204
  - `t₁.*f` when N = 1 and `f` is a pointer to data member of a class `T`
8205
+ and `is_same_v<T, remove_cvref_t<decltype(t₁)>> ||`
8206
  `is_base_of_v<T, remove_cvref_t<decltype(t₁)>>` is `true`;
8207
  - `t₁.get().*f` when N = 1 and `f` is a pointer to data member of a
8208
  class `T` and `remove_cvref_t<decltype(t₁)>` is a specialization of
8209
  `reference_wrapper`;
8210
  - `(*t₁).*f` when N = 1 and `f` is a pointer to data member of a class
 
8318
 
8319
  // [refwrap.invoke], invocation
8320
  template<class... ArgTypes>
8321
  constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) const
8322
  noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);
8323
+
8324
+ // [refwrap.comparisons], comparisons
8325
+ friend constexpr bool operator==(reference_wrapper, reference_wrapper);
8326
+ friend constexpr bool operator==(reference_wrapper, const T&);
8327
+ friend constexpr bool operator==(reference_wrapper, reference_wrapper<const T>);
8328
+
8329
+ friend constexpr auto operator<=>(reference_wrapper, reference_wrapper);
8330
+ friend constexpr auto operator<=>(reference_wrapper, const T&);
8331
+ friend constexpr auto operator<=>(reference_wrapper, reference_wrapper<const T>);
8332
  };
8333
 
8334
  template<class T>
8335
  reference_wrapper(T&) -> reference_wrapper<T>;
8336
  }
 
8344
  [[term.trivially.copyable.type]].
8345
 
8346
  The template parameter `T` of `reference_wrapper` may be an incomplete
8347
  type.
8348
 
8349
+ [*Note 1*: Using the comparison operators described in
8350
+ [[refwrap.comparisons]] with `T` being an incomplete type can lead to an
8351
+ ill-formed program with no diagnostic required
8352
+ [[temp.point]], [[temp.constr.atomic]]. — *end note*]
8353
+
8354
  #### Constructors <a id="refwrap.const">[[refwrap.const]]</a>
8355
 
8356
  ``` cpp
8357
  template<class U>
8358
  constexpr reference_wrapper(U&& u) noexcept(see below);
 
8413
  ```
8414
 
8415
  *Mandates:* `T` is a complete type.
8416
 
8417
  *Returns:* *INVOKE*(get(),
8418
+ std::forward\<ArgTypes\>(args)...) [[func.require]].
8419
+
8420
+ #### Comparisons <a id="refwrap.comparisons">[[refwrap.comparisons]]</a>
8421
+
8422
+ ``` cpp
8423
+ friend constexpr bool operator==(reference_wrapper x, reference_wrapper y);
8424
+ ```
8425
+
8426
+ *Constraints:* The expression `x.get() == y.get()` is well-formed and
8427
+ its result is convertible to `bool`.
8428
+
8429
+ *Returns:* `x.get() == y.get()`.
8430
+
8431
+ ``` cpp
8432
+ friend constexpr bool operator==(reference_wrapper x, const T& y);
8433
+ ```
8434
+
8435
+ *Constraints:* The expression `x.get() == y` is well-formed and its
8436
+ result is convertible to `bool`.
8437
+
8438
+ *Returns:* `x.get() == y`.
8439
+
8440
+ ``` cpp
8441
+ friend constexpr bool operator==(reference_wrapper x, reference_wrapper<const T> y);
8442
+ ```
8443
+
8444
+ *Constraints:* `is_const_v<T>` is `false` and the expression
8445
+ `x.get() == y.get()` is well-formed and its result is convertible to
8446
+ `bool`.
8447
+
8448
+ *Returns:* `x.get() == y.get()`.
8449
+
8450
+ ``` cpp
8451
+ friend constexpr auto operator<=>(reference_wrapper x, reference_wrapper y);
8452
+ ```
8453
+
8454
+ *Constraints:* The expression *`synth-three-way`*`(x.get(), y.get())` is
8455
+ well-formed.
8456
+
8457
+ *Returns:* *`synth-three-way`*`(x.get(), y.get())`.
8458
+
8459
+ ``` cpp
8460
+ friend constexpr auto operator<=>(reference_wrapper x, const T& y);
8461
+ ```
8462
+
8463
+ *Constraints:* The expression *`synth-three-way`*`(x.get(), y)` is
8464
+ well-formed.
8465
+
8466
+ *Returns:* *`synth-three-way`*`(x.get(), y)`.
8467
+
8468
+ ``` cpp
8469
+ friend constexpr auto operator<=>(reference_wrapper x, reference_wrapper<const T> y);
8470
+ ```
8471
+
8472
+ *Constraints:* `is_const_v<T>` is `false`. The expression
8473
+ *`synth-three-way`*`(x.get(), y.get())` is well-formed.
8474
+
8475
+ *Returns:* *`synth-three-way`*`(x.get(), y.get())`.
8476
 
8477
  #### Helper functions <a id="refwrap.helpers">[[refwrap.helpers]]</a>
8478
 
8479
  The template parameter `T` of the following `ref` and `cref` function
8480
  templates may be an incomplete type.
 
9387
  wrapper [[term.perfect.forwarding.call.wrapper]] `g` with call pattern
9388
  `!invoke(fd, call_args...)`.
9389
 
9390
  *Throws:* Any exception thrown by the initialization of `fd`.
9391
 
9392
+ ``` cpp
9393
+ template<auto f> constexpr unspecified not_fn() noexcept;
9394
+ ```
9395
+
9396
+ In the text that follows:
9397
+
9398
+ - `F` is the type of `f`,
9399
+ - `g` is a value of the result of a `not_fn` invocation,
9400
+ - `call_args` is an argument pack used in a function call
9401
+ expression [[expr.call]] of `g`.
9402
+
9403
+ *Mandates:* If `is_pointer_v<F> || is_member_pointer_v<F>` is `true`,
9404
+ then `f != nullptr` is `true`.
9405
+
9406
+ *Returns:* A perfect forwarding call wrapper [[func.require]] `g` that
9407
+ does not have state entities, and has the call pattern
9408
+ `!invoke(f, call_args...)`.
9409
+
9410
  ### Function templates `bind_front` and `bind_back` <a id="func.bind.partial">[[func.bind.partial]]</a>
9411
 
9412
  ``` cpp
9413
  template<class F, class... Args>
9414
  constexpr unspecified bind_front(F&& f, Args&&... args);
 
9454
  invocation.
9455
 
9456
  *Throws:* Any exception thrown by the initialization of the state
9457
  entities of `g` [[func.def]].
9458
 
9459
+ ``` cpp
9460
+ template<auto f, class... Args>
9461
+ constexpr unspecified bind_front(Args&&... args);
9462
+ template<auto f, class... Args>
9463
+ constexpr unspecified bind_back(Args&&... args);
9464
+ ```
9465
+
9466
+ Within this subclause:
9467
+
9468
+ - `F` is the type of `f`,
9469
+ - `g` is a value of the result of a `bind_front` or `bind_back`
9470
+ invocation,
9471
+ - `BoundArgs` is a pack that denotes `decay_t<Args>...`,
9472
+ - `bound_args` is a pack of bound argument entities of `g` [[func.def]]
9473
+ of types `BoundArgs...`, direct-non-list-initialized with
9474
+ `std::forward<Args>(args)...`, respectively, and
9475
+ - `call_args` is an argument pack used in a function call
9476
+ expression [[expr.call]] of `g`.
9477
+
9478
+ *Mandates:*
9479
+
9480
+ - `(is_constructible_v<BoundArgs, Args> && ...)` is `true`, and
9481
+ - `(is_move_constructible_v<BoundArgs> && ...)` is `true`, and
9482
+ - if `is_pointer_v<F> || is_member_pointer_v<F>` is `true`, then
9483
+ `f != nullptr` is `true`.
9484
+
9485
+ *Preconditions:* For each `Tᵢ` in `BoundArgs`, `Tᵢ` meets the
9486
+ *Cpp17MoveConstructible* requirements.
9487
+
9488
+ *Returns:* A perfect forwarding call wrapper [[func.require]] `g` that
9489
+ does not have a target object, and has the call pattern:
9490
+
9491
+ - `invoke(f, bound_args..., call_args...)` for a `bind_front`
9492
+ invocation, or
9493
+ - `invoke(f, call_args..., bound_args...)` for a `bind_back` invocation.
9494
+
9495
+ *Throws:* Any exception thrown by the initialization of `bound_args`.
9496
+
9497
  ### Function object binders <a id="func.bind">[[func.bind]]</a>
9498
 
9499
  #### General <a id="func.bind.general">[[func.bind.general]]</a>
9500
 
9501
  Subclause [[func.bind]] describes a uniform mechanism for binding
 
9630
  ``` cpp
9631
  namespace std::placeholders {
9632
  // M is the number of placeholders
9633
  see below _1;
9634
  see below _2;
9635
+
 
 
9636
  see below _M;
9637
  }
9638
  ```
9639
 
9640
  The number `M` of placeholders is *implementation-defined*.
 
9678
  #### General <a id="func.wrap.general">[[func.wrap.general]]</a>
9679
 
9680
  Subclause [[func.wrap]] describes polymorphic wrapper classes that
9681
  encapsulate arbitrary callable objects.
9682
 
9683
+ Let `t` be an object of a type that is a specialization of `function`,
9684
+ `copyable_function`, or `move_only_function`, such that the target
9685
+ object `x` of `t` has a type that is a specialization of `function`,
9686
+ `copyable_function`, or `move_only_function`. Each argument of the
9687
+ invocation of `x` evaluated as part of the invocation of `t` may alias
9688
+ an argument in the same position in the invocation of `t` that has the
9689
+ same type, even if the corresponding parameter is not of reference type.
9690
+
9691
+ [*Example 1*:
9692
+
9693
+ ``` cpp
9694
+ move_only_function<void(T)> f{copyable_function<void(T)>{[](T) {}}};
9695
+ T t;
9696
+ f(t); // it is unspecified how many copies of T are made
9697
+ ```
9698
+
9699
+ — *end example*]
9700
+
9701
+ *Recommended practice:* Implementations should avoid double wrapping
9702
+ when constructing polymorphic wrappers from one another.
9703
+
9704
  #### Class `bad_function_call` <a id="func.wrap.badcall">[[func.wrap.badcall]]</a>
9705
 
9706
  An exception of type `bad_function_call` is thrown by
9707
  `function::operator()` [[func.wrap.func.inv]] when the function wrapper
9708
  object has no target.
 
9727
 
9728
  ##### General <a id="func.wrap.func.general">[[func.wrap.func.general]]</a>
9729
 
9730
  ``` cpp
9731
  namespace std {
 
 
9732
  template<class R, class... ArgTypes>
9733
  class function<R(ArgTypes...)> {
9734
  public:
9735
  using result_type = R;
9736
 
 
9774
  The `function` class template provides polymorphic wrappers that
9775
  generalize the notion of a function pointer. Wrappers can store, copy,
9776
  and call arbitrary callable objects [[func.def]], given a call signature
9777
  [[func.def]].
9778
 
 
 
 
 
 
 
9779
  The `function` class template is a call wrapper [[func.def]] whose call
9780
  signature [[func.def]] is `R(ArgTypes...)`.
9781
 
9782
  [*Note 1*: The types deduced by the deduction guides for `function`
9783
  might change in future revisions of C++. — *end note*]
 
9799
  ``` cpp
9800
  function(const function& f);
9801
  ```
9802
 
9803
  *Ensures:* `!*this` if `!f`; otherwise, the target object of `*this` is
9804
+ a copy of the target object of `f`.
9805
 
9806
  *Throws:* Nothing if `f`’s target is a specialization of
9807
  `reference_wrapper` or a function pointer. Otherwise, may throw
9808
  `bad_alloc` or any exception thrown by the copy constructor of the
9809
  stored callable object.
 
9833
  Let `FD` be `decay_t<F>`.
9834
 
9835
  *Constraints:*
9836
 
9837
  - `is_same_v<remove_cvref_t<F>, function>` is `false`, and
9838
+ - `is_invocable_r_v<R, FD&, ArgTypes...>` is `true`.
 
9839
 
9840
  *Mandates:*
9841
 
9842
  - `is_copy_constructible_v<FD>` is `true`, and
9843
  - `is_constructible_v<FD, F>` is `true`.
 
9918
 
9919
  ``` cpp
9920
  template<class F> function& operator=(F&& f);
9921
  ```
9922
 
9923
+ *Constraints:* `is_invocable_r_v<R, decay_t<F>&, ArgTypes...>` is
9924
+ `true`.
9925
 
9926
  *Effects:* As if by: `function(std::forward<F>(f)).swap(*this);`
9927
 
9928
  *Returns:* `*this`.
9929
 
 
10003
  void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
10004
  ```
10005
 
10006
  *Effects:* As if by: `f1.swap(f2);`
10007
 
10008
+ #### Move-only wrapper <a id="func.wrap.move">[[func.wrap.move]]</a>
10009
 
10010
  ##### General <a id="func.wrap.move.general">[[func.wrap.move.general]]</a>
10011
 
10012
  The header provides partial specializations of `move_only_function` for
10013
  each combination of the possible replacements of the placeholders cv,
 
10025
 
10026
  ##### Class template `move_only_function` <a id="func.wrap.move.class">[[func.wrap.move.class]]</a>
10027
 
10028
  ``` cpp
10029
  namespace std {
 
 
10030
  template<class R, class... ArgTypes>
10031
  class move_only_function<R(ArgTypes...) cv ref noexcept(noex)> {
10032
  public:
10033
  using result_type = R;
10034
 
10035
+ // [func.wrap.move.ctor], constructors, assignments, and destructor
10036
  move_only_function() noexcept;
10037
  move_only_function(nullptr_t) noexcept;
10038
  move_only_function(move_only_function&&) noexcept;
10039
  template<class F> move_only_function(F&&);
10040
  template<class T, class... Args>
 
10074
 
10075
  [*Note 1*: Such small-object optimization can only be applied to a type
10076
  `T` for which `is_nothrow_move_constructible_v<T>` is
10077
  `true`. — *end note*]
10078
 
10079
+ ##### Constructors, assignments, and destructor <a id="func.wrap.move.ctor">[[func.wrap.move.ctor]]</a>
10080
 
10081
  ``` cpp
10082
  template<class VT>
10083
  static constexpr bool is-callable-from = see below;
10084
  ```
 
10267
  friend bool operator==(const move_only_function& f, nullptr_t) noexcept;
10268
  ```
10269
 
10270
  *Returns:* `true` if `f` has no target object, otherwise `false`.
10271
 
10272
+ #### Copyable wrapper <a id="func.wrap.copy">[[func.wrap.copy]]</a>
10273
+
10274
+ ##### General <a id="func.wrap.copy.general">[[func.wrap.copy.general]]</a>
10275
+
10276
+ The header provides partial specializations of `copyable_function` for
10277
+ each combination of the possible replacements of the placeholders cv,
10278
+ *ref*, and *noex* where
10279
+
10280
+ - cv is either const or empty,
10281
+ - *ref* is either `&`, `&&`, or empty, and
10282
+ - *noex* is either `true` or `false`.
10283
+
10284
+ For each of the possible combinations of the placeholders mentioned
10285
+ above, there is a placeholder *inv-quals* defined as follows:
10286
+
10287
+ - If *ref* is empty, let *inv-quals* be cv`&`,
10288
+ - otherwise, let *inv-quals* be cv *ref*.
10289
+
10290
+ ##### Class template `copyable_function` <a id="func.wrap.copy.class">[[func.wrap.copy.class]]</a>
10291
+
10292
+ ``` cpp
10293
+ namespace std {
10294
+ template<class R, class... ArgTypes>
10295
+ class copyable_function<R(ArgTypes...) cv ref noexcept(noex)> {
10296
+ public:
10297
+ using result_type = R;
10298
+
10299
+ // [func.wrap.copy.ctor], constructors, assignments, and destructor
10300
+ copyable_function() noexcept;
10301
+ copyable_function(nullptr_t) noexcept;
10302
+ copyable_function(const copyable_function&);
10303
+ copyable_function(copyable_function&&) noexcept;
10304
+ template<class F> copyable_function(F&&);
10305
+ template<class T, class... Args>
10306
+ explicit copyable_function(in_place_type_t<T>, Args&&...);
10307
+ template<class T, class U, class... Args>
10308
+ explicit copyable_function(in_place_type_t<T>, initializer_list<U>, Args&&...);
10309
+
10310
+ copyable_function& operator=(const copyable_function&);
10311
+ copyable_function& operator=(copyable_function&&);
10312
+ copyable_function& operator=(nullptr_t) noexcept;
10313
+ template<class F> copyable_function& operator=(F&&);
10314
+
10315
+ ~copyable_function();
10316
+
10317
+ // [func.wrap.copy.inv], invocation
10318
+ explicit operator bool() const noexcept;
10319
+ R operator()(ArgTypes...) cv ref noexcept(noex);
10320
+
10321
+ // [func.wrap.copy.util], utility
10322
+ void swap(copyable_function&) noexcept;
10323
+ friend void swap(copyable_function&, copyable_function&) noexcept;
10324
+ friend bool operator==(const copyable_function&, nullptr_t) noexcept;
10325
+
10326
+ private:
10327
+ template<class VT>
10328
+ static constexpr bool is-callable-from = see below; // exposition only
10329
+ };
10330
+ }
10331
+ ```
10332
+
10333
+ The `copyable_function` class template provides polymorphic wrappers
10334
+ that generalize the notion of a callable object [[func.def]]. These
10335
+ wrappers can store, copy, move, and call arbitrary callable objects,
10336
+ given a call signature.
10337
+
10338
+ *Recommended practice:* Implementations should avoid the use of
10339
+ dynamically allocated memory for a small contained value.
10340
+
10341
+ [*Note 1*: Such small-object optimization can only be applied to a type
10342
+ `T` for which `is_nothrow_move_constructible_v<T>` is
10343
+ `true`. — *end note*]
10344
+
10345
+ ##### Constructors, assignments, and destructor <a id="func.wrap.copy.ctor">[[func.wrap.copy.ctor]]</a>
10346
+
10347
+ ``` cpp
10348
+ template<class VT>
10349
+ static constexpr bool is-callable-from = see below;
10350
+ ```
10351
+
10352
+ If *noex* is `true`, *`is-callable-from`*`<VT>` is equal to:
10353
+
10354
+ ``` cpp
10355
+ is_nothrow_invocable_r_v<R, VT cv ref, ArgTypes...> &&
10356
+ is_nothrow_invocable_r_v<R, VT inv-quals, ArgTypes...>
10357
+ ```
10358
+
10359
+ Otherwise, *`is-callable-from`*`<VT>` is equal to:
10360
+
10361
+ ``` cpp
10362
+ is_invocable_r_v<R, VT cv ref, ArgTypes...> &&
10363
+ is_invocable_r_v<R, VT inv-quals, ArgTypes...>
10364
+ ```
10365
+
10366
+ ``` cpp
10367
+ copyable_function() noexcept;
10368
+ copyable_function(nullptr_t) noexcept;
10369
+ ```
10370
+
10371
+ *Ensures:* `*this` has no target object.
10372
+
10373
+ ``` cpp
10374
+ copyable_function(const copyable_function& f);
10375
+ ```
10376
+
10377
+ *Ensures:* `*this` has no target object if `f` had no target object.
10378
+ Otherwise, the target object of `*this` is a copy of the target object
10379
+ of `f`.
10380
+
10381
+ *Throws:* Any exception thrown by the initialization of the target
10382
+ object. May throw `bad_alloc`.
10383
+
10384
+ ``` cpp
10385
+ copyable_function(copyable_function&& f) noexcept;
10386
+ ```
10387
+
10388
+ *Ensures:* The target object of `*this` is the target object `f` had
10389
+ before construction, and `f` is in a valid state with an unspecified
10390
+ value.
10391
+
10392
+ ``` cpp
10393
+ template<class F> copyable_function(F&& f);
10394
+ ```
10395
+
10396
+ Let `VT` be `decay_t<F>`.
10397
+
10398
+ *Constraints:*
10399
+
10400
+ - `remove_cvref_t<F>` is not the same type as `copyable_function`, and
10401
+ - `remove_cvref_t<F>` is not a specialization of `in_place_type_t`, and
10402
+ - *`is-callable-from`*`<VT>` is `true`.
10403
+
10404
+ *Mandates:*
10405
+
10406
+ - `is_constructible_v<VT, F>` is `true`, and
10407
+ - `is_copy_constructible_v<VT>` is `true`.
10408
+
10409
+ *Preconditions:* `VT` meets the *Cpp17Destructible* and
10410
+ *Cpp17CopyConstructible* requirements.
10411
+
10412
+ *Ensures:* `*this` has no target object if any of the following hold:
10413
+
10414
+ - `f` is a null function pointer value, or
10415
+ - `f` is a null member pointer value, or
10416
+ - `remove_cvref_t<F>` is a specialization of the `copyable_function`
10417
+ class template, and `f` has no target object.
10418
+
10419
+ Otherwise, `*this` has a target object of type `VT`
10420
+ direct-non-list-initialized with `std::forward<F>(f)`.
10421
+
10422
+ *Throws:* Any exception thrown by the initialization of the target
10423
+ object. May throw `bad_alloc` unless `VT` is a function pointer or a
10424
+ specialization of `reference_wrapper`.
10425
+
10426
+ ``` cpp
10427
+ template<class T, class... Args>
10428
+ explicit copyable_function(in_place_type_t<T>, Args&&... args);
10429
+ ```
10430
+
10431
+ Let `VT` be `decay_t<T>`.
10432
+
10433
+ *Constraints:*
10434
+
10435
+ - `is_constructible_v<VT, Args...>` is `true`, and
10436
+ - *`is-callable-from`*`<VT>` is `true`.
10437
+
10438
+ *Mandates:*
10439
+
10440
+ - `VT` is the same type as `T`, and
10441
+ - `is_copy_constructible_v<VT>` is `true`.
10442
+
10443
+ *Preconditions:* `VT` meets the *Cpp17Destructible* and
10444
+ *Cpp17CopyConstructible* requirements.
10445
+
10446
+ *Ensures:* `*this` has a target object of type `VT`
10447
+ direct-non-list-initialized with `std::forward<Args>(args)...`.
10448
+
10449
+ *Throws:* Any exception thrown by the initialization of the target
10450
+ object. May throw `bad_alloc` unless `VT` is a pointer or a
10451
+ specialization of `reference_wrapper`.
10452
+
10453
+ ``` cpp
10454
+ template<class T, class U, class... Args>
10455
+ explicit copyable_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
10456
+ ```
10457
+
10458
+ Let `VT` be `decay_t<T>`.
10459
+
10460
+ *Constraints:*
10461
+
10462
+ - `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`, and
10463
+ - *`is-callable-from`*`<VT>` is `true`.
10464
+
10465
+ *Mandates:*
10466
+
10467
+ - `VT` is the same type as `T`, and
10468
+ - `is_copy_constructible_v<VT>` is `true`.
10469
+
10470
+ *Preconditions:* `VT` meets the *Cpp17Destructible* and
10471
+ *Cpp17CopyConstructible* requirements.
10472
+
10473
+ *Ensures:* `*this` has a target object of type `VT`
10474
+ direct-non-list-initialized with `ilist, std::forward<Args>(args)...`.
10475
+
10476
+ *Throws:* Any exception thrown by the initialization of the target
10477
+ object. May throw `bad_alloc` unless `VT` is a pointer or a
10478
+ specialization of `reference_wrapper`.
10479
+
10480
+ ``` cpp
10481
+ copyable_function& operator=(const copyable_function& f);
10482
+ ```
10483
+
10484
+ *Effects:* Equivalent to: `copyable_function(f).swap(*this);`
10485
+
10486
+ *Returns:* `*this`.
10487
+
10488
+ ``` cpp
10489
+ copyable_function& operator=(copyable_function&& f);
10490
+ ```
10491
+
10492
+ *Effects:* Equivalent to: `copyable_function(std::move(f)).swap(*this);`
10493
+
10494
+ *Returns:* `*this`.
10495
+
10496
+ ``` cpp
10497
+ copyable_function& operator=(nullptr_t) noexcept;
10498
+ ```
10499
+
10500
+ *Effects:* Destroys the target object of `*this`, if any.
10501
+
10502
+ *Returns:* `*this`.
10503
+
10504
+ ``` cpp
10505
+ template<class F> copyable_function& operator=(F&& f);
10506
+ ```
10507
+
10508
+ *Effects:* Equivalent to:
10509
+ `copyable_function(std::forward<F>(f)).swap(*this);`
10510
+
10511
+ *Returns:* `*this`.
10512
+
10513
+ ``` cpp
10514
+ ~copyable_function();
10515
+ ```
10516
+
10517
+ *Effects:* Destroys the target object of `*this`, if any.
10518
+
10519
+ ##### Invocation <a id="func.wrap.copy.inv">[[func.wrap.copy.inv]]</a>
10520
+
10521
+ ``` cpp
10522
+ explicit operator bool() const noexcept;
10523
+ ```
10524
+
10525
+ *Returns:* `true` if `*this` has a target object, otherwise `false`.
10526
+
10527
+ ``` cpp
10528
+ R operator()(ArgTypes... args) cv ref noexcept(noex);
10529
+ ```
10530
+
10531
+ *Preconditions:* `*this` has a target object.
10532
+
10533
+ *Effects:* Equivalent to:
10534
+
10535
+ ``` cpp
10536
+ return INVOKE<R>(static_cast<F inv-quals>(f), std::forward<ArgTypes>(args)...);
10537
+ ```
10538
+
10539
+ where `f` is an lvalue designating the target object of `*this` and `F`
10540
+ is the type of `f`.
10541
+
10542
+ ##### Utility <a id="func.wrap.copy.util">[[func.wrap.copy.util]]</a>
10543
+
10544
+ ``` cpp
10545
+ void swap(copyable_function& other) noexcept;
10546
+ ```
10547
+
10548
+ *Effects:* Exchanges the target objects of `*this` and `other`.
10549
+
10550
+ ``` cpp
10551
+ friend void swap(copyable_function& f1, copyable_function& f2) noexcept;
10552
+ ```
10553
+
10554
+ *Effects:* Equivalent to `f1.swap(f2)`.
10555
+
10556
+ ``` cpp
10557
+ friend bool operator==(const copyable_function& f, nullptr_t) noexcept;
10558
+ ```
10559
+
10560
+ *Returns:* `true` if `f` has no target object, otherwise `false`.
10561
+
10562
+ #### Non-owning wrapper <a id="func.wrap.ref">[[func.wrap.ref]]</a>
10563
+
10564
+ ##### General <a id="func.wrap.ref.general">[[func.wrap.ref.general]]</a>
10565
+
10566
+ The header provides partial specializations of `function_ref` for each
10567
+ combination of the possible replacements of the placeholders cv and
10568
+ *noex* where:
10569
+
10570
+ - cv is either const or empty, and
10571
+ - *noex* is either `true` or `false`.
10572
+
10573
+ ##### Class template `function_ref` <a id="func.wrap.ref.class">[[func.wrap.ref.class]]</a>
10574
+
10575
+ ``` cpp
10576
+ namespace std {
10577
+ template<class R, class... ArgTypes>
10578
+ class function_ref<R(ArgTypes...) cv noexcept(noex)> {
10579
+ public:
10580
+ // [func.wrap.ref.ctor], constructors and assignment operators
10581
+ template<class F> function_ref(F*) noexcept;
10582
+ template<class F> constexpr function_ref(F&&) noexcept;
10583
+ template<auto f> constexpr function_ref(nontype_t<f>) noexcept;
10584
+ template<auto f, class U> constexpr function_ref(nontype_t<f>, U&&) noexcept;
10585
+ template<auto f, class T> constexpr function_ref(nontype_t<f>, cv T*) noexcept;
10586
+
10587
+ constexpr function_ref(const function_ref&) noexcept = default;
10588
+ constexpr function_ref& operator=(const function_ref&) noexcept = default;
10589
+ template<class T> function_ref& operator=(T) = delete;
10590
+
10591
+ // [func.wrap.ref.inv], invocation
10592
+ R operator()(ArgTypes...) const noexcept(noex);
10593
+
10594
+ private:
10595
+ template<class... T>
10596
+ static constexpr bool is-invocable-using = see belownc; // exposition only
10597
+
10598
+ R (*thunk-ptr)(BoundEntityType, ArgTypes&&...) noexcept(noex); // exposition only
10599
+ BoundEntityType bound-entity; // exposition only
10600
+ };
10601
+
10602
+ // [func.wrap.ref.deduct], deduction guides
10603
+ template<class F>
10604
+ function_ref(F*) -> function_ref<F>;
10605
+ template<auto f>
10606
+ function_ref(nontype_t<f>) -> function_ref<see below>;
10607
+ template<auto f, class T>
10608
+ function_ref(nontype_t<f>, T&&) -> function_ref<see below>;
10609
+ }
10610
+ ```
10611
+
10612
+ An object of class `function_ref<R(Args...) cv noexcept(noex)>` stores a
10613
+ pointer to function *`thunk-ptr`* and an object *`bound-entity`*. The
10614
+ object *`bound-entity`* has an unspecified trivially copyable type
10615
+ *`BoundEntityType`*, that models `copyable` and is capable of storing a
10616
+ pointer to object value or a pointer to function value. The type of
10617
+ *`thunk-ptr`* is `R(*)(BoundEntityType, Args&&...) noexcept(noex)`.
10618
+
10619
+ Each specialization of `function_ref` is a trivially copyable type
10620
+ [[term.trivially.copyable.type]] that models `copyable`.
10621
+
10622
+ Within subclause  [[func.wrap.ref]], `call-args` is an argument pack
10623
+ with elements such that
10624
+
10625
+ ``` cpp
10626
+ decltype((call-args))...
10627
+ ```
10628
+
10629
+ denote `ArgTypes&&...` respectively.
10630
+
10631
+ ##### Constructors and assignment operators <a id="func.wrap.ref.ctor">[[func.wrap.ref.ctor]]</a>
10632
+
10633
+ ``` cpp
10634
+ template<class... T>
10635
+ static constexpr bool is-invocable-using = see below;
10636
+ ```
10637
+
10638
+ If *noex* is `true`, *`is-invocable-using`*`<T...>` is equal to:
10639
+
10640
+ ``` cpp
10641
+ is_nothrow_invocable_r_v<R, T..., ArgTypes...>
10642
+ ```
10643
+
10644
+ Otherwise, *`is-invocable-using`*`<T...>` is equal to:
10645
+
10646
+ ``` cpp
10647
+ is_invocable_r_v<R, T..., ArgTypes...>
10648
+ ```
10649
+
10650
+ ``` cpp
10651
+ template<class F> function_ref(F* f) noexcept;
10652
+ ```
10653
+
10654
+ *Constraints:*
10655
+
10656
+ - `is_function_v<F>` is `true`, and
10657
+ - *`is-invocable-using`*`<F>` is `true`.
10658
+
10659
+ *Preconditions:* `f` is not a null pointer.
10660
+
10661
+ *Effects:* Initializes *bound-entity* with `f`, and *thunk-ptr* with the
10662
+ address of a function *`thunk`* such that
10663
+ *`thunk`*`(`*`bound-entity`*`, `*`call-args`*`...)` is
10664
+ expression-equivalent [[defns.expression.equivalent]] to
10665
+ `invoke_r<R>(f, `*`call-args`*`...)`.
10666
+
10667
+ ``` cpp
10668
+ template<class F> constexpr function_ref(F&& f) noexcept;
10669
+ ```
10670
+
10671
+ Let `T` be `remove_reference_t<F>`.
10672
+
10673
+ *Constraints:*
10674
+
10675
+ - `remove_cvref_t<F>` is not the same type as `function_ref`,
10676
+ - `is_member_pointer_v<T>` is `false`, and
10677
+ - *`is-invocable-using`*`<cv T&>` is `true`.
10678
+
10679
+ *Effects:* Initializes *bound-entity* with `addressof(f)`, and
10680
+ *thunk-ptr* with the address of a function *`thunk`* such that
10681
+ *`thunk`*`(`*`bound-entity`*`, `*`call-args`*`...)` is
10682
+ expression-equivalent [[defns.expression.equivalent]] to
10683
+ `invoke_r<R>(static_cast<cv T&>(f), `*`call-args`*`...)`.
10684
+
10685
+ ``` cpp
10686
+ template<auto f> constexpr function_ref(nontype_t<f>) noexcept;
10687
+ ```
10688
+
10689
+ Let `F` be `decltype(f)`.
10690
+
10691
+ *Constraints:* *`is-invocable-using`*`<F>` is `true`.
10692
+
10693
+ *Mandates:* If `is_pointer_v<F> || is_member_pointer_v<F>` is `true`,
10694
+ then `f != nullptr` is `true`.
10695
+
10696
+ *Effects:* Initializes *bound-entity* with a pointer to an unspecified
10697
+ object or null pointer value, and *thunk-ptr* with the address of a
10698
+ function *`thunk`* such that
10699
+ *`thunk`*`(`*`bound-entity`*`, `*`call-args`*`...)` is
10700
+ expression-equivalent [[defns.expression.equivalent]] to
10701
+ `invoke_r<R>(f, `*`call-args`*`...)`.
10702
+
10703
+ ``` cpp
10704
+ template<auto f, class U>
10705
+ constexpr function_ref(nontype_t<f>, U&& obj) noexcept;
10706
+ ```
10707
+
10708
+ Let `T` be `remove_reference_t<U>` and `F` be `decltype(f)`.
10709
+
10710
+ *Constraints:*
10711
+
10712
+ - `is_rvalue_reference_v<U&&>` is `false`, and
10713
+ - *`is-invocable-using`*`<F, cv T&>` is `true`.
10714
+
10715
+ *Mandates:* If `is_pointer_v<F> || is_member_pointer_v<F>` is `true`,
10716
+ then `f != nullptr` is `true`.
10717
+
10718
+ *Effects:* Initializes *bound-entity* with `addressof(obj)`, and
10719
+ *thunk-ptr* with the address of a function *`thunk`* such that
10720
+ *`thunk`*`(`*`bound-entity`*`, `*`call-args`*`...)` is
10721
+ expression-equivalent [[defns.expression.equivalent]] to
10722
+ `invoke_r<R>(f, static_cast<cv T&>(obj), `*`call-args`*`...)`.
10723
+
10724
+ ``` cpp
10725
+ template<auto f, class T>
10726
+ constexpr function_ref(nontype_t<f>, cv T* obj) noexcept;
10727
+ ```
10728
+
10729
+ Let `F` be `decltype(f)`.
10730
+
10731
+ *Constraints:* *`is-invocable-using`*`<F, cv T*>` is `true`.
10732
+
10733
+ *Mandates:* If `is_pointer_v<F> || is_member_pointer_v<F>` is `true`,
10734
+ then `f != nullptr` is `true`.
10735
+
10736
+ *Preconditions:* If `is_member_pointer_v<F>` is `true`, `obj` is not a
10737
+ null pointer.
10738
+
10739
+ *Effects:* Initializes *bound-entity* with `obj`, and *thunk-ptr* with
10740
+ the address of a function *`thunk`* such that
10741
+ *`thunk`*`(`*`bound-entity`*`, `*`call-args`*`...)` is
10742
+ expression-equivalent [[defns.expression.equivalent]] to
10743
+ `invoke_r<R>(f, obj, `*`call-args`*`...)`.
10744
+
10745
+ ``` cpp
10746
+ template<class T> function_ref& operator=(T) = delete;
10747
+ ```
10748
+
10749
+ *Constraints:*
10750
+
10751
+ - `T` is not the same type as `function_ref`,
10752
+ - `is_pointer_v<T>` is `false`, and
10753
+ - `T` is not a specialization of `nontype_t`.
10754
+
10755
+ ##### Invocation <a id="func.wrap.ref.inv">[[func.wrap.ref.inv]]</a>
10756
+
10757
+ ``` cpp
10758
+ R operator()(ArgTypes... args) const noexcept(noex);
10759
+ ```
10760
+
10761
+ *Effects:* Equivalent to:
10762
+ `return `*`thunk-ptr`*`(`*`bound-entity`*`, std::forward<ArgTypes>(args)...);`
10763
+
10764
+ ##### Deduction guides <a id="func.wrap.ref.deduct">[[func.wrap.ref.deduct]]</a>
10765
+
10766
+ ``` cpp
10767
+ template<class F>
10768
+ function_ref(F*) -> function_ref<F>;
10769
+ ```
10770
+
10771
+ *Constraints:* `is_function_v<F>` is `true`.
10772
+
10773
+ ``` cpp
10774
+ template<auto f>
10775
+ function_ref(nontype_t<f>) -> function_ref<see below>;
10776
+ ```
10777
+
10778
+ Let `F` be `remove_pointer_t<decltype(f)>`.
10779
+
10780
+ *Constraints:* `is_function_v<F>` is `true`.
10781
+
10782
+ *Remarks:* The deduced type is `function_ref<F>`.
10783
+
10784
+ ``` cpp
10785
+ template<auto f, class T>
10786
+ function_ref(nontype_t<f>, T&&) -> function_ref<see below>;
10787
+ ```
10788
+
10789
+ Let `F` be `decltype(f)`.
10790
+
10791
+ *Constraints:*
10792
+
10793
+ - `F` is of the form `R(G::*)(A...) cv `\\ₒₚₜ ` noexcept(E)` for a type
10794
+ `G`, or
10795
+ - `F` is of the form `M G::*` for a type `G` and an object type `M`, in
10796
+ which case let `R` be `invoke_result_t<F, T&>`, `A...` be an empty
10797
+ pack, and `E` be `false`, or
10798
+ - `F` is of the form `R(*)(G, A...) noexcept(E)` for a type `G`.
10799
+
10800
+ *Remarks:* The deduced type is `function_ref<R(A...) noexcept(E)>`.
10801
+
10802
  ### Searchers <a id="func.search">[[func.search]]</a>
10803
 
10804
  #### General <a id="func.search.general">[[func.search.general]]</a>
10805
 
10806
  Subclause [[func.search]] provides function object types
 
10912
  Hash hf = Hash(),
10913
  BinaryPredicate pred = BinaryPredicate());
10914
  ```
10915
 
10916
  *Preconditions:* The value type of `RandomAccessIterator1` meets the
10917
+ *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*, and
10918
  *Cpp17CopyAssignable* requirements.
10919
 
10920
  Let `V` be `iterator_traits<RandomAccessIterator1>::value_type`. For any
10921
  two values `A` and `B` of type `V`, if `pred(A, B) == true`, then
10922
  `hf(A) == hf(B)` is `true`.
 
11079
  - meet the requirement that the expression `h(k)`, where `h` is an
11080
  object of type `hash<Key>` and `k` is an object of type `Key`, shall
11081
  not throw an exception unless `hash<Key>` is a program-defined
11082
  specialization.
11083
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11084
  ## Bit manipulation <a id="bit">[[bit]]</a>
11085
 
11086
  ### General <a id="bit.general">[[bit.general]]</a>
11087
 
11088
  The header `<bit>` provides components to access, manipulate and process
 
11111
  template<class T>
11112
  constexpr int bit_width(T x) noexcept;
11113
 
11114
  // [bit.rotate], rotating
11115
  template<class T>
11116
+ constexpr T rotl(T x, int s) noexcept;
11117
  template<class T>
11118
+ constexpr T rotr(T x, int s) noexcept;
11119
 
11120
  // [bit.count], counting
11121
  template<class T>
11122
  constexpr int countl_zero(T x) noexcept;
11123
  template<class T>
 
11149
 
11150
  - `sizeof(To) == sizeof(From)` is `true`;
11151
  - `is_trivially_copyable_v<To>` is `true`; and
11152
  - `is_trivially_copyable_v<From>` is `true`.
11153
 
11154
+ *Mandates:* Neither `To` nor `From` are consteval-only
11155
+ types [[basic.types.general]].
11156
+
11157
+ `To`, `From`, and the types of all subobjects of `To` and `From` are
11158
+ types `T` such that:
11159
+
11160
+ - `is_union_v<T>` is `false`;
11161
+ - `is_pointer_v<T>` is `false`;
11162
+ - `is_member_pointer_v<T>` is `false`;
11163
+ - `is_volatile_v<T>` is `false`; and
11164
+ - `T` has no non-static data members of reference type.
11165
+
11166
  *Returns:* An object of type `To`. Implicitly creates objects nested
11167
  within the result [[intro.object]]. Each bit of the value representation
11168
  of the result is equal to the corresponding bit in the object
11169
  representation of `from`. Padding bits of the result are unspecified.
11170
  For the result and each object created within it, if there is no value
11171
  of the object’s type corresponding to the value representation produced,
11172
  the behavior is undefined. If there are multiple such values, which
11173
  value is produced is unspecified. A bit in the value representation of
11174
  the result is indeterminate if it does not correspond to a bit in the
11175
+ value representation of `from` or corresponds to a bit for which the
11176
+ smallest enclosing object is not within its lifetime or has an
11177
+ indeterminate value [[basic.indet]]. A bit in the value representation
11178
+ of the result is erroneous if it corresponds to a bit for which the
11179
+ smallest enclosing object has an erroneous value. For each bit b in the
11180
+ value representation of the result that is indeterminate or erroneous,
11181
+ let u be the smallest object containing that bit enclosing b:
11182
 
11183
+ - If u is of unsigned ordinary character type or `std::byte` type, u has
11184
+ an indeterminate value if any of the bits in its value representation
11185
+ are indeterminate, or otherwise has an erroneous value.
11186
+ - Otherwise, if b is indeterminate, the behavior is undefined.
11187
+ - Otherwise, the behavior is erroneous, and the result is as specified
11188
+ above.
11189
 
11190
+ The result does not otherwise contain any indeterminate or erroneous
11191
+ values.
 
 
 
11192
 
11193
  ### `byteswap` <a id="bit.byteswap">[[bit.byteswap]]</a>
11194
 
11195
  ``` cpp
11196
  template<class T>
 
11263
  In the following descriptions, let `N` denote
11264
  `numeric_limits<T>::digits`.
11265
 
11266
  ``` cpp
11267
  template<class T>
11268
+ constexpr T rotl(T x, int s) noexcept;
11269
  ```
11270
 
11271
  *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
11272
 
11273
  Let `r` be `s % N`.
 
11275
  *Returns:* If `r` is `0`, `x`; if `r` is positive,
11276
  `(x << r) | (x >> (N - r))`; if `r` is negative, `rotr(x, -r)`.
11277
 
11278
  ``` cpp
11279
  template<class T>
11280
+ constexpr T rotr(T x, int s) noexcept;
11281
  ```
11282
 
11283
  *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
11284
 
11285
  Let `r` be `s % N`.
 
11375
  big-endian, `endian::native` is equal to `endian::big`. If all scalar
11376
  types are little-endian, `endian::native` is equal to `endian::little`.
11377
  Otherwise, `endian::native` is not equal to either `endian::big` or
11378
  `endian::little`.
11379
 
11380
+ ## Header `<stdbit.h>` synopsis <a id="stdbit.h.syn">[[stdbit.h.syn]]</a>
11381
+
11382
+ ``` cpp
11383
+ // all freestanding
11384
+
11385
+ #define __STDC_VERSION_STDBIT_H__ 202311L
11386
+
11387
+ #define __STDC_ENDIAN_BIG__ see below
11388
+ #define __STDC_ENDIAN_LITTLE__ see below
11389
+ #define __STDC_ENDIAN_NATIVE__ see below
11390
+
11391
+ unsigned int stdc_leading_zeros_uc(unsigned char value);
11392
+ unsigned int stdc_leading_zeros_us(unsigned short value);
11393
+ unsigned int stdc_leading_zeros_ui(unsigned int value);
11394
+ unsigned int stdc_leading_zeros_ul(unsigned long int value);
11395
+ unsigned int stdc_leading_zeros_ull(unsigned long long int value);
11396
+ template<class T> see below stdc_leading_zeros(T value);
11397
+
11398
+ unsigned int stdc_leading_ones_uc(unsigned char value);
11399
+ unsigned int stdc_leading_ones_us(unsigned short value);
11400
+ unsigned int stdc_leading_ones_ui(unsigned int value);
11401
+ unsigned int stdc_leading_ones_ul(unsigned long int value);
11402
+ unsigned int stdc_leading_ones_ull(unsigned long long int value);
11403
+ template<class T> see below stdc_leading_ones(T value);
11404
+
11405
+ unsigned int stdc_trailing_zeros_uc(unsigned char value);
11406
+ unsigned int stdc_trailing_zeros_us(unsigned short value);
11407
+ unsigned int stdc_trailing_zeros_ui(unsigned int value);
11408
+ unsigned int stdc_trailing_zeros_ul(unsigned long int value);
11409
+ unsigned int stdc_trailing_zeros_ull(unsigned long long int value);
11410
+ template<class T> see below stdc_trailing_zeros(T value);
11411
+
11412
+ unsigned int stdc_trailing_ones_uc(unsigned char value);
11413
+ unsigned int stdc_trailing_ones_us(unsigned short value);
11414
+ unsigned int stdc_trailing_ones_ui(unsigned int value);
11415
+ unsigned int stdc_trailing_ones_ul(unsigned long int value);
11416
+ unsigned int stdc_trailing_ones_ull(unsigned long long int value);
11417
+ template<class T> see below stdc_trailing_ones(T value);
11418
+
11419
+ unsigned int stdc_first_leading_zero_uc(unsigned char value);
11420
+ unsigned int stdc_first_leading_zero_us(unsigned short value);
11421
+ unsigned int stdc_first_leading_zero_ui(unsigned int value);
11422
+ unsigned int stdc_first_leading_zero_ul(unsigned long int value);
11423
+ unsigned int stdc_first_leading_zero_ull(unsigned long long int value);
11424
+ template<class T> see below stdc_first_leading_zero(T value);
11425
+
11426
+ unsigned int stdc_first_leading_one_uc(unsigned char value);
11427
+ unsigned int stdc_first_leading_one_us(unsigned short value);
11428
+ unsigned int stdc_first_leading_one_ui(unsigned int value);
11429
+ unsigned int stdc_first_leading_one_ul(unsigned long int value);
11430
+ unsigned int stdc_first_leading_one_ull(unsigned long long int value);
11431
+ template<class T> see below stdc_first_leading_one(T value);
11432
+
11433
+ unsigned int stdc_first_trailing_zero_uc(unsigned char value);
11434
+ unsigned int stdc_first_trailing_zero_us(unsigned short value);
11435
+ unsigned int stdc_first_trailing_zero_ui(unsigned int value);
11436
+ unsigned int stdc_first_trailing_zero_ul(unsigned long int value);
11437
+ unsigned int stdc_first_trailing_zero_ull(unsigned long long int value);
11438
+ template<class T> see below stdc_first_trailing_zero(T value);
11439
+
11440
+ unsigned int stdc_first_trailing_one_uc(unsigned char value);
11441
+ unsigned int stdc_first_trailing_one_us(unsigned short value);
11442
+ unsigned int stdc_first_trailing_one_ui(unsigned int value);
11443
+ unsigned int stdc_first_trailing_one_ul(unsigned long int value);
11444
+ unsigned int stdc_first_trailing_one_ull(unsigned long long int value);
11445
+ template<class T> see below stdc_first_trailing_one(T value);
11446
+
11447
+ unsigned int stdc_count_zeros_uc(unsigned char value);
11448
+ unsigned int stdc_count_zeros_us(unsigned short value);
11449
+ unsigned int stdc_count_zeros_ui(unsigned int value);
11450
+ unsigned int stdc_count_zeros_ul(unsigned long int value);
11451
+ unsigned int stdc_count_zeros_ull(unsigned long long int value);
11452
+ template<class T> see below stdc_count_zeros(T value);
11453
+
11454
+ unsigned int stdc_count_ones_uc(unsigned char value);
11455
+ unsigned int stdc_count_ones_us(unsigned short value);
11456
+ unsigned int stdc_count_ones_ui(unsigned int value);
11457
+ unsigned int stdc_count_ones_ul(unsigned long int value);
11458
+ unsigned int stdc_count_ones_ull(unsigned long long int value);
11459
+ template<class T> see below stdc_count_ones(T value);
11460
+
11461
+ bool stdc_has_single_bit_uc(unsigned char value);
11462
+ bool stdc_has_single_bit_us(unsigned short value);
11463
+ bool stdc_has_single_bit_ui(unsigned int value);
11464
+ bool stdc_has_single_bit_ul(unsigned long int value);
11465
+ bool stdc_has_single_bit_ull(unsigned long long int value);
11466
+ template<class T> bool stdc_has_single_bit(T value);
11467
+
11468
+ unsigned int stdc_bit_width_uc(unsigned char value);
11469
+ unsigned int stdc_bit_width_us(unsigned short value);
11470
+ unsigned int stdc_bit_width_ui(unsigned int value);
11471
+ unsigned int stdc_bit_width_ul(unsigned long int value);
11472
+ unsigned int stdc_bit_width_ull(unsigned long long int value);
11473
+ template<class T> see below stdc_bit_width(T value);
11474
+
11475
+ unsigned char stdc_bit_floor_uc(unsigned char value);
11476
+ unsigned short stdc_bit_floor_us(unsigned short value);
11477
+ unsigned int stdc_bit_floor_ui(unsigned int value);
11478
+ unsigned long int stdc_bit_floor_ul(unsigned long int value);
11479
+ unsigned long long int stdc_bit_floor_ull(unsigned long long int value);
11480
+ template<class T> T stdc_bit_floor(T value);
11481
+
11482
+ unsigned char stdc_bit_ceil_uc(unsigned char value);
11483
+ unsigned short stdc_bit_ceil_us(unsigned short value);
11484
+ unsigned int stdc_bit_ceil_ui(unsigned int value);
11485
+ unsigned long int stdc_bit_ceil_ul(unsigned long int value);
11486
+ unsigned long long int stdc_bit_ceil_ull(unsigned long long int value);
11487
+ template<class T> T stdc_bit_ceil(T value);
11488
+ ```
11489
+
11490
+ For a function template whose return type is not specified above, the
11491
+ return type is an *implementation-defined* unsigned integer type large
11492
+ enough to represent all possible result values. Each function template
11493
+ has the same semantics as the corresponding type-generic function with
11494
+ the same name specified in See also: ISO C 7.18.
11495
+
11496
+ *Mandates:* `T` is an unsigned integer type.
11497
+
11498
+ Otherwise, the contents and meaning of the header `<stdbit.h>` are the
11499
+ same as the C standard library header `<stdbit.h>`.
11500
+
11501
+ See also: ISO C 7.18
11502
+
11503
  <!-- Link reference definitions -->
11504
  [algorithms]: algorithms.md#algorithms
11505
  [algorithms.general]: algorithms.md#algorithms.general
 
11506
  [allocator.requirements.general]: library.md#allocator.requirements.general
11507
  [allocator.uses.construction]: mem.md#allocator.uses.construction
11508
  [any]: #any
11509
  [any.assign]: #any.assign
11510
  [any.bad.any.cast]: #any.bad.any.cast
 
11522
  [arithmetic.operations.minus]: #arithmetic.operations.minus
11523
  [arithmetic.operations.modulus]: #arithmetic.operations.modulus
11524
  [arithmetic.operations.multiplies]: #arithmetic.operations.multiplies
11525
  [arithmetic.operations.negate]: #arithmetic.operations.negate
11526
  [arithmetic.operations.plus]: #arithmetic.operations.plus
 
11527
  [basic.fundamental]: basic.md#basic.fundamental
11528
  [basic.indet]: basic.md#basic.indet
11529
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
11530
  [basic.types.general]: basic.md#basic.types.general
11531
  [bit]: #bit
 
11535
  [bit.endian]: #bit.endian
11536
  [bit.general]: #bit.general
11537
  [bit.pow.two]: #bit.pow.two
11538
  [bit.rotate]: #bit.rotate
11539
  [bit.syn]: #bit.syn
 
11540
  [bitset]: #bitset
11541
  [bitset.cons]: #bitset.cons
11542
  [bitset.hash]: #bitset.hash
11543
  [bitset.members]: #bitset.members
11544
  [bitset.operators]: #bitset.operators
 
11547
  [bitwise.operations.and]: #bitwise.operations.and
11548
  [bitwise.operations.general]: #bitwise.operations.general
11549
  [bitwise.operations.not]: #bitwise.operations.not
11550
  [bitwise.operations.or]: #bitwise.operations.or
11551
  [bitwise.operations.xor]: #bitwise.operations.xor
 
 
 
 
11552
  [class.base.init]: class.md#class.base.init
11553
  [class.copy.ctor]: class.md#class.copy.ctor
11554
  [comparisons]: #comparisons
11555
  [comparisons.equal.to]: #comparisons.equal.to
11556
  [comparisons.general]: #comparisons.general
 
11559
  [comparisons.less]: #comparisons.less
11560
  [comparisons.less.equal]: #comparisons.less.equal
11561
  [comparisons.not.equal.to]: #comparisons.not.equal.to
11562
  [comparisons.three.way]: #comparisons.three.way
11563
  [concepts.equality]: concepts.md#concepts.equality
11564
+ [container.reqmts]: containers.md#container.reqmts
11565
  [cpp17.copyassignable]: #cpp17.copyassignable
 
11566
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
11567
  [cpp17.destructible]: #cpp17.destructible
11568
  [cpp17.hash]: #cpp17.hash
11569
  [cpp17.moveassignable]: #cpp17.moveassignable
11570
  [cpp17.moveconstructible]: #cpp17.moveconstructible
11571
  [dcl.constexpr]: dcl.md#dcl.constexpr
11572
  [dcl.init.general]: dcl.md#dcl.init.general
11573
  [declval]: #declval
11574
  [defns.expression.equivalent]: intro.md#defns.expression.equivalent
 
11575
  [defns.order.ptr]: #defns.order.ptr
11576
  [defns.referenceable]: intro.md#defns.referenceable
 
 
 
 
 
 
 
 
 
 
11577
  [expected]: #expected
11578
  [expected.bad]: #expected.bad
11579
  [expected.bad.void]: #expected.bad.void
11580
  [expected.expected]: #expected.expected
11581
  [expected.general]: #expected.general
 
11613
  [expr.mul]: expr.md#expr.mul
11614
  [expr.or]: expr.md#expr.or
11615
  [expr.rel]: expr.md#expr.rel
11616
  [expr.unary.op]: expr.md#expr.unary.op
11617
  [expr.xor]: expr.md#expr.xor
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11618
  [forward]: #forward
11619
  [freestanding.item]: library.md#freestanding.item
11620
  [func.bind]: #func.bind
11621
  [func.bind.bind]: #func.bind.bind
11622
  [func.bind.general]: #func.bind.general
 
11635
  [func.search.bmh]: #func.search.bmh
11636
  [func.search.default]: #func.search.default
11637
  [func.search.general]: #func.search.general
11638
  [func.wrap]: #func.wrap
11639
  [func.wrap.badcall]: #func.wrap.badcall
11640
+ [func.wrap.copy]: #func.wrap.copy
11641
+ [func.wrap.copy.class]: #func.wrap.copy.class
11642
+ [func.wrap.copy.ctor]: #func.wrap.copy.ctor
11643
+ [func.wrap.copy.general]: #func.wrap.copy.general
11644
+ [func.wrap.copy.inv]: #func.wrap.copy.inv
11645
+ [func.wrap.copy.util]: #func.wrap.copy.util
11646
  [func.wrap.func]: #func.wrap.func
11647
  [func.wrap.func.alg]: #func.wrap.func.alg
11648
  [func.wrap.func.cap]: #func.wrap.func.cap
11649
  [func.wrap.func.con]: #func.wrap.func.con
11650
  [func.wrap.func.general]: #func.wrap.func.general
 
11657
  [func.wrap.move.class]: #func.wrap.move.class
11658
  [func.wrap.move.ctor]: #func.wrap.move.ctor
11659
  [func.wrap.move.general]: #func.wrap.move.general
11660
  [func.wrap.move.inv]: #func.wrap.move.inv
11661
  [func.wrap.move.util]: #func.wrap.move.util
11662
+ [func.wrap.ref]: #func.wrap.ref
11663
+ [func.wrap.ref.class]: #func.wrap.ref.class
11664
+ [func.wrap.ref.ctor]: #func.wrap.ref.ctor
11665
+ [func.wrap.ref.deduct]: #func.wrap.ref.deduct
11666
+ [func.wrap.ref.general]: #func.wrap.ref.general
11667
+ [func.wrap.ref.inv]: #func.wrap.ref.inv
11668
  [function.objects]: #function.objects
11669
  [function.objects.general]: #function.objects.general
11670
  [functional.syn]: #functional.syn
11671
+ [intro.abstract]: intro.md#intro.abstract
11672
  [intro.multithread]: basic.md#intro.multithread
11673
  [intro.object]: basic.md#intro.object
11674
  [invalid.argument]: diagnostics.md#invalid.argument
11675
  [istream.formatted]: input.md#istream.formatted
11676
+ [iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
11677
+ [iterator.requirements.general]: iterators.md#iterator.requirements.general
11678
+ [lex.ccon]: lex.md#lex.ccon
11679
  [logical.operations]: #logical.operations
11680
  [logical.operations.and]: #logical.operations.and
11681
  [logical.operations.general]: #logical.operations.general
11682
  [logical.operations.not]: #logical.operations.not
11683
  [logical.operations.or]: #logical.operations.or
11684
  [meta.rqmts]: meta.md#meta.rqmts
11685
  [meta.trans.other]: meta.md#meta.trans.other
 
11686
  [optional]: #optional
11687
  [optional.assign]: #optional.assign
11688
  [optional.assign.copy]: #optional.assign.copy
11689
  [optional.assign.copy.templ]: #optional.assign.copy.templ
11690
  [optional.assign.move]: #optional.assign.move
 
11693
  [optional.comp.with.t]: #optional.comp.with.t
11694
  [optional.ctor]: #optional.ctor
11695
  [optional.dtor]: #optional.dtor
11696
  [optional.general]: #optional.general
11697
  [optional.hash]: #optional.hash
11698
+ [optional.iterators]: #optional.iterators
11699
  [optional.mod]: #optional.mod
11700
  [optional.monadic]: #optional.monadic
11701
  [optional.nullops]: #optional.nullops
11702
  [optional.nullopt]: #optional.nullopt
11703
  [optional.observe]: #optional.observe
11704
  [optional.optional]: #optional.optional
11705
  [optional.optional.general]: #optional.optional.general
11706
+ [optional.optional.ref]: #optional.optional.ref
11707
+ [optional.optional.ref.general]: #optional.optional.ref.general
11708
+ [optional.ref.assign]: #optional.ref.assign
11709
+ [optional.ref.ctor]: #optional.ref.ctor
11710
+ [optional.ref.expos]: #optional.ref.expos
11711
+ [optional.ref.iterators]: #optional.ref.iterators
11712
+ [optional.ref.mod]: #optional.ref.mod
11713
+ [optional.ref.monadic]: #optional.ref.monadic
11714
+ [optional.ref.observe]: #optional.ref.observe
11715
+ [optional.ref.swap]: #optional.ref.swap
11716
  [optional.relops]: #optional.relops
11717
  [optional.specalg]: #optional.specalg
11718
  [optional.swap]: #optional.swap
11719
  [optional.syn]: #optional.syn
11720
  [ostream.formatted]: input.md#ostream.formatted
 
11725
  [pair.piecewise]: #pair.piecewise
11726
  [pairs]: #pairs
11727
  [pairs.general]: #pairs.general
11728
  [pairs.pair]: #pairs.pair
11729
  [pairs.spec]: #pairs.spec
11730
+ [random.access.iterators]: iterators.md#random.access.iterators
11731
  [range.cmp]: #range.cmp
11732
  [range.utility.helpers]: ranges.md#range.utility.helpers
11733
  [refwrap]: #refwrap
11734
  [refwrap.access]: #refwrap.access
11735
  [refwrap.assign]: #refwrap.assign
11736
  [refwrap.common.ref]: #refwrap.common.ref
11737
+ [refwrap.comparisons]: #refwrap.comparisons
11738
  [refwrap.const]: #refwrap.const
11739
  [refwrap.general]: #refwrap.general
11740
  [refwrap.helpers]: #refwrap.helpers
11741
  [refwrap.invoke]: #refwrap.invoke
11742
+ [stdbit.h.syn]: #stdbit.h.syn
 
11743
  [support.signal]: support.md#support.signal
11744
  [swappable.requirements]: library.md#swappable.requirements
11745
+ [temp.constr.atomic]: temp.md#temp.constr.atomic
11746
+ [temp.point]: temp.md#temp.point
11747
  [temp.type]: temp.md#temp.type
11748
  [template.bitset]: #template.bitset
11749
  [template.bitset.general]: #template.bitset.general
11750
  [term.object.representation]: basic.md#term.object.representation
11751
  [term.object.type]: basic.md#term.object.type
11752
  [term.odr.use]: basic.md#term.odr.use
11753
  [term.perfect.forwarding.call.wrapper]: #term.perfect.forwarding.call.wrapper
11754
  [term.simple.call.wrapper]: #term.simple.call.wrapper
11755
+ [term.structural.type]: temp.md#term.structural.type
11756
  [term.trivially.copyable.type]: basic.md#term.trivially.copyable.type
11757
  [term.unevaluated.operand]: expr.md#term.unevaluated.operand
 
11758
  [tuple]: #tuple
11759
  [tuple.apply]: #tuple.apply
11760
  [tuple.assign]: #tuple.assign
11761
  [tuple.cnstr]: #tuple.cnstr
11762
  [tuple.common.ref]: #tuple.common.ref
 
11769
  [tuple.special]: #tuple.special
11770
  [tuple.swap]: #tuple.swap
11771
  [tuple.syn]: #tuple.syn
11772
  [tuple.traits]: #tuple.traits
11773
  [tuple.tuple]: #tuple.tuple
11774
+ [tuple.tuple.general]: #tuple.tuple.general
 
 
 
 
11775
  [unord]: containers.md#unord
11776
  [unord.hash]: #unord.hash
11777
  [utilities]: #utilities
11778
  [utilities.general]: #utilities.general
11779
  [utilities.summary]: #utilities.summary
 
11781
  [utility.as.const]: #utility.as.const
11782
  [utility.exchange]: #utility.exchange
11783
  [utility.intcmp]: #utility.intcmp
11784
  [utility.swap]: #utility.swap
11785
  [utility.syn]: #utility.syn
11786
+ [utility.undefined]: #utility.undefined
11787
  [utility.underlying]: #utility.underlying
 
11788
  [variant]: #variant
11789
  [variant.assign]: #variant.assign
11790
  [variant.bad.access]: #variant.bad.access
11791
  [variant.ctor]: #variant.ctor
11792
  [variant.dtor]: #variant.dtor
 
11807
  [variant.visit]: #variant.visit
11808
 
11809
  [^1]: Such a type is a function pointer or a class type which has a
11810
  member `operator()` or a class type which has a conversion to a
11811
  pointer to function.