From Jason Turner

[utilities]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpthftzfjo/{from.md → to.md} +5375 -7286
tmp/tmpthftzfjo/{from.md → to.md} RENAMED
@@ -8,40 +8,36 @@ 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
- | [[intseq]] | Compile-time integer sequences | |
16
  | [[pairs]] | Pairs | |
17
  | [[tuple]] | Tuples | `<tuple>` |
18
  | [[optional]] | Optional objects | `<optional>` |
19
  | [[variant]] | Variants | `<variant>` |
20
  | [[any]] | Storage for any type | `<any>` |
 
21
  | [[bitset]] | Fixed-size sequences of bits | `<bitset>` |
22
- | [[memory]] | Memory | `<cstdlib>`, `<memory>` |
23
- | [[smartptr]] | Smart pointers | `<memory>` |
24
- | [[mem.res]] | Memory resources | `<memory_resource>` |
25
- | [[allocator.adaptor]] | Scoped allocators | `<scoped_allocator>` |
26
  | [[function.objects]] | Function objects | `<functional>` |
27
- | [[meta]] | Type traits | `<type_traits>` |
28
- | [[ratio]] | Compile-time rational arithmetic | `<ratio>` |
29
  | [[type.index]] | Type indexes | `<typeindex>` |
30
  | [[execpol]] | Execution policies | `<execution>` |
31
  | [[charconv]] | Primitive numeric conversions | `<charconv>` |
32
  | [[format]] | Formatting | `<format>` |
 
33
 
34
 
35
  ## Utility components <a id="utility">[[utility]]</a>
36
 
37
  ### Header `<utility>` synopsis <a id="utility.syn">[[utility.syn]]</a>
38
 
39
  The header `<utility>` contains some basic function and class templates
40
  that are used throughout the rest of the library.
41
 
42
  ``` cpp
 
43
  #include <compare> // see [compare.syn]
44
  #include <initializer_list> // see [initializer.list.syn]
45
 
46
  namespace std {
47
  // [utility.swap], swap
@@ -50,17 +46,19 @@ namespace std {
50
  template<class T, size_t N>
51
  constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);
52
 
53
  // [utility.exchange], exchange
54
  template<class T, class U = T>
55
- constexpr T exchange(T& obj, U&& new_val);
56
 
57
  // [forward], forward/move
58
  template<class T>
59
  constexpr T&& forward(remove_reference_t<T>& t) noexcept;
60
  template<class T>
61
  constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
 
 
62
  template<class T>
63
  constexpr remove_reference_t<T>&& move(T&&) noexcept;
64
  template<class T>
65
  constexpr conditional_t<
66
  !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>
@@ -92,10 +90,17 @@ namespace std {
92
  constexpr bool cmp_greater_equal(T t, U u) noexcept;
93
 
94
  template<class R, class T>
95
  constexpr bool in_range(T t) noexcept;
96
 
 
 
 
 
 
 
 
97
  // [intseq], compile-time integer sequences%
98
  %
99
  %
100
 
101
  template<class T, T...>
@@ -113,20 +118,38 @@ namespace std {
113
 
114
  // [pairs], class template pair
115
  template<class T1, class T2>
116
  struct pair;
117
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
118
  // [pairs.spec], pair specialized algorithms
119
- template<class T1, class T2>
120
- constexpr bool operator==(const pair<T1, T2>&, const pair<T1, T2>&);
121
- template<class T1, class T2>
122
- constexpr common_comparison_category_t<synth-three-way-result<T1>,
123
- synth-three-way-result<T2>>
124
- operator<=>(const pair<T1, T2>&, const pair<T1, T2>&);
125
 
126
  template<class T1, class T2>
127
  constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
 
 
 
128
 
129
  template<class T1, class T2>
130
  constexpr see below make_pair(T1&&, T2&&);
131
 
132
  // [pair.astuple], tuple-like access to pair
@@ -182,17 +205,17 @@ namespace std {
182
 
183
  template<class T>
184
  struct in_place_type_t {
185
  explicit in_place_type_t() = default;
186
  };
187
- template<class T> inline constexpr in_place_type_t<T> in_place_type{};
188
 
189
  template<size_t I>
190
  struct in_place_index_t {
191
  explicit in_place_index_t() = default;
192
  };
193
- template<size_t I> inline constexpr in_place_index_t<I> in_place_index{};
194
  }
195
  ```
196
 
197
  ### `swap` <a id="utility.swap">[[utility.swap]]</a>
198
 
@@ -208,13 +231,11 @@ template<class T>
208
  ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
209
  ([[cpp17.moveassignable]]) requirements.
210
 
211
  *Effects:* Exchanges values stored in two locations.
212
 
213
- *Remarks:* This function is a designated customization
214
- point [[namespace.std]]. The expression inside `noexcept` is equivalent
215
- to:
216
 
217
  ``` cpp
218
  is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>
219
  ```
220
 
@@ -232,21 +253,27 @@ template<class T, size_t N>
232
 
233
  ### `exchange` <a id="utility.exchange">[[utility.exchange]]</a>
234
 
235
  ``` cpp
236
  template<class T, class U = T>
237
- constexpr T exchange(T& obj, U&& new_val);
238
  ```
239
 
240
  *Effects:* Equivalent to:
241
 
242
  ``` cpp
243
  T old_val = std::move(obj);
244
  obj = std::forward<U>(new_val);
245
  return old_val;
246
  ```
247
 
 
 
 
 
 
 
248
  ### Forward/move helpers <a id="forward">[[forward]]</a>
249
 
250
  The library provides templated helper functions to simplify applying
251
  move semantics to an lvalue and to simplify the implementation of
252
  forwarding functions. All functions specified in this subclause are
@@ -287,17 +314,58 @@ forwarded to `A`’s constructor as an rvalue. In the second call to
287
  constructor as an lvalue. In both cases, `A2` is deduced as `double`, so
288
  1.414 is forwarded to `A`’s constructor as an rvalue.
289
 
290
  — *end example*]
291
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
292
  ``` cpp
293
  template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;
294
  ```
295
 
296
  *Returns:* `static_cast<remove_reference_t<T>&&>(t)`.
297
 
298
- [*Example 2*:
299
 
300
  ``` cpp
301
  template<class T, class A1>
302
  shared_ptr<T> factory(A1&& a1) {
303
  return shared_ptr<T>(new T(std::forward<A1>(a1)));
@@ -310,11 +378,11 @@ struct A {
310
  };
311
 
312
  void g() {
313
  A a;
314
  shared_ptr<A> sp1 = factory<A>(a); // ``a'' binds to A(const A&)
315
- shared_ptr<A> sp1 = factory<A>(std::move(a)); // ``a'' binds to A(A&&)
316
  }
317
  ```
318
 
319
  In the first call to `factory`, `A1` is deduced as `A&`, so `a` is
320
  forwarded as a non-const lvalue. This binds to the constructor
@@ -343,17 +411,17 @@ template<class T> constexpr add_const_t<T>& as_const(T& t) noexcept;
343
 
344
  ### Function template `declval` <a id="declval">[[declval]]</a>
345
 
346
  The library provides the function template `declval` to simplify the
347
  definition of expressions which occur as unevaluated operands
348
- [[expr.prop]].
349
 
350
  ``` cpp
351
  template<class T> add_rvalue_reference_t<T> declval() noexcept; // as unevaluated operand
352
  ```
353
 
354
- *Mandates:* This function is not odr-used [[basic.def.odr]].
355
 
356
  *Remarks:* The template parameter `T` of `declval` may be an incomplete
357
  type.
358
 
359
  [*Example 1*:
@@ -361,12 +429,12 @@ type.
361
  ``` cpp
362
  template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&);
363
  ```
364
 
365
  declares a function template `convert` which only participates in
366
- overloading if the type `From` can be explicitly converted to type `To`.
367
- For another example see class template `common_type`
368
  [[meta.trans.other]].
369
 
370
  — *end example*]
371
 
372
  ### Integer comparison functions <a id="utility.intcmp">[[utility.intcmp]]</a>
@@ -458,52 +526,47 @@ return cmp_greater_equal(t, numeric_limits<R>::min()) &&
458
 
459
  [*Note 1*: These function templates cannot be used to compare `byte`,
460
  `char`, `char8_t`, `char16_t`, `char32_t`, `wchar_t`, and
461
  `bool`. — *end note*]
462
 
463
- ## Compile-time integer sequences <a id="intseq">[[intseq]]</a>
464
 
465
- ### In general <a id="intseq.general">[[intseq.general]]</a>
466
-
467
- The library provides a class template that can represent an integer
468
- sequence. When used as an argument to a function template the template
469
- parameter pack defining the sequence can be deduced and used in a pack
470
- expansion.
471
 
472
- [*Note 1*: The `index_sequence` alias template is provided for the
473
- common case of an integer sequence of type `size_t`; see also
474
- [[tuple.apply]]. — *end note*]
475
 
476
- ### Class template `integer_sequence` <a id="intseq.intseq">[[intseq.intseq]]</a>
477
 
478
  ``` cpp
479
- namespace std {
480
- template<class T, T... I> struct integer_sequence {
481
- using value_type = T;
482
- static constexpr size_t size() noexcept { return sizeof...(I); }
483
- };
484
- }
485
  ```
486
 
487
- *Mandates:* `T` is an integer type.
 
 
 
488
 
489
- ### Alias template `make_integer_sequence` <a id="intseq.make">[[intseq.make]]</a>
490
 
491
  ``` cpp
492
- template<class T, T N>
493
- using make_integer_sequence = integer_sequence<T, see below>;
 
 
 
 
 
 
 
 
 
494
  ```
495
 
496
- *Mandates:* `N` ≥ 0.
497
-
498
- The alias template `make_integer_sequence` denotes a specialization of
499
- `integer_sequence` with `N` non-type template arguments. The type
500
- `make_integer_sequence<T, N>` is an alias for the type
501
- `integer_sequence<T, 0, 1, ..., N-1>`.
502
-
503
- [*Note 1*: `make_integer_sequence<int, 0>` is an alias for the type
504
- `integer_sequence<int>`. — *end note*]
505
 
506
  ## Pairs <a id="pairs">[[pairs]]</a>
507
 
508
  ### In general <a id="pairs.general">[[pairs.general]]</a>
509
 
@@ -527,28 +590,45 @@ namespace std {
527
 
528
  pair(const pair&) = default;
529
  pair(pair&&) = default;
530
  constexpr explicit(see below) pair();
531
  constexpr explicit(see below) pair(const T1& x, const T2& y);
532
- template<class U1, class U2>
533
  constexpr explicit(see below) pair(U1&& x, U2&& y);
 
 
534
  template<class U1, class U2>
535
  constexpr explicit(see below) pair(const pair<U1, U2>& p);
536
  template<class U1, class U2>
537
  constexpr explicit(see below) pair(pair<U1, U2>&& p);
 
 
 
 
538
  template<class... Args1, class... Args2>
539
  constexpr pair(piecewise_construct_t,
540
  tuple<Args1...> first_args, tuple<Args2...> second_args);
541
 
542
  constexpr pair& operator=(const pair& p);
 
543
  template<class U1, class U2>
544
  constexpr pair& operator=(const pair<U1, U2>& p);
 
 
545
  constexpr pair& operator=(pair&& p) noexcept(see below);
 
546
  template<class U1, class U2>
547
  constexpr pair& operator=(pair<U1, U2>&& p);
 
 
 
 
 
 
548
 
549
  constexpr void swap(pair& p) noexcept(see below);
 
550
  };
551
 
552
  template<class T1, class T2>
553
  pair(T1, T2) -> pair<T1, T2>;
554
  }
@@ -558,12 +638,12 @@ Constructors and member functions of `pair` do not throw exceptions
558
  unless one of the element-wise operations specified to be called for
559
  that operation throws an exception.
560
 
561
  The defaulted move and copy constructor, respectively, of `pair` is a
562
  constexpr function if and only if all required element-wise
563
- initializations for move and copy, respectively, would satisfy the
564
- requirements for a constexpr function.
565
 
566
  If
567
  `(is_trivially_destructible_v<T1> && is_trivially_destructible_v<T2>)`
568
  is `true`, then the destructor of `pair` is trivial.
569
 
@@ -577,135 +657,168 @@ template-argument-equivalent [[temp.type]] if and only if `p1.first` and
577
  constexpr explicit(see below) pair();
578
  ```
579
 
580
  *Constraints:*
581
 
582
- - `is_default_constructible_v<first_type>` is `true` and
583
- - `is_default_constructible_v<second_type>` is `true`.
584
 
585
  *Effects:* Value-initializes `first` and `second`.
586
 
587
  *Remarks:* The expression inside `explicit` evaluates to `true` if and
588
- only if either `first_type` or `second_type` is not implicitly
589
- default-constructible.
590
 
591
  [*Note 1*: This behavior can be implemented with a trait that checks
592
- whether a `const first_type&` or a `const second_type&` can be
593
- initialized with `{}`. — *end note*]
594
 
595
  ``` cpp
596
  constexpr explicit(see below) pair(const T1& x, const T2& y);
597
  ```
598
 
599
  *Constraints:*
600
 
601
- - `is_copy_constructible_v<first_type>` is `true` and
602
- - `is_copy_constructible_v<second_type>` is `true`.
603
 
604
  *Effects:* Initializes `first` with `x` and `second` with `y`.
605
 
606
  *Remarks:* The expression inside `explicit` is equivalent to:
607
 
608
  ``` cpp
609
- !is_convertible_v<const first_type&, first_type> ||
610
- !is_convertible_v<const second_type&, second_type>
611
  ```
612
 
613
  ``` cpp
614
- template<class U1, class U2> constexpr explicit(see below) pair(U1&& x, U2&& y);
615
  ```
616
 
617
  *Constraints:*
618
 
619
- - `is_constructible_v<first_type, U1>` is `true` and
620
- - `is_constructible_v<second_type, U2>` is `true`.
621
 
622
  *Effects:* Initializes `first` with `std::forward<U1>(x)` and `second`
623
  with `std::forward<U2>(y)`.
624
 
625
  *Remarks:* The expression inside `explicit` is equivalent to:
626
 
627
  ``` cpp
628
- !is_convertible_v<U1, first_type> || !is_convertible_v<U2, second_type>
629
  ```
630
 
 
 
 
 
631
  ``` cpp
 
632
  template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>& p);
633
- ```
634
-
635
- *Constraints:*
636
-
637
- - `is_constructible_v<first_type, const U1&>` is `true` and
638
- - `is_constructible_v<second_type, const U2&>` is `true`.
639
-
640
- *Effects:* Initializes members from the corresponding members of the
641
- argument.
642
-
643
- *Remarks:* The expression inside explicit is equivalent to:
644
-
645
- ``` cpp
646
- !is_convertible_v<const U1&, first_type> || !is_convertible_v<const U2&, second_type>
647
- ```
648
-
649
- ``` cpp
650
  template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>&& p);
 
 
651
  ```
652
 
 
 
653
  *Constraints:*
654
 
655
- - `is_constructible_v<first_type, U1>` is `true` and
656
- - `is_constructible_v<second_type, U2>` is `true`.
 
 
 
657
 
658
- *Effects:* Initializes `first` with `std::forward<U1>(p.first)` and
659
- `second` with `std::forward<U2>(p.second)`.
660
 
661
- *Remarks:* The expression inside explicit is equivalent to:
662
 
663
  ``` cpp
664
- !is_convertible_v<U1, first_type> || !is_convertible_v<U2, second_type>
 
665
  ```
666
 
 
 
 
 
 
 
 
 
 
667
  ``` cpp
668
  template<class... Args1, class... Args2>
669
  constexpr pair(piecewise_construct_t,
670
  tuple<Args1...> first_args, tuple<Args2...> second_args);
671
  ```
672
 
673
  *Mandates:*
674
 
675
- - `is_constructible_v<first_type, Args1...>` is `true` and
676
- - `is_constructible_v<second_type, Args2...>` is `true`.
677
 
678
  *Effects:* Initializes `first` with arguments of types `Args1...`
679
  obtained by forwarding the elements of `first_args` and initializes
680
  `second` with arguments of types `Args2...` obtained by forwarding the
681
  elements of `second_args`. (Here, forwarding an element `x` of type `U`
682
  within a `tuple` object means calling `std::forward<U>(x)`.) This form
683
  of construction, whereby constructor arguments for `first` and `second`
684
  are each provided in a separate `tuple` object, is called *piecewise
685
  construction*.
686
 
 
 
 
 
687
  ``` cpp
688
  constexpr pair& operator=(const pair& p);
689
  ```
690
 
691
  *Effects:* Assigns `p.first` to `first` and `p.second` to `second`.
692
 
 
 
693
  *Remarks:* This operator is defined as deleted unless
694
- `is_copy_assignable_v<first_type>` is `true` and
695
- `is_copy_assignable_v<second_type>` is `true`.
 
 
 
 
 
 
 
 
 
 
 
696
 
697
  *Returns:* `*this`.
698
 
699
  ``` cpp
700
  template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p);
701
  ```
702
 
703
  *Constraints:*
704
 
705
- - `is_assignable_v<first_type&, const U1&>` is `true` and
706
- - `is_assignable_v<second_type&, const U2&>` is `true`.
 
 
 
 
 
 
 
 
 
 
 
 
 
707
 
708
  *Effects:* Assigns `p.first` to `first` and `p.second` to `second`.
709
 
710
  *Returns:* `*this`.
711
 
@@ -713,69 +826,144 @@ template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p);
713
  constexpr pair& operator=(pair&& p) noexcept(see below);
714
  ```
715
 
716
  *Constraints:*
717
 
718
- - `is_move_assignable_v<first_type>` is `true` and
719
- - `is_move_assignable_v<second_type>` is `true`.
720
 
721
- *Effects:* Assigns to `first` with `std::forward<first_type>(p.first)`
722
- and to `second` with
723
- `std::forward<second_type>(p.second)`.
724
 
725
  *Returns:* `*this`.
726
 
727
- *Remarks:* The expression inside `noexcept` is equivalent to:
728
 
729
  ``` cpp
730
  is_nothrow_move_assignable_v<T1> && is_nothrow_move_assignable_v<T2>
731
  ```
732
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
733
  ``` cpp
734
  template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p);
735
  ```
736
 
737
  *Constraints:*
738
 
739
- - `is_assignable_v<first_type&, U1>` is `true` and
740
- - `is_assignable_v<second_type&, U2>` is `true`.
741
 
742
  *Effects:* Assigns to `first` with `std::forward<U1>(p.first)` and to
743
  `second` with
744
  `std::forward<U2>(p.second)`.
745
 
746
  *Returns:* `*this`.
747
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
748
  ``` cpp
749
  constexpr void swap(pair& p) noexcept(see below);
 
750
  ```
751
 
 
 
 
 
 
 
 
752
  *Preconditions:* `first` is swappable with [[swappable.requirements]]
753
  `p.first` and `second` is swappable with `p.second`.
754
 
755
  *Effects:* Swaps `first` with `p.first` and `second` with `p.second`.
756
 
757
- *Remarks:* The expression inside `noexcept` is equivalent to:
758
 
759
- ``` cpp
760
- is_nothrow_swappable_v<first_type> && is_nothrow_swappable_v<second_type>
761
- ```
 
762
 
763
  ### Specialized algorithms <a id="pairs.spec">[[pairs.spec]]</a>
764
 
765
  ``` cpp
766
- template<class T1, class T2>
767
- constexpr bool operator==(const pair<T1, T2>& x, const pair<T1, T2>& y);
768
  ```
769
 
 
 
 
770
  *Returns:* `x.first == y.first && x.second == y.second`.
771
 
772
  ``` cpp
773
- template<class T1, class T2>
774
- constexpr common_comparison_category_t<synth-three-way-result<T1>,
775
- synth-three-way-result<T2>>
776
- operator<=>(const pair<T1, T2>& x, const pair<T1, T2>& y);
777
  ```
778
 
779
  *Effects:* Equivalent to:
780
 
781
  ``` cpp
@@ -784,14 +972,20 @@ return synth-three-way(x.second, y.second);
784
  ```
785
 
786
  ``` cpp
787
  template<class T1, class T2>
788
  constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
 
 
789
  ```
790
 
791
- *Constraints:* `is_swappable_v<T1>` is `true` and `is_swappable_v<T2>`
792
- is `true`.
 
 
 
 
793
 
794
  *Effects:* Equivalent to `x.swap(y)`.
795
 
796
  ``` cpp
797
  template<class T1, class T2>
@@ -916,17 +1110,32 @@ arguments is similar to an instantiation of `pair` with the same two
916
  arguments. See  [[pairs]].
917
 
918
  ### Header `<tuple>` synopsis <a id="tuple.syn">[[tuple.syn]]</a>
919
 
920
  ``` cpp
 
921
  #include <compare> // see [compare.syn]
922
 
923
  namespace std {
924
  // [tuple.tuple], class template tuple
925
  template<class... Types>
926
  class tuple;
927
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
928
  // [tuple.creation], tuple creation functions
929
  inline constexpr unspecified ignore;
930
 
931
  template<class... TTypes>
932
  constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&...);
@@ -935,18 +1144,18 @@ namespace std {
935
  constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&...) noexcept;
936
 
937
  template<class... TTypes>
938
  constexpr tuple<TTypes&...> tie(TTypes&...) noexcept;
939
 
940
- template<class... Tuples>
941
  constexpr tuple<CTypes...> tuple_cat(Tuples&&...);
942
 
943
  // [tuple.apply], calling a function with a tuple of arguments
944
- template<class F, class Tuple>
945
- constexpr decltype(auto) apply(F&& f, Tuple&& t);
946
 
947
- template<class T, class Tuple>
948
  constexpr T make_from_tuple(Tuple&& t);
949
 
950
  // [tuple.helper], tuple helper classes
951
  template<class T> struct tuple_size; // not defined
952
  template<class T> struct tuple_size<const T>;
@@ -981,28 +1190,45 @@ namespace std {
981
  constexpr const T&& get(const tuple<Types...>&& t) noexcept;
982
 
983
  // [tuple.rel], relational operators
984
  template<class... TTypes, class... UTypes>
985
  constexpr bool operator==(const tuple<TTypes...>&, const tuple<UTypes...>&);
 
 
986
  template<class... TTypes, class... UTypes>
987
  constexpr common_comparison_category_t<synth-three-way-result<TTypes, UTypes>...>
988
  operator<=>(const tuple<TTypes...>&, const tuple<UTypes...>&);
 
 
989
 
990
  // [tuple.traits], allocator-related traits
991
  template<class... Types, class Alloc>
992
  struct uses_allocator<tuple<Types...>, Alloc>;
993
 
994
  // [tuple.special], specialized algorithms
995
  template<class... Types>
996
  constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(see below);
 
 
997
 
998
  // [tuple.helper], tuple helper classes
999
  template<class T>
1000
- inline constexpr size_t tuple_size_v = tuple_size<T>::value;
1001
  }
1002
  ```
1003
 
 
 
 
 
 
 
 
 
 
 
 
1004
  ### Class template `tuple` <a id="tuple.tuple">[[tuple.tuple]]</a>
1005
 
1006
  ``` cpp
1007
  namespace std {
1008
  template<class... Types>
@@ -1015,19 +1241,30 @@ namespace std {
1015
  constexpr explicit(see below) tuple(UTypes&&...); // only if sizeof...(Types) >= 1
1016
 
1017
  tuple(const tuple&) = default;
1018
  tuple(tuple&&) = default;
1019
 
 
 
1020
  template<class... UTypes>
1021
  constexpr explicit(see below) tuple(const tuple<UTypes...>&);
1022
  template<class... UTypes>
1023
  constexpr explicit(see below) tuple(tuple<UTypes...>&&);
 
 
1024
 
 
 
1025
  template<class U1, class U2>
1026
  constexpr explicit(see below) tuple(const pair<U1, U2>&); // only if sizeof...(Types) == 2
1027
  template<class U1, class U2>
1028
  constexpr explicit(see below) tuple(pair<U1, U2>&&); // only if sizeof...(Types) == 2
 
 
 
 
 
1029
 
1030
  // allocator-extended constructors
1031
  template<class Alloc>
1032
  constexpr explicit(see below)
1033
  tuple(allocator_arg_t, const Alloc& a);
@@ -1039,39 +1276,71 @@ namespace std {
1039
  tuple(allocator_arg_t, const Alloc& a, UTypes&&...);
1040
  template<class Alloc>
1041
  constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&);
1042
  template<class Alloc>
1043
  constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&);
 
 
 
1044
  template<class Alloc, class... UTypes>
1045
  constexpr explicit(see below)
1046
  tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
1047
  template<class Alloc, class... UTypes>
1048
  constexpr explicit(see below)
1049
  tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
 
 
 
 
 
 
1050
  template<class Alloc, class U1, class U2>
1051
  constexpr explicit(see below)
1052
  tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
1053
  template<class Alloc, class U1, class U2>
1054
  constexpr explicit(see below)
1055
  tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
 
 
 
 
 
 
1056
 
1057
  // [tuple.assign], tuple assignment
1058
  constexpr tuple& operator=(const tuple&);
 
1059
  constexpr tuple& operator=(tuple&&) noexcept(see below);
 
1060
 
1061
  template<class... UTypes>
1062
  constexpr tuple& operator=(const tuple<UTypes...>&);
 
 
1063
  template<class... UTypes>
1064
  constexpr tuple& operator=(tuple<UTypes...>&&);
 
 
1065
 
1066
  template<class U1, class U2>
1067
  constexpr tuple& operator=(const pair<U1, U2>&); // only if sizeof...(Types) == 2
 
 
 
1068
  template<class U1, class U2>
1069
  constexpr tuple& operator=(pair<U1, U2>&&); // only if sizeof...(Types) == 2
 
 
 
 
 
 
 
1070
 
1071
  // [tuple.swap], tuple swap
1072
  constexpr void swap(tuple&) noexcept(see below);
 
1073
  };
1074
 
1075
  template<class... UTypes>
1076
  tuple(UTypes...) -> tuple<UTypes...>;
1077
  template<class T1, class T2>
@@ -1095,17 +1364,19 @@ indexing is zero-based.
1095
  For each `tuple` constructor, an exception is thrown only if the
1096
  construction of one of the types in `Types` throws an exception.
1097
 
1098
  The defaulted move and copy constructor, respectively, of `tuple` is a
1099
  constexpr function if and only if all required element-wise
1100
- initializations for move and copy, respectively, would satisfy the
1101
- requirements for a constexpr function. The defaulted move and copy
1102
  constructor of `tuple<>` are constexpr functions.
1103
 
1104
  If `is_trivially_destructible_v<Tᵢ>` is `true` for all `Tᵢ`, then the
1105
  destructor of `tuple` is trivial.
1106
 
 
 
1107
  ``` cpp
1108
  constexpr explicit(see below) tuple();
1109
  ```
1110
 
1111
  *Constraints:* `is_default_constructible_v<``Tᵢ``>` is `true` for all i.
@@ -1137,23 +1408,43 @@ parameter.
1137
 
1138
  ``` cpp
1139
  template<class... UTypes> constexpr explicit(see below) tuple(UTypes&&... u);
1140
  ```
1141
 
1142
- *Constraints:* `sizeof...(Types)` equals `sizeof...(UTypes)` and
1143
- `sizeof...(Types)` ≥ 1 and `is_constructible_v<``Tᵢ``, ``Uᵢ``>` is
1144
- `true` for all i.
 
 
 
 
 
 
 
 
 
 
 
 
1145
 
1146
  *Effects:* Initializes the elements in the tuple with the corresponding
1147
  value in `std::forward<UTypes>(u)`.
1148
 
1149
  *Remarks:* The expression inside `explicit` is equivalent to:
1150
 
1151
  ``` cpp
1152
  !conjunction_v<is_convertible<UTypes, Types>...>
1153
  ```
1154
 
 
 
 
 
 
 
 
 
1155
  ``` cpp
1156
  tuple(const tuple& u) = default;
1157
  ```
1158
 
1159
  *Mandates:* `is_copy_constructible_v<``Tᵢ``>` is `true` for all i.
@@ -1169,91 +1460,108 @@ tuple(tuple&& u) = default;
1169
 
1170
  *Effects:* For all i, initializes the iᵗʰ element of `*this` with
1171
  `std::forward<``Tᵢ``>(get<`i`>(u))`.
1172
 
1173
  ``` cpp
 
1174
  template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>& u);
1175
- ```
1176
-
1177
- *Constraints:*
1178
-
1179
- - `sizeof...(Types)` equals `sizeof...(UTypes)` and
1180
- - `is_constructible_v<``Tᵢ``, const ``Uᵢ``&>` is `true` for all i, and
1181
- - either `sizeof...(Types)` is not 1, or (when `Types...` expands to `T`
1182
- and `UTypes...` expands to `U`)
1183
- `is_convertible_v<const tuple<U>&, T>`,
1184
- `is_constructible_v<T, const tuple<U>&>`, and `is_same_v<T, U>` are
1185
- all `false`.
1186
-
1187
- *Effects:* Initializes each element of `*this` with the corresponding
1188
- element of `u`.
1189
-
1190
- *Remarks:* The expression inside `explicit` is equivalent to:
1191
-
1192
- ``` cpp
1193
- !conjunction_v<is_convertible<const UTypes&, Types>...>
1194
- ```
1195
-
1196
- ``` cpp
1197
  template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&& u);
 
1198
  ```
1199
 
 
 
 
1200
  *Constraints:*
1201
 
1202
  - `sizeof...(Types)` equals `sizeof...(UTypes)`, and
1203
- - `is_constructible_v<``Tᵢ``, ``Uᵢ``>` is `true` for all i, and
 
1204
  - either `sizeof...(Types)` is not 1, or (when `Types...` expands to `T`
1205
- and `UTypes...` expands to `U`) `is_convertible_v<tuple<U>, T>`,
1206
- `is_constructible_v<T, tuple<U>>`, and `is_same_v<T, U>` are all
1207
  `false`.
1208
 
1209
- *Effects:* For all i, initializes the iᵗʰ element of `*this` with
1210
- `std::forward<``Uᵢ``>(get<`i`>(u))`.
1211
 
1212
  *Remarks:* The expression inside `explicit` is equivalent to:
1213
 
1214
  ``` cpp
1215
- !conjunction_v<is_convertible<UTypes, Types>...>
1216
  ```
1217
 
 
 
 
 
 
 
 
 
1218
  ``` cpp
 
1219
  template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>& u);
1220
- ```
1221
-
1222
- *Constraints:*
1223
-
1224
- - `sizeof...(Types)` is 2,
1225
- - `is_constructible_v<``T₀``, const U1&>` is `true`, and
1226
- - `is_constructible_v<``T₁``, const U2&>` is `true`.
1227
-
1228
- *Effects:* Initializes the first element with `u.first` and the second
1229
- element with `u.second`.
1230
-
1231
- The expression inside `explicit` is equivalent to:
1232
-
1233
- ``` cpp
1234
- !is_convertible_v<const U1&, $T_0$> || !is_convertible_v<const U2&, $T_1$>
1235
- ```
1236
-
1237
- ``` cpp
1238
  template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&& u);
 
1239
  ```
1240
 
 
 
1241
  *Constraints:*
1242
 
1243
  - `sizeof...(Types)` is 2,
1244
- - `is_constructible_v<``T₀``, U1>` is `true`, and
1245
- - `is_constructible_v<``T₁``, U2>` is `true`.
 
 
1246
 
1247
- *Effects:* Initializes the first element with
1248
- `std::forward<U1>(u.first)` and the second element with
1249
- `std::forward<U2>(u.second)`.
1250
 
1251
- The expression inside `explicit` is equivalent to:
1252
 
1253
  ``` cpp
1254
- !is_convertible_v<U1, $T_0$> || !is_convertible_v<U2, $T_1$>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1255
  ```
1256
 
1257
  ``` cpp
1258
  template<class Alloc>
1259
  constexpr explicit(see below)
@@ -1266,26 +1574,41 @@ template<class Alloc, class... UTypes>
1266
  tuple(allocator_arg_t, const Alloc& a, UTypes&&...);
1267
  template<class Alloc>
1268
  constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&);
1269
  template<class Alloc>
1270
  constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&);
 
 
 
1271
  template<class Alloc, class... UTypes>
1272
  constexpr explicit(see below)
1273
  tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
1274
  template<class Alloc, class... UTypes>
1275
  constexpr explicit(see below)
1276
  tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
 
 
 
 
 
 
1277
  template<class Alloc, class U1, class U2>
1278
  constexpr explicit(see below)
1279
  tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
1280
  template<class Alloc, class U1, class U2>
1281
  constexpr explicit(see below)
1282
  tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
 
 
 
 
 
 
1283
  ```
1284
 
1285
- *Preconditions:* `Alloc` meets the *Cpp17Allocator* requirements
1286
- ([[cpp17.allocator]]).
1287
 
1288
  *Effects:* Equivalent to the preceding constructors except that each
1289
  element is constructed with uses-allocator
1290
  construction [[allocator.uses.construction]].
1291
 
@@ -1303,13 +1626,24 @@ constexpr tuple& operator=(const tuple& u);
1303
  ```
1304
 
1305
  *Effects:* Assigns each element of `u` to the corresponding element of
1306
  `*this`.
1307
 
 
 
1308
  *Remarks:* This operator is defined as deleted unless
1309
  `is_copy_assignable_v<``Tᵢ``>` is `true` for all i.
1310
 
 
 
 
 
 
 
 
 
 
1311
  *Returns:* `*this`.
1312
 
1313
  ``` cpp
1314
  constexpr tuple& operator=(tuple&& u) noexcept(see below);
1315
  ```
@@ -1317,19 +1651,31 @@ constexpr tuple& operator=(tuple&& u) noexcept(see below);
1317
  *Constraints:* `is_move_assignable_v<``Tᵢ``>` is `true` for all i.
1318
 
1319
  *Effects:* For all i, assigns `std::forward<``Tᵢ``>(get<`i`>(u))` to
1320
  `get<`i`>(*this)`.
1321
 
1322
- *Remarks:* The expression inside `noexcept` is equivalent to the logical
1323
- <span class="smallcaps">and</span> of the following expressions:
 
 
1324
 
1325
  ``` cpp
1326
  is_nothrow_move_assignable_v<Tᵢ>
1327
  ```
1328
 
1329
  where Tᵢ is the iᵗʰ type in `Types`.
1330
 
 
 
 
 
 
 
 
 
 
 
1331
  *Returns:* `*this`.
1332
 
1333
  ``` cpp
1334
  template<class... UTypes> constexpr tuple& operator=(const tuple<UTypes...>& u);
1335
  ```
@@ -1342,10 +1688,24 @@ template<class... UTypes> constexpr tuple& operator=(const tuple<UTypes...>& u);
1342
  *Effects:* Assigns each element of `u` to the corresponding element of
1343
  `*this`.
1344
 
1345
  *Returns:* `*this`.
1346
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1347
  ``` cpp
1348
  template<class... UTypes> constexpr tuple& operator=(tuple<UTypes...>&& u);
1349
  ```
1350
 
1351
  *Constraints:*
@@ -1356,10 +1716,24 @@ template<class... UTypes> constexpr tuple& operator=(tuple<UTypes...>&& u);
1356
  *Effects:* For all i, assigns `std::forward<``Uᵢ``>(get<`i`>(u))` to
1357
  `get<`i`>(*this)`.
1358
 
1359
  *Returns:* `*this`.
1360
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1361
  ``` cpp
1362
  template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>& u);
1363
  ```
1364
 
1365
  *Constraints:*
@@ -1371,10 +1745,25 @@ template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>& u);
1371
  *Effects:* Assigns `u.first` to the first element of `*this` and
1372
  `u.second` to the second element of `*this`.
1373
 
1374
  *Returns:* `*this`.
1375
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1376
  ``` cpp
1377
  template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&& u);
1378
  ```
1379
 
1380
  *Constraints:*
@@ -1387,40 +1776,96 @@ template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&& u);
1387
  `*this` and
1388
  `std::forward<U2>(u.second)` to the second element of `*this`.
1389
 
1390
  *Returns:* `*this`.
1391
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1392
  #### `swap` <a id="tuple.swap">[[tuple.swap]]</a>
1393
 
1394
  ``` cpp
1395
  constexpr void swap(tuple& rhs) noexcept(see below);
 
1396
  ```
1397
 
1398
- *Preconditions:* Each element in `*this` is swappable
1399
- with [[swappable.requirements]] the corresponding element in `rhs`.
1400
 
1401
- *Effects:* Calls `swap` for each element in `*this` and its
1402
- corresponding element in `rhs`.
1403
 
1404
- *Remarks:* The expression inside `noexcept` is equivalent to the logical
1405
- <span class="smallcaps">and</span> of the following expressions:
 
1406
 
1407
- ``` cpp
1408
- is_nothrow_swappable_v<Tᵢ>
1409
- ```
1410
 
1411
- where Tᵢ is the iᵗʰ type in `Types`.
 
1412
 
1413
  *Throws:* Nothing unless one of the element-wise `swap` calls throws an
1414
  exception.
1415
 
 
 
 
 
 
 
1416
  ### Tuple creation functions <a id="tuple.creation">[[tuple.creation]]</a>
1417
 
1418
- In the function descriptions that follow, the members of a template
1419
- parameter pack `XTypes` are denoted by `X`ᵢ for i in \[`0`,
1420
- `sizeof...(`*X*`Types)`) in order, where indexing is zero-based.
1421
-
1422
  ``` cpp
1423
  template<class... TTypes>
1424
  constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&... t);
1425
  ```
1426
 
@@ -1429,11 +1874,11 @@ template<class... TTypes>
1429
 
1430
  [*Example 1*:
1431
 
1432
  ``` cpp
1433
  int i; float j;
1434
- make_tuple(1, ref(i), cref(j))
1435
  ```
1436
 
1437
  creates a tuple of type `tuple<int, int&, const float&>`.
1438
 
1439
  — *end example*]
@@ -1473,90 +1918,96 @@ tie(i, ignore, s) = make_tuple(42, 3.14, "C++");
1473
  ```
1474
 
1475
  — *end example*]
1476
 
1477
  ``` cpp
1478
- template<class... Tuples>
1479
  constexpr tuple<CTypes...> tuple_cat(Tuples&&... tpls);
1480
  ```
1481
 
1482
- In the following paragraphs, let `Tᵢ` be the iᵗʰ type in `Tuples`, `Uᵢ`
1483
- be `remove_reference_t<T`ᵢ`>`, and `tpᵢ` be the iᵗʰ parameter in the
1484
- function parameter pack `tpls`, where all indexing is zero-based.
1485
 
1486
- *Preconditions:* For all i, `Uᵢ` is the type cvᵢ `tuple<``Argsᵢ``...>`,
1487
- where cvᵢ is the (possibly empty) iᵗʰ *cv-qualifier-seq* and `Argsᵢ` is
1488
- the template parameter pack representing the element types in `Uᵢ`. Let
1489
- `A_ik` be the kᵗʰ type in `Argsᵢ`. For all `A_ik` the following
1490
- requirements are met:
 
 
 
 
1491
 
1492
- - If `Tᵢ` is deduced as an lvalue reference type, then
1493
- `is_constructible_v<``A_ik``, `cvᵢ `A_ik``&> == true`, otherwise
1494
- - `is_constructible_v<``A_ik``, `cvᵢ `A_ik``&&> == true`.
 
1495
 
1496
- *Remarks:* The types in `CTypes` are equal to the ordered sequence of
1497
- the extended types `Args₀``..., ``Args₁``..., `…`, ``Args_n-1``...`,
1498
- where n is equal to `sizeof...(Tuples)`. Let `eᵢ``...` be the iᵗʰ
1499
- ordered sequence of tuple elements of the resulting `tuple` object
1500
- corresponding to the type sequence `Argsᵢ`.
1501
 
1502
- *Returns:* A `tuple` object constructed by initializing the kᵢᵗʰ type
1503
- element `e_ik` in `eᵢ``...` with
1504
-
1505
- ``` cpp
1506
- get<kᵢ>(std::forward<$T_i$>($tp_i$))
1507
- ```
1508
-
1509
- for each valid kᵢ and each group `eᵢ` in order.
1510
-
1511
- [*Note 1*: An implementation may support additional types in the
1512
- template parameter pack `Tuples` that support the `tuple`-like protocol,
1513
- such as `pair` and `array`. — *end note*]
1514
 
1515
  ### Calling a function with a `tuple` of arguments <a id="tuple.apply">[[tuple.apply]]</a>
1516
 
1517
  ``` cpp
1518
- template<class F, class Tuple>
1519
- constexpr decltype(auto) apply(F&& f, Tuple&& t);
1520
  ```
1521
 
1522
  *Effects:* Given the exposition-only function:
1523
 
1524
  ``` cpp
1525
- template<class F, class Tuple, size_t... I>
 
1526
  constexpr decltype(auto) apply-impl(F&& f, Tuple&& t, index_sequence<I...>) {
1527
  // exposition only
1528
- return INVOKE(std::forward<F>(f), std::get<I>(std::forward<Tuple>(t))...); // see [func.require]
 
1529
  }
1530
  ```
1531
 
1532
  Equivalent to:
1533
 
1534
  ``` cpp
1535
  return apply-impl(std::forward<F>(f), std::forward<Tuple>(t),
1536
  make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
1537
  ```
1538
 
 
 
 
 
1539
  ``` cpp
1540
- template<class T, class Tuple>
 
 
 
 
1541
  constexpr T make_from_tuple(Tuple&& t);
1542
  ```
1543
 
 
 
 
 
1544
  *Effects:* Given the exposition-only function:
1545
 
1546
  ``` cpp
1547
- template<class T, class Tuple, size_t... I>
 
 
1548
  constexpr T make-from-tuple-impl(Tuple&& t, index_sequence<I...>) { // exposition only
1549
  return T(get<I>(std::forward<Tuple>(t))...);
1550
  }
 
1551
  ```
1552
 
1553
  Equivalent to:
1554
 
1555
  ``` cpp
1556
  return make-from-tuple-impl<T>(
1557
- forward<Tuple>(t),
1558
  make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
1559
  ```
1560
 
1561
  [*Note 1*: The type of `T` must be supplied as an explicit template
1562
  parameter, as it cannot be deduced from the argument
@@ -1593,13 +2044,13 @@ is zero-based.
1593
  template<class T> struct tuple_size<const T>;
1594
  ```
1595
 
1596
  Let `TS` denote `tuple_size<T>` of the cv-unqualified type `T`. If the
1597
  expression `TS::value` is well-formed when treated as an unevaluated
1598
- operand, then each specialization of the template meets the
1599
- *Cpp17UnaryTypeTrait* requirements [[meta.rqmts]] with a base
1600
- characteristic of
1601
 
1602
  ``` cpp
1603
  integral_constant<size_t, TS::value>
1604
  ```
1605
 
@@ -1659,11 +2110,11 @@ is a non-reference type `T`, the return type is `T&&`. — *end note*]
1659
 
1660
  [*Note 2*: \[Note B\]Constness is shallow. If a type `T` in `Types` is
1661
  some reference type `X&`, the return type is `X&`, not `const X&`.
1662
  However, if the element type is a non-reference type `T`, the return
1663
  type is `const T&`. This is consistent with how constness is defined to
1664
- work for member variables of reference type. — *end note*]
1665
 
1666
  ``` cpp
1667
  template<class T, class... Types>
1668
  constexpr T& get(tuple<Types...>& t) noexcept;
1669
  template<class T, class... Types>
@@ -1698,80 +2149,160 @@ type depended on a template parameter would have required using the
1698
  ### Relational operators <a id="tuple.rel">[[tuple.rel]]</a>
1699
 
1700
  ``` cpp
1701
  template<class... TTypes, class... UTypes>
1702
  constexpr bool operator==(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
 
 
1703
  ```
1704
 
 
 
1705
  *Mandates:* For all `i`, where 0 ≤ `i` < `sizeof...(TTypes)`,
1706
- `get<i>(t) == get<i>(u)` is a valid expression returning a type that is
1707
- convertible to `bool`. `sizeof...(TTypes)` equals `sizeof...(UTypes)`.
 
 
 
1708
 
1709
  *Returns:* `true` if `get<i>(t) == get<i>(u)` for all `i`, otherwise
1710
- `false`. For any two zero-length tuples `e` and `f`, `e == f` returns
1711
- `true`.
1712
 
1713
- *Effects:* The elementary comparisons are performed in order from the
1714
- zeroth index upwards. No comparisons or element accesses are performed
1715
- after the first equality comparison that evaluates to `false`.
 
 
 
 
 
 
 
1716
 
1717
  ``` cpp
1718
  template<class... TTypes, class... UTypes>
1719
  constexpr common_comparison_category_t<synth-three-way-result<TTypes, UTypes>...>
1720
  operator<=>(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
 
 
 
1721
  ```
1722
 
1723
- *Effects:* Performs a lexicographical comparison between `t` and `u`.
1724
- For any two zero-length tuples `t` and `u`, `t <=> u` returns
1725
- `strong_ordering::equal`. Otherwise, equivalent to:
 
 
 
 
1726
 
1727
  ``` cpp
1728
  if (auto c = synth-three-way(get<0>(t), get<0>(u)); c != 0) return c;
1729
  return $t_tail$ <=> $u_tail$;
1730
  ```
1731
 
1732
- where `r_tail` for some tuple `r` is a tuple containing all but the
1733
- first element of `r`.
 
 
 
1734
 
1735
  [*Note 1*: The above definition does not require `tₜₐᵢₗ` (or `uₜₐᵢₗ`)
1736
- to be constructed. It may not even be possible, as `t` and `u` are not
1737
- required to be copy constructible. Also, all comparison functions are
1738
- short circuited; they do not perform element accesses beyond what is
1739
- required to determine the result of the comparison. — *end note*]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1740
 
1741
  ### Tuple traits <a id="tuple.traits">[[tuple.traits]]</a>
1742
 
1743
  ``` cpp
1744
  template<class... Types, class Alloc>
1745
  struct uses_allocator<tuple<Types...>, Alloc> : true_type { };
1746
  ```
1747
 
1748
- *Preconditions:* `Alloc` meets the *Cpp17Allocator* requirements
1749
- ([[cpp17.allocator]]).
1750
 
1751
  [*Note 1*: Specialization of this trait informs other library
1752
  components that `tuple` can be constructed with an allocator, even
1753
  though it does not have a nested `allocator_type`. — *end note*]
1754
 
1755
  ### Tuple specialized algorithms <a id="tuple.special">[[tuple.special]]</a>
1756
 
1757
  ``` cpp
1758
  template<class... Types>
1759
  constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(see below);
 
 
1760
  ```
1761
 
1762
- *Constraints:* `is_swappable_v<T>` is `true` for every type `T` in
1763
- `Types`.
1764
 
1765
- *Remarks:* The expression inside `noexcept` is equivalent to:
1766
-
1767
- ``` cpp
1768
- noexcept(x.swap(y))
1769
- ```
1770
 
1771
  *Effects:* As if by `x.swap(y)`.
1772
 
 
 
 
 
 
 
1773
  ## Optional objects <a id="optional">[[optional]]</a>
1774
 
1775
  ### In general <a id="optional.general">[[optional.general]]</a>
1776
 
1777
  Subclause  [[optional]] describes class template `optional` that
@@ -1790,10 +2321,15 @@ contained object is tracked by the optional object.
1790
  namespace std {
1791
  // [optional.optional], class template optional
1792
  template<class T>
1793
  class optional;
1794
 
 
 
 
 
 
1795
  // [optional.nullopt], no-value state indicator
1796
  struct nullopt_t{see below};
1797
  inline constexpr nullopt_t nullopt(unspecified);
1798
 
1799
  // [optional.bad.access], class bad_optional_access
@@ -1832,17 +2368,18 @@ namespace std {
1832
  template<class T, class U> constexpr bool operator>(const T&, const optional<U>&);
1833
  template<class T, class U> constexpr bool operator<=(const optional<T>&, const U&);
1834
  template<class T, class U> constexpr bool operator<=(const T&, const optional<U>&);
1835
  template<class T, class U> constexpr bool operator>=(const optional<T>&, const U&);
1836
  template<class T, class U> constexpr bool operator>=(const T&, const optional<U>&);
1837
- template<class T, three_way_comparable_with<T> U>
 
1838
  constexpr compare_three_way_result_t<T, U>
1839
  operator<=>(const optional<T>&, const U&);
1840
 
1841
  // [optional.specalg], specialized algorithms
1842
  template<class T>
1843
- void swap(optional<T>&, optional<T>&) noexcept(see below);
1844
 
1845
  template<class T>
1846
  constexpr optional<see below> make_optional(T&&);
1847
  template<class T, class... Args>
1848
  constexpr optional<T> make_optional(Args&&... args);
@@ -1855,10 +2392,12 @@ namespace std {
1855
  }
1856
  ```
1857
 
1858
  ### Class template `optional` <a id="optional.optional">[[optional.optional]]</a>
1859
 
 
 
1860
  ``` cpp
1861
  namespace std {
1862
  template<class T>
1863
  class optional {
1864
  public:
@@ -1874,48 +2413,60 @@ namespace std {
1874
  template<class U, class... Args>
1875
  constexpr explicit optional(in_place_t, initializer_list<U>, Args&&...);
1876
  template<class U = T>
1877
  constexpr explicit(see below) optional(U&&);
1878
  template<class U>
1879
- explicit(see below) optional(const optional<U>&);
1880
  template<class U>
1881
- explicit(see below) optional(optional<U>&&);
1882
 
1883
  // [optional.dtor], destructor
1884
- ~optional();
1885
 
1886
  // [optional.assign], assignment
1887
- optional& operator=(nullopt_t) noexcept;
1888
  constexpr optional& operator=(const optional&);
1889
  constexpr optional& operator=(optional&&) noexcept(see below);
1890
- template<class U = T> optional& operator=(U&&);
1891
- template<class U> optional& operator=(const optional<U>&);
1892
- template<class U> optional& operator=(optional<U>&&);
1893
- template<class... Args> T& emplace(Args&&...);
1894
- template<class U, class... Args> T& emplace(initializer_list<U>, Args&&...);
1895
 
1896
  // [optional.swap], swap
1897
- void swap(optional&) noexcept(see below);
1898
 
1899
  // [optional.observe], observers
1900
- constexpr const T* operator->() const;
1901
- constexpr T* operator->();
1902
- constexpr const T& operator*() const&;
1903
- constexpr T& operator*() &;
1904
- constexpr T&& operator*() &&;
1905
- constexpr const T&& operator*() const&&;
1906
  constexpr explicit operator bool() const noexcept;
1907
  constexpr bool has_value() const noexcept;
1908
  constexpr const T& value() const &;
1909
  constexpr T& value() &;
1910
  constexpr T&& value() &&;
1911
  constexpr const T&& value() const &&;
1912
  template<class U> constexpr T value_or(U&&) const &;
1913
  template<class U> constexpr T value_or(U&&) &&;
1914
 
 
 
 
 
 
 
 
 
 
 
 
 
1915
  // [optional.mod], modifiers
1916
- void reset() noexcept;
1917
 
1918
  private:
1919
  T *val; // exposition only
1920
  };
1921
 
@@ -1927,25 +2478,35 @@ namespace std {
1927
  Any instance of `optional<T>` at any given time either contains a value
1928
  or does not contain a value. When an instance of `optional<T>` *contains
1929
  a value*, it means that an object of type `T`, referred to as the
1930
  optional object’s *contained value*, is allocated within the storage of
1931
  the optional object. Implementations are not permitted to use additional
1932
- storage, such as dynamic memory, to allocate its contained value. The
1933
- contained value shall be allocated in a region of the `optional<T>`
1934
- storage suitably aligned for the type `T`. When an object of type
1935
- `optional<T>` is contextually converted to `bool`, the conversion
1936
- returns `true` if the object contains a value; otherwise the conversion
1937
- returns `false`.
1938
 
1939
- Member `val` is provided for exposition only. When an `optional<T>`
1940
- object contains a value, `val` points to the contained value.
1941
 
1942
  `T` shall be a type other than cv `in_place_t` or cv `nullopt_t` that
1943
  meets the *Cpp17Destructible* requirements ([[cpp17.destructible]]).
1944
 
1945
  #### Constructors <a id="optional.ctor">[[optional.ctor]]</a>
1946
 
 
 
 
 
 
 
 
 
 
 
 
 
1947
  ``` cpp
1948
  constexpr optional() noexcept;
1949
  constexpr optional(nullopt_t) noexcept;
1950
  ```
1951
 
@@ -1956,15 +2517,14 @@ these constructors are constexpr constructors [[dcl.constexpr]].
1956
 
1957
  ``` cpp
1958
  constexpr optional(const optional& rhs);
1959
  ```
1960
 
1961
- *Effects:* If `rhs` contains a value, initializes the contained value as
1962
- if direct-non-list-initializing an object of type `T` with the
1963
- expression `*rhs`.
1964
 
1965
- *Ensures:* `bool(rhs) == bool(*this)`.
1966
 
1967
  *Throws:* Any exception thrown by the selected constructor of `T`.
1968
 
1969
  *Remarks:* This constructor is defined as deleted unless
1970
  `is_copy_constructible_v<T>` is `true`. If
@@ -1975,31 +2535,29 @@ trivial.
1975
  constexpr optional(optional&& rhs) noexcept(see below);
1976
  ```
1977
 
1978
  *Constraints:* `is_move_constructible_v<T>` is `true`.
1979
 
1980
- *Effects:* If `rhs` contains a value, initializes the contained value as
1981
- if direct-non-list-initializing an object of type `T` with the
1982
- expression `std::move(*rhs)`. `bool(rhs)` is unchanged.
1983
 
1984
- *Ensures:* `bool(rhs) == bool(*this)`.
1985
 
1986
  *Throws:* Any exception thrown by the selected constructor of `T`.
1987
 
1988
- *Remarks:* The expression inside `noexcept` is equivalent to
1989
  `is_nothrow_move_constructible_v<T>`. If
1990
  `is_trivially_move_constructible_v<T>` is `true`, this constructor is
1991
  trivial.
1992
 
1993
  ``` cpp
1994
  template<class... Args> constexpr explicit optional(in_place_t, Args&&... args);
1995
  ```
1996
 
1997
  *Constraints:* `is_constructible_v<T, Args...>` is `true`.
1998
 
1999
- *Effects:* Initializes the contained value as if
2000
- direct-non-list-initializing an object of type `T` with the arguments
2001
  `std::forward<Args>(args)...`.
2002
 
2003
  *Ensures:* `*this` contains a value.
2004
 
2005
  *Throws:* Any exception thrown by the selected constructor of `T`.
@@ -2013,12 +2571,11 @@ template<class U, class... Args>
2013
  ```
2014
 
2015
  *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
2016
  `true`.
2017
 
2018
- *Effects:* Initializes the contained value as if
2019
- direct-non-list-initializing an object of type `T` with the arguments
2020
  `il, std::forward<Args>(args)...`.
2021
 
2022
  *Ensures:* `*this` contains a value.
2023
 
2024
  *Throws:* Any exception thrown by the selected constructor of `T`.
@@ -2028,16 +2585,19 @@ constexpr constructor, this constructor is a constexpr constructor.
2028
 
2029
  ``` cpp
2030
  template<class U = T> constexpr explicit(see below) optional(U&& v);
2031
  ```
2032
 
2033
- *Constraints:* `is_constructible_v<T, U>` is `true`,
2034
- `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`, and
2035
- `is_same_v<remove_cvref_t<U>, optional>` is `false`.
2036
 
2037
- *Effects:* Initializes the contained value as if
2038
- direct-non-list-initializing an object of type `T` with the expression
 
 
 
 
 
2039
  `std::forward<U>(v)`.
2040
 
2041
  *Ensures:* `*this` contains a value.
2042
 
2043
  *Throws:* Any exception thrown by the selected constructor of `T`.
@@ -2049,60 +2609,46 @@ this constructor is a constexpr constructor. The expression inside
2049
  ``` cpp
2050
  !is_convertible_v<U, T>
2051
  ```
2052
 
2053
  ``` cpp
2054
- template<class U> explicit(see below) optional(const optional<U>& rhs);
2055
  ```
2056
 
2057
  *Constraints:*
2058
 
2059
- - `is_constructible_v<T, const U&>` is `true`,
2060
- - `is_constructible_v<T, optional<U>&>` is `false`,
2061
- - `is_constructible_v<T, optional<U>&&>` is `false`,
2062
- - `is_constructible_v<T, const optional<U>&>` is `false`,
2063
- - `is_constructible_v<T, const optional<U>&&>` is `false`,
2064
- - `is_convertible_v<optional<U>&, T>` is `false`,
2065
- - `is_convertible_v<optional<U>&&, T>` is `false`,
2066
- - `is_convertible_v<const optional<U>&, T>` is `false`, and
2067
- - `is_convertible_v<const optional<U>&&, T>` is `false`.
2068
 
2069
- *Effects:* If `rhs` contains a value, initializes the contained value as
2070
- if direct-non-list-initializing an object of type `T` with the
2071
- expression `*rhs`.
2072
 
2073
- *Ensures:* `bool(rhs)` == `bool(*this)`.
2074
 
2075
  *Throws:* Any exception thrown by the selected constructor of `T`.
2076
 
2077
  *Remarks:* The expression inside `explicit` is equivalent to:
2078
 
2079
  ``` cpp
2080
  !is_convertible_v<const U&, T>
2081
  ```
2082
 
2083
  ``` cpp
2084
- template<class U> explicit(see below) optional(optional<U>&& rhs);
2085
  ```
2086
 
2087
  *Constraints:*
2088
 
2089
- - `is_constructible_v<T, U>` is true,
2090
- - `is_constructible_v<T, optional<U>&>` is `false`,
2091
- - `is_constructible_v<T, optional<U>&&>` is `false`,
2092
- - `is_constructible_v<T, const optional<U>&>` is `false`,
2093
- - `is_constructible_v<T, const optional<U>&&>` is `false`,
2094
- - `is_convertible_v<optional<U>&, T>` is `false`,
2095
- - `is_convertible_v<optional<U>&&, T>` is `false`,
2096
- - `is_convertible_v<const optional<U>&, T>` is `false`, and
2097
- - `is_convertible_v<const optional<U>&&, T>` is `false`.
2098
 
2099
- *Effects:* If `rhs` contains a value, initializes the contained value as
2100
- if direct-non-list-initializing an object of type `T` with the
2101
- expression `std::move(*rhs)`. `bool(rhs)` is unchanged.
2102
 
2103
- *Ensures:* `bool(rhs)` == `bool(*this)`.
2104
 
2105
  *Throws:* Any exception thrown by the selected constructor of `T`.
2106
 
2107
  *Remarks:* The expression inside `explicit` is equivalent to:
2108
 
@@ -2111,11 +2657,11 @@ expression `std::move(*rhs)`. `bool(rhs)` is unchanged.
2111
  ```
2112
 
2113
  #### Destructor <a id="optional.dtor">[[optional.dtor]]</a>
2114
 
2115
  ``` cpp
2116
- ~optional();
2117
  ```
2118
 
2119
  *Effects:* If `is_trivially_destructible_v<T> != true` and `*this`
2120
  contains a value, calls
2121
 
@@ -2127,11 +2673,11 @@ val->T::~T()
2127
  destructor is trivial.
2128
 
2129
  #### Assignment <a id="optional.assign">[[optional.assign]]</a>
2130
 
2131
  ``` cpp
2132
- optional<T>& operator=(nullopt_t) noexcept;
2133
  ```
2134
 
2135
  *Effects:* If `*this` contains a value, calls `val->T::T̃()` to destroy
2136
  the contained value; otherwise no effect.
2137
 
@@ -2146,22 +2692,22 @@ constexpr optional<T>& operator=(const optional& rhs);
2146
  *Effects:* See [[optional.assign.copy]].
2147
 
2148
  **Table: `optional::operator=(const optional&)` effects** <a id="optional.assign.copy">[optional.assign.copy]</a>
2149
 
2150
  | | `*this` contains a value | `*this` does not contain a value |
2151
- | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
2152
- | `rhs` contains a value | assigns `*rhs` to the contained value | initializes the contained value as if direct-non-list-initializing an object of type `T` with `*rhs` |
2153
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2154
 
2155
 
2156
- *Ensures:* `bool(rhs) == bool(*this)`.
2157
 
2158
  *Returns:* `*this`.
2159
 
2160
  *Remarks:* If any exception is thrown, the result of the expression
2161
- `bool(*this)` remains unchanged. If an exception is thrown during the
2162
- call to `T`’s copy constructor, no effect. If an exception is thrown
2163
  during the call to `T`’s copy assignment, the state of its contained
2164
  value is as defined by the exception safety guarantee of `T`’s copy
2165
  assignment. This operator is defined as deleted unless
2166
  `is_copy_constructible_v<T>` is `true` and `is_copy_assignable_v<T>` is
2167
  `true`. If `is_trivially_copy_constructible_v<T> &&`
@@ -2174,161 +2720,146 @@ constexpr optional& operator=(optional&& rhs) noexcept(see below);
2174
 
2175
  *Constraints:* `is_move_constructible_v<T>` is `true` and
2176
  `is_move_assignable_v<T>` is `true`.
2177
 
2178
  *Effects:* See [[optional.assign.move]]. The result of the expression
2179
- `bool(rhs)` remains unchanged.
2180
 
2181
  **Table: `optional::operator=(optional&&)` effects** <a id="optional.assign.move">[optional.assign.move]</a>
2182
 
2183
  | | `*this` contains a value | `*this` does not contain a value |
2184
- | ------------------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
2185
- | `rhs` contains a value | assigns `std::move(*rhs)` to the contained value | initializes the contained value as if direct-non-list-initializing an object of type `T` with `std::move(*rhs)` |
2186
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2187
 
2188
 
2189
- *Ensures:* `bool(rhs) == bool(*this)`.
2190
 
2191
  *Returns:* `*this`.
2192
 
2193
- *Remarks:* The expression inside `noexcept` is equivalent to:
2194
 
2195
  ``` cpp
2196
  is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T>
2197
  ```
2198
 
2199
- If any exception is thrown, the result of the expression `bool(*this)`
2200
- remains unchanged. If an exception is thrown during the call to `T`’s
2201
- move constructor, the state of `*rhs.val` is determined by the exception
2202
- safety guarantee of `T`’s move constructor. If an exception is thrown
2203
- during the call to `T`’s move assignment, the state of `*val` and
2204
- `*rhs.val` is determined by the exception safety guarantee of `T`’s move
2205
- assignment. If `is_trivially_move_constructible_v<T> &&`
 
2206
  `is_trivially_move_assignable_v<T> &&` `is_trivially_destructible_v<T>`
2207
  is `true`, this assignment operator is trivial.
2208
 
2209
  ``` cpp
2210
- template<class U = T> optional<T>& operator=(U&& v);
2211
  ```
2212
 
2213
  *Constraints:* `is_same_v<remove_cvref_t<U>, optional>` is `false`,
2214
  `conjunction_v<is_scalar<T>, is_same<T, decay_t<U>>>` is `false`,
2215
  `is_constructible_v<T, U>` is `true`, and `is_assignable_v<T&, U>` is
2216
  `true`.
2217
 
2218
  *Effects:* If `*this` contains a value, assigns `std::forward<U>(v)` to
2219
- the contained value; otherwise initializes the contained value as if
2220
- direct-non-list-initializing object of type `T` with
2221
- `std::forward<U>(v)`.
2222
 
2223
  *Ensures:* `*this` contains a value.
2224
 
2225
  *Returns:* `*this`.
2226
 
2227
  *Remarks:* If any exception is thrown, the result of the expression
2228
- `bool(*this)` remains unchanged. If an exception is thrown during the
2229
- call to `T`’s constructor, the state of `v` is determined by the
2230
  exception safety guarantee of `T`’s constructor. If an exception is
2231
  thrown during the call to `T`’s assignment, the state of `*val` and `v`
2232
  is determined by the exception safety guarantee of `T`’s assignment.
2233
 
2234
  ``` cpp
2235
- template<class U> optional<T>& operator=(const optional<U>& rhs);
2236
  ```
2237
 
2238
  *Constraints:*
2239
 
2240
  - `is_constructible_v<T, const U&>` is `true`,
2241
  - `is_assignable_v<T&, const U&>` is `true`,
2242
- - `is_constructible_v<T, optional<U>&>` is `false`,
2243
- - `is_constructible_v<T, optional<U>&&>` is `false`,
2244
- - `is_constructible_v<T, const optional<U>&>` is `false`,
2245
- - `is_constructible_v<T, const optional<U>&&>` is `false`,
2246
- - `is_convertible_v<optional<U>&, T>` is `false`,
2247
- - `is_convertible_v<optional<U>&&, T>` is `false`,
2248
- - `is_convertible_v<const optional<U>&, T>` is `false`,
2249
- - `is_convertible_v<const optional<U>&&, T>` is `false`,
2250
  - `is_assignable_v<T&, optional<U>&>` is `false`,
2251
  - `is_assignable_v<T&, optional<U>&&>` is `false`,
2252
  - `is_assignable_v<T&, const optional<U>&>` is `false`, and
2253
  - `is_assignable_v<T&, const optional<U>&&>` is `false`.
2254
 
2255
  *Effects:* See [[optional.assign.copy.templ]].
2256
 
2257
  **Table: `optional::operator=(const optional<U>&)` effects** <a id="optional.assign.copy.templ">[optional.assign.copy.templ]</a>
2258
 
2259
  | | `*this` contains a value | `*this` does not contain a value |
2260
- | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
2261
- | `rhs` contains a value | assigns `*rhs` to the contained value | initializes the contained value as if direct-non-list-initializing an object of type `T` with `*rhs` |
2262
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2263
 
2264
 
2265
- *Ensures:* `bool(rhs) == bool(*this)`.
2266
 
2267
  *Returns:* `*this`.
2268
 
2269
  *Remarks:* If any exception is thrown, the result of the expression
2270
- `bool(*this)` remains unchanged. If an exception is thrown during the
2271
- call to `T`’s constructor, the state of `*rhs.val` is determined by the
2272
- exception safety guarantee of `T`’s constructor. If an exception is
2273
  thrown during the call to `T`’s assignment, the state of `*val` and
2274
  `*rhs.val` is determined by the exception safety guarantee of `T`’s
2275
  assignment.
2276
 
2277
  ``` cpp
2278
- template<class U> optional<T>& operator=(optional<U>&& rhs);
2279
  ```
2280
 
2281
  *Constraints:*
2282
 
2283
  - `is_constructible_v<T, U>` is `true`,
2284
  - `is_assignable_v<T&, U>` is `true`,
2285
- - `is_constructible_v<T, optional<U>&>` is `false`,
2286
- - `is_constructible_v<T, optional<U>&&>` is `false`,
2287
- - `is_constructible_v<T, const optional<U>&>` is `false`,
2288
- - `is_constructible_v<T, const optional<U>&&>` is `false`,
2289
- - `is_convertible_v<optional<U>&, T>` is `false`,
2290
- - `is_convertible_v<optional<U>&&, T>` is `false`,
2291
- - `is_convertible_v<const optional<U>&, T>` is `false`,
2292
- - `is_convertible_v<const optional<U>&&, T>` is `false`,
2293
  - `is_assignable_v<T&, optional<U>&>` is `false`,
2294
  - `is_assignable_v<T&, optional<U>&&>` is `false`,
2295
  - `is_assignable_v<T&, const optional<U>&>` is `false`, and
2296
  - `is_assignable_v<T&, const optional<U>&&>` is `false`.
2297
 
2298
  *Effects:* See [[optional.assign.move.templ]]. The result of the
2299
- expression `bool(rhs)` remains unchanged.
2300
 
2301
  **Table: `optional::operator=(optional<U>&&)` effects** <a id="optional.assign.move.templ">[optional.assign.move.templ]</a>
2302
 
2303
  | | `*this` contains a value | `*this` does not contain a value |
2304
- | ------------------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
2305
- | `rhs` contains a value | assigns `std::move(*rhs)` to the contained value | initializes the contained value as if direct-non-list-initializing an object of type `T` with `std::move(*rhs)` |
2306
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2307
 
2308
 
2309
- *Ensures:* `bool(rhs) == bool(*this)`.
2310
 
2311
  *Returns:* `*this`.
2312
 
2313
  *Remarks:* If any exception is thrown, the result of the expression
2314
- `bool(*this)` remains unchanged. If an exception is thrown during the
2315
- call to `T`’s constructor, the state of `*rhs.val` is determined by the
2316
- exception safety guarantee of `T`’s constructor. If an exception is
2317
  thrown during the call to `T`’s assignment, the state of `*val` and
2318
  `*rhs.val` is determined by the exception safety guarantee of `T`’s
2319
  assignment.
2320
 
2321
  ``` cpp
2322
- template<class... Args> T& emplace(Args&&... args);
2323
  ```
2324
 
2325
  *Mandates:* `is_constructible_v<T, Args...>` is `true`.
2326
 
2327
- *Effects:* Calls `*this = nullopt`. Then initializes the contained value
2328
- as if direct-non-list-initializing an object of type `T` with the
2329
- arguments `std::forward<Args>(args)...`.
2330
 
2331
  *Ensures:* `*this` contains a value.
2332
 
2333
  *Returns:* A reference to the new contained value.
2334
 
@@ -2337,19 +2868,18 @@ arguments `std::forward<Args>(args)...`.
2337
  *Remarks:* If an exception is thrown during the call to `T`’s
2338
  constructor, `*this` does not contain a value, and the previous `*val`
2339
  (if any) has been destroyed.
2340
 
2341
  ``` cpp
2342
- template<class U, class... Args> T& emplace(initializer_list<U> il, Args&&... args);
2343
  ```
2344
 
2345
  *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
2346
  `true`.
2347
 
2348
- *Effects:* Calls `*this = nullopt`. Then initializes the contained value
2349
- as if direct-non-list-initializing an object of type `T` with the
2350
- arguments `il, std::forward<Args>(args)...`.
2351
 
2352
  *Ensures:* `*this` contains a value.
2353
 
2354
  *Returns:* A reference to the new contained value.
2355
 
@@ -2360,75 +2890,72 @@ constructor, `*this` does not contain a value, and the previous `*val`
2360
  (if any) has been destroyed.
2361
 
2362
  #### Swap <a id="optional.swap">[[optional.swap]]</a>
2363
 
2364
  ``` cpp
2365
- void swap(optional& rhs) noexcept(see below);
2366
  ```
2367
 
2368
  *Mandates:* `is_move_constructible_v<T>` is `true`.
2369
 
2370
- *Preconditions:* Lvalues of type `T` are swappable.
 
2371
 
2372
  *Effects:* See [[optional.swap]].
2373
 
2374
  **Table: `optional::swap(optional&)` effects** <a id="optional.swap">[optional.swap]</a>
2375
 
2376
  | | `*this` contains a value | `*this` does not contain a value |
2377
- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2378
- | `rhs` contains a value | calls `swap(*(*this), *rhs)` | initializes the contained value of `*this` as if direct-non-list-initializing an object of type `T` with the expression `std::move(*rhs)`, followed by `rhs.val->T::~T()`; postcondition is that `*this` contains a value and `rhs` does not contain a value |
2379
- | `rhs` does not contain a value | initializes the contained value of `rhs` as if direct-non-list-initializing an object of type `T` with the expression `std::move(*(*this))`, followed by `val->T::~T()`; postcondition is that `*this` does not contain a value and `rhs` contains a value | no effect |
2380
 
2381
 
2382
  *Throws:* Any exceptions thrown by the operations in the relevant part
2383
  of [[optional.swap]].
2384
 
2385
- *Remarks:* The expression inside `noexcept` is equivalent to:
2386
 
2387
  ``` cpp
2388
  is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T>
2389
  ```
2390
 
2391
- If any exception is thrown, the results of the expressions `bool(*this)`
2392
- and `bool(rhs)` remain unchanged. If an exception is thrown during the
2393
- call to function `swap`, the state of `*val` and `*rhs.val` is
2394
- determined by the exception safety guarantee of `swap` for lvalues of
2395
- `T`. If an exception is thrown during the call to `T`’s move
2396
- constructor, the state of `*val` and `*rhs.val` is determined by the
2397
- exception safety guarantee of `T`’s move constructor.
2398
 
2399
  #### Observers <a id="optional.observe">[[optional.observe]]</a>
2400
 
2401
  ``` cpp
2402
- constexpr const T* operator->() const;
2403
- constexpr T* operator->();
2404
  ```
2405
 
2406
  *Preconditions:* `*this` contains a value.
2407
 
2408
  *Returns:* `val`.
2409
 
2410
- *Throws:* Nothing.
2411
-
2412
  *Remarks:* These functions are constexpr functions.
2413
 
2414
  ``` cpp
2415
- constexpr const T& operator*() const&;
2416
- constexpr T& operator*() &;
2417
  ```
2418
 
2419
  *Preconditions:* `*this` contains a value.
2420
 
2421
  *Returns:* `*val`.
2422
 
2423
- *Throws:* Nothing.
2424
-
2425
  *Remarks:* These functions are constexpr functions.
2426
 
2427
  ``` cpp
2428
- constexpr T&& operator*() &&;
2429
- constexpr const T&& operator*() const&&;
2430
  ```
2431
 
2432
  *Preconditions:* `*this` contains a value.
2433
 
2434
  *Effects:* Equivalent to: `return std::move(*val);`
@@ -2455,22 +2982,22 @@ constexpr T& value() &;
2455
  ```
2456
 
2457
  *Effects:* Equivalent to:
2458
 
2459
  ``` cpp
2460
- return bool(*this) ? *val : throw bad_optional_access();
2461
  ```
2462
 
2463
  ``` cpp
2464
  constexpr T&& value() &&;
2465
  constexpr const T&& value() const &&;
2466
  ```
2467
 
2468
  *Effects:* Equivalent to:
2469
 
2470
  ``` cpp
2471
- return bool(*this) ? std::move(*val) : throw bad_optional_access();
2472
  ```
2473
 
2474
  ``` cpp
2475
  template<class U> constexpr T value_or(U&& v) const &;
2476
  ```
@@ -2479,11 +3006,11 @@ template<class U> constexpr T value_or(U&& v) const&;
2479
  `true`.
2480
 
2481
  *Effects:* Equivalent to:
2482
 
2483
  ``` cpp
2484
- return bool(*this) ? **this : static_cast<T>(std::forward<U>(v));
2485
  ```
2486
 
2487
  ``` cpp
2488
  template<class U> constexpr T value_or(U&& v) &&;
2489
  ```
@@ -2492,17 +3019,145 @@ template<class U> constexpr T value_or(U&& v) &&;
2492
  `true`.
2493
 
2494
  *Effects:* Equivalent to:
2495
 
2496
  ``` cpp
2497
- return bool(*this) ? std::move(**this) : static_cast<T>(std::forward<U>(v));
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2498
  ```
2499
 
2500
  #### Modifiers <a id="optional.mod">[[optional.mod]]</a>
2501
 
2502
  ``` cpp
2503
- void reset() noexcept;
2504
  ```
2505
 
2506
  *Effects:* If `*this` contains a value, calls `val->T::T̃()` to destroy
2507
  the contained value; otherwise no effect.
2508
 
@@ -2525,15 +3180,17 @@ Type `nullopt_t` shall not have a default constructor or an
2525
  initializer-list constructor, and shall not be an aggregate.
2526
 
2527
  ### Class `bad_optional_access` <a id="optional.bad.access">[[optional.bad.access]]</a>
2528
 
2529
  ``` cpp
 
2530
  class bad_optional_access : public exception {
2531
  public:
2532
  // see [exception] for the specification of the special member functions
2533
  const char* what() const noexcept override;
2534
  };
 
2535
  ```
2536
 
2537
  The class `bad_optional_access` defines the type of objects thrown as
2538
  exceptions to report the situation where an attempt is made to access
2539
  the value of an optional object that does not contain a value.
@@ -2553,12 +3210,12 @@ template<class T, class U> constexpr bool operator==(const optional<T>& x, const
2553
  *Mandates:* The expression `*x == *y` is well-formed and its result is
2554
  convertible to `bool`.
2555
 
2556
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
2557
 
2558
- *Returns:* If `bool(x) != bool(y)`, `false`; otherwise if
2559
- `bool(x) == false`, `true`; otherwise `*x == *y`.
2560
 
2561
  *Remarks:* Specializations of this function template for which
2562
  `*x == *y` is a core constant expression are constexpr functions.
2563
 
2564
  ``` cpp
@@ -2566,12 +3223,12 @@ template<class T, class U> constexpr bool operator!=(const optional<T>& x, const
2566
  ```
2567
 
2568
  *Mandates:* The expression `*x != *y` is well-formed and its result is
2569
  convertible to `bool`.
2570
 
2571
- *Returns:* If `bool(x) != bool(y)`, `true`; otherwise, if
2572
- `bool(x) == false`, `false`; otherwise `*x != *y`.
2573
 
2574
  *Remarks:* Specializations of this function template for which
2575
  `*x != *y` is a core constant expression are constexpr functions.
2576
 
2577
  ``` cpp
@@ -2630,11 +3287,12 @@ convertible to `bool`.
2630
  template<class T, three_way_comparable_with<T> U>
2631
  constexpr compare_three_way_result_t<T, U>
2632
  operator<=>(const optional<T>& x, const optional<U>& y);
2633
  ```
2634
 
2635
- *Returns:* If `x && y`, `*x <=> *y`; otherwise `bool(x) <=> bool(y)`.
 
2636
 
2637
  *Remarks:* Specializations of this function template for which
2638
  `*x <=> *y` is a core constant expression are constexpr functions.
2639
 
2640
  ### Comparison with `nullopt` <a id="optional.nullops">[[optional.nullops]]</a>
@@ -2647,11 +3305,11 @@ template<class T> constexpr bool operator==(const optional<T>& x, nullopt_t) noe
2647
 
2648
  ``` cpp
2649
  template<class T> constexpr strong_ordering operator<=>(const optional<T>& x, nullopt_t) noexcept;
2650
  ```
2651
 
2652
- *Returns:* `bool(x) <=> false`.
2653
 
2654
  ### Comparison with `T` <a id="optional.comp.with.t">[[optional.comp.with.t]]</a>
2655
 
2656
  ``` cpp
2657
  template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
@@ -2660,124 +3318,126 @@ template<class T, class U> constexpr bool operator==(const optional<T>& x, const
2660
  *Mandates:* The expression `*x == v` is well-formed and its result is
2661
  convertible to `bool`.
2662
 
2663
  [*Note 1*: `T` need not be *Cpp17EqualityComparable*. — *end note*]
2664
 
2665
- *Effects:* Equivalent to: `return bool(x) ? *x == v : false;`
2666
 
2667
  ``` cpp
2668
  template<class T, class U> constexpr bool operator==(const T& v, const optional<U>& x);
2669
  ```
2670
 
2671
  *Mandates:* The expression `v == *x` is well-formed and its result is
2672
  convertible to `bool`.
2673
 
2674
- *Effects:* Equivalent to: `return bool(x) ? v == *x : false;`
2675
 
2676
  ``` cpp
2677
  template<class T, class U> constexpr bool operator!=(const optional<T>& x, const U& v);
2678
  ```
2679
 
2680
  *Mandates:* The expression `*x != v` is well-formed and its result is
2681
  convertible to `bool`.
2682
 
2683
- *Effects:* Equivalent to: `return bool(x) ? *x != v : true;`
2684
 
2685
  ``` cpp
2686
  template<class T, class U> constexpr bool operator!=(const T& v, const optional<U>& x);
2687
  ```
2688
 
2689
  *Mandates:* The expression `v != *x` is well-formed and its result is
2690
  convertible to `bool`.
2691
 
2692
- *Effects:* Equivalent to: `return bool(x) ? v != *x : true;`
2693
 
2694
  ``` cpp
2695
  template<class T, class U> constexpr bool operator<(const optional<T>& x, const U& v);
2696
  ```
2697
 
2698
  *Mandates:* The expression `*x < v` is well-formed and its result is
2699
  convertible to `bool`.
2700
 
2701
- *Effects:* Equivalent to: `return bool(x) ? *x < v : true;`
2702
 
2703
  ``` cpp
2704
  template<class T, class U> constexpr bool operator<(const T& v, const optional<U>& x);
2705
  ```
2706
 
2707
  *Mandates:* The expression `v < *x` is well-formed and its result is
2708
  convertible to `bool`.
2709
 
2710
- *Effects:* Equivalent to: `return bool(x) ? v < *x : false;`
2711
 
2712
  ``` cpp
2713
  template<class T, class U> constexpr bool operator>(const optional<T>& x, const U& v);
2714
  ```
2715
 
2716
  *Mandates:* The expression `*x > v` is well-formed and its result is
2717
  convertible to `bool`.
2718
 
2719
- *Effects:* Equivalent to: `return bool(x) ? *x > v : false;`
2720
 
2721
  ``` cpp
2722
  template<class T, class U> constexpr bool operator>(const T& v, const optional<U>& x);
2723
  ```
2724
 
2725
  *Mandates:* The expression `v > *x` is well-formed and its result is
2726
  convertible to `bool`.
2727
 
2728
- *Effects:* Equivalent to: `return bool(x) ? v > *x : true;`
2729
 
2730
  ``` cpp
2731
  template<class T, class U> constexpr bool operator<=(const optional<T>& x, const U& v);
2732
  ```
2733
 
2734
  *Mandates:* The expression `*x <= v` is well-formed and its result is
2735
  convertible to `bool`.
2736
 
2737
- *Effects:* Equivalent to: `return bool(x) ? *x <= v : true;`
2738
 
2739
  ``` cpp
2740
  template<class T, class U> constexpr bool operator<=(const T& v, const optional<U>& x);
2741
  ```
2742
 
2743
  *Mandates:* The expression `v <= *x` is well-formed and its result is
2744
  convertible to `bool`.
2745
 
2746
- *Effects:* Equivalent to: `return bool(x) ? v <= *x : false;`
2747
 
2748
  ``` cpp
2749
  template<class T, class U> constexpr bool operator>=(const optional<T>& x, const U& v);
2750
  ```
2751
 
2752
  *Mandates:* The expression `*x >= v` is well-formed and its result is
2753
  convertible to `bool`.
2754
 
2755
- *Effects:* Equivalent to: `return bool(x) ? *x >= v : false;`
2756
 
2757
  ``` cpp
2758
  template<class T, class U> constexpr bool operator>=(const T& v, const optional<U>& x);
2759
  ```
2760
 
2761
  *Mandates:* The expression `v >= *x` is well-formed and its result is
2762
  convertible to `bool`.
2763
 
2764
- *Effects:* Equivalent to: `return bool(x) ? v >= *x : true;`
2765
 
2766
  ``` cpp
2767
- template<class T, three_way_comparable_with<T> U>
 
2768
  constexpr compare_three_way_result_t<T, U>
2769
  operator<=>(const optional<T>& x, const U& v);
2770
  ```
2771
 
2772
  *Effects:* Equivalent to:
2773
- `return bool(x) ? *x <=> v : strong_ordering::less;`
2774
 
2775
  ### Specialized algorithms <a id="optional.specalg">[[optional.specalg]]</a>
2776
 
2777
  ``` cpp
2778
- template<class T> void swap(optional<T>& x, optional<T>& y) noexcept(noexcept(x.swap(y)));
 
2779
  ```
2780
 
2781
  *Constraints:* `is_move_constructible_v<T>` is `true` and
2782
  `is_swappable_v<T>` is `true`.
2783
 
@@ -2811,11 +3471,11 @@ template<class T, class U, class... Args>
2811
  template<class T> struct hash<optional<T>>;
2812
  ```
2813
 
2814
  The specialization `hash<optional<T>>` is enabled [[unord.hash]] if and
2815
  only if `hash<remove_const_t<T>>` is enabled. When enabled, for an
2816
- object `o` of type `optional<T>`, if `bool(o) == true`, then
2817
  `hash<optional<T>>()(o)` evaluates to the same value as
2818
  `hash<remove_const_t<T>>()(*o)`; otherwise it evaluates to an
2819
  unspecified value. The member functions are not guaranteed to be
2820
  `noexcept`.
2821
 
@@ -2840,11 +3500,11 @@ namespace std {
2840
 
2841
  // [variant.helper], variant helper classes
2842
  template<class T> struct variant_size; // not defined
2843
  template<class T> struct variant_size<const T>;
2844
  template<class T>
2845
- inline constexpr size_t variant_size_v = variant_size<T>::value;
2846
 
2847
  template<class... Types>
2848
  struct variant_size<variant<Types...>>;
2849
 
2850
  template<size_t I, class T> struct variant_alternative; // not defined
@@ -2923,11 +3583,11 @@ namespace std {
2923
  constexpr bool operator==(monostate, monostate) noexcept;
2924
  constexpr strong_ordering operator<=>(monostate, monostate) noexcept;
2925
 
2926
  // [variant.specalg], specialized algorithms
2927
  template<class... Types>
2928
- void swap(variant<Types...>&, variant<Types...>&) noexcept(see below);
2929
 
2930
  // [variant.bad.access], class bad_variant_access
2931
  class bad_variant_access;
2932
 
2933
  // [variant.hash], hash support
@@ -2937,10 +3597,12 @@ namespace std {
2937
  }
2938
  ```
2939
 
2940
  ### Class template `variant` <a id="variant.variant">[[variant.variant]]</a>
2941
 
 
 
2942
  ``` cpp
2943
  namespace std {
2944
  template<class... Types>
2945
  class variant {
2946
  public:
@@ -2961,47 +3623,46 @@ namespace std {
2961
  constexpr explicit variant(in_place_index_t<I>, Args&&...);
2962
  template<size_t I, class U, class... Args>
2963
  constexpr explicit variant(in_place_index_t<I>, initializer_list<U>, Args&&...);
2964
 
2965
  // [variant.dtor], destructor
2966
- ~variant();
2967
 
2968
  // [variant.assign], assignment
2969
  constexpr variant& operator=(const variant&);
2970
  constexpr variant& operator=(variant&&) noexcept(see below);
2971
 
2972
- template<class T> variant& operator=(T&&) noexcept(see below);
2973
 
2974
  // [variant.mod], modifiers
2975
  template<class T, class... Args>
2976
- T& emplace(Args&&...);
2977
  template<class T, class U, class... Args>
2978
- T& emplace(initializer_list<U>, Args&&...);
2979
  template<size_t I, class... Args>
2980
- variant_alternative_t<I, variant<Types...>>& emplace(Args&&...);
2981
  template<size_t I, class U, class... Args>
2982
- variant_alternative_t<I, variant<Types...>>& emplace(initializer_list<U>, Args&&...);
 
2983
 
2984
  // [variant.status], value status
2985
  constexpr bool valueless_by_exception() const noexcept;
2986
  constexpr size_t index() const noexcept;
2987
 
2988
  // [variant.swap], swap
2989
- void swap(variant&) noexcept(see below);
2990
  };
2991
  }
2992
  ```
2993
 
2994
  Any instance of `variant` at any given time either holds a value of one
2995
  of its alternative types or holds no value. When an instance of
2996
  `variant` holds a value of alternative type `T`, it means that a value
2997
  of type `T`, referred to as the `variant` object’s *contained value*, is
2998
  allocated within the storage of the `variant` object. Implementations
2999
  are not permitted to use additional storage, such as dynamic memory, to
3000
- allocate the contained value. The contained value shall be allocated in
3001
- a region of the `variant` storage suitably aligned for all types in
3002
- `Types`.
3003
 
3004
  All types in `Types` shall meet the *Cpp17Destructible* requirements (
3005
  [[cpp17.destructible]]).
3006
 
3007
  A program that instantiates the definition of `variant` with no template
@@ -3024,13 +3685,13 @@ type `T₀`.
3024
  *Ensures:* `valueless_by_exception()` is `false` and `index()` is `0`.
3025
 
3026
  *Throws:* Any exception thrown by the value-initialization of `T₀`.
3027
 
3028
  *Remarks:* This function is `constexpr` if and only if the
3029
- value-initialization of the alternative type `T₀` would satisfy the
3030
- requirements for a constexpr function. The expression inside `noexcept`
3031
- is equivalent to `is_nothrow_default_constructible_v<``T₀``>`.
3032
 
3033
  [*Note 1*: See also class `monostate`. — *end note*]
3034
 
3035
  ``` cpp
3036
  constexpr variant(const variant& w);
@@ -3060,12 +3721,12 @@ same alternative as `w` and direct-initializes the contained value with
3060
  `get<j>(std::move(w))`, where `j` is `w.index()`. Otherwise, initializes
3061
  the `variant` to not hold a value.
3062
 
3063
  *Throws:* Any exception thrown by move-constructing any `Tᵢ` for all i.
3064
 
3065
- *Remarks:* The expression inside `noexcept` is equivalent to the logical
3066
- of `is_nothrow_move_constructible_v<``Tᵢ``>` for all i. If
3067
  `is_trivially_move_constructible_v<``Tᵢ``>` is `true` for all i, this
3068
  constructor is trivial.
3069
 
3070
  ``` cpp
3071
  template<class T> constexpr variant(T&& t) noexcept(see below);
@@ -3093,19 +3754,19 @@ which is the type of the contained value after construction.
3093
  is ill-formed, as both alternative types have an equally viable
3094
  constructor for the argument.
3095
  — *end note*]
3096
 
3097
  *Effects:* Initializes `*this` to hold the alternative type `Tⱼ` and
3098
- direct-initializes the contained value as if
3099
- direct-non-list-initializing it with `std::forward<T>(t)`.
3100
 
3101
  *Ensures:* `holds_alternative<``Tⱼ``>(*this)` is `true`.
3102
 
3103
  *Throws:* Any exception thrown by the initialization of the selected
3104
  alternative `Tⱼ`.
3105
 
3106
- *Remarks:* The expression inside `noexcept` is equivalent to
3107
  `is_nothrow_constructible_v<``Tⱼ``, T>`. If `Tⱼ`’s selected constructor
3108
  is a constexpr constructor, this constructor is a constexpr constructor.
3109
 
3110
  ``` cpp
3111
  template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&... args);
@@ -3114,13 +3775,12 @@ template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>,
3114
  *Constraints:*
3115
 
3116
  - There is exactly one occurrence of `T` in `Types...` and
3117
  - `is_constructible_v<T, Args...>` is `true`.
3118
 
3119
- *Effects:* Initializes the contained value as if
3120
- direct-non-list-initializing an object of type `T` with the arguments
3121
- `std::forward<Args>(args)...`.
3122
 
3123
  *Ensures:* `holds_alternative<T>(*this)` is `true`.
3124
 
3125
  *Throws:* Any exception thrown by calling the selected constructor of
3126
  `T`.
@@ -3136,13 +3796,12 @@ template<class T, class U, class... Args>
3136
  *Constraints:*
3137
 
3138
  - There is exactly one occurrence of `T` in `Types...` and
3139
  - `is_constructible_v<T, initializer_list<U>&, Args...>` is `true`.
3140
 
3141
- *Effects:* Initializes the contained value as if
3142
- direct-non-list-initializing an object of type `T` with the arguments
3143
- `il, std::forward<Args>(args)...`.
3144
 
3145
  *Ensures:* `holds_alternative<T>(*this)` is `true`.
3146
 
3147
  *Throws:* Any exception thrown by calling the selected constructor of
3148
  `T`.
@@ -3157,13 +3816,12 @@ template<size_t I, class... Args> constexpr explicit variant(in_place_index_t<I>
3157
  *Constraints:*
3158
 
3159
  - `I` is less than `sizeof...(Types)` and
3160
  - `is_constructible_v<``T_I``, Args...>` is `true`.
3161
 
3162
- *Effects:* Initializes the contained value as if
3163
- direct-non-list-initializing an object of type `T_I` with the arguments
3164
- `std::forward<Args>(args)...`.
3165
 
3166
  *Ensures:* `index()` is `I`.
3167
 
3168
  *Throws:* Any exception thrown by calling the selected constructor of
3169
  `T_I`.
@@ -3180,23 +3838,22 @@ template<size_t I, class U, class... Args>
3180
 
3181
  - `I` is less than `sizeof...(Types)` and
3182
  - `is_constructible_v<``T_I``, initializer_list<U>&, Args...>` is
3183
  `true`.
3184
 
3185
- *Effects:* Initializes the contained value as if
3186
- direct-non-list-initializing an object of type `T_I` with the arguments
3187
- `il, std::forward<Args>(args)...`.
3188
 
3189
  *Ensures:* `index()` is `I`.
3190
 
3191
  *Remarks:* If `T_I`’s selected constructor is a constexpr constructor,
3192
  this constructor is a constexpr constructor.
3193
 
3194
  #### Destructor <a id="variant.dtor">[[variant.dtor]]</a>
3195
 
3196
  ``` cpp
3197
- ~variant();
3198
  ```
3199
 
3200
  *Effects:* If `valueless_by_exception()` is `false`, destroys the
3201
  currently contained value.
3202
 
@@ -3221,14 +3878,14 @@ Let j be `rhs.index()`.
3221
  - Otherwise, if either `is_nothrow_copy_constructible_v<``Tⱼ``>` is
3222
  `true` or `is_nothrow_move_constructible_v<``Tⱼ``>` is `false`,
3223
  equivalent to `emplace<`j`>(get<`j`>(rhs))`.
3224
  - Otherwise, equivalent to `operator=(variant(rhs))`.
3225
 
3226
- *Returns:* `*this`.
3227
-
3228
  *Ensures:* `index() == rhs.index()`.
3229
 
 
 
3230
  *Remarks:* This operator is defined as deleted unless
3231
  `is_copy_constructible_v<``Tᵢ``> &&` `is_copy_assignable_v<``Tᵢ``>` is
3232
  `true` for all i. If `is_trivially_copy_constructible_v<``Tᵢ``> &&`
3233
  `is_trivially_copy_assignable_v<``Tᵢ``> &&`
3234
  `is_trivially_destructible_v<``Tᵢ``>` is `true` for all i, this
@@ -3255,23 +3912,23 @@ Let j be `rhs.index()`.
3255
  *Returns:* `*this`.
3256
 
3257
  *Remarks:* If `is_trivially_move_constructible_v<``Tᵢ``> &&`
3258
  `is_trivially_move_assignable_v<``Tᵢ``> &&`
3259
  `is_trivially_destructible_v<``Tᵢ``>` is `true` for all i, this
3260
- assignment operator is trivial. The expression inside `noexcept` is
3261
- equivalent to:
3262
  `is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_move_assignable_v<``Tᵢ``>`
3263
  for all i.
3264
 
3265
  - If an exception is thrown during the call to `Tⱼ`’s move construction
3266
  (with j being `rhs.index()`), the `variant` will hold no value.
3267
  - If an exception is thrown during the call to `Tⱼ`’s move assignment,
3268
  the state of the contained value is as defined by the exception safety
3269
  guarantee of `Tⱼ`’s move assignment; `index()` will be j.
3270
 
3271
  ``` cpp
3272
- template<class T> variant& operator=(T&& t) noexcept(see below);
3273
  ```
3274
 
3275
  Let `Tⱼ` be a type that is determined as follows: build an imaginary
3276
  function *FUN*(Tᵢ) for each alternative type `Tᵢ` for which `Tᵢ`` x[] =`
3277
  `{std::forward<T>(t)};` is well-formed for some invented variable `x`.
@@ -3299,18 +3956,18 @@ which is the type of the contained value after assignment.
3299
  - If `*this` holds a `Tⱼ`, assigns `std::forward<T>(t)` to the value
3300
  contained in `*this`.
3301
  - Otherwise, if `is_nothrow_constructible_v<``Tⱼ``, T> ||`
3302
  `!is_nothrow_move_constructible_v<``Tⱼ``>` is `true`, equivalent to
3303
  `emplace<`j`>(std::forward<T>(t))`.
3304
- - Otherwise, equivalent to `operator=(variant(std::forward<T>(t)))`.
3305
 
3306
  *Ensures:* `holds_alternative<``Tⱼ``>(*this)` is `true`, with `Tⱼ`
3307
  selected by the imaginary function overload resolution described above.
3308
 
3309
  *Returns:* `*this`.
3310
 
3311
- *Remarks:* The expression inside `noexcept` is equivalent to:
3312
 
3313
  ``` cpp
3314
  is_nothrow_assignable_v<Tⱼ&, T> && is_nothrow_constructible_v<Tⱼ, T>
3315
  ```
3316
 
@@ -3318,16 +3975,16 @@ is_nothrow_assignable_v<Tⱼ&, T> && is_nothrow_constructible_v<Tⱼ, T>
3318
  `std::forward<T>(t)` to the value contained in `*this`, the state of
3319
  the contained value and `t` are as defined by the exception safety
3320
  guarantee of the assignment expression; `valueless_by_exception()`
3321
  will be `false`.
3322
  - If an exception is thrown during the initialization of the contained
3323
- value, the `variant` object might not hold a value.
3324
 
3325
  #### Modifiers <a id="variant.mod">[[variant.mod]]</a>
3326
 
3327
  ``` cpp
3328
- template<class T, class... Args> T& emplace(Args&&... args);
3329
  ```
3330
 
3331
  *Constraints:* `is_constructible_v<T, Args...>` is `true`, and `T`
3332
  occurs exactly once in `Types`.
3333
 
@@ -3338,11 +3995,12 @@ return emplace<I>(std::forward<Args>(args)...);
3338
  ```
3339
 
3340
  where I is the zero-based index of `T` in `Types`.
3341
 
3342
  ``` cpp
3343
- template<class T, class U, class... Args> T& emplace(initializer_list<U> il, Args&&... args);
 
3344
  ```
3345
 
3346
  *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
3347
  `true`, and `T` occurs exactly once in `Types`.
3348
 
@@ -3354,56 +4012,57 @@ return emplace<I>(il, std::forward<Args>(args)...);
3354
 
3355
  where I is the zero-based index of `T` in `Types`.
3356
 
3357
  ``` cpp
3358
  template<size_t I, class... Args>
3359
- variant_alternative_t<I, variant<Types...>>& emplace(Args&&... args);
3360
  ```
3361
 
3362
  *Mandates:* `I` < `sizeof...(Types)`.
3363
 
3364
  *Constraints:* `is_constructible_v<``T_I``, Args...>` is `true`.
3365
 
3366
  *Effects:* Destroys the currently contained value if
3367
- `valueless_by_exception()` is `false`. Then initializes the contained
3368
- value as if direct-non-list-initializing a value of type `T_I` with the
3369
- arguments `std::forward<Args>(args)...`.
3370
 
3371
  *Ensures:* `index()` is `I`.
3372
 
3373
  *Returns:* A reference to the new contained value.
3374
 
3375
  *Throws:* Any exception thrown during the initialization of the
3376
  contained value.
3377
 
3378
  *Remarks:* If an exception is thrown during the initialization of the
3379
- contained value, the `variant` might not hold a value.
3380
 
3381
  ``` cpp
3382
  template<size_t I, class U, class... Args>
3383
- variant_alternative_t<I, variant<Types...>>& emplace(initializer_list<U> il, Args&&... args);
 
3384
  ```
3385
 
3386
  *Mandates:* `I` < `sizeof...(Types)`.
3387
 
3388
  *Constraints:*
3389
  `is_constructible_v<``T_I``, initializer_list<U>&, Args...>` is `true`.
3390
 
3391
  *Effects:* Destroys the currently contained value if
3392
- `valueless_by_exception()` is `false`. Then initializes the contained
3393
- value as if direct-non-list-initializing a value of type `T_I` with the
3394
- arguments `il, std::forward<Args>(args)...`.
3395
 
3396
  *Ensures:* `index()` is `I`.
3397
 
3398
  *Returns:* A reference to the new contained value.
3399
 
3400
  *Throws:* Any exception thrown during the initialization of the
3401
  contained value.
3402
 
3403
  *Remarks:* If an exception is thrown during the initialization of the
3404
- contained value, the `variant` might not hold a value.
3405
 
3406
  #### Value status <a id="variant.status">[[variant.status]]</a>
3407
 
3408
  ``` cpp
3409
  constexpr bool valueless_by_exception() const noexcept;
@@ -3411,14 +4070,14 @@ constexpr bool valueless_by_exception() const noexcept;
3411
 
3412
  *Effects:* Returns `false` if and only if the `variant` holds a value.
3413
 
3414
  [*Note 1*:
3415
 
3416
- A `variant` might not hold a value if an exception is thrown during a
3417
- type-changing assignment or emplacement. The latter means that even a
3418
- `variant<float, int>` can become `valueless_by_exception()`, for
3419
- instance by
3420
 
3421
  ``` cpp
3422
  struct S { operator int() { throw 42; }};
3423
  variant<float, int> v{12.f};
3424
  v.emplace<1>(S());
@@ -3435,17 +4094,17 @@ constexpr size_t index() const noexcept;
3435
  alternative of the contained value.
3436
 
3437
  #### Swap <a id="variant.swap">[[variant.swap]]</a>
3438
 
3439
  ``` cpp
3440
- void swap(variant& rhs) noexcept(see below);
3441
  ```
3442
 
3443
  *Mandates:* `is_move_constructible_v<``Tᵢ``>` is `true` for all i.
3444
 
3445
- *Preconditions:* Lvalues of type `Tᵢ` are
3446
- swappable [[swappable.requirements]].
3447
 
3448
  *Effects:*
3449
 
3450
  - If `valueless_by_exception() && rhs.valueless_by_exception()` no
3451
  effect.
@@ -3463,11 +4122,11 @@ with i being `index()` and j being `rhs.index()`.
3463
  values of `*this` and of `rhs` are determined by the exception safety
3464
  guarantee of `swap` for lvalues of `Tᵢ` with i being `index()`. If an
3465
  exception is thrown during the exchange of the values of `*this` and
3466
  `rhs`, the states of the values of `*this` and of `rhs` are determined
3467
  by the exception safety guarantee of `variant`’s move constructor. The
3468
- expression inside `noexcept` is equivalent to the logical of
3469
  `is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_swappable_v<``Tᵢ``>`
3470
  for all i.
3471
 
3472
  ### `variant` helper classes <a id="variant.helper">[[variant.helper]]</a>
3473
 
@@ -3478,11 +4137,11 @@ template<class T> struct variant_size;
3478
  All specializations of `variant_size` meet the *Cpp17UnaryTypeTrait*
3479
  requirements [[meta.rqmts]] with a base characteristic of
3480
  `integral_constant<size_t, N>` for some `N`.
3481
 
3482
  ``` cpp
3483
- template<class T> class variant_size<const T>;
3484
  ```
3485
 
3486
  Let `VS` denote `variant_size<T>` of the cv-unqualified type `T`. Then
3487
  each specialization of the template meets the *Cpp17UnaryTypeTrait*
3488
  requirements [[meta.rqmts]] with a base characteristic of
@@ -3492,11 +4151,11 @@ requirements [[meta.rqmts]] with a base characteristic of
3492
  template<class... Types>
3493
  struct variant_size<variant<Types...>> : integral_constant<size_t, sizeof...(Types)> { };
3494
  ```
3495
 
3496
  ``` cpp
3497
- template<size_t I, class T> class variant_alternative<I, const T>;
3498
  ```
3499
 
3500
  Let `VA` denote `variant_alternative<I, T>` of the cv-unqualified type
3501
  `T`. Then each specialization of the template meets the
3502
  *Cpp17TransformationTrait* requirements [[meta.rqmts]] with a member
@@ -3685,41 +4344,62 @@ template<class Visitor, class... Variants>
3685
  constexpr see below visit(Visitor&& vis, Variants&&... vars);
3686
  template<class R, class Visitor, class... Variants>
3687
  constexpr R visit(Visitor&& vis, Variants&&... vars);
3688
  ```
3689
 
3690
- Let n be `sizeof...(Variants)`. Let `m` be a pack of n values of type
3691
- `size_t`. Such a pack is called valid if 0 ≤
3692
- `mᵢ` < `variant_size_v<remove_reference_t<Variantsᵢ``>>` for all
3693
- 0 ≤ i < n. For each valid pack `m`, let e(`m`) denote the expression:
3694
 
3695
  ``` cpp
3696
- INVOKE(std::forward<Visitor>(vis), get<m>(std::forward<Variants>(vars))...) // see [func.require]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3697
  ```
3698
 
3699
  for the first form and
3700
 
3701
  ``` cpp
3702
- INVOKE<R>(std::forward<Visitor>(vis), get<m>(std::forward<Variants>(vars))...) // see [func.require]
3703
  ```
3704
 
3705
  for the second form.
3706
 
3707
- *Mandates:* For each valid pack `m`, e(`m`) is a valid expression. All
3708
- such expressions are of the same type and value category.
3709
 
3710
- *Returns:* e(`m`), where `m` is the pack for which `mᵢ` is
3711
- `vars`ᵢ`.index()` for all 0 ≤ i < n. The return type is
3712
- `decltype(`e(`m`)`)` for the first form.
3713
 
3714
- *Throws:* `bad_variant_access` if any `variant` in `vars` is
3715
- `valueless_by_exception()`.
3716
 
3717
  *Complexity:* For n ≤ 1, the invocation of the callable object is
3718
  implemented in constant time, i.e., for n = 1, it does not depend on the
3719
- number of alternative types of `Variants₀`. For n > 1, the invocation of
3720
- the callable object has no complexity requirements.
3721
 
3722
  ### Class `monostate` <a id="variant.monostate">[[variant.monostate]]</a>
3723
 
3724
  ``` cpp
3725
  struct monostate{};
@@ -3741,30 +4421,32 @@ always compare equal. — *end note*]
3741
 
3742
  ### Specialized algorithms <a id="variant.specalg">[[variant.specalg]]</a>
3743
 
3744
  ``` cpp
3745
  template<class... Types>
3746
- void swap(variant<Types...>& v, variant<Types...>& w) noexcept(see below);
3747
  ```
3748
 
3749
  *Constraints:*
3750
  `is_move_constructible_v<``Tᵢ``> && is_swappable_v<``Tᵢ``>` is `true`
3751
  for all i.
3752
 
3753
  *Effects:* Equivalent to `v.swap(w)`.
3754
 
3755
- *Remarks:* The expression inside `noexcept` is equivalent to
3756
  `noexcept(v.swap(w))`.
3757
 
3758
  ### Class `bad_variant_access` <a id="variant.bad.access">[[variant.bad.access]]</a>
3759
 
3760
  ``` cpp
 
3761
  class bad_variant_access : public exception {
3762
  public:
3763
  // see [exception] for the specification of the special member functions
3764
  const char* what() const noexcept override;
3765
  };
 
3766
  ```
3767
 
3768
  Objects of type `bad_variant_access` are thrown to report invalid
3769
  accesses to the value of a `variant` object.
3770
 
@@ -3790,14 +4472,16 @@ template<> struct hash<monostate>;
3790
 
3791
  The specialization is enabled [[unord.hash]].
3792
 
3793
  ## Storage for any type <a id="any">[[any]]</a>
3794
 
3795
- This subclause describes components that C++ programs may use to perform
3796
- operations on objects of a discriminated type.
3797
 
3798
- [*Note 1*: The discriminated type may contain values of different types
 
 
 
3799
  but does not attempt conversion between them, i.e., `5` is held strictly
3800
  as an `int` and is not implicitly convertible either to `"5"` or to
3801
  `5.0`. This indifference to interpretation but awareness of type
3802
  effectively allows safe, generic containers of single values, with no
3803
  scope for surprises from ambiguous conversions. — *end note*]
@@ -3835,15 +4519,17 @@ namespace std {
3835
  ```
3836
 
3837
  ### Class `bad_any_cast` <a id="any.bad.any.cast">[[any.bad.any.cast]]</a>
3838
 
3839
  ``` cpp
 
3840
  class bad_any_cast : public bad_cast {
3841
  public:
3842
  // see [exception] for the specification of the special member functions
3843
  const char* what() const noexcept override;
3844
  };
 
3845
  ```
3846
 
3847
  Objects of type `bad_any_cast` are thrown by a failed `any_cast`
3848
  [[any.nonmembers]].
3849
 
@@ -3853,10 +4539,12 @@ const char* what() const noexcept override;
3853
 
3854
  *Returns:* An *implementation-defined* NTBS.
3855
 
3856
  ### Class `any` <a id="any.class">[[any.class]]</a>
3857
 
 
 
3858
  ``` cpp
3859
  namespace std {
3860
  class any {
3861
  public:
3862
  // [any.cons], construction and destruction
@@ -3973,13 +4661,12 @@ Let `VT` be `decay_t<T>`.
3973
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
3974
  `is_constructible_v<VT, Args...>` is `true`.
3975
 
3976
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
3977
 
3978
- *Effects:* Initializes the contained value as if
3979
- direct-non-list-initializing an object of type `VT` with the arguments
3980
- `std::forward<Args>(args)...`.
3981
 
3982
  *Ensures:* `*this` contains a value of type `VT`.
3983
 
3984
  *Throws:* Any exception thrown by the selected constructor of `VT`.
3985
 
@@ -3993,13 +4680,12 @@ Let `VT` be `decay_t<T>`.
3993
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
3994
  `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`.
3995
 
3996
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
3997
 
3998
- *Effects:* Initializes the contained value as if
3999
- direct-non-list-initializing an object of type `VT` with the arguments
4000
- `il, std::forward<Args>(args)...`.
4001
 
4002
  *Ensures:* `*this` contains a value.
4003
 
4004
  *Throws:* Any exception thrown by the selected constructor of `VT`.
4005
 
@@ -4027,15 +4713,15 @@ contained value.
4027
  any& operator=(any&& rhs) noexcept;
4028
  ```
4029
 
4030
  *Effects:* As if by `any(std::move(rhs)).swap(*this)`.
4031
 
4032
- *Returns:* `*this`.
4033
-
4034
  *Ensures:* The state of `*this` is equivalent to the original state of
4035
  `rhs`.
4036
 
 
 
4037
  ``` cpp
4038
  template<class T>
4039
  any& operator=(T&& rhs);
4040
  ```
4041
 
@@ -4066,13 +4752,12 @@ Let `VT` be `decay_t<T>`.
4066
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
4067
  `is_constructible_v<VT, Args...>` is `true`.
4068
 
4069
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
4070
 
4071
- *Effects:* Calls `reset()`. Then initializes the contained value as if
4072
- direct-non-list-initializing an object of type `VT` with the arguments
4073
- `std::forward<Args>(args)...`.
4074
 
4075
  *Ensures:* `*this` contains a value.
4076
 
4077
  *Returns:* A reference to the new contained value.
4078
 
@@ -4092,13 +4777,12 @@ Let `VT` be `decay_t<T>`.
4092
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
4093
  `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`.
4094
 
4095
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
4096
 
4097
- *Effects:* Calls `reset()`. Then initializes the contained value as if
4098
- direct-non-list-initializing an object of type `VT` with the arguments
4099
- `il, std::forward<Args>(args)...`.
4100
 
4101
  *Ensures:* `*this` contains a value.
4102
 
4103
  *Returns:* A reference to the new contained value.
4104
 
@@ -4233,32 +4917,1887 @@ bool is_string(const any& operand) {
4233
  }
4234
  ```
4235
 
4236
  — *end example*]
4237
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4238
  ## Bitsets <a id="bitset">[[bitset]]</a>
4239
 
4240
  ### Header `<bitset>` synopsis <a id="bitset.syn">[[bitset.syn]]</a>
4241
 
4242
  The header `<bitset>` defines a class template and several related
4243
  functions for representing and manipulating fixed-size sequences of
4244
  bits.
4245
 
4246
  ``` cpp
4247
- #include <string>
4248
  #include <iosfwd> // for istream[istream.syn], ostream[ostream.syn], see [iosfwd.syn]
4249
 
4250
  namespace std {
4251
  template<size_t N> class bitset;
4252
 
4253
  // [bitset.operators], bitset operators
4254
  template<size_t N>
4255
- bitset<N> operator&(const bitset<N>&, const bitset<N>&) noexcept;
4256
  template<size_t N>
4257
- bitset<N> operator|(const bitset<N>&, const bitset<N>&) noexcept;
4258
  template<size_t N>
4259
- bitset<N> operator^(const bitset<N>&, const bitset<N>&) noexcept;
4260
  template<class charT, class traits, size_t N>
4261
  basic_istream<charT, traits>&
4262
  operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
4263
  template<class charT, class traits, size_t N>
4264
  basic_ostream<charT, traits>&
@@ -4266,82 +6805,85 @@ namespace std {
4266
  }
4267
  ```
4268
 
4269
  ### Class template `bitset` <a id="template.bitset">[[template.bitset]]</a>
4270
 
 
 
4271
  ``` cpp
4272
  namespace std {
4273
  template<size_t N> class bitset {
4274
  public:
4275
  // bit reference
4276
  class reference {
4277
  friend class bitset;
4278
- reference() noexcept;
4279
 
4280
  public:
4281
- reference(const reference&) = default;
4282
- ~reference();
4283
- reference& operator=(bool x) noexcept; // for b[i] = x;
4284
- reference& operator=(const reference&) noexcept; // for b[i] = b[j];
4285
- bool operator~() const noexcept; // flips the bit
4286
- operator bool() const noexcept; // for x = b[i];
4287
- reference& flip() noexcept; // for b[i].flip();
4288
  };
4289
 
4290
  // [bitset.cons], constructors
4291
  constexpr bitset() noexcept;
4292
  constexpr bitset(unsigned long long val) noexcept;
4293
  template<class charT, class traits, class Allocator>
4294
- explicit bitset(
4295
  const basic_string<charT, traits, Allocator>& str,
4296
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
4297
  typename basic_string<charT, traits, Allocator>::size_type n
4298
  = basic_string<charT, traits, Allocator>::npos,
4299
  charT zero = charT('0'),
4300
  charT one = charT('1'));
4301
  template<class charT>
4302
- explicit bitset(
4303
  const charT* str,
4304
  typename basic_string<charT>::size_type n = basic_string<charT>::npos,
4305
  charT zero = charT('0'),
4306
  charT one = charT('1'));
4307
 
4308
  // [bitset.members], bitset operations
4309
- bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
4310
- bitset<N>& operator|=(const bitset<N>& rhs) noexcept;
4311
- bitset<N>& operator^=(const bitset<N>& rhs) noexcept;
4312
- bitset<N>& operator<<=(size_t pos) noexcept;
4313
- bitset<N>& operator>>=(size_t pos) noexcept;
4314
- bitset<N>& set() noexcept;
4315
- bitset<N>& set(size_t pos, bool val = true);
4316
- bitset<N>& reset() noexcept;
4317
- bitset<N>& reset(size_t pos);
4318
- bitset<N> operator~() const noexcept;
4319
- bitset<N>& flip() noexcept;
4320
- bitset<N>& flip(size_t pos);
 
 
4321
 
4322
  // element access
4323
- constexpr bool operator[](size_t pos) const; // for b[i];
4324
- reference operator[](size_t pos); // for b[i];
4325
 
4326
- unsigned long to_ulong() const;
4327
- unsigned long long to_ullong() const;
4328
  template<class charT = char,
4329
  class traits = char_traits<charT>,
4330
  class Allocator = allocator<charT>>
4331
- basic_string<charT, traits, Allocator>
4332
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
4333
 
4334
- size_t count() const noexcept;
 
4335
  constexpr size_t size() const noexcept;
4336
- bool operator==(const bitset<N>& rhs) const noexcept;
4337
- bool test(size_t pos) const;
4338
- bool all() const noexcept;
4339
- bool any() const noexcept;
4340
- bool none() const noexcept;
4341
- bitset<N> operator<<(size_t pos) const noexcept;
4342
- bitset<N> operator>>(size_t pos) const noexcept;
4343
  };
4344
 
4345
  // [bitset.hash], hash support
4346
  template<class T> struct hash;
4347
  template<size_t N> struct hash<bitset<N>>;
@@ -4357,11 +6899,11 @@ zero. Each bit has a non-negative position `pos`. When converting
4357
  between an object of class `bitset<N>` and a value of some integral
4358
  type, bit position `pos` corresponds to the *bit value* `1 << pos`. The
4359
  integral value corresponding to two or more bits is the sum of their bit
4360
  values.
4361
 
4362
- The functions described in this subclause can report three kinds of
4363
  errors, each associated with a distinct exception:
4364
 
4365
  - an *invalid-argument* error is associated with exceptions of type
4366
  `invalid_argument` [[invalid.argument]];
4367
  - an *out-of-range* error is associated with exceptions of type
@@ -4381,16 +6923,17 @@ constexpr bitset() noexcept;
4381
  constexpr bitset(unsigned long long val) noexcept;
4382
  ```
4383
 
4384
  *Effects:* Initializes the first `M` bit positions to the corresponding
4385
  bit values in `val`. `M` is the smaller of `N` and the number of bits in
4386
- the value representation [[basic.types]] of `unsigned long long`. If
4387
- `M < N`, the remaining bit positions are initialized to zero.
 
4388
 
4389
  ``` cpp
4390
  template<class charT, class traits, class Allocator>
4391
- explicit bitset(
4392
  const basic_string<charT, traits, Allocator>& str,
4393
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
4394
  typename basic_string<charT, traits, Allocator>::size_type n
4395
  = basic_string<charT, traits, Allocator>::npos,
4396
  charT zero = charT('0'),
@@ -4416,11 +6959,11 @@ The function uses `traits::eq` to compare the character values.
4416
  any of the `rlen` characters in `str` beginning at position `pos` is
4417
  other than `zero` or `one`.
4418
 
4419
  ``` cpp
4420
  template<class charT>
4421
- explicit bitset(
4422
  const charT* str,
4423
  typename basic_string<charT>::size_type n = basic_string<charT>::npos,
4424
  charT zero = charT('0'),
4425
  charT one = charT('1'));
4426
  ```
@@ -4435,38 +6978,38 @@ bitset(n == basic_string<charT>::npos
4435
  ```
4436
 
4437
  #### Members <a id="bitset.members">[[bitset.members]]</a>
4438
 
4439
  ``` cpp
4440
- bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
4441
  ```
4442
 
4443
  *Effects:* Clears each bit in `*this` for which the corresponding bit in
4444
  `rhs` is clear, and leaves all other bits unchanged.
4445
 
4446
  *Returns:* `*this`.
4447
 
4448
  ``` cpp
4449
- bitset<N>& operator|=(const bitset<N>& rhs) noexcept;
4450
  ```
4451
 
4452
  *Effects:* Sets each bit in `*this` for which the corresponding bit in
4453
  `rhs` is set, and leaves all other bits unchanged.
4454
 
4455
  *Returns:* `*this`.
4456
 
4457
  ``` cpp
4458
- bitset<N>& operator^=(const bitset<N>& rhs) noexcept;
4459
  ```
4460
 
4461
  *Effects:* Toggles each bit in `*this` for which the corresponding bit
4462
  in `rhs` is set, and leaves all other bits unchanged.
4463
 
4464
  *Returns:* `*this`.
4465
 
4466
  ``` cpp
4467
- bitset<N>& operator<<=(size_t pos) noexcept;
4468
  ```
4469
 
4470
  *Effects:* Replaces each bit at position `I` in `*this` with a value
4471
  determined as follows:
4472
 
@@ -4475,11 +7018,11 @@ determined as follows:
4475
  position `I - pos`.
4476
 
4477
  *Returns:* `*this`.
4478
 
4479
  ``` cpp
4480
- bitset<N>& operator>>=(size_t pos) noexcept;
4481
  ```
4482
 
4483
  *Effects:* Replaces each bit at position `I` in `*this` with a value
4484
  determined as follows:
4485
 
@@ -4488,19 +7031,31 @@ determined as follows:
4488
  position `I + pos`.
4489
 
4490
  *Returns:* `*this`.
4491
 
4492
  ``` cpp
4493
- bitset<N>& set() noexcept;
 
 
 
 
 
 
 
 
 
 
 
 
4494
  ```
4495
 
4496
  *Effects:* Sets all bits in `*this`.
4497
 
4498
  *Returns:* `*this`.
4499
 
4500
  ``` cpp
4501
- bitset<N>& set(size_t pos, bool val = true);
4502
  ```
4503
 
4504
  *Effects:* Stores a new value in the bit at position `pos` in `*this`.
4505
  If `val` is `true`, the stored value is one, otherwise it is zero.
4506
 
@@ -4508,67 +7063,95 @@ If `val` is `true`, the stored value is one, otherwise it is zero.
4508
 
4509
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
4510
  position.
4511
 
4512
  ``` cpp
4513
- bitset<N>& reset() noexcept;
4514
  ```
4515
 
4516
  *Effects:* Resets all bits in `*this`.
4517
 
4518
  *Returns:* `*this`.
4519
 
4520
  ``` cpp
4521
- bitset<N>& reset(size_t pos);
4522
  ```
4523
 
4524
  *Effects:* Resets the bit at position `pos` in `*this`.
4525
 
4526
  *Returns:* `*this`.
4527
 
4528
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
4529
  position.
4530
 
4531
  ``` cpp
4532
- bitset<N> operator~() const noexcept;
4533
  ```
4534
 
4535
- *Effects:* Constructs an object `x` of class `bitset<N>` and initializes
4536
- it with `*this`.
4537
 
4538
  *Returns:* `x.flip()`.
4539
 
4540
  ``` cpp
4541
- bitset<N>& flip() noexcept;
4542
  ```
4543
 
4544
  *Effects:* Toggles all bits in `*this`.
4545
 
4546
  *Returns:* `*this`.
4547
 
4548
  ``` cpp
4549
- bitset<N>& flip(size_t pos);
4550
  ```
4551
 
4552
  *Effects:* Toggles the bit at position `pos` in `*this`.
4553
 
4554
  *Returns:* `*this`.
4555
 
4556
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
4557
  position.
4558
 
4559
  ``` cpp
4560
- unsigned long to_ulong() const;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4561
  ```
4562
 
4563
  *Returns:* `x`.
4564
 
4565
  *Throws:* `overflow_error` if the integral value `x` corresponding to
4566
  the bits in `*this` cannot be represented as type `unsigned long`.
4567
 
4568
  ``` cpp
4569
- unsigned long long to_ullong() const;
4570
  ```
4571
 
4572
  *Returns:* `x`.
4573
 
4574
  *Throws:* `overflow_error` if the integral value `x` corresponding to
@@ -4576,11 +7159,11 @@ the bits in `*this` cannot be represented as type `unsigned long long`.
4576
 
4577
  ``` cpp
4578
  template<class charT = char,
4579
  class traits = char_traits<charT>,
4580
  class Allocator = allocator<charT>>
4581
- basic_string<charT, traits, Allocator>
4582
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
4583
  ```
4584
 
4585
  *Effects:* Constructs a string object of the appropriate type and
4586
  initializes it to a string of length `N` characters. Each character is
@@ -4591,11 +7174,11 @@ Bit value zero becomes the character `zero`, bit value one becomes the
4591
  character `one`.
4592
 
4593
  *Returns:* The created object.
4594
 
4595
  ``` cpp
4596
- size_t count() const noexcept;
4597
  ```
4598
 
4599
  *Returns:* A count of the number of bits set in `*this`.
4600
 
4601
  ``` cpp
@@ -4603,84 +7186,44 @@ constexpr size_t size() const noexcept;
4603
  ```
4604
 
4605
  *Returns:* `N`.
4606
 
4607
  ``` cpp
4608
- bool operator==(const bitset<N>& rhs) const noexcept;
4609
  ```
4610
 
4611
  *Returns:* `true` if the value of each bit in `*this` equals the value
4612
  of the corresponding bit in `rhs`.
4613
 
4614
  ``` cpp
4615
- bool test(size_t pos) const;
4616
  ```
4617
 
4618
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
4619
  one.
4620
 
4621
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
4622
  position.
4623
 
4624
  ``` cpp
4625
- bool all() const noexcept;
4626
  ```
4627
 
4628
  *Returns:* `count() == size()`.
4629
 
4630
  ``` cpp
4631
- bool any() const noexcept;
4632
  ```
4633
 
4634
  *Returns:* `count() != 0`.
4635
 
4636
  ``` cpp
4637
- bool none() const noexcept;
4638
  ```
4639
 
4640
  *Returns:* `count() == 0`.
4641
 
4642
- ``` cpp
4643
- bitset<N> operator<<(size_t pos) const noexcept;
4644
- ```
4645
-
4646
- *Returns:* `bitset<N>(*this) <<= pos`.
4647
-
4648
- ``` cpp
4649
- bitset<N> operator>>(size_t pos) const noexcept;
4650
- ```
4651
-
4652
- *Returns:* `bitset<N>(*this) >>= pos`.
4653
-
4654
- ``` cpp
4655
- constexpr bool operator[](size_t pos) const;
4656
- ```
4657
-
4658
- *Preconditions:* `pos` is valid.
4659
-
4660
- *Returns:* `true` if the bit at position `pos` in `*this` has the value
4661
- one, otherwise `false`.
4662
-
4663
- *Throws:* Nothing.
4664
-
4665
- ``` cpp
4666
- bitset<N>::reference operator[](size_t pos);
4667
- ```
4668
-
4669
- *Preconditions:* `pos` is valid.
4670
-
4671
- *Returns:* An object of type `bitset<N>::reference` such that
4672
- `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
4673
- equivalent to `this->set(pos, val)`.
4674
-
4675
- *Throws:* Nothing.
4676
-
4677
- *Remarks:* For the purpose of determining the presence of a data
4678
- race [[intro.multithread]], any access or update through the resulting
4679
- reference potentially accesses or modifies, respectively, the entire
4680
- underlying bitset.
4681
-
4682
  ### `bitset` hash support <a id="bitset.hash">[[bitset.hash]]</a>
4683
 
4684
  ``` cpp
4685
  template<size_t N> struct hash<bitset<N>>;
4686
  ```
@@ -4688,23 +7231,26 @@ template<size_t N> struct hash<bitset<N>>;
4688
  The specialization is enabled [[unord.hash]].
4689
 
4690
  ### `bitset` operators <a id="bitset.operators">[[bitset.operators]]</a>
4691
 
4692
  ``` cpp
4693
- bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
 
4694
  ```
4695
 
4696
  *Returns:* `bitset<N>(lhs) &= rhs`.
4697
 
4698
  ``` cpp
4699
- bitset<N> operator|(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
 
4700
  ```
4701
 
4702
  *Returns:* `bitset<N>(lhs) |= rhs`.
4703
 
4704
  ``` cpp
4705
- bitset<N> operator^(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
 
4706
  ```
4707
 
4708
  *Returns:* `bitset<N>(lhs) ^= rhs`.
4709
 
4710
  ``` cpp
@@ -4724,13 +7270,13 @@ the following occurs:
4724
  - `N` characters have been extracted and stored;
4725
  - end-of-file occurs on the input sequence;
4726
  - the next input character is neither `is.widen(’0’)` nor
4727
  `is.widen(’1’)` (in which case the input character is not extracted).
4728
 
4729
- If `N > 0` and no characters are stored in `str`, calls
4730
- `is.setstate(ios_base::failbit)` (which may throw `ios_base::failure`
4731
- [[iostate.flags]]).
4732
 
4733
  *Returns:* `is`.
4734
 
4735
  ``` cpp
4736
  template<class charT, class traits, size_t N>
@@ -4746,4630 +7292,172 @@ os << x.template to_string<charT, traits, allocator<charT>>(
4746
  use_facet<ctype<charT>>(os.getloc()).widen('1'))
4747
  ```
4748
 
4749
  (see  [[ostream.formatted]]).
4750
 
4751
- ## Memory <a id="memory">[[memory]]</a>
4752
-
4753
- ### In general <a id="memory.general">[[memory.general]]</a>
4754
-
4755
- Subclause  [[memory]] describes the contents of the header `<memory>`
4756
- and some of the contents of the header `<cstdlib>`.
4757
-
4758
- ### Header `<memory>` synopsis <a id="memory.syn">[[memory.syn]]</a>
4759
-
4760
- The header `<memory>` defines several types and function templates that
4761
- describe properties of pointers and pointer-like types, manage memory
4762
- for containers and other template types, destroy objects, and construct
4763
- objects in uninitialized memory buffers ([[pointer.traits]]–
4764
- [[specialized.addressof]] and [[specialized.algorithms]]). The header
4765
- also defines the templates `unique_ptr`, `shared_ptr`, `weak_ptr`, and
4766
- various function templates that operate on objects of these types
4767
- [[smartptr]].
4768
-
4769
- ``` cpp
4770
- #include <compare> // see [compare.syn]
4771
-
4772
- namespace std {
4773
- // [pointer.traits], pointer traits
4774
- template<class Ptr> struct pointer_traits;
4775
- template<class T> struct pointer_traits<T*>;
4776
-
4777
- // [pointer.conversion], pointer conversion
4778
- template<class T>
4779
- constexpr T* to_address(T* p) noexcept;
4780
- template<class Ptr>
4781
- constexpr auto to_address(const Ptr& p) noexcept;
4782
-
4783
- // [util.dynamic.safety], pointer safety%
4784
- %
4785
- {pointer_safety{pointer_safety{pointer_safety}
4786
- enum class pointer_safety { relaxed, preferred, strict };
4787
- void declare_reachable(void* p);
4788
- template<class T>
4789
- T* undeclare_reachable(T* p);
4790
- void declare_no_pointers(char* p, size_t n);
4791
- void undeclare_no_pointers(char* p, size_t n);
4792
- pointer_safety get_pointer_safety() noexcept;
4793
-
4794
- // [ptr.align], pointer alignment
4795
- void* align(size_t alignment, size_t size, void*& ptr, size_t& space);
4796
- template<size_t N, class T>
4797
- [[nodiscard]] constexpr T* assume_aligned(T* ptr);
4798
-
4799
- // [allocator.tag], allocator argument tag
4800
- struct allocator_arg_t { explicit allocator_arg_t() = default; };
4801
- inline constexpr allocator_arg_t allocator_arg{};
4802
-
4803
- // [allocator.uses], uses_allocator
4804
- template<class T, class Alloc> struct uses_allocator;
4805
-
4806
- // [allocator.uses.trait], uses_allocator
4807
- template<class T, class Alloc>
4808
- inline constexpr bool uses_allocator_v = uses_allocator<T, Alloc>::value;
4809
-
4810
- // [allocator.uses.construction], uses-allocator construction
4811
- template<class T, class Alloc, class... Args>
4812
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
4813
- Args&&... args) noexcept -> see below;
4814
- template<class T, class Alloc, class Tuple1, class Tuple2>
4815
- constexpr auto uses_allocator_construction_args(const Alloc& alloc, piecewise_construct_t,
4816
- Tuple1&& x, Tuple2&& y)
4817
- noexcept -> see below;
4818
- template<class T, class Alloc>
4819
- constexpr auto uses_allocator_construction_args(const Alloc& alloc) noexcept -> see below;
4820
- template<class T, class Alloc, class U, class V>
4821
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
4822
- U&& u, V&& v) noexcept -> see below;
4823
- template<class T, class Alloc, class U, class V>
4824
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
4825
- const pair<U,V>& pr) noexcept -> see below;
4826
- template<class T, class Alloc, class U, class V>
4827
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
4828
- pair<U,V>&& pr) noexcept -> see below;
4829
- template<class T, class Alloc, class... Args>
4830
- constexpr T make_obj_using_allocator(const Alloc& alloc, Args&&... args);
4831
- template<class T, class Alloc, class... Args>
4832
- constexpr T* uninitialized_construct_using_allocator(T* p, const Alloc& alloc,
4833
- Args&&... args);
4834
-
4835
- // [allocator.traits], allocator traits
4836
- template<class Alloc> struct allocator_traits;
4837
-
4838
- // [default.allocator], the default allocator
4839
- template<class T> class allocator;
4840
- template<class T, class U>
4841
- constexpr bool operator==(const allocator<T>&, const allocator<U>&) noexcept;
4842
-
4843
- // [specialized.addressof], addressof
4844
- template<class T>
4845
- constexpr T* addressof(T& r) noexcept;
4846
- template<class T>
4847
- const T* addressof(const T&&) = delete;
4848
-
4849
- // [specialized.algorithms], specialized algorithms
4850
- // [special.mem.concepts], special memory concepts
4851
- template<class I>
4852
- concept no-throw-input-iterator = see below; // exposition only
4853
- template<class I>
4854
- concept no-throw-forward-iterator = see below; // exposition only
4855
- template<class S, class I>
4856
- concept no-throw-sentinel = see below; // exposition only
4857
- template<class R>
4858
- concept no-throw-input-range = see below; // exposition only
4859
- template<class R>
4860
- concept no-throw-forward-range = see below; // exposition only
4861
-
4862
- template<class NoThrowForwardIterator>
4863
- void uninitialized_default_construct(NoThrowForwardIterator first,
4864
- NoThrowForwardIterator last);
4865
- template<class ExecutionPolicy, class NoThrowForwardIterator>
4866
- void uninitialized_default_construct(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4867
- NoThrowForwardIterator first,
4868
- NoThrowForwardIterator last);
4869
- template<class NoThrowForwardIterator, class Size>
4870
- NoThrowForwardIterator
4871
- uninitialized_default_construct_n(NoThrowForwardIterator first, Size n);
4872
- template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>
4873
- NoThrowForwardIterator
4874
- uninitialized_default_construct_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4875
- NoThrowForwardIterator first, Size n);
4876
-
4877
- namespace ranges {
4878
- template<no-throw-forward-iterator I, no-throw-sentinel<I> S>
4879
- requires default_initializable<iter_value_t<I>>
4880
- I uninitialized_default_construct(I first, S last);
4881
- template<no-throw-forward-range R>
4882
- requires default_initializable<range_value_t<R>>
4883
- borrowed_iterator_t<R> uninitialized_default_construct(R&& r);
4884
-
4885
- template<no-throw-forward-iterator I>
4886
- requires default_initializable<iter_value_t<I>>
4887
- I uninitialized_default_construct_n(I first, iter_difference_t<I> n);
4888
- }
4889
-
4890
- template<class NoThrowForwardIterator>
4891
- void uninitialized_value_construct(NoThrowForwardIterator first,
4892
- NoThrowForwardIterator last);
4893
- template<class ExecutionPolicy, class NoThrowForwardIterator>
4894
- void uninitialized_value_construct(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4895
- NoThrowForwardIterator first,
4896
- NoThrowForwardIterator last);
4897
- template<class NoThrowForwardIterator, class Size>
4898
- NoThrowForwardIterator
4899
- uninitialized_value_construct_n(NoThrowForwardIterator first, Size n);
4900
- template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>
4901
- NoThrowForwardIterator
4902
- uninitialized_value_construct_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4903
- NoThrowForwardIterator first, Size n);
4904
-
4905
- namespace ranges {
4906
- template<no-throw-forward-iterator I, no-throw-sentinel<I> S>
4907
- requires default_initializable<iter_value_t<I>>
4908
- I uninitialized_value_construct(I first, S last);
4909
- template<no-throw-forward-range R>
4910
- requires default_initializable<range_value_t<R>>
4911
- borrowed_iterator_t<R> uninitialized_value_construct(R&& r);
4912
-
4913
- template<no-throw-forward-iterator I>
4914
- requires default_initializable<iter_value_t<I>>
4915
- I uninitialized_value_construct_n(I first, iter_difference_t<I> n);
4916
- }
4917
-
4918
- template<class InputIterator, class NoThrowForwardIterator>
4919
- NoThrowForwardIterator uninitialized_copy(InputIterator first, InputIterator last,
4920
- NoThrowForwardIterator result);
4921
- template<class ExecutionPolicy, class InputIterator, class NoThrowForwardIterator>
4922
- NoThrowForwardIterator uninitialized_copy(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4923
- InputIterator first, InputIterator last,
4924
- NoThrowForwardIterator result);
4925
- template<class InputIterator, class Size, class NoThrowForwardIterator>
4926
- NoThrowForwardIterator uninitialized_copy_n(InputIterator first, Size n,
4927
- NoThrowForwardIterator result);
4928
- template<class ExecutionPolicy, class InputIterator, class Size, class NoThrowForwardIterator>
4929
- NoThrowForwardIterator uninitialized_copy_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4930
- InputIterator first, Size n,
4931
- NoThrowForwardIterator result);
4932
-
4933
- namespace ranges {
4934
- template<class I, class O>
4935
- using uninitialized_copy_result = in_out_result<I, O>;
4936
- template<input_iterator I, sentinel_for<I> S1,
4937
- no-throw-forward-iterator O, no-throw-sentinel<O> S2>
4938
- requires constructible_from<iter_value_t<O>, iter_reference_t<I>>
4939
- uninitialized_copy_result<I, O>
4940
- uninitialized_copy(I ifirst, S1 ilast, O ofirst, S2 olast);
4941
- template<input_range IR, no-throw-forward-range OR>
4942
- requires constructible_from<range_value_t<OR>, range_reference_t<IR>>
4943
- uninitialized_copy_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
4944
- uninitialized_copy(IR&& in_range, OR&& out_range);
4945
-
4946
- template<class I, class O>
4947
- using uninitialized_copy_n_result = in_out_result<I, O>;
4948
- template<input_iterator I, no-throw-forward-iterator O, no-throw-sentinel<O> S>
4949
- requires constructible_from<iter_value_t<O>, iter_reference_t<I>>
4950
- uninitialized_copy_n_result<I, O>
4951
- uninitialized_copy_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
4952
- }
4953
-
4954
- template<class InputIterator, class NoThrowForwardIterator>
4955
- NoThrowForwardIterator uninitialized_move(InputIterator first, InputIterator last,
4956
- NoThrowForwardIterator result);
4957
- template<class ExecutionPolicy, class InputIterator, class NoThrowForwardIterator>
4958
- NoThrowForwardIterator uninitialized_move(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4959
- InputIterator first, InputIterator last,
4960
- NoThrowForwardIterator result);
4961
- template<class InputIterator, class Size, class NoThrowForwardIterator>
4962
- pair<InputIterator, NoThrowForwardIterator>
4963
- uninitialized_move_n(InputIterator first, Size n, NoThrowForwardIterator result);
4964
- template<class ExecutionPolicy, class InputIterator, class Size, class NoThrowForwardIterator>
4965
- pair<InputIterator, NoThrowForwardIterator>
4966
- uninitialized_move_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4967
- InputIterator first, Size n, NoThrowForwardIterator result);
4968
-
4969
- namespace ranges {
4970
- template<class I, class O>
4971
- using uninitialized_move_result = in_out_result<I, O>;
4972
- template<input_iterator I, sentinel_for<I> S1,
4973
- no-throw-forward-iterator O, no-throw-sentinel<O> S2>
4974
- requires constructible_from<iter_value_t<O>, iter_rvalue_reference_t<I>>
4975
- uninitialized_move_result<I, O>
4976
- uninitialized_move(I ifirst, S1 ilast, O ofirst, S2 olast);
4977
- template<input_range IR, no-throw-forward-range OR>
4978
- requires constructible_from<range_value_t<OR>, range_rvalue_reference_t<IR>>
4979
- uninitialized_move_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
4980
- uninitialized_move(IR&& in_range, OR&& out_range);
4981
-
4982
- template<class I, class O>
4983
- using uninitialized_move_n_result = in_out_result<I, O>;
4984
- template<input_iterator I,
4985
- no-throw-forward-iterator O, no-throw-sentinel<O> S>
4986
- requires constructible_from<iter_value_t<O>, iter_rvalue_reference_t<I>>
4987
- uninitialized_move_n_result<I, O>
4988
- uninitialized_move_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
4989
- }
4990
-
4991
- template<class NoThrowForwardIterator, class T>
4992
- void uninitialized_fill(NoThrowForwardIterator first, NoThrowForwardIterator last,
4993
- const T& x);
4994
- template<class ExecutionPolicy, class NoThrowForwardIterator, class T>
4995
- void uninitialized_fill(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
4996
- NoThrowForwardIterator first, NoThrowForwardIterator last,
4997
- const T& x);
4998
- template<class NoThrowForwardIterator, class Size, class T>
4999
- NoThrowForwardIterator
5000
- uninitialized_fill_n(NoThrowForwardIterator first, Size n, const T& x);
5001
- template<class ExecutionPolicy, class NoThrowForwardIterator, class Size, class T>
5002
- NoThrowForwardIterator
5003
- uninitialized_fill_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5004
- NoThrowForwardIterator first, Size n, const T& x);
5005
-
5006
- namespace ranges {
5007
- template<no-throw-forward-iterator I, no-throw-sentinel<I> S, class T>
5008
- requires constructible_from<iter_value_t<I>, const T&>
5009
- I uninitialized_fill(I first, S last, const T& x);
5010
- template<no-throw-forward-range R, class T>
5011
- requires constructible_from<range_value_t<R>, const T&>
5012
- borrowed_iterator_t<R> uninitialized_fill(R&& r, const T& x);
5013
-
5014
- template<no-throw-forward-iterator I, class T>
5015
- requires constructible_from<iter_value_t<I>, const T&>
5016
- I uninitialized_fill_n(I first, iter_difference_t<I> n, const T& x);
5017
- }
5018
-
5019
- // [specialized.construct], construct_at
5020
- template<class T, class... Args>
5021
- constexpr T* construct_at(T* location, Args&&... args);
5022
-
5023
- namespace ranges {
5024
- template<class T, class... Args>
5025
- constexpr T* construct_at(T* location, Args&&... args);
5026
- }
5027
-
5028
- // [specialized.destroy], destroy
5029
- template<class T>
5030
- constexpr void destroy_at(T* location);
5031
- template<class NoThrowForwardIterator>
5032
- constexpr void destroy(NoThrowForwardIterator first, NoThrowForwardIterator last);
5033
- template<class ExecutionPolicy, class NoThrowForwardIterator>
5034
- void destroy(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5035
- NoThrowForwardIterator first, NoThrowForwardIterator last);
5036
- template<class NoThrowForwardIterator, class Size>
5037
- constexpr NoThrowForwardIterator destroy_n(NoThrowForwardIterator first, Size n);
5038
- template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>
5039
- NoThrowForwardIterator destroy_n(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5040
- NoThrowForwardIterator first, Size n);
5041
-
5042
- namespace ranges {
5043
- template<destructible T>
5044
- constexpr void destroy_at(T* location) noexcept;
5045
-
5046
- template<no-throw-input-iterator I, no-throw-sentinel<I> S>
5047
- requires destructible<iter_value_t<I>>
5048
- constexpr I destroy(I first, S last) noexcept;
5049
- template<no-throw-input-range R>
5050
- requires destructible<range_value_t<R>>
5051
- constexpr borrowed_iterator_t<R> destroy(R&& r) noexcept;
5052
-
5053
- template<no-throw-input-iterator I>
5054
- requires destructible<iter_value_t<I>>
5055
- constexpr I destroy_n(I first, iter_difference_t<I> n) noexcept;
5056
- }
5057
-
5058
- // [unique.ptr], class template unique_ptr
5059
- template<class T> struct default_delete;
5060
- template<class T> struct default_delete<T[]>;
5061
- template<class T, class D = default_delete<T>> class unique_ptr;
5062
- template<class T, class D> class unique_ptr<T[], D>;
5063
-
5064
- template<class T, class... Args>
5065
- unique_ptr<T> make_unique(Args&&... args); // T is not array
5066
- template<class T>
5067
- unique_ptr<T> make_unique(size_t n); // T is U[]
5068
- template<class T, class... Args>
5069
- unspecified make_unique(Args&&...) = delete; // T is U[N]
5070
-
5071
- template<class T>
5072
- unique_ptr<T> make_unique_for_overwrite(); // T is not array
5073
- template<class T>
5074
- unique_ptr<T> make_unique_for_overwrite(size_t n); // T is U[]
5075
- template<class T, class... Args>
5076
- unspecified make_unique_for_overwrite(Args&&...) = delete; // T is U[N]
5077
-
5078
- template<class T, class D>
5079
- void swap(unique_ptr<T, D>& x, unique_ptr<T, D>& y) noexcept;
5080
-
5081
- template<class T1, class D1, class T2, class D2>
5082
- bool operator==(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
5083
- template<class T1, class D1, class T2, class D2>
5084
- bool operator<(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
5085
- template<class T1, class D1, class T2, class D2>
5086
- bool operator>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
5087
- template<class T1, class D1, class T2, class D2>
5088
- bool operator<=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
5089
- template<class T1, class D1, class T2, class D2>
5090
- bool operator>=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
5091
- template<class T1, class D1, class T2, class D2>
5092
- requires three_way_comparable_with<typename unique_ptr<T1, D1>::pointer,
5093
- typename unique_ptr<T2, D2>::pointer>
5094
- compare_three_way_result_t<typename unique_ptr<T1, D1>::pointer,
5095
- typename unique_ptr<T2, D2>::pointer>
5096
- operator<=>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
5097
-
5098
- template<class T, class D>
5099
- bool operator==(const unique_ptr<T, D>& x, nullptr_t) noexcept;
5100
- template<class T, class D>
5101
- bool operator<(const unique_ptr<T, D>& x, nullptr_t);
5102
- template<class T, class D>
5103
- bool operator<(nullptr_t, const unique_ptr<T, D>& y);
5104
- template<class T, class D>
5105
- bool operator>(const unique_ptr<T, D>& x, nullptr_t);
5106
- template<class T, class D>
5107
- bool operator>(nullptr_t, const unique_ptr<T, D>& y);
5108
- template<class T, class D>
5109
- bool operator<=(const unique_ptr<T, D>& x, nullptr_t);
5110
- template<class T, class D>
5111
- bool operator<=(nullptr_t, const unique_ptr<T, D>& y);
5112
- template<class T, class D>
5113
- bool operator>=(const unique_ptr<T, D>& x, nullptr_t);
5114
- template<class T, class D>
5115
- bool operator>=(nullptr_t, const unique_ptr<T, D>& y);
5116
- template<class T, class D>
5117
- requires three_way_comparable_with<typename unique_ptr<T, D>::pointer, nullptr_t>
5118
- compare_three_way_result_t<typename unique_ptr<T, D>::pointer, nullptr_t>
5119
- operator<=>(const unique_ptr<T, D>& x, nullptr_t);
5120
-
5121
- template<class E, class T, class Y, class D>
5122
- basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const unique_ptr<Y, D>& p);
5123
-
5124
- // [util.smartptr.weak.bad], class bad_weak_ptr
5125
- class bad_weak_ptr;
5126
-
5127
- // [util.smartptr.shared], class template shared_ptr
5128
- template<class T> class shared_ptr;
5129
-
5130
- // [util.smartptr.shared.create], shared_ptr creation
5131
- template<class T, class... Args>
5132
- shared_ptr<T> make_shared(Args&&... args); // T is not array
5133
- template<class T, class A, class... Args>
5134
- shared_ptr<T> allocate_shared(const A& a, Args&&... args); // T is not array
5135
-
5136
- template<class T>
5137
- shared_ptr<T> make_shared(size_t N); // T is U[]
5138
- template<class T, class A>
5139
- shared_ptr<T> allocate_shared(const A& a, size_t N); // T is U[]
5140
-
5141
- template<class T>
5142
- shared_ptr<T> make_shared(); // T is U[N]
5143
- template<class T, class A>
5144
- shared_ptr<T> allocate_shared(const A& a); // T is U[N]
5145
-
5146
- template<class T>
5147
- shared_ptr<T> make_shared(size_t N, const remove_extent_t<T>& u); // T is U[]
5148
- template<class T, class A>
5149
- shared_ptr<T> allocate_shared(const A& a, size_t N,
5150
- const remove_extent_t<T>& u); // T is U[]
5151
-
5152
- template<class T>
5153
- shared_ptr<T> make_shared(const remove_extent_t<T>& u); // T is U[N]
5154
- template<class T, class A>
5155
- shared_ptr<T> allocate_shared(const A& a, const remove_extent_t<T>& u); // T is U[N]
5156
-
5157
- template<class T>
5158
- shared_ptr<T> make_shared_for_overwrite(); // T is not U[]
5159
- template<class T, class A>
5160
- shared_ptr<T> allocate_shared_for_overwrite(const A& a); // T is not U[]
5161
-
5162
- template<class T>
5163
- shared_ptr<T> make_shared_for_overwrite(size_t N); // T is U[]
5164
- template<class T, class A>
5165
- shared_ptr<T> allocate_shared_for_overwrite(const A& a, size_t N); // T is U[]
5166
-
5167
- // [util.smartptr.shared.cmp], shared_ptr comparisons
5168
- template<class T, class U>
5169
- bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
5170
- template<class T, class U>
5171
- strong_ordering operator<=>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
5172
-
5173
- template<class T>
5174
- bool operator==(const shared_ptr<T>& x, nullptr_t) noexcept;
5175
- template<class T>
5176
- strong_ordering operator<=>(const shared_ptr<T>& x, nullptr_t) noexcept;
5177
-
5178
- // [util.smartptr.shared.spec], shared_ptr specialized algorithms
5179
- template<class T>
5180
- void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
5181
-
5182
- // [util.smartptr.shared.cast], shared_ptr casts
5183
- template<class T, class U>
5184
- shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
5185
- template<class T, class U>
5186
- shared_ptr<T> static_pointer_cast(shared_ptr<U>&& r) noexcept;
5187
- template<class T, class U>
5188
- shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;
5189
- template<class T, class U>
5190
- shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;
5191
- template<class T, class U>
5192
- shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;
5193
- template<class T, class U>
5194
- shared_ptr<T> const_pointer_cast(shared_ptr<U>&& r) noexcept;
5195
- template<class T, class U>
5196
- shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;
5197
- template<class T, class U>
5198
- shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U>&& r) noexcept;
5199
-
5200
- // [util.smartptr.getdeleter], shared_ptr get_deleter
5201
- template<class D, class T>
5202
- D* get_deleter(const shared_ptr<T>& p) noexcept;
5203
-
5204
- // [util.smartptr.shared.io], shared_ptr I/O
5205
- template<class E, class T, class Y>
5206
- basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);
5207
-
5208
- // [util.smartptr.weak], class template weak_ptr
5209
- template<class T> class weak_ptr;
5210
-
5211
- // [util.smartptr.weak.spec], weak_ptr specialized algorithms
5212
- template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
5213
-
5214
- // [util.smartptr.ownerless], class template owner_less
5215
- template<class T = void> struct owner_less;
5216
-
5217
- // [util.smartptr.enab], class template enable_shared_from_this
5218
- template<class T> class enable_shared_from_this;
5219
-
5220
- // [util.smartptr.hash], hash support
5221
- template<class T> struct hash;
5222
- template<class T, class D> struct hash<unique_ptr<T, D>>;
5223
- template<class T> struct hash<shared_ptr<T>>;
5224
-
5225
- // [util.smartptr.atomic], atomic smart pointers
5226
- template<class T> struct atomic;
5227
- template<class T> struct atomic<shared_ptr<T>>;
5228
- template<class T> struct atomic<weak_ptr<T>>;
5229
- }
5230
- ```
5231
-
5232
- ### Pointer traits <a id="pointer.traits">[[pointer.traits]]</a>
5233
-
5234
- The class template `pointer_traits` supplies a uniform interface to
5235
- certain attributes of pointer-like types.
5236
-
5237
- ``` cpp
5238
- namespace std {
5239
- template<class Ptr> struct pointer_traits {
5240
- using pointer = Ptr;
5241
- using element_type = see below;
5242
- using difference_type = see below;
5243
-
5244
- template<class U> using rebind = see below;
5245
-
5246
- static pointer pointer_to(see below r);
5247
- };
5248
-
5249
- template<class T> struct pointer_traits<T*> {
5250
- using pointer = T*;
5251
- using element_type = T;
5252
- using difference_type = ptrdiff_t;
5253
-
5254
- template<class U> using rebind = U*;
5255
-
5256
- static constexpr pointer pointer_to(see below r) noexcept;
5257
- };
5258
- }
5259
- ```
5260
-
5261
- #### Member types <a id="pointer.traits.types">[[pointer.traits.types]]</a>
5262
-
5263
- ``` cpp
5264
- using element_type = see below;
5265
- ```
5266
-
5267
- *Type:* `Ptr::element_type` if the *qualified-id* `Ptr::element_type` is
5268
- valid and denotes a type [[temp.deduct]]; otherwise, `T` if `Ptr` is a
5269
- class template instantiation of the form `SomePointer<T, Args>`, where
5270
- `Args` is zero or more type arguments; otherwise, the specialization is
5271
- ill-formed.
5272
-
5273
- ``` cpp
5274
- using difference_type = see below;
5275
- ```
5276
-
5277
- *Type:* `Ptr::difference_type` if the *qualified-id*
5278
- `Ptr::difference_type` is valid and denotes a type [[temp.deduct]];
5279
- otherwise, `ptrdiff_t`.
5280
-
5281
- ``` cpp
5282
- template<class U> using rebind = see below;
5283
- ```
5284
-
5285
- *Alias template:* `Ptr::rebind<U>` if the *qualified-id*
5286
- `Ptr::rebind<U>` is valid and denotes a type [[temp.deduct]]; otherwise,
5287
- `SomePointer<U, Args>` if `Ptr` is a class template instantiation of the
5288
- form `SomePointer<T, Args>`, where `Args` is zero or more type
5289
- arguments; otherwise, the instantiation of `rebind` is ill-formed.
5290
-
5291
- #### Member functions <a id="pointer.traits.functions">[[pointer.traits.functions]]</a>
5292
-
5293
- ``` cpp
5294
- static pointer pointer_traits::pointer_to(see below r);
5295
- static constexpr pointer pointer_traits<T*>::pointer_to(see below r) noexcept;
5296
- ```
5297
-
5298
- *Mandates:* For the first member function, `Ptr::pointer_to(r)` is
5299
- well-formed.
5300
-
5301
- *Preconditions:* For the first member function, `Ptr::pointer_to(r)`
5302
- returns a pointer to `r` through which indirection is valid.
5303
-
5304
- *Returns:* The first member function returns `Ptr::pointer_to(r)`. The
5305
- second member function returns `addressof(r)`.
5306
-
5307
- *Remarks:* If `element_type` is cv `void`, the type of `r` is
5308
- unspecified; otherwise, it is `element_type&`.
5309
-
5310
- #### Optional members <a id="pointer.traits.optmem">[[pointer.traits.optmem]]</a>
5311
-
5312
- Specializations of `pointer_traits` may define the member declared in
5313
- this subclause to customize the behavior of the standard library.
5314
-
5315
- ``` cpp
5316
- static element_type* to_address(pointer p) noexcept;
5317
- ```
5318
-
5319
- *Returns:* A pointer of type `element_type*` that references the same
5320
- location as the argument `p`.
5321
-
5322
- [*Note 1*: This function should be the inverse of `pointer_to`. If
5323
- defined, it customizes the behavior of the non-member function
5324
- `to_address` [[pointer.conversion]]. — *end note*]
5325
-
5326
- ### Pointer conversion <a id="pointer.conversion">[[pointer.conversion]]</a>
5327
-
5328
- ``` cpp
5329
- template<class T> constexpr T* to_address(T* p) noexcept;
5330
- ```
5331
-
5332
- *Mandates:* `T` is not a function type.
5333
-
5334
- *Returns:* `p`.
5335
-
5336
- ``` cpp
5337
- template<class Ptr> constexpr auto to_address(const Ptr& p) noexcept;
5338
- ```
5339
-
5340
- *Returns:* `pointer_traits<Ptr>::to_address(p)` if that expression is
5341
- well-formed (see [[pointer.traits.optmem]]), otherwise
5342
- `to_address(p.operator->())`.
5343
-
5344
- ### Pointer safety <a id="util.dynamic.safety">[[util.dynamic.safety]]</a>
5345
-
5346
- A complete object is *declared reachable* while the number of calls to
5347
- `declare_reachable` with an argument referencing the object exceeds the
5348
- number of calls to `undeclare_reachable` with an argument referencing
5349
- the object.
5350
-
5351
- ``` cpp
5352
- void declare_reachable(void* p);
5353
- ```
5354
-
5355
- *Preconditions:* `p` is a safely-derived
5356
- pointer [[basic.stc.dynamic.safety]] or a null pointer value.
5357
-
5358
- *Effects:* If `p` is not null, the complete object referenced by `p` is
5359
- subsequently declared reachable [[basic.stc.dynamic.safety]].
5360
-
5361
- *Throws:* May throw `bad_alloc` if the system cannot allocate additional
5362
- memory that may be required to track objects declared reachable.
5363
-
5364
- ``` cpp
5365
- template<class T> T* undeclare_reachable(T* p);
5366
- ```
5367
-
5368
- *Preconditions:* If `p` is not null, the complete object referenced by
5369
- `p` has been previously declared reachable, and is live [[basic.life]]
5370
- from the time of the call until the last `undeclare_reachable(p)` call
5371
- on the object.
5372
-
5373
- *Returns:* A safely derived copy of `p` which compares equal to `p`.
5374
-
5375
- *Throws:* Nothing.
5376
-
5377
- [*Note 1*: It is expected that calls to `declare_reachable(p)` will
5378
- consume a small amount of memory in addition to that occupied by the
5379
- referenced object until the matching call to `undeclare_reachable(p)` is
5380
- encountered. Long running programs should arrange that calls are
5381
- matched. — *end note*]
5382
-
5383
- ``` cpp
5384
- void declare_no_pointers(char* p, size_t n);
5385
- ```
5386
-
5387
- *Preconditions:* No bytes in the specified range are currently
5388
- registered with `declare_no_pointers()`. If the specified range is in an
5389
- allocated object, then it is entirely within a single allocated object.
5390
- The object is live until the corresponding `undeclare_no_pointers()`
5391
- call.
5392
-
5393
- [*Note 2*: In a garbage-collecting implementation, the fact that a
5394
- region in an object is registered with `declare_no_pointers()` should
5395
- not prevent the object from being collected. — *end note*]
5396
-
5397
- *Effects:* The `n` bytes starting at `p` no longer contain traceable
5398
- pointer locations, independent of their type. Hence indirection through
5399
- a pointer located there is undefined if the object it points to was
5400
- created by global `operator new` and not previously declared reachable.
5401
-
5402
- [*Note 3*: This may be used to inform a garbage collector or leak
5403
- detector that this region of memory need not be traced. — *end note*]
5404
-
5405
- *Throws:* Nothing.
5406
-
5407
- [*Note 4*: Under some conditions implementations may need to allocate
5408
- memory. However, the request can be ignored if memory allocation
5409
- fails. — *end note*]
5410
-
5411
- ``` cpp
5412
- void undeclare_no_pointers(char* p, size_t n);
5413
- ```
5414
-
5415
- *Preconditions:* The same range has previously been passed to
5416
- `declare_no_pointers()`.
5417
-
5418
- *Effects:* Unregisters a range registered with `declare_no_pointers()`
5419
- for destruction. It shall be called before the lifetime of the object
5420
- ends.
5421
-
5422
- *Throws:* Nothing.
5423
-
5424
- ``` cpp
5425
- pointer_safety get_pointer_safety() noexcept;
5426
- ```
5427
-
5428
- *Returns:* `pointer_safety::strict` if the implementation has strict
5429
- pointer safety [[basic.stc.dynamic.safety]]. It is
5430
- *implementation-defined* whether `get_pointer_safety` returns
5431
- `pointer_safety::relaxed` or `pointer_safety::preferred` if the
5432
- implementation has relaxed pointer safety.[^1]
5433
-
5434
- ### Pointer alignment <a id="ptr.align">[[ptr.align]]</a>
5435
-
5436
- ``` cpp
5437
- void* align(size_t alignment, size_t size, void*& ptr, size_t& space);
5438
- ```
5439
-
5440
- *Preconditions:*
5441
-
5442
- - `alignment` is a power of two
5443
- - `ptr` represents the address of contiguous storage of at least `space`
5444
- bytes
5445
-
5446
- *Effects:* If it is possible to fit `size` bytes of storage aligned by
5447
- `alignment` into the buffer pointed to by `ptr` with length `space`, the
5448
- function updates `ptr` to represent the first possible address of such
5449
- storage and decreases `space` by the number of bytes used for alignment.
5450
- Otherwise, the function does nothing.
5451
-
5452
- *Returns:* A null pointer if the requested aligned buffer would not fit
5453
- into the available space, otherwise the adjusted value of `ptr`.
5454
-
5455
- [*Note 1*: The function updates its `ptr` and `space` arguments so that
5456
- it can be called repeatedly with possibly different `alignment` and
5457
- `size` arguments for the same buffer. — *end note*]
5458
-
5459
- ``` cpp
5460
- template<size_t N, class T>
5461
- [[nodiscard]] constexpr T* assume_aligned(T* ptr);
5462
- ```
5463
-
5464
- *Mandates:* `N` is a power of two.
5465
-
5466
- *Preconditions:* `ptr` points to an object `X` of a type
5467
- similar [[conv.qual]] to `T`, where `X` has alignment `N`
5468
- [[basic.align]].
5469
-
5470
- *Returns:* `ptr`.
5471
-
5472
- *Throws:* Nothing.
5473
-
5474
- [*Note 2*: The alignment assumption on an object `X` expressed by a
5475
- call to `assume_aligned` may result in generation of more efficient
5476
- code. It is up to the program to ensure that the assumption actually
5477
- holds. The call does not cause the compiler to verify or enforce this.
5478
- An implementation might only make the assumption for those operations on
5479
- `X` that access `X` through the pointer returned by
5480
- `assume_aligned`. — *end note*]
5481
-
5482
- ### Allocator argument tag <a id="allocator.tag">[[allocator.tag]]</a>
5483
-
5484
- ``` cpp
5485
- namespace std {
5486
- struct allocator_arg_t { explicit allocator_arg_t() = default; };
5487
- inline constexpr allocator_arg_t allocator_arg{};
5488
- }
5489
- ```
5490
-
5491
- The `allocator_arg_t` struct is an empty class type used as a unique
5492
- type to disambiguate constructor and function overloading. Specifically,
5493
- several types (see `tuple`  [[tuple]]) have constructors with
5494
- `allocator_arg_t` as the first argument, immediately followed by an
5495
- argument of a type that meets the *Cpp17Allocator* requirements (
5496
- [[cpp17.allocator]]).
5497
-
5498
- ### `uses_allocator` <a id="allocator.uses">[[allocator.uses]]</a>
5499
-
5500
- #### `uses_allocator` trait <a id="allocator.uses.trait">[[allocator.uses.trait]]</a>
5501
-
5502
- ``` cpp
5503
- template<class T, class Alloc> struct uses_allocator;
5504
- ```
5505
-
5506
- *Remarks:* Automatically detects whether `T` has a nested
5507
- `allocator_type` that is convertible from `Alloc`. Meets the
5508
- *Cpp17BinaryTypeTrait* requirements [[meta.rqmts]]. The implementation
5509
- shall provide a definition that is derived from `true_type` if the
5510
- *qualified-id* `T::allocator_type` is valid and denotes a
5511
- type [[temp.deduct]] and
5512
- `is_convertible_v<Alloc, T::allocator_type> != false`, otherwise it
5513
- shall be derived from `false_type`. A program may specialize this
5514
- template to derive from `true_type` for a program-defined type `T` that
5515
- does not have a nested `allocator_type` but nonetheless can be
5516
- constructed with an allocator where either:
5517
-
5518
- - the first argument of a constructor has type `allocator_arg_t` and the
5519
- second argument has type `Alloc` or
5520
- - the last argument of a constructor has type `Alloc`.
5521
-
5522
- #### Uses-allocator construction <a id="allocator.uses.construction">[[allocator.uses.construction]]</a>
5523
-
5524
- *Uses-allocator construction* with allocator `alloc` and constructor
5525
- arguments `args...` refers to the construction of an object of type `T`
5526
- such that `alloc` is passed to the constructor of `T` if `T` uses an
5527
- allocator type compatible with `alloc`. When applied to the construction
5528
- of an object of type `T`, it is equivalent to initializing it with the
5529
- value of the expression `make_obj_using_allocator<T>(alloc, args...)`,
5530
- described below.
5531
-
5532
- The following utility functions support three conventions for passing
5533
- `alloc` to a constructor:
5534
-
5535
- - If `T` does not use an allocator compatible with `alloc`, then `alloc`
5536
- is ignored.
5537
- - Otherwise, if `T` has a constructor invocable as
5538
- `T(allocator_arg, alloc, args...)` (leading-allocator convention),
5539
- then uses-allocator construction chooses this constructor form.
5540
- - Otherwise, if `T` has a constructor invocable as `T(args..., alloc)`
5541
- (trailing-allocator convention), then uses-allocator construction
5542
- chooses this constructor form.
5543
-
5544
- The `uses_allocator_construction_args` function template takes an
5545
- allocator and argument list and produces (as a tuple) a new argument
5546
- list matching one of the above conventions. Additionally, overloads are
5547
- provided that treat specializations of `pair` such that uses-allocator
5548
- construction is applied individually to the `first` and `second` data
5549
- members. The `make_obj_using_allocator` and
5550
- `uninitialized_construct_using_allocator` function templates apply the
5551
- modified constructor arguments to construct an object of type `T` as a
5552
- return value or in-place, respectively.
5553
-
5554
- [*Note 1*: For `uses_allocator_construction_args` and
5555
- `make_obj_using_allocator`, type `T` is not deduced and must therefore
5556
- be specified explicitly by the caller. — *end note*]
5557
-
5558
- ``` cpp
5559
- template<class T, class Alloc, class... Args>
5560
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
5561
- Args&&... args) noexcept -> see below;
5562
- ```
5563
-
5564
- *Constraints:* `T` is not a specialization of `pair`.
5565
-
5566
- *Returns:* A `tuple` value determined as follows:
5567
-
5568
- - If `uses_allocator_v<T, Alloc>` is `false` and
5569
- `is_constructible_v<T, Args...>` is `true`, return
5570
- `forward_as_tuple(std::forward<Args>(args)...)`.
5571
- - Otherwise, if `uses_allocator_v<T, Alloc>` is `true` and
5572
- `is_constructible_v<T, allocator_arg_t, const Alloc&, Args...>` is
5573
- `true`, return
5574
- ``` cpp
5575
- tuple<allocator_arg_t, const Alloc&, Args&&...>(
5576
- allocator_arg, alloc, std::forward<Args>(args)...)
5577
- ```
5578
- - Otherwise, if `uses_allocator_v<T, Alloc>` is `true` and
5579
- `is_constructible_v<T, Args..., const Alloc&>` is `true`, return
5580
- `forward_as_tuple(std::forward<Args>(args)..., alloc)`.
5581
- - Otherwise, the program is ill-formed.
5582
-
5583
- [*Note 1*: This definition prevents a silent failure to pass the
5584
- allocator to a constructor of a type for which
5585
- `uses_allocator_v<T, Alloc>` is `true`. — *end note*]
5586
-
5587
- ``` cpp
5588
- template<class T, class Alloc, class Tuple1, class Tuple2>
5589
- constexpr auto uses_allocator_construction_args(const Alloc& alloc, piecewise_construct_t,
5590
- Tuple1&& x, Tuple2&& y)
5591
- noexcept -> see below;
5592
- ```
5593
-
5594
- *Constraints:* `T` is a specialization of `pair`.
5595
-
5596
- *Effects:* For `T` specified as `pair<T1, T2>`, equivalent to:
5597
-
5598
- ``` cpp
5599
- return make_tuple(
5600
- piecewise_construct,
5601
- apply([&alloc](auto&&... args1) {
5602
- return uses_allocator_construction_args<T1>(
5603
- alloc, std::forward<decltype(args1)>(args1)...);
5604
- }, std::forward<Tuple1>(x)),
5605
- apply([&alloc](auto&&... args2) {
5606
- return uses_allocator_construction_args<T2>(
5607
- alloc, std::forward<decltype(args2)>(args2)...);
5608
- }, std::forward<Tuple2>(y)));
5609
- ```
5610
-
5611
- ``` cpp
5612
- template<class T, class Alloc>
5613
- constexpr auto uses_allocator_construction_args(const Alloc& alloc) noexcept -> see below;
5614
- ```
5615
-
5616
- *Constraints:* `T` is a specialization of `pair`.
5617
-
5618
- *Effects:* Equivalent to:
5619
-
5620
- ``` cpp
5621
- return uses_allocator_construction_args<T>(alloc, piecewise_construct,
5622
- tuple<>{}, tuple<>{});
5623
- ```
5624
-
5625
- ``` cpp
5626
- template<class T, class Alloc, class U, class V>
5627
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
5628
- U&& u, V&& v) noexcept -> see below;
5629
- ```
5630
-
5631
- *Constraints:* `T` is a specialization of `pair`.
5632
-
5633
- *Effects:* Equivalent to:
5634
-
5635
- ``` cpp
5636
- return uses_allocator_construction_args<T>(alloc, piecewise_construct,
5637
- forward_as_tuple(std::forward<U>(u)),
5638
- forward_as_tuple(std::forward<V>(v)));
5639
- ```
5640
-
5641
- ``` cpp
5642
- template<class T, class Alloc, class U, class V>
5643
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
5644
- const pair<U,V>& pr) noexcept -> see below;
5645
- ```
5646
-
5647
- *Constraints:* `T` is a specialization of `pair`.
5648
-
5649
- *Effects:* Equivalent to:
5650
-
5651
- ``` cpp
5652
- return uses_allocator_construction_args<T>(alloc, piecewise_construct,
5653
- forward_as_tuple(pr.first),
5654
- forward_as_tuple(pr.second));
5655
- ```
5656
-
5657
- ``` cpp
5658
- template<class T, class Alloc, class U, class V>
5659
- constexpr auto uses_allocator_construction_args(const Alloc& alloc,
5660
- pair<U,V>&& pr) noexcept -> see below;
5661
- ```
5662
-
5663
- *Constraints:* `T` is a specialization of `pair`.
5664
-
5665
- *Effects:* Equivalent to:
5666
-
5667
- ``` cpp
5668
- return uses_allocator_construction_args<T>(alloc, piecewise_construct,
5669
- forward_as_tuple(std::move(pr).first),
5670
- forward_as_tuple(std::move(pr).second));
5671
- ```
5672
-
5673
- ``` cpp
5674
- template<class T, class Alloc, class... Args>
5675
- constexpr T make_obj_using_allocator(const Alloc& alloc, Args&&... args);
5676
- ```
5677
-
5678
- *Effects:* Equivalent to:
5679
-
5680
- ``` cpp
5681
- return make_from_tuple<T>(uses_allocator_construction_args<T>(
5682
- alloc, std::forward<Args>(args)...));
5683
- ```
5684
-
5685
- ``` cpp
5686
- template<class T, class Alloc, class... Args>
5687
- constexpr T* uninitialized_construct_using_allocator(T* p, const Alloc& alloc, Args&&... args);
5688
- ```
5689
-
5690
- *Effects:* Equivalent to:
5691
-
5692
- ``` cpp
5693
- return apply([&]<class... U>(U&&... xs) {
5694
- return construct_at(p, std::forward<U>(xs)...);
5695
- }, uses_allocator_construction_args<T>(alloc, std::forward<Args>(args)...));
5696
- ```
5697
-
5698
- ### Allocator traits <a id="allocator.traits">[[allocator.traits]]</a>
5699
-
5700
- The class template `allocator_traits` supplies a uniform interface to
5701
- all allocator types. An allocator cannot be a non-class type, however,
5702
- even if `allocator_traits` supplies the entire required interface.
5703
-
5704
- [*Note 1*: Thus, it is always possible to create a derived class from
5705
- an allocator. — *end note*]
5706
-
5707
- ``` cpp
5708
- namespace std {
5709
- template<class Alloc> struct allocator_traits {
5710
- using allocator_type = Alloc;
5711
-
5712
- using value_type = typename Alloc::value_type;
5713
-
5714
- using pointer = see below;
5715
- using const_pointer = see below;
5716
- using void_pointer = see below;
5717
- using const_void_pointer = see below;
5718
-
5719
- using difference_type = see below;
5720
- using size_type = see below;
5721
-
5722
- using propagate_on_container_copy_assignment = see below;
5723
- using propagate_on_container_move_assignment = see below;
5724
- using propagate_on_container_swap = see below;
5725
- using is_always_equal = see below;
5726
-
5727
- template<class T> using rebind_alloc = see below;
5728
- template<class T> using rebind_traits = allocator_traits<rebind_alloc<T>>;
5729
-
5730
- [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n);
5731
- [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n,
5732
- const_void_pointer hint);
5733
-
5734
- static constexpr void deallocate(Alloc& a, pointer p, size_type n);
5735
-
5736
- template<class T, class... Args>
5737
- static constexpr void construct(Alloc& a, T* p, Args&&... args);
5738
-
5739
- template<class T>
5740
- static constexpr void destroy(Alloc& a, T* p);
5741
-
5742
- static constexpr size_type max_size(const Alloc& a) noexcept;
5743
-
5744
- static constexpr Alloc select_on_container_copy_construction(const Alloc& rhs);
5745
- };
5746
- }
5747
- ```
5748
-
5749
- #### Member types <a id="allocator.traits.types">[[allocator.traits.types]]</a>
5750
-
5751
- ``` cpp
5752
- using pointer = see below;
5753
- ```
5754
-
5755
- *Type:* `Alloc::pointer` if the *qualified-id* `Alloc::pointer` is valid
5756
- and denotes a type [[temp.deduct]]; otherwise, `value_type*`.
5757
-
5758
- ``` cpp
5759
- using const_pointer = see below;
5760
- ```
5761
-
5762
- *Type:* `Alloc::const_pointer` if the *qualified-id*
5763
- `Alloc::const_pointer` is valid and denotes a type [[temp.deduct]];
5764
- otherwise, `pointer_traits<pointer>::rebind<const value_type>`.
5765
-
5766
- ``` cpp
5767
- using void_pointer = see below;
5768
- ```
5769
-
5770
- *Type:* `Alloc::void_pointer` if the *qualified-id*
5771
- `Alloc::void_pointer` is valid and denotes a type [[temp.deduct]];
5772
- otherwise, `pointer_traits<pointer>::rebind<void>`.
5773
-
5774
- ``` cpp
5775
- using const_void_pointer = see below;
5776
- ```
5777
-
5778
- *Type:* `Alloc::const_void_pointer` if the *qualified-id*
5779
- `Alloc::const_void_pointer` is valid and denotes a type [[temp.deduct]];
5780
- otherwise, `pointer_traits<pointer>::rebind<const void>`.
5781
-
5782
- ``` cpp
5783
- using difference_type = see below;
5784
- ```
5785
-
5786
- *Type:* `Alloc::difference_type` if the *qualified-id*
5787
- `Alloc::difference_type` is valid and denotes a type [[temp.deduct]];
5788
- otherwise, `pointer_traits<pointer>::difference_type`.
5789
-
5790
- ``` cpp
5791
- using size_type = see below;
5792
- ```
5793
-
5794
- *Type:* `Alloc::size_type` if the *qualified-id* `Alloc::size_type` is
5795
- valid and denotes a type [[temp.deduct]]; otherwise,
5796
- `make_unsigned_t<difference_type>`.
5797
-
5798
- ``` cpp
5799
- using propagate_on_container_copy_assignment = see below;
5800
- ```
5801
-
5802
- *Type:* `Alloc::propagate_on_container_copy_assignment` if the
5803
- *qualified-id* `Alloc::propagate_on_container_copy_assignment` is valid
5804
- and denotes a type [[temp.deduct]]; otherwise `false_type`.
5805
-
5806
- ``` cpp
5807
- using propagate_on_container_move_assignment = see below;
5808
- ```
5809
-
5810
- *Type:* `Alloc::propagate_on_container_move_assignment` if the
5811
- *qualified-id* `Alloc::propagate_on_container_move_assignment` is valid
5812
- and denotes a type [[temp.deduct]]; otherwise `false_type`.
5813
-
5814
- ``` cpp
5815
- using propagate_on_container_swap = see below;
5816
- ```
5817
-
5818
- *Type:* `Alloc::propagate_on_container_swap` if the *qualified-id*
5819
- `Alloc::propagate_on_container_swap` is valid and denotes a
5820
- type [[temp.deduct]]; otherwise `false_type`.
5821
-
5822
- ``` cpp
5823
- using is_always_equal = see below;
5824
- ```
5825
-
5826
- *Type:* `Alloc::is_always_equal` if the *qualified-id*
5827
- `Alloc::is_always_equal` is valid and denotes a type [[temp.deduct]];
5828
- otherwise `is_empty<Alloc>::type`.
5829
-
5830
- ``` cpp
5831
- template<class T> using rebind_alloc = see below;
5832
- ```
5833
-
5834
- *Alias template:* `Alloc::rebind<T>::other` if the *qualified-id*
5835
- `Alloc::rebind<T>::other` is valid and denotes a type [[temp.deduct]];
5836
- otherwise, `Alloc<T, Args>` if `Alloc` is a class template instantiation
5837
- of the form `Alloc<U, Args>`, where `Args` is zero or more type
5838
- arguments; otherwise, the instantiation of `rebind_alloc` is ill-formed.
5839
-
5840
- #### Static member functions <a id="allocator.traits.members">[[allocator.traits.members]]</a>
5841
-
5842
- ``` cpp
5843
- [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n);
5844
- ```
5845
-
5846
- *Returns:* `a.allocate(n)`.
5847
-
5848
- ``` cpp
5849
- [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n, const_void_pointer hint);
5850
- ```
5851
-
5852
- *Returns:* `a.allocate(n, hint)` if that expression is well-formed;
5853
- otherwise, `a.allocate(n)`.
5854
-
5855
- ``` cpp
5856
- static constexpr void deallocate(Alloc& a, pointer p, size_type n);
5857
- ```
5858
-
5859
- *Effects:* Calls `a.deallocate(p, n)`.
5860
-
5861
- *Throws:* Nothing.
5862
-
5863
- ``` cpp
5864
- template<class T, class... Args>
5865
- static constexpr void construct(Alloc& a, T* p, Args&&... args);
5866
- ```
5867
-
5868
- *Effects:* Calls `a.construct(p, std::forward<Args>(args)...)` if that
5869
- call is well-formed; otherwise, invokes
5870
- `construct_at(p, std::forward<Args>(args)...)`.
5871
-
5872
- ``` cpp
5873
- template<class T>
5874
- static constexpr void destroy(Alloc& a, T* p);
5875
- ```
5876
-
5877
- *Effects:* Calls `a.destroy(p)` if that call is well-formed; otherwise,
5878
- invokes `destroy_at(p)`.
5879
-
5880
- ``` cpp
5881
- static constexpr size_type max_size(const Alloc& a) noexcept;
5882
- ```
5883
-
5884
- *Returns:* `a.max_size()` if that expression is well-formed; otherwise,
5885
- `numeric_limits<size_type>::max()/sizeof(value_type)`.
5886
-
5887
- ``` cpp
5888
- static constexpr Alloc select_on_container_copy_construction(const Alloc& rhs);
5889
- ```
5890
-
5891
- *Returns:* `rhs.select_on_container_copy_construction()` if that
5892
- expression is well-formed; otherwise, `rhs`.
5893
-
5894
- ### The default allocator <a id="default.allocator">[[default.allocator]]</a>
5895
-
5896
- All specializations of the default allocator meet the allocator
5897
- completeness requirements [[allocator.requirements.completeness]].
5898
-
5899
- ``` cpp
5900
- namespace std {
5901
- template<class T> class allocator {
5902
- public:
5903
- using value_type = T;
5904
- using size_type = size_t;
5905
- using difference_type = ptrdiff_t;
5906
- using propagate_on_container_move_assignment = true_type;
5907
- using is_always_equal = true_type;
5908
-
5909
- constexpr allocator() noexcept;
5910
- constexpr allocator(const allocator&) noexcept;
5911
- template<class U> constexpr allocator(const allocator<U>&) noexcept;
5912
- constexpr ~allocator();
5913
- constexpr allocator& operator=(const allocator&) = default;
5914
-
5915
- [[nodiscard]] constexpr T* allocate(size_t n);
5916
- constexpr void deallocate(T* p, size_t n);
5917
- };
5918
- }
5919
- ```
5920
-
5921
- #### Members <a id="allocator.members">[[allocator.members]]</a>
5922
-
5923
- Except for the destructor, member functions of the default allocator
5924
- shall not introduce data races [[intro.multithread]] as a result of
5925
- concurrent calls to those member functions from different threads. Calls
5926
- to these functions that allocate or deallocate a particular unit of
5927
- storage shall occur in a single total order, and each such deallocation
5928
- call shall happen before the next allocation (if any) in this order.
5929
-
5930
- ``` cpp
5931
- [[nodiscard]] constexpr T* allocate(size_t n);
5932
- ```
5933
-
5934
- *Mandates:* `T` is not an incomplete type [[basic.types]].
5935
-
5936
- *Returns:* A pointer to the initial element of an array of `n` `T`.
5937
-
5938
- *Remarks:* The storage for the array is obtained by calling
5939
- `::operator new` [[new.delete]], but it is unspecified when or how often
5940
- this function is called. This function starts the lifetime of the array
5941
- object, but not that of any of the array elements.
5942
-
5943
- *Throws:* `bad_array_new_length` if
5944
- `numeric_limits<size_t>::max() / sizeof(T) < n`, or `bad_alloc` if the
5945
- storage cannot be obtained.
5946
-
5947
- ``` cpp
5948
- constexpr void deallocate(T* p, size_t n);
5949
- ```
5950
-
5951
- *Preconditions:* `p` is a pointer value obtained from `allocate()`. `n`
5952
- equals the value passed as the first argument to the invocation of
5953
- allocate which returned `p`.
5954
-
5955
- *Effects:* Deallocates the storage referenced by `p` .
5956
-
5957
- *Remarks:* Uses `::operator delete` [[new.delete]], but it is
5958
- unspecified when this function is called.
5959
-
5960
- #### Operators <a id="allocator.globals">[[allocator.globals]]</a>
5961
-
5962
- ``` cpp
5963
- template<class T, class U>
5964
- constexpr bool operator==(const allocator<T>&, const allocator<U>&) noexcept;
5965
- ```
5966
-
5967
- *Returns:* `true`.
5968
-
5969
- ### `addressof` <a id="specialized.addressof">[[specialized.addressof]]</a>
5970
-
5971
- ``` cpp
5972
- template<class T> constexpr T* addressof(T& r) noexcept;
5973
- ```
5974
-
5975
- *Returns:* The actual address of the object or function referenced by
5976
- `r`, even in the presence of an overloaded `operator&`.
5977
-
5978
- *Remarks:* An expression `addressof(E)` is a constant
5979
- subexpression [[defns.const.subexpr]] if `E` is an lvalue constant
5980
- subexpression.
5981
-
5982
- ### C library memory allocation <a id="c.malloc">[[c.malloc]]</a>
5983
-
5984
- [*Note 1*: The header `<cstdlib>` declares the functions described in
5985
- this subclause. — *end note*]
5986
-
5987
- ``` cpp
5988
- void* aligned_alloc(size_t alignment, size_t size);
5989
- void* calloc(size_t nmemb, size_t size);
5990
- void* malloc(size_t size);
5991
- void* realloc(void* ptr, size_t size);
5992
- ```
5993
-
5994
- *Effects:* These functions have the semantics specified in the C
5995
- standard library.
5996
-
5997
- *Remarks:* These functions do not attempt to allocate storage by calling
5998
- `::operator new()` [[new.delete]].
5999
-
6000
- Storage allocated directly with these functions is implicitly declared
6001
- reachable (see  [[basic.stc.dynamic.safety]]) on allocation, ceases to
6002
- be declared reachable on deallocation, and need not cease to be declared
6003
- reachable as the result of an `undeclare_reachable()` call.
6004
-
6005
- [*Note 1*: This allows existing C libraries to remain unaffected by
6006
- restrictions on pointers that are not safely derived, at the expense of
6007
- providing far fewer garbage collection and leak detection options for
6008
- `malloc()`-allocated objects. It also allows `malloc()` to be
6009
- implemented with a separate allocation arena, bypassing the normal
6010
- `declare_reachable()` implementation. The above functions should never
6011
- intentionally be used as a replacement for `declare_reachable()`, and
6012
- newly written code is strongly encouraged to treat memory allocated with
6013
- these functions as though it were allocated with
6014
- `operator new`. — *end note*]
6015
-
6016
- These functions implicitly create objects [[intro.object]] in the
6017
- returned region of storage and return a pointer to a suitable created
6018
- object. In the case of `calloc` and `realloc`, the objects are created
6019
- before the storage is zeroed or copied, respectively.
6020
-
6021
- ``` cpp
6022
- void free(void* ptr);
6023
- ```
6024
-
6025
- *Effects:* This function has the semantics specified in the C standard
6026
- library.
6027
-
6028
- *Remarks:* This function does not attempt to deallocate storage by
6029
- calling `::operator delete()`.
6030
-
6031
- See also: ISO C 7.22.3
6032
-
6033
- ## Smart pointers <a id="smartptr">[[smartptr]]</a>
6034
-
6035
- ### Class template `unique_ptr` <a id="unique.ptr">[[unique.ptr]]</a>
6036
-
6037
- A *unique pointer* is an object that owns another object and manages
6038
- that other object through a pointer. More precisely, a unique pointer is
6039
- an object *u* that stores a pointer to a second object *p* and will
6040
- dispose of *p* when *u* is itself destroyed (e.g., when leaving block
6041
- scope [[stmt.dcl]]). In this context, *u* is said to *own* `p`.
6042
-
6043
- The mechanism by which *u* disposes of *p* is known as *p*’s associated
6044
- *deleter*, a function object whose correct invocation results in *p*’s
6045
- appropriate disposition (typically its deletion).
6046
-
6047
- Let the notation *u.p* denote the pointer stored by *u*, and let *u.d*
6048
- denote the associated deleter. Upon request, *u* can *reset* (replace)
6049
- *u.p* and *u.d* with another pointer and deleter, but properly disposes
6050
- of its owned object via the associated deleter before such replacement
6051
- is considered completed.
6052
-
6053
- Each object of a type `U` instantiated from the `unique_ptr` template
6054
- specified in this subclause has the strict ownership semantics,
6055
- specified above, of a unique pointer. In partial satisfaction of these
6056
- semantics, each such `U` is *Cpp17MoveConstructible* and
6057
- *Cpp17MoveAssignable*, but is not *Cpp17CopyConstructible* nor
6058
- *Cpp17CopyAssignable*. The template parameter `T` of `unique_ptr` may be
6059
- an incomplete type.
6060
-
6061
- [*Note 1*: The uses of `unique_ptr` include providing exception safety
6062
- for dynamically allocated memory, passing ownership of dynamically
6063
- allocated memory to a function, and returning dynamically allocated
6064
- memory from a function. — *end note*]
6065
-
6066
- #### Default deleters <a id="unique.ptr.dltr">[[unique.ptr.dltr]]</a>
6067
-
6068
- ##### In general <a id="unique.ptr.dltr.general">[[unique.ptr.dltr.general]]</a>
6069
-
6070
- The class template `default_delete` serves as the default deleter
6071
- (destruction policy) for the class template `unique_ptr`.
6072
-
6073
- The template parameter `T` of `default_delete` may be an incomplete
6074
- type.
6075
-
6076
- ##### `default_delete` <a id="unique.ptr.dltr.dflt">[[unique.ptr.dltr.dflt]]</a>
6077
-
6078
- ``` cpp
6079
- namespace std {
6080
- template<class T> struct default_delete {
6081
- constexpr default_delete() noexcept = default;
6082
- template<class U> default_delete(const default_delete<U>&) noexcept;
6083
- void operator()(T*) const;
6084
- };
6085
- }
6086
- ```
6087
-
6088
- ``` cpp
6089
- template<class U> default_delete(const default_delete<U>& other) noexcept;
6090
- ```
6091
-
6092
- *Constraints:* `U*` is implicitly convertible to `T*`.
6093
-
6094
- *Effects:* Constructs a `default_delete` object from another
6095
- `default_delete<U>` object.
6096
-
6097
- ``` cpp
6098
- void operator()(T* ptr) const;
6099
- ```
6100
-
6101
- *Mandates:* `T` is a complete type.
6102
-
6103
- *Effects:* Calls `delete` on `ptr`.
6104
-
6105
- ##### `default_delete<T[]>` <a id="unique.ptr.dltr.dflt1">[[unique.ptr.dltr.dflt1]]</a>
6106
-
6107
- ``` cpp
6108
- namespace std {
6109
- template<class T> struct default_delete<T[]> {
6110
- constexpr default_delete() noexcept = default;
6111
- template<class U> default_delete(const default_delete<U[]>&) noexcept;
6112
- template<class U> void operator()(U* ptr) const;
6113
- };
6114
- }
6115
- ```
6116
-
6117
- ``` cpp
6118
- template<class U> default_delete(const default_delete<U[]>& other) noexcept;
6119
- ```
6120
-
6121
- *Constraints:* `U(*)[]` is convertible to `T(*)[]`.
6122
-
6123
- *Effects:* Constructs a `default_delete` object from another
6124
- `default_delete<U[]>` object.
6125
-
6126
- ``` cpp
6127
- template<class U> void operator()(U* ptr) const;
6128
- ```
6129
-
6130
- *Mandates:* `U` is a complete type.
6131
-
6132
- *Constraints:* `U(*)[]` is convertible to `T(*)[]`.
6133
-
6134
- *Effects:* Calls `delete[]` on `ptr`.
6135
-
6136
- #### `unique_ptr` for single objects <a id="unique.ptr.single">[[unique.ptr.single]]</a>
6137
-
6138
- ``` cpp
6139
- namespace std {
6140
- template<class T, class D = default_delete<T>> class unique_ptr {
6141
- public:
6142
- using pointer = see below;
6143
- using element_type = T;
6144
- using deleter_type = D;
6145
-
6146
- // [unique.ptr.single.ctor], constructors
6147
- constexpr unique_ptr() noexcept;
6148
- explicit unique_ptr(pointer p) noexcept;
6149
- unique_ptr(pointer p, see below d1) noexcept;
6150
- unique_ptr(pointer p, see below d2) noexcept;
6151
- unique_ptr(unique_ptr&& u) noexcept;
6152
- constexpr unique_ptr(nullptr_t) noexcept;
6153
- template<class U, class E>
6154
- unique_ptr(unique_ptr<U, E>&& u) noexcept;
6155
-
6156
- // [unique.ptr.single.dtor], destructor
6157
- ~unique_ptr();
6158
-
6159
- // [unique.ptr.single.asgn], assignment
6160
- unique_ptr& operator=(unique_ptr&& u) noexcept;
6161
- template<class U, class E>
6162
- unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
6163
- unique_ptr& operator=(nullptr_t) noexcept;
6164
-
6165
- // [unique.ptr.single.observers], observers
6166
- add_lvalue_reference_t<T> operator*() const;
6167
- pointer operator->() const noexcept;
6168
- pointer get() const noexcept;
6169
- deleter_type& get_deleter() noexcept;
6170
- const deleter_type& get_deleter() const noexcept;
6171
- explicit operator bool() const noexcept;
6172
-
6173
- // [unique.ptr.single.modifiers], modifiers
6174
- pointer release() noexcept;
6175
- void reset(pointer p = pointer()) noexcept;
6176
- void swap(unique_ptr& u) noexcept;
6177
-
6178
- // disable copy from lvalue
6179
- unique_ptr(const unique_ptr&) = delete;
6180
- unique_ptr& operator=(const unique_ptr&) = delete;
6181
- };
6182
- }
6183
- ```
6184
-
6185
- The default type for the template parameter `D` is `default_delete`. A
6186
- client-supplied template argument `D` shall be a function object type
6187
- [[function.objects]], lvalue reference to function, or lvalue reference
6188
- to function object type for which, given a value `d` of type `D` and a
6189
- value `ptr` of type `unique_ptr<T, D>::pointer`, the expression `d(ptr)`
6190
- is valid and has the effect of disposing of the pointer as appropriate
6191
- for that deleter.
6192
-
6193
- If the deleter’s type `D` is not a reference type, `D` shall meet the
6194
- *Cpp17Destructible* requirements ([[cpp17.destructible]]).
6195
-
6196
- If the *qualified-id* `remove_reference_t<D>::pointer` is valid and
6197
- denotes a type [[temp.deduct]], then `unique_ptr<T,
6198
- D>::pointer` shall be a synonym for `remove_reference_t<D>::pointer`.
6199
- Otherwise `unique_ptr<T, D>::pointer` shall be a synonym for
6200
- `element_type*`. The type `unique_ptr<T,
6201
- D>::pointer` shall meet the *Cpp17NullablePointer* requirements (
6202
- [[cpp17.nullablepointer]]).
6203
-
6204
- [*Example 1*: Given an allocator type `X` ([[cpp17.allocator]]) and
6205
- letting `A` be a synonym for `allocator_traits<X>`, the types
6206
- `A::pointer`, `A::const_pointer`, `A::void_pointer`, and
6207
- `A::const_void_pointer` may be used as
6208
- `unique_ptr<T, D>::pointer`. — *end example*]
6209
-
6210
- ##### Constructors <a id="unique.ptr.single.ctor">[[unique.ptr.single.ctor]]</a>
6211
-
6212
- ``` cpp
6213
- constexpr unique_ptr() noexcept;
6214
- constexpr unique_ptr(nullptr_t) noexcept;
6215
- ```
6216
-
6217
- *Preconditions:* `D` meets the *Cpp17DefaultConstructible* requirements
6218
- ([[cpp17.defaultconstructible]]), and that construction does not throw
6219
- an exception.
6220
-
6221
- *Constraints:* `is_pointer_v<deleter_type>` is `false` and
6222
- `is_default_constructible_v<deleter_type>` is `true`.
6223
-
6224
- *Effects:* Constructs a `unique_ptr` object that owns nothing,
6225
- value-initializing the stored pointer and the stored deleter.
6226
-
6227
- *Ensures:* `get() == nullptr`. `get_deleter()` returns a reference to
6228
- the stored deleter.
6229
-
6230
- ``` cpp
6231
- explicit unique_ptr(pointer p) noexcept;
6232
- ```
6233
-
6234
- *Constraints:* `is_pointer_v<deleter_type>` is `false` and
6235
- `is_default_constructible_v<deleter_type>` is `true`.
6236
-
6237
- *Mandates:* This constructor is not selected by class template argument
6238
- deduction [[over.match.class.deduct]].
6239
-
6240
- *Preconditions:* `D` meets the *Cpp17DefaultConstructible* requirements
6241
- ([[cpp17.defaultconstructible]]), and that construction does not throw
6242
- an exception.
6243
-
6244
- *Effects:* Constructs a `unique_ptr` which owns `p`, initializing the
6245
- stored pointer with `p` and value-initializing the stored deleter.
6246
-
6247
- *Ensures:* `get() == p`. `get_deleter()` returns a reference to the
6248
- stored deleter.
6249
-
6250
- ``` cpp
6251
- unique_ptr(pointer p, const D& d) noexcept;
6252
- unique_ptr(pointer p, remove_reference_t<D>&& d) noexcept;
6253
- ```
6254
-
6255
- *Constraints:* `is_constructible_v<D, decltype(d)>` is `true`.
6256
-
6257
- *Mandates:* These constructors are not selected by class template
6258
- argument deduction [[over.match.class.deduct]].
6259
-
6260
- *Preconditions:* For the first constructor, if `D` is not a reference
6261
- type, `D` meets the *Cpp17CopyConstructible* requirements and such
6262
- construction does not exit via an exception. For the second constructor,
6263
- if `D` is not a reference type, `D` meets the *Cpp17MoveConstructible*
6264
- requirements and such construction does not exit via an exception.
6265
-
6266
- *Effects:* Constructs a `unique_ptr` object which owns `p`, initializing
6267
- the stored pointer with `p` and initializing the deleter from
6268
- `std::forward<decltype(d)>(d)`.
6269
-
6270
- *Ensures:* `get() == p`. `get_deleter()` returns a reference to the
6271
- stored deleter. If `D` is a reference type then `get_deleter()` returns
6272
- a reference to the lvalue `d`.
6273
-
6274
- *Remarks:* If `D` is a reference type, the second constructor is defined
6275
- as deleted.
6276
-
6277
- [*Example 1*:
6278
-
6279
- ``` cpp
6280
- D d;
6281
- unique_ptr<int, D> p1(new int, D()); // D must be Cpp17MoveConstructible
6282
- unique_ptr<int, D> p2(new int, d); // D must be Cpp17CopyConstructible
6283
- unique_ptr<int, D&> p3(new int, d); // p3 holds a reference to d
6284
- unique_ptr<int, const D&> p4(new int, D()); // error: rvalue deleter object combined
6285
- // with reference deleter type
6286
- ```
6287
-
6288
- — *end example*]
6289
-
6290
- ``` cpp
6291
- unique_ptr(unique_ptr&& u) noexcept;
6292
- ```
6293
-
6294
- *Constraints:* `is_move_constructible_v<D>` is `true`.
6295
-
6296
- *Preconditions:* If `D` is not a reference type, `D` meets the
6297
- *Cpp17MoveConstructible* requirements ([[cpp17.moveconstructible]]).
6298
- Construction of the deleter from an rvalue of type `D` does not throw an
6299
- exception.
6300
-
6301
- *Effects:* Constructs a `unique_ptr` from `u`. If `D` is a reference
6302
- type, this deleter is copy constructed from `u`’s deleter; otherwise,
6303
- this deleter is move constructed from `u`’s deleter.
6304
-
6305
- [*Note 1*: The construction of the deleter can be implemented with
6306
- `std::forward<D>`. — *end note*]
6307
-
6308
- *Ensures:* `get()` yields the value `u.get()` yielded before the
6309
- construction. `u.get() == nullptr`. `get_deleter()` returns a reference
6310
- to the stored deleter that was constructed from `u.get_deleter()`. If
6311
- `D` is a reference type then `get_deleter()` and `u.get_deleter()` both
6312
- reference the same lvalue deleter.
6313
-
6314
- ``` cpp
6315
- template<class U, class E> unique_ptr(unique_ptr<U, E>&& u) noexcept;
6316
- ```
6317
-
6318
- *Constraints:*
6319
-
6320
- - `unique_ptr<U, E>::pointer` is implicitly convertible to `pointer`,
6321
- - `U` is not an array type, and
6322
- - either `D` is a reference type and `E` is the same type as `D`, or `D`
6323
- is not a reference type and `E` is implicitly convertible to `D`.
6324
-
6325
- *Preconditions:* If `E` is not a reference type, construction of the
6326
- deleter from an rvalue of type `E` is well-formed and does not throw an
6327
- exception. Otherwise, `E` is a reference type and construction of the
6328
- deleter from an lvalue of type `E` is well-formed and does not throw an
6329
- exception.
6330
-
6331
- *Effects:* Constructs a `unique_ptr` from `u`. If `E` is a reference
6332
- type, this deleter is copy constructed from `u`’s deleter; otherwise,
6333
- this deleter is move constructed from `u`’s deleter.
6334
-
6335
- [*Note 2*: The deleter constructor can be implemented with
6336
- `std::forward<E>`. — *end note*]
6337
-
6338
- *Ensures:* `get()` yields the value `u.get()` yielded before the
6339
- construction. `u.get() == nullptr`. `get_deleter()` returns a reference
6340
- to the stored deleter that was constructed from `u.get_deleter()`.
6341
-
6342
- ##### Destructor <a id="unique.ptr.single.dtor">[[unique.ptr.single.dtor]]</a>
6343
-
6344
- ``` cpp
6345
- ~unique_ptr();
6346
- ```
6347
-
6348
- *Preconditions:* The expression `get_deleter()(get())` is well-formed,
6349
- has well-defined behavior, and does not throw exceptions.
6350
-
6351
- [*Note 3*: The use of `default_delete` requires `T` to be a complete
6352
- type. — *end note*]
6353
-
6354
- *Effects:* If `get() == nullptr` there are no effects. Otherwise
6355
- `get_deleter()(get())`.
6356
-
6357
- ##### Assignment <a id="unique.ptr.single.asgn">[[unique.ptr.single.asgn]]</a>
6358
-
6359
- ``` cpp
6360
- unique_ptr& operator=(unique_ptr&& u) noexcept;
6361
- ```
6362
-
6363
- *Constraints:* `is_move_assignable_v<D>` is `true`.
6364
-
6365
- *Preconditions:* If `D` is not a reference type, `D` meets the
6366
- *Cpp17MoveAssignable* requirements ([[cpp17.moveassignable]]) and
6367
- assignment of the deleter from an rvalue of type `D` does not throw an
6368
- exception. Otherwise, `D` is a reference type; `remove_reference_t<D>`
6369
- meets the *Cpp17CopyAssignable* requirements and assignment of the
6370
- deleter from an lvalue of type `D` does not throw an exception.
6371
-
6372
- *Effects:* Calls `reset(u.release())` followed by
6373
- `get_deleter() = std::forward<D>(u.get_deleter())`.
6374
-
6375
- *Returns:* `*this`.
6376
-
6377
- *Ensures:* `u.get() == nullptr`.
6378
-
6379
- ``` cpp
6380
- template<class U, class E> unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
6381
- ```
6382
-
6383
- *Constraints:*
6384
-
6385
- - `unique_ptr<U, E>::pointer` is implicitly convertible to `pointer`,
6386
- and
6387
- - `U` is not an array type, and
6388
- - `is_assignable_v<D&, E&&>` is `true`.
6389
-
6390
- *Preconditions:* If `E` is not a reference type, assignment of the
6391
- deleter from an rvalue of type `E` is well-formed and does not throw an
6392
- exception. Otherwise, `E` is a reference type and assignment of the
6393
- deleter from an lvalue of type `E` is well-formed and does not throw an
6394
- exception.
6395
-
6396
- *Effects:* Calls `reset(u.release())` followed by
6397
- `get_deleter() = std::forward<E>(u.get_deleter())`.
6398
-
6399
- *Returns:* `*this`.
6400
-
6401
- *Ensures:* `u.get() == nullptr`.
6402
-
6403
- ``` cpp
6404
- unique_ptr& operator=(nullptr_t) noexcept;
6405
- ```
6406
-
6407
- *Effects:* As if by `reset()`.
6408
-
6409
- *Ensures:* `get() == nullptr`.
6410
-
6411
- *Returns:* `*this`.
6412
-
6413
- ##### Observers <a id="unique.ptr.single.observers">[[unique.ptr.single.observers]]</a>
6414
-
6415
- ``` cpp
6416
- add_lvalue_reference_t<T> operator*() const;
6417
- ```
6418
-
6419
- *Preconditions:* `get() != nullptr`.
6420
-
6421
- *Returns:* `*get()`.
6422
-
6423
- ``` cpp
6424
- pointer operator->() const noexcept;
6425
- ```
6426
-
6427
- *Preconditions:* `get() != nullptr`.
6428
-
6429
- *Returns:* `get()`.
6430
-
6431
- [*Note 4*: The use of this function typically requires that `T` be a
6432
- complete type. — *end note*]
6433
-
6434
- ``` cpp
6435
- pointer get() const noexcept;
6436
- ```
6437
-
6438
- *Returns:* The stored pointer.
6439
-
6440
- ``` cpp
6441
- deleter_type& get_deleter() noexcept;
6442
- const deleter_type& get_deleter() const noexcept;
6443
- ```
6444
-
6445
- *Returns:* A reference to the stored deleter.
6446
-
6447
- ``` cpp
6448
- explicit operator bool() const noexcept;
6449
- ```
6450
-
6451
- *Returns:* `get() != nullptr`.
6452
-
6453
- ##### Modifiers <a id="unique.ptr.single.modifiers">[[unique.ptr.single.modifiers]]</a>
6454
-
6455
- ``` cpp
6456
- pointer release() noexcept;
6457
- ```
6458
-
6459
- *Ensures:* `get() == nullptr`.
6460
-
6461
- *Returns:* The value `get()` had at the start of the call to `release`.
6462
-
6463
- ``` cpp
6464
- void reset(pointer p = pointer()) noexcept;
6465
- ```
6466
-
6467
- *Preconditions:* The expression `get_deleter()(get())` is well-formed,
6468
- has well-defined behavior, and does not throw exceptions.
6469
-
6470
- *Effects:* Assigns `p` to the stored pointer, and then if and only if
6471
- the old value of the stored pointer, `old_p`, was not equal to
6472
- `nullptr`, calls `get_deleter()(old_p)`.
6473
-
6474
- [*Note 5*: The order of these operations is significant because the
6475
- call to `get_deleter()` may destroy `*this`. — *end note*]
6476
-
6477
- *Ensures:* `get() == p`.
6478
-
6479
- [*Note 6*: The postcondition does not hold if the call to
6480
- `get_deleter()` destroys `*this` since `this->get()` is no longer a
6481
- valid expression. — *end note*]
6482
-
6483
- ``` cpp
6484
- void swap(unique_ptr& u) noexcept;
6485
- ```
6486
-
6487
- *Preconditions:* `get_deleter()` is swappable [[swappable.requirements]]
6488
- and does not throw an exception under `swap`.
6489
-
6490
- *Effects:* Invokes `swap` on the stored pointers and on the stored
6491
- deleters of `*this` and `u`.
6492
-
6493
- #### `unique_ptr` for array objects with a runtime length <a id="unique.ptr.runtime">[[unique.ptr.runtime]]</a>
6494
-
6495
- ``` cpp
6496
- namespace std {
6497
- template<class T, class D> class unique_ptr<T[], D> {
6498
- public:
6499
- using pointer = see below;
6500
- using element_type = T;
6501
- using deleter_type = D;
6502
-
6503
- // [unique.ptr.runtime.ctor], constructors
6504
- constexpr unique_ptr() noexcept;
6505
- template<class U> explicit unique_ptr(U p) noexcept;
6506
- template<class U> unique_ptr(U p, see below d) noexcept;
6507
- template<class U> unique_ptr(U p, see below d) noexcept;
6508
- unique_ptr(unique_ptr&& u) noexcept;
6509
- template<class U, class E>
6510
- unique_ptr(unique_ptr<U, E>&& u) noexcept;
6511
- constexpr unique_ptr(nullptr_t) noexcept;
6512
-
6513
- // destructor
6514
- ~unique_ptr();
6515
-
6516
- // assignment
6517
- unique_ptr& operator=(unique_ptr&& u) noexcept;
6518
- template<class U, class E>
6519
- unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
6520
- unique_ptr& operator=(nullptr_t) noexcept;
6521
-
6522
- // [unique.ptr.runtime.observers], observers
6523
- T& operator[](size_t i) const;
6524
- pointer get() const noexcept;
6525
- deleter_type& get_deleter() noexcept;
6526
- const deleter_type& get_deleter() const noexcept;
6527
- explicit operator bool() const noexcept;
6528
-
6529
- // [unique.ptr.runtime.modifiers], modifiers
6530
- pointer release() noexcept;
6531
- template<class U> void reset(U p) noexcept;
6532
- void reset(nullptr_t = nullptr) noexcept;
6533
- void swap(unique_ptr& u) noexcept;
6534
-
6535
- // disable copy from lvalue
6536
- unique_ptr(const unique_ptr&) = delete;
6537
- unique_ptr& operator=(const unique_ptr&) = delete;
6538
- };
6539
- }
6540
- ```
6541
-
6542
- A specialization for array types is provided with a slightly altered
6543
- interface.
6544
-
6545
- - Conversions between different types of `unique_ptr<T[], D>` that would
6546
- be disallowed for the corresponding pointer-to-array types, and
6547
- conversions to or from the non-array forms of `unique_ptr`, produce an
6548
- ill-formed program.
6549
- - Pointers to types derived from `T` are rejected by the constructors,
6550
- and by `reset`.
6551
- - The observers `operator*` and `operator->` are not provided.
6552
- - The indexing observer `operator[]` is provided.
6553
- - The default deleter will call `delete[]`.
6554
-
6555
- Descriptions are provided below only for members that differ from the
6556
- primary template.
6557
-
6558
- The template argument `T` shall be a complete type.
6559
-
6560
- ##### Constructors <a id="unique.ptr.runtime.ctor">[[unique.ptr.runtime.ctor]]</a>
6561
-
6562
- ``` cpp
6563
- template<class U> explicit unique_ptr(U p) noexcept;
6564
- ```
6565
-
6566
- This constructor behaves the same as the constructor in the primary
6567
- template that takes a single parameter of type `pointer`.
6568
-
6569
- *Constraints:*
6570
-
6571
- - `U` is the same type as `pointer`, or
6572
- - `pointer` is the same type as `element_type*`, `U` is a pointer type
6573
- `V*`, and `V(*)[]` is convertible to `element_type(*)[]`.
6574
-
6575
- ``` cpp
6576
- template<class U> unique_ptr(U p, see below d) noexcept;
6577
- template<class U> unique_ptr(U p, see below d) noexcept;
6578
- ```
6579
-
6580
- These constructors behave the same as the constructors in the primary
6581
- template that take a parameter of type `pointer` and a second parameter.
6582
-
6583
- *Constraints:*
6584
-
6585
- - `U` is the same type as `pointer`,
6586
- - `U` is `nullptr_t`, or
6587
- - `pointer` is the same type as `element_type*`, `U` is a pointer type
6588
- `V*`, and `V(*)[]` is convertible to `element_type(*)[]`.
6589
-
6590
- ``` cpp
6591
- template<class U, class E> unique_ptr(unique_ptr<U, E>&& u) noexcept;
6592
- ```
6593
-
6594
- This constructor behaves the same as in the primary template.
6595
-
6596
- *Constraints:* Where `UP` is `unique_ptr<U, E>`:
6597
-
6598
- - `U` is an array type, and
6599
- - `pointer` is the same type as `element_type*`, and
6600
- - `UP::pointer` is the same type as `UP::element_type*`, and
6601
- - `UP::element_type(*)[]` is convertible to `element_type(*)[]`, and
6602
- - either `D` is a reference type and `E` is the same type as `D`, or `D`
6603
- is not a reference type and `E` is implicitly convertible to `D`.
6604
-
6605
- [*Note 1*: This replaces the *Constraints:* specification of the
6606
- primary template. — *end note*]
6607
-
6608
- ##### Assignment <a id="unique.ptr.runtime.asgn">[[unique.ptr.runtime.asgn]]</a>
6609
-
6610
- ``` cpp
6611
- template<class U, class E> unique_ptr& operator=(unique_ptr<U, E>&& u)noexcept;
6612
- ```
6613
-
6614
- This operator behaves the same as in the primary template.
6615
-
6616
- *Constraints:* Where `UP` is `unique_ptr<U, E>`:
6617
-
6618
- - `U` is an array type, and
6619
- - `pointer` is the same type as `element_type*`, and
6620
- - `UP::pointer` is the same type as `UP::element_type*`, and
6621
- - `UP::element_type(*)[]` is convertible to `element_type(*)[]`, and
6622
- - `is_assignable_v<D&, E&&>` is `true`.
6623
-
6624
- [*Note 2*: This replaces the *Constraints:* specification of the
6625
- primary template. — *end note*]
6626
-
6627
- ##### Observers <a id="unique.ptr.runtime.observers">[[unique.ptr.runtime.observers]]</a>
6628
-
6629
- ``` cpp
6630
- T& operator[](size_t i) const;
6631
- ```
6632
-
6633
- *Preconditions:* `i` < the number of elements in the array to which the
6634
- stored pointer points.
6635
-
6636
- *Returns:* `get()[i]`.
6637
-
6638
- ##### Modifiers <a id="unique.ptr.runtime.modifiers">[[unique.ptr.runtime.modifiers]]</a>
6639
-
6640
- ``` cpp
6641
- void reset(nullptr_t p = nullptr) noexcept;
6642
- ```
6643
-
6644
- *Effects:* Equivalent to `reset(pointer())`.
6645
-
6646
- ``` cpp
6647
- template<class U> void reset(U p) noexcept;
6648
- ```
6649
-
6650
- This function behaves the same as the `reset` member of the primary
6651
- template.
6652
-
6653
- *Constraints:*
6654
-
6655
- - `U` is the same type as `pointer`, or
6656
- - `pointer` is the same type as `element_type*`, `U` is a pointer type
6657
- `V*`, and `V(*)[]` is convertible to `element_type(*)[]`.
6658
-
6659
- #### Creation <a id="unique.ptr.create">[[unique.ptr.create]]</a>
6660
-
6661
- ``` cpp
6662
- template<class T, class... Args> unique_ptr<T> make_unique(Args&&... args);
6663
- ```
6664
-
6665
- *Constraints:* `T` is not an array type.
6666
-
6667
- *Returns:* `unique_ptr<T>(new T(std::forward<Args>(args)...))`.
6668
-
6669
- ``` cpp
6670
- template<class T> unique_ptr<T> make_unique(size_t n);
6671
- ```
6672
-
6673
- *Constraints:* `T` is an array of unknown bound.
6674
-
6675
- *Returns:* `unique_ptr<T>(new remove_extent_t<T>[n]())`.
6676
-
6677
- ``` cpp
6678
- template<class T, class... Args> unspecified make_unique(Args&&...) = delete;
6679
- ```
6680
-
6681
- *Constraints:* `T` is an array of known bound.
6682
-
6683
- ``` cpp
6684
- template<class T> unique_ptr<T> make_unique_for_overwrite();
6685
- ```
6686
-
6687
- *Constraints:* `T` is not an array type.
6688
-
6689
- *Returns:* `unique_ptr<T>(new T)`.
6690
-
6691
- ``` cpp
6692
- template<class T> unique_ptr<T> make_unique_for_overwrite(size_t n);
6693
- ```
6694
-
6695
- *Constraints:* `T` is an array of unknown bound.
6696
-
6697
- *Returns:* `unique_ptr<T>(new remove_extent_t<T>[n])`.
6698
-
6699
- ``` cpp
6700
- template<class T, class... Args> unspecified make_unique_for_overwrite(Args&&...) = delete;
6701
- ```
6702
-
6703
- *Constraints:* `T` is an array of known bound.
6704
-
6705
- #### Specialized algorithms <a id="unique.ptr.special">[[unique.ptr.special]]</a>
6706
-
6707
- ``` cpp
6708
- template<class T, class D> void swap(unique_ptr<T, D>& x, unique_ptr<T, D>& y) noexcept;
6709
- ```
6710
-
6711
- *Constraints:* `is_swappable_v<D>` is `true`.
6712
-
6713
- *Effects:* Calls `x.swap(y)`.
6714
-
6715
- ``` cpp
6716
- template<class T1, class D1, class T2, class D2>
6717
- bool operator==(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
6718
- ```
6719
-
6720
- *Returns:* `x.get() == y.get()`.
6721
-
6722
- ``` cpp
6723
- template<class T1, class D1, class T2, class D2>
6724
- bool operator<(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
6725
- ```
6726
-
6727
- Let `CT` denote
6728
-
6729
- ``` cpp
6730
- common_type_t<typename unique_ptr<T1, D1>::pointer,
6731
- typename unique_ptr<T2, D2>::pointer>
6732
- ```
6733
-
6734
- *Mandates:*
6735
-
6736
- - `unique_ptr<T1, D1>::pointer` is implicitly convertible to `CT` and
6737
- - `unique_ptr<T2, D2>::pointer` is implicitly convertible to `CT`.
6738
-
6739
- *Preconditions:* The specialization `less<CT>` is a function object
6740
- type [[function.objects]] that induces a strict weak
6741
- ordering [[alg.sorting]] on the pointer values.
6742
-
6743
- *Returns:* `less<CT>()(x.get(), y.get())`.
6744
-
6745
- ``` cpp
6746
- template<class T1, class D1, class T2, class D2>
6747
- bool operator>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
6748
- ```
6749
-
6750
- *Returns:* `y < x`.
6751
-
6752
- ``` cpp
6753
- template<class T1, class D1, class T2, class D2>
6754
- bool operator<=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
6755
- ```
6756
-
6757
- *Returns:* `!(y < x)`.
6758
-
6759
- ``` cpp
6760
- template<class T1, class D1, class T2, class D2>
6761
- bool operator>=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
6762
- ```
6763
-
6764
- *Returns:* `!(x < y)`.
6765
-
6766
- ``` cpp
6767
- template<class T1, class D1, class T2, class D2>
6768
- requires three_way_comparable_with<typename unique_ptr<T1, D1>::pointer,
6769
- typename unique_ptr<T2, D2>::pointer>
6770
- compare_three_way_result_t<typename unique_ptr<T1, D1>::pointer,
6771
- typename unique_ptr<T2, D2>::pointer>
6772
- operator<=>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
6773
- ```
6774
-
6775
- *Returns:* `compare_three_way()(x.get(), y.get())`.
6776
-
6777
- ``` cpp
6778
- template<class T, class D>
6779
- bool operator==(const unique_ptr<T, D>& x, nullptr_t) noexcept;
6780
- ```
6781
-
6782
- *Returns:* `!x`.
6783
-
6784
- ``` cpp
6785
- template<class T, class D>
6786
- bool operator<(const unique_ptr<T, D>& x, nullptr_t);
6787
- template<class T, class D>
6788
- bool operator<(nullptr_t, const unique_ptr<T, D>& x);
6789
- ```
6790
-
6791
- *Preconditions:* The specialization `less<unique_ptr<T, D>::pointer>` is
6792
- a function object type [[function.objects]] that induces a strict weak
6793
- ordering [[alg.sorting]] on the pointer values.
6794
-
6795
- *Returns:* The first function template returns
6796
-
6797
- ``` cpp
6798
- less<unique_ptr<T, D>::pointer>()(x.get(), nullptr)
6799
- ```
6800
-
6801
- The second function template returns
6802
-
6803
- ``` cpp
6804
- less<unique_ptr<T, D>::pointer>()(nullptr, x.get())
6805
- ```
6806
-
6807
- ``` cpp
6808
- template<class T, class D>
6809
- bool operator>(const unique_ptr<T, D>& x, nullptr_t);
6810
- template<class T, class D>
6811
- bool operator>(nullptr_t, const unique_ptr<T, D>& x);
6812
- ```
6813
-
6814
- *Returns:* The first function template returns `nullptr < x`. The second
6815
- function template returns `x < nullptr`.
6816
-
6817
- ``` cpp
6818
- template<class T, class D>
6819
- bool operator<=(const unique_ptr<T, D>& x, nullptr_t);
6820
- template<class T, class D>
6821
- bool operator<=(nullptr_t, const unique_ptr<T, D>& x);
6822
- ```
6823
-
6824
- *Returns:* The first function template returns `!(nullptr < x)`. The
6825
- second function template returns `!(x < nullptr)`.
6826
-
6827
- ``` cpp
6828
- template<class T, class D>
6829
- bool operator>=(const unique_ptr<T, D>& x, nullptr_t);
6830
- template<class T, class D>
6831
- bool operator>=(nullptr_t, const unique_ptr<T, D>& x);
6832
- ```
6833
-
6834
- *Returns:* The first function template returns `!(x < nullptr)`. The
6835
- second function template returns `!(nullptr < x)`.
6836
-
6837
- ``` cpp
6838
- template<class T, class D>
6839
- requires three_way_comparable_with<typename unique_ptr<T, D>::pointer, nullptr_t>
6840
- compare_three_way_result_t<typename unique_ptr<T, D>::pointer, nullptr_t>
6841
- operator<=>(const unique_ptr<T, D>& x, nullptr_t);
6842
- ```
6843
-
6844
- *Returns:* `compare_three_way()(x.get(), nullptr)`.
6845
-
6846
- #### I/O <a id="unique.ptr.io">[[unique.ptr.io]]</a>
6847
-
6848
- ``` cpp
6849
- template<class E, class T, class Y, class D>
6850
- basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const unique_ptr<Y, D>& p);
6851
- ```
6852
-
6853
- *Constraints:* `os << p.get()` is a valid expression.
6854
-
6855
- *Effects:* Equivalent to: `os << p.get();`
6856
-
6857
- *Returns:* `os`.
6858
-
6859
- ### Class `bad_weak_ptr` <a id="util.smartptr.weak.bad">[[util.smartptr.weak.bad]]</a>
6860
-
6861
- ``` cpp
6862
- namespace std {
6863
- class bad_weak_ptr : public exception {
6864
- public:
6865
- // see [exception] for the specification of the special member functions
6866
- const char* what() const noexcept override;
6867
- };
6868
- }
6869
- ```
6870
-
6871
- An exception of type `bad_weak_ptr` is thrown by the `shared_ptr`
6872
- constructor taking a `weak_ptr`.
6873
-
6874
- ``` cpp
6875
- const char* what() const noexcept override;
6876
- ```
6877
-
6878
- *Returns:* An *implementation-defined* NTBS.
6879
-
6880
- ### Class template `shared_ptr` <a id="util.smartptr.shared">[[util.smartptr.shared]]</a>
6881
-
6882
- The `shared_ptr` class template stores a pointer, usually obtained via
6883
- `new`. `shared_ptr` implements semantics of shared ownership; the last
6884
- remaining owner of the pointer is responsible for destroying the object,
6885
- or otherwise releasing the resources associated with the stored pointer.
6886
- A `shared_ptr` is said to be empty if it does not own a pointer.
6887
-
6888
- ``` cpp
6889
- namespace std {
6890
- template<class T> class shared_ptr {
6891
- public:
6892
- using element_type = remove_extent_t<T>;
6893
- using weak_type = weak_ptr<T>;
6894
-
6895
- // [util.smartptr.shared.const], constructors
6896
- constexpr shared_ptr() noexcept;
6897
- constexpr shared_ptr(nullptr_t) noexcept : shared_ptr() { }
6898
- template<class Y>
6899
- explicit shared_ptr(Y* p);
6900
- template<class Y, class D>
6901
- shared_ptr(Y* p, D d);
6902
- template<class Y, class D, class A>
6903
- shared_ptr(Y* p, D d, A a);
6904
- template<class D>
6905
- shared_ptr(nullptr_t p, D d);
6906
- template<class D, class A>
6907
- shared_ptr(nullptr_t p, D d, A a);
6908
- template<class Y>
6909
- shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
6910
- template<class Y>
6911
- shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
6912
- shared_ptr(const shared_ptr& r) noexcept;
6913
- template<class Y>
6914
- shared_ptr(const shared_ptr<Y>& r) noexcept;
6915
- shared_ptr(shared_ptr&& r) noexcept;
6916
- template<class Y>
6917
- shared_ptr(shared_ptr<Y>&& r) noexcept;
6918
- template<class Y>
6919
- explicit shared_ptr(const weak_ptr<Y>& r);
6920
- template<class Y, class D>
6921
- shared_ptr(unique_ptr<Y, D>&& r);
6922
-
6923
- // [util.smartptr.shared.dest], destructor
6924
- ~shared_ptr();
6925
-
6926
- // [util.smartptr.shared.assign], assignment
6927
- shared_ptr& operator=(const shared_ptr& r) noexcept;
6928
- template<class Y>
6929
- shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
6930
- shared_ptr& operator=(shared_ptr&& r) noexcept;
6931
- template<class Y>
6932
- shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;
6933
- template<class Y, class D>
6934
- shared_ptr& operator=(unique_ptr<Y, D>&& r);
6935
-
6936
- // [util.smartptr.shared.mod], modifiers
6937
- void swap(shared_ptr& r) noexcept;
6938
- void reset() noexcept;
6939
- template<class Y>
6940
- void reset(Y* p);
6941
- template<class Y, class D>
6942
- void reset(Y* p, D d);
6943
- template<class Y, class D, class A>
6944
- void reset(Y* p, D d, A a);
6945
-
6946
- // [util.smartptr.shared.obs], observers
6947
- element_type* get() const noexcept;
6948
- T& operator*() const noexcept;
6949
- T* operator->() const noexcept;
6950
- element_type& operator[](ptrdiff_t i) const;
6951
- long use_count() const noexcept;
6952
- explicit operator bool() const noexcept;
6953
- template<class U>
6954
- bool owner_before(const shared_ptr<U>& b) const noexcept;
6955
- template<class U>
6956
- bool owner_before(const weak_ptr<U>& b) const noexcept;
6957
- };
6958
-
6959
- template<class T>
6960
- shared_ptr(weak_ptr<T>) -> shared_ptr<T>;
6961
- template<class T, class D>
6962
- shared_ptr(unique_ptr<T, D>) -> shared_ptr<T>;
6963
- }
6964
- ```
6965
-
6966
- Specializations of `shared_ptr` shall be *Cpp17CopyConstructible*,
6967
- *Cpp17CopyAssignable*, and *Cpp17LessThanComparable*, allowing their use
6968
- in standard containers. Specializations of `shared_ptr` shall be
6969
- contextually convertible to `bool`, allowing their use in boolean
6970
- expressions and declarations in conditions.
6971
-
6972
- The template parameter `T` of `shared_ptr` may be an incomplete type.
6973
-
6974
- [*Note 1*: `T` may be a function type. — *end note*]
6975
-
6976
- [*Example 1*:
6977
-
6978
- ``` cpp
6979
- if (shared_ptr<X> px = dynamic_pointer_cast<X>(py)) {
6980
- // do something with px
6981
- }
6982
- ```
6983
-
6984
- — *end example*]
6985
-
6986
- For purposes of determining the presence of a data race, member
6987
- functions shall access and modify only the `shared_ptr` and `weak_ptr`
6988
- objects themselves and not objects they refer to. Changes in
6989
- `use_count()` do not reflect modifications that can introduce data
6990
- races.
6991
-
6992
- For the purposes of subclause [[smartptr]], a pointer type `Y*` is said
6993
- to be *compatible with* a pointer type `T*` when either `Y*` is
6994
- convertible to `T*` or `Y` is `U[N]` and `T` is cv `U[]`.
6995
-
6996
- #### Constructors <a id="util.smartptr.shared.const">[[util.smartptr.shared.const]]</a>
6997
-
6998
- In the constructor definitions below, enables `shared_from_this` with
6999
- `p`, for a pointer `p` of type `Y*`, means that if `Y` has an
7000
- unambiguous and accessible base class that is a specialization of
7001
- `enable_shared_from_this` [[util.smartptr.enab]], then `remove_cv_t<Y>*`
7002
- shall be implicitly convertible to `T*` and the constructor evaluates
7003
- the statement:
7004
-
7005
- ``` cpp
7006
- if (p != nullptr && p->weak_this.expired())
7007
- p->weak_this = shared_ptr<remove_cv_t<Y>>(*this, const_cast<remove_cv_t<Y>*>(p));
7008
- ```
7009
-
7010
- The assignment to the `weak_this` member is not atomic and conflicts
7011
- with any potentially concurrent access to the same object
7012
- [[intro.multithread]].
7013
-
7014
- ``` cpp
7015
- constexpr shared_ptr() noexcept;
7016
- ```
7017
-
7018
- *Ensures:* `use_count() == 0 && get() == nullptr`.
7019
-
7020
- ``` cpp
7021
- template<class Y> explicit shared_ptr(Y* p);
7022
- ```
7023
-
7024
- *Mandates:* `Y` is a complete type.
7025
-
7026
- *Constraints:* When `T` is an array type, the expression `delete[] p` is
7027
- well-formed and either `T` is `U[N]` and `Y(*)[N]` is convertible to
7028
- `T*`, or `T` is `U[]` and `Y(*)[]` is convertible to `T*`. When `T` is
7029
- not an array type, the expression `delete p` is well-formed and `Y*` is
7030
- convertible to `T*`.
7031
-
7032
- *Preconditions:* The expression `delete[] p`, when `T` is an array type,
7033
- or `delete p`, when `T` is not an array type, has well-defined behavior,
7034
- and does not throw exceptions.
7035
-
7036
- *Effects:* When `T` is not an array type, constructs a `shared_ptr`
7037
- object that owns the pointer `p`. Otherwise, constructs a `shared_ptr`
7038
- that owns `p` and a deleter of an unspecified type that calls
7039
- `delete[] p`. When `T` is not an array type, enables `shared_from_this`
7040
- with `p`. If an exception is thrown, `delete p` is called when `T` is
7041
- not an array type, `delete[] p` otherwise.
7042
-
7043
- *Ensures:* `use_count() == 1 && get() == p`.
7044
-
7045
- *Throws:* `bad_alloc`, or an *implementation-defined* exception when a
7046
- resource other than memory could not be obtained.
7047
-
7048
- ``` cpp
7049
- template<class Y, class D> shared_ptr(Y* p, D d);
7050
- template<class Y, class D, class A> shared_ptr(Y* p, D d, A a);
7051
- template<class D> shared_ptr(nullptr_t p, D d);
7052
- template<class D, class A> shared_ptr(nullptr_t p, D d, A a);
7053
- ```
7054
-
7055
- *Constraints:* `is_move_constructible_v<D>` is `true`, and `d(p)` is a
7056
- well-formed expression. For the first two overloads:
7057
-
7058
- - If `T` is an array type, then either `T` is `U[N]` and `Y(*)[N]` is
7059
- convertible to `T*`, or `T` is `U[]` and `Y(*)[]` is convertible to
7060
- `T*`.
7061
- - If `T` is not an array type, then `Y*` is convertible to `T*`.
7062
-
7063
- *Preconditions:* Construction of `d` and a deleter of type `D`
7064
- initialized with `std::move(d)` do not throw exceptions. The expression
7065
- `d(p)` has well-defined behavior and does not throw exceptions. `A`
7066
- meets the *Cpp17Allocator* requirements ([[cpp17.allocator]]).
7067
-
7068
- *Effects:* Constructs a `shared_ptr` object that owns the object `p` and
7069
- the deleter `d`. When `T` is not an array type, the first and second
7070
- constructors enable `shared_from_this` with `p`. The second and fourth
7071
- constructors shall use a copy of `a` to allocate memory for internal
7072
- use. If an exception is thrown, `d(p)` is called.
7073
-
7074
- *Ensures:* `use_count() == 1 && get() == p`.
7075
-
7076
- *Throws:* `bad_alloc`, or an *implementation-defined* exception when a
7077
- resource other than memory could not be obtained.
7078
-
7079
- ``` cpp
7080
- template<class Y> shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
7081
- template<class Y> shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
7082
- ```
7083
-
7084
- *Effects:* Constructs a `shared_ptr` instance that stores `p` and shares
7085
- ownership with the initial value of `r`.
7086
-
7087
- *Ensures:* `get() == p`. For the second overload, `r` is empty and
7088
- `r.get() == nullptr`.
7089
-
7090
- [*Note 1*: To avoid the possibility of a dangling pointer, the user of
7091
- this constructor should ensure that `p` remains valid at least until the
7092
- ownership group of `r` is destroyed. — *end note*]
7093
-
7094
- [*Note 2*: This constructor allows creation of an empty `shared_ptr`
7095
- instance with a non-null stored pointer. — *end note*]
7096
-
7097
- ``` cpp
7098
- shared_ptr(const shared_ptr& r) noexcept;
7099
- template<class Y> shared_ptr(const shared_ptr<Y>& r) noexcept;
7100
- ```
7101
-
7102
- *Constraints:* For the second constructor, `Y*` is compatible with `T*`.
7103
-
7104
- *Effects:* If `r` is empty, constructs an empty `shared_ptr` object;
7105
- otherwise, constructs a `shared_ptr` object that shares ownership with
7106
- `r`.
7107
-
7108
- *Ensures:* `get() == r.get() && use_count() == r.use_count()`.
7109
-
7110
- ``` cpp
7111
- shared_ptr(shared_ptr&& r) noexcept;
7112
- template<class Y> shared_ptr(shared_ptr<Y>&& r) noexcept;
7113
- ```
7114
-
7115
- *Constraints:* For the second constructor, `Y*` is compatible with `T*`.
7116
-
7117
- *Effects:* Move constructs a `shared_ptr` instance from `r`.
7118
-
7119
- *Ensures:* `*this` shall contain the old value of `r`. `r` shall be
7120
- empty. `r.get() == nullptr`.
7121
-
7122
- ``` cpp
7123
- template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);
7124
- ```
7125
-
7126
- *Constraints:* `Y*` is compatible with `T*`.
7127
-
7128
- *Effects:* Constructs a `shared_ptr` object that shares ownership with
7129
- `r` and stores a copy of the pointer stored in `r`. If an exception is
7130
- thrown, the constructor has no effect.
7131
-
7132
- *Ensures:* `use_count() == r.use_count()`.
7133
-
7134
- *Throws:* `bad_weak_ptr` when `r.expired()`.
7135
-
7136
- ``` cpp
7137
- template<class Y, class D> shared_ptr(unique_ptr<Y, D>&& r);
7138
- ```
7139
-
7140
- *Constraints:* `Y*` is compatible with `T*` and
7141
- `unique_ptr<Y, D>::pointer` is convertible to `element_type*`.
7142
-
7143
- *Effects:* If `r.get() == nullptr`, equivalent to `shared_ptr()`.
7144
- Otherwise, if `D` is not a reference type, equivalent to
7145
- `shared_ptr(r.release(), r.get_deleter())`. Otherwise, equivalent to
7146
- `shared_ptr(r.release(), ref(r.get_deleter()))`. If an exception is
7147
- thrown, the constructor has no effect.
7148
-
7149
- #### Destructor <a id="util.smartptr.shared.dest">[[util.smartptr.shared.dest]]</a>
7150
-
7151
- ``` cpp
7152
- ~shared_ptr();
7153
- ```
7154
-
7155
- *Effects:*
7156
-
7157
- - If `*this` is empty or shares ownership with another `shared_ptr`
7158
- instance (`use_count() > 1`), there are no side effects.
7159
- - Otherwise, if `*this` owns an object `p` and a deleter `d`, `d(p)` is
7160
- called.
7161
- - Otherwise, `*this` owns a pointer `p`, and `delete p` is called.
7162
-
7163
- [*Note 1*: Since the destruction of `*this` decreases the number of
7164
- instances that share ownership with `*this` by one, after `*this` has
7165
- been destroyed all `shared_ptr` instances that shared ownership with
7166
- `*this` will report a `use_count()` that is one less than its previous
7167
- value. — *end note*]
7168
-
7169
- #### Assignment <a id="util.smartptr.shared.assign">[[util.smartptr.shared.assign]]</a>
7170
-
7171
- ``` cpp
7172
- shared_ptr& operator=(const shared_ptr& r) noexcept;
7173
- template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
7174
- ```
7175
-
7176
- *Effects:* Equivalent to `shared_ptr(r).swap(*this)`.
7177
-
7178
- *Returns:* `*this`.
7179
-
7180
- [*Note 1*:
7181
-
7182
- The use count updates caused by the temporary object construction and
7183
- destruction are not observable side effects, so the implementation may
7184
- meet the effects (and the implied guarantees) via different means,
7185
- without creating a temporary. In particular, in the example:
7186
-
7187
- ``` cpp
7188
- shared_ptr<int> p(new int);
7189
- shared_ptr<void> q(p);
7190
- p = p;
7191
- q = p;
7192
- ```
7193
-
7194
- both assignments may be no-ops.
7195
-
7196
- — *end note*]
7197
-
7198
- ``` cpp
7199
- shared_ptr& operator=(shared_ptr&& r) noexcept;
7200
- template<class Y> shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;
7201
- ```
7202
-
7203
- *Effects:* Equivalent to `shared_ptr(std::move(r)).swap(*this)`.
7204
-
7205
- *Returns:* `*this`.
7206
-
7207
- ``` cpp
7208
- template<class Y, class D> shared_ptr& operator=(unique_ptr<Y, D>&& r);
7209
- ```
7210
-
7211
- *Effects:* Equivalent to `shared_ptr(std::move(r)).swap(*this)`.
7212
-
7213
- *Returns:* `*this`.
7214
-
7215
- #### Modifiers <a id="util.smartptr.shared.mod">[[util.smartptr.shared.mod]]</a>
7216
-
7217
- ``` cpp
7218
- void swap(shared_ptr& r) noexcept;
7219
- ```
7220
-
7221
- *Effects:* Exchanges the contents of `*this` and `r`.
7222
-
7223
- ``` cpp
7224
- void reset() noexcept;
7225
- ```
7226
-
7227
- *Effects:* Equivalent to `shared_ptr().swap(*this)`.
7228
-
7229
- ``` cpp
7230
- template<class Y> void reset(Y* p);
7231
- ```
7232
-
7233
- *Effects:* Equivalent to `shared_ptr(p).swap(*this)`.
7234
-
7235
- ``` cpp
7236
- template<class Y, class D> void reset(Y* p, D d);
7237
- ```
7238
-
7239
- *Effects:* Equivalent to `shared_ptr(p, d).swap(*this)`.
7240
-
7241
- ``` cpp
7242
- template<class Y, class D, class A> void reset(Y* p, D d, A a);
7243
- ```
7244
-
7245
- *Effects:* Equivalent to `shared_ptr(p, d, a).swap(*this)`.
7246
-
7247
- #### Observers <a id="util.smartptr.shared.obs">[[util.smartptr.shared.obs]]</a>
7248
-
7249
- ``` cpp
7250
- element_type* get() const noexcept;
7251
- ```
7252
-
7253
- *Returns:* The stored pointer.
7254
-
7255
- ``` cpp
7256
- T& operator*() const noexcept;
7257
- ```
7258
-
7259
- *Preconditions:* `get() != 0`.
7260
-
7261
- *Returns:* `*get()`.
7262
-
7263
- *Remarks:* When `T` is an array type or cv `void`, it is unspecified
7264
- whether this member function is declared. If it is declared, it is
7265
- unspecified what its return type is, except that the declaration
7266
- (although not necessarily the definition) of the function shall be
7267
- well-formed.
7268
-
7269
- ``` cpp
7270
- T* operator->() const noexcept;
7271
- ```
7272
-
7273
- *Preconditions:* `get() != 0`.
7274
-
7275
- *Returns:* `get()`.
7276
-
7277
- *Remarks:* When `T` is an array type, it is unspecified whether this
7278
- member function is declared. If it is declared, it is unspecified what
7279
- its return type is, except that the declaration (although not
7280
- necessarily the definition) of the function shall be well-formed.
7281
-
7282
- ``` cpp
7283
- element_type& operator[](ptrdiff_t i) const;
7284
- ```
7285
-
7286
- *Preconditions:* `get() != 0 && i >= 0`. If `T` is `U[N]`, `i < N`.
7287
-
7288
- *Returns:* `get()[i]`.
7289
-
7290
- *Remarks:* When `T` is not an array type, it is unspecified whether this
7291
- member function is declared. If it is declared, it is unspecified what
7292
- its return type is, except that the declaration (although not
7293
- necessarily the definition) of the function shall be well-formed.
7294
-
7295
- *Throws:* Nothing.
7296
-
7297
- ``` cpp
7298
- long use_count() const noexcept;
7299
- ```
7300
-
7301
- *Returns:* The number of `shared_ptr` objects, `*this` included, that
7302
- share ownership with `*this`, or `0` when `*this` is empty.
7303
-
7304
- *Synchronization:* None.
7305
-
7306
- [*Note 1*: `get() == nullptr` does not imply a specific return value of
7307
- `use_count()`. — *end note*]
7308
-
7309
- [*Note 2*: `weak_ptr<T>::lock()` can affect the return value of
7310
- `use_count()`. — *end note*]
7311
-
7312
- [*Note 3*: When multiple threads can affect the return value of
7313
- `use_count()`, the result should be treated as approximate. In
7314
- particular, `use_count() == 1` does not imply that accesses through a
7315
- previously destroyed `shared_ptr` have in any sense
7316
- completed. — *end note*]
7317
-
7318
- ``` cpp
7319
- explicit operator bool() const noexcept;
7320
- ```
7321
-
7322
- *Returns:* `get() != 0`.
7323
-
7324
- ``` cpp
7325
- template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
7326
- template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
7327
- ```
7328
-
7329
- *Returns:* An unspecified value such that
7330
-
7331
- - `x.owner_before(y)` defines a strict weak ordering as defined
7332
- in  [[alg.sorting]];
7333
- - under the equivalence relation defined by `owner_before`,
7334
- `!a.owner_before(b) && !b.owner_before(a)`, two `shared_ptr` or
7335
- `weak_ptr` instances are equivalent if and only if they share
7336
- ownership or are both empty.
7337
-
7338
- #### Creation <a id="util.smartptr.shared.create">[[util.smartptr.shared.create]]</a>
7339
-
7340
- The common requirements that apply to all `make_shared`,
7341
- `allocate_shared`, `make_shared_for_overwrite`, and
7342
- `allocate_shared_for_overwrite` overloads, unless specified otherwise,
7343
- are described below.
7344
-
7345
- ``` cpp
7346
- template<class T, ...>
7347
- shared_ptr<T> make_shared(args);
7348
- template<class T, class A, ...>
7349
- shared_ptr<T> allocate_shared(const A& a, args);
7350
- template<class T, ...>
7351
- shared_ptr<T> make_shared_for_overwrite(args);
7352
- template<class T, class A, ...>
7353
- shared_ptr<T> allocate_shared_for_overwrite(const A& a, args);
7354
- ```
7355
-
7356
- *Preconditions:* `A` meets the *Cpp17Allocator* requirements
7357
- ([[cpp17.allocator]]).
7358
-
7359
- *Effects:* Allocates memory for an object of type `T` (or `U[N]` when
7360
- `T` is `U[]`, where `N` is determined from *args* as specified by the
7361
- concrete overload). The object is initialized from *args* as specified
7362
- by the concrete overload. The `allocate_shared` and
7363
- `allocate_shared_for_overwrite` templates use a copy of `a` (rebound for
7364
- an unspecified `value_type`) to allocate memory. If an exception is
7365
- thrown, the functions have no effect.
7366
-
7367
- *Returns:* A `shared_ptr` instance that stores and owns the address of
7368
- the newly constructed object.
7369
-
7370
- *Ensures:* `r.get() != 0 && r.use_count() == 1`, where `r` is the return
7371
- value.
7372
-
7373
- *Throws:* `bad_alloc`, or an exception thrown from `allocate` or from
7374
- the initialization of the object.
7375
-
7376
- *Remarks:*
7377
-
7378
- - Implementations should perform no more than one memory allocation.
7379
- \[*Note 1*: This provides efficiency equivalent to an intrusive smart
7380
- pointer. — *end note*]
7381
- - When an object of an array type `U` is specified to have an initial
7382
- value of `u` (of the same type), this shall be interpreted to mean
7383
- that each array element of the object has as its initial value the
7384
- corresponding element from `u`.
7385
- - When an object of an array type is specified to have a default initial
7386
- value, this shall be interpreted to mean that each array element of
7387
- the object has a default initial value.
7388
- - When a (sub)object of a non-array type `U` is specified to have an
7389
- initial value of `v`, or `U(l...)`, where `l...` is a list of
7390
- constructor arguments, `make_shared` shall initialize this (sub)object
7391
- via the expression `::new(pv) U(v)` or `::new(pv) U(l...)`
7392
- respectively, where `pv` has type `void*` and points to storage
7393
- suitable to hold an object of type `U`.
7394
- - When a (sub)object of a non-array type `U` is specified to have an
7395
- initial value of `v`, or `U(l...)`, where `l...` is a list of
7396
- constructor arguments, `allocate_shared` shall initialize this
7397
- (sub)object via the expression
7398
- - `allocator_traits<A2>::construct(a2, pv, v)` or
7399
- - `allocator_traits<A2>::construct(a2, pv, l...)`
7400
-
7401
- respectively, where `pv` points to storage suitable to hold an object
7402
- of type `U` and `a2` of type `A2` is a rebound copy of the allocator
7403
- `a` passed to `allocate_shared` such that its `value_type` is
7404
- `remove_cv_t<U>`.
7405
- - When a (sub)object of non-array type `U` is specified to have a
7406
- default initial value, `make_shared` shall initialize this (sub)object
7407
- via the expression `::new(pv) U()`, where `pv` has type `void*` and
7408
- points to storage suitable to hold an object of type `U`.
7409
- - When a (sub)object of non-array type `U` is specified to have a
7410
- default initial value, `allocate_shared` shall initialize this
7411
- (sub)object via the expression
7412
- `allocator_traits<A2>::construct(a2, pv)`, where `pv` points to
7413
- storage suitable to hold an object of type `U` and `a2` of type `A2`
7414
- is a rebound copy of the allocator `a` passed to `allocate_shared`
7415
- such that its `value_type` is `remove_cv_t<U>`.
7416
- - When a (sub)object of non-array type `U` is initialized by
7417
- `make_shared_for_overwrite` or `allocate_shared_for_overwrite`, it is
7418
- initialized via the expression `::new(pv) U`, where `pv` has type
7419
- `void*` and points to storage suitable to hold an object of type `U`.
7420
- - Array elements are initialized in ascending order of their addresses.
7421
- - When the lifetime of the object managed by the return value ends, or
7422
- when the initialization of an array element throws an exception, the
7423
- initialized elements are destroyed in the reverse order of their
7424
- original construction.
7425
- - When a (sub)object of non-array type `U` that was initialized by
7426
- `make_shared` is to be destroyed, it is destroyed via the expression
7427
- `pv->~U()` where `pv` points to that object of type `U`.
7428
- - When a (sub)object of non-array type `U` that was initialized by
7429
- `allocate_shared` is to be destroyed, it is destroyed via the
7430
- expression `allocator_traits<A2>::destroy(a2, pv)` where `pv` points
7431
- to that object of type `remove_cv_t<U>` and `a2` of type `A2` is a
7432
- rebound copy of the allocator `a` passed to `allocate_shared` such
7433
- that its `value_type` is `remove_cv_t<U>`.
7434
-
7435
- [*Note 1*: These functions will typically allocate more memory than
7436
- `sizeof(T)` to allow for internal bookkeeping structures such as
7437
- reference counts. — *end note*]
7438
-
7439
- ``` cpp
7440
- template<class T, class... Args>
7441
- shared_ptr<T> make_shared(Args&&... args); // T is not array
7442
- template<class T, class A, class... Args>
7443
- shared_ptr<T> allocate_shared(const A& a, Args&&... args); // T is not array
7444
- ```
7445
-
7446
- *Constraints:* `T` is not an array type.
7447
-
7448
- *Returns:* A `shared_ptr` to an object of type `T` with an initial value
7449
- `T(forward<Args>(args)...)`.
7450
-
7451
- *Remarks:* The `shared_ptr` constructors called by these functions
7452
- enable `shared_from_this` with the address of the newly constructed
7453
- object of type `T`.
7454
-
7455
- [*Example 1*:
7456
-
7457
- ``` cpp
7458
- shared_ptr<int> p = make_shared<int>(); // shared_ptr to int()
7459
- shared_ptr<vector<int>> q = make_shared<vector<int>>(16, 1);
7460
- // shared_ptr to vector of 16 elements with value 1
7461
- ```
7462
-
7463
- — *end example*]
7464
-
7465
- ``` cpp
7466
- template<class T> shared_ptr<T>
7467
- make_shared(size_t N); // T is U[]
7468
- template<class T, class A>
7469
- shared_ptr<T> allocate_shared(const A& a, size_t N); // T is U[]
7470
- ```
7471
-
7472
- *Constraints:* `T` is of the form `U[]`.
7473
-
7474
- *Returns:* A `shared_ptr` to an object of type `U[N]` with a default
7475
- initial value, where `U` is `remove_extent_t<T>`.
7476
-
7477
- [*Example 2*:
7478
-
7479
- ``` cpp
7480
- shared_ptr<double[]> p = make_shared<double[]>(1024);
7481
- // shared_ptr to a value-initialized double[1024]
7482
- shared_ptr<double[][2][2]> q = make_shared<double[][2][2]>(6);
7483
- // shared_ptr to a value-initialized double[6][2][2]
7484
- ```
7485
-
7486
- — *end example*]
7487
-
7488
- ``` cpp
7489
- template<class T>
7490
- shared_ptr<T> make_shared(); // T is U[N]
7491
- template<class T, class A>
7492
- shared_ptr<T> allocate_shared(const A& a); // T is U[N]
7493
- ```
7494
-
7495
- *Constraints:* `T` is of the form `U[N]`.
7496
-
7497
- *Returns:* A `shared_ptr` to an object of type `T` with a default
7498
- initial value.
7499
-
7500
- [*Example 3*:
7501
-
7502
- ``` cpp
7503
- shared_ptr<double[1024]> p = make_shared<double[1024]>();
7504
- // shared_ptr to a value-initialized double[1024]
7505
- shared_ptr<double[6][2][2]> q = make_shared<double[6][2][2]>();
7506
- // shared_ptr to a value-initialized double[6][2][2]
7507
- ```
7508
-
7509
- — *end example*]
7510
-
7511
- ``` cpp
7512
- template<class T>
7513
- shared_ptr<T> make_shared(size_t N,
7514
- const remove_extent_t<T>& u); // T is U[]
7515
- template<class T, class A>
7516
- shared_ptr<T> allocate_shared(const A& a, size_t N,
7517
- const remove_extent_t<T>& u); // T is U[]
7518
- ```
7519
-
7520
- *Constraints:* `T` is of the form `U[]`.
7521
-
7522
- *Returns:* A `shared_ptr` to an object of type `U[N]`, where `U` is
7523
- `remove_extent_t<T>` and each array element has an initial value of `u`.
7524
-
7525
- [*Example 4*:
7526
-
7527
- ``` cpp
7528
- shared_ptr<double[]> p = make_shared<double[]>(1024, 1.0);
7529
- // shared_ptr to a double[1024], where each element is 1.0
7530
- shared_ptr<double[][2]> q = make_shared<double[][2]>(6, {1.0, 0.0});
7531
- // shared_ptr to a double[6][2], where each double[2] element is {1.0, 0.0}
7532
- shared_ptr<vector<int>[]> r = make_shared<vector<int>[]>(4, {1, 2});
7533
- // shared_ptr to a vector<int>[4], where each vector has contents {1, 2}
7534
- ```
7535
-
7536
- — *end example*]
7537
-
7538
- ``` cpp
7539
- template<class T>
7540
- shared_ptr<T> make_shared(const remove_extent_t<T>& u); // T is U[N]
7541
- template<class T, class A>
7542
- shared_ptr<T> allocate_shared(const A& a,
7543
- const remove_extent_t<T>& u); // T is U[N]
7544
- ```
7545
-
7546
- *Constraints:* `T` is of the form `U[N]`.
7547
-
7548
- *Returns:* A `shared_ptr` to an object of type `T`, where each array
7549
- element of type `remove_extent_t<T>` has an initial value of `u`.
7550
-
7551
- [*Example 5*:
7552
-
7553
- ``` cpp
7554
- shared_ptr<double[1024]> p = make_shared<double[1024]>(1.0);
7555
- // shared_ptr to a double[1024], where each element is 1.0
7556
- shared_ptr<double[6][2]> q = make_shared<double[6][2]>({1.0, 0.0});
7557
- // shared_ptr to a double[6][2], where each double[2] element is {1.0, 0.0}
7558
- shared_ptr<vector<int>[4]> r = make_shared<vector<int>[4]>({1, 2});
7559
- // shared_ptr to a vector<int>[4], where each vector has contents {1, 2}
7560
- ```
7561
-
7562
- — *end example*]
7563
-
7564
- ``` cpp
7565
- template<class T>
7566
- shared_ptr<T> make_shared_for_overwrite();
7567
- template<class T, class A>
7568
- shared_ptr<T> allocate_shared_for_overwrite(const A& a);
7569
- ```
7570
-
7571
- *Constraints:* `T` is not an array of unknown bound.
7572
-
7573
- *Returns:* A `shared_ptr` to an object of type `T`.
7574
-
7575
- [*Example 6*:
7576
-
7577
- ``` cpp
7578
- struct X { double data[1024]; };
7579
- shared_ptr<X> p = make_shared_for_overwrite<X>();
7580
- // shared_ptr to a default-initialized X, where each element in X::data has an indeterminate value
7581
-
7582
- shared_ptr<double[1024]> q = make_shared_for_overwrite<double[1024]>();
7583
- // shared_ptr to a default-initialized double[1024], where each element has an indeterminate value
7584
- ```
7585
-
7586
- — *end example*]
7587
-
7588
- ``` cpp
7589
- template<class T>
7590
- shared_ptr<T> make_shared_for_overwrite(size_t N);
7591
- template<class T, class A>
7592
- shared_ptr<T> allocate_shared_for_overwrite(const A& a, size_t N);
7593
- ```
7594
-
7595
- *Constraints:* `T` is an array of unknown bound.
7596
-
7597
- *Returns:* A `shared_ptr` to an object of type `U[N]`, where `U` is
7598
- `remove_extent_t<T>`.
7599
-
7600
- [*Example 7*:
7601
-
7602
- ``` cpp
7603
- shared_ptr<double[]> p = make_shared_for_overwrite<double[]>(1024);
7604
- // shared_ptr to a default-initialized double[1024], where each element has an indeterminate value
7605
- ```
7606
-
7607
- — *end example*]
7608
-
7609
- #### Comparison <a id="util.smartptr.shared.cmp">[[util.smartptr.shared.cmp]]</a>
7610
-
7611
- ``` cpp
7612
- template<class T, class U>
7613
- bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
7614
- ```
7615
-
7616
- *Returns:* `a.get() == b.get()`.
7617
-
7618
- ``` cpp
7619
- template<class T>
7620
- bool operator==(const shared_ptr<T>& a, nullptr_t) noexcept;
7621
- ```
7622
-
7623
- *Returns:* `!a`.
7624
-
7625
- ``` cpp
7626
- template<class T, class U>
7627
- strong_ordering operator<=>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
7628
- ```
7629
-
7630
- *Returns:* `compare_three_way()(a.get(), b.get())`.
7631
-
7632
- [*Note 1*: Defining a comparison function allows `shared_ptr` objects
7633
- to be used as keys in associative containers. — *end note*]
7634
-
7635
- ``` cpp
7636
- template<class T>
7637
- strong_ordering operator<=>(const shared_ptr<T>& a, nullptr_t) noexcept;
7638
- ```
7639
-
7640
- *Returns:* `compare_three_way()(a.get(), nullptr)`.
7641
-
7642
- #### Specialized algorithms <a id="util.smartptr.shared.spec">[[util.smartptr.shared.spec]]</a>
7643
-
7644
- ``` cpp
7645
- template<class T>
7646
- void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
7647
- ```
7648
-
7649
- *Effects:* Equivalent to `a.swap(b)`.
7650
-
7651
- #### Casts <a id="util.smartptr.shared.cast">[[util.smartptr.shared.cast]]</a>
7652
-
7653
- ``` cpp
7654
- template<class T, class U>
7655
- shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
7656
- template<class T, class U>
7657
- shared_ptr<T> static_pointer_cast(shared_ptr<U>&& r) noexcept;
7658
- ```
7659
-
7660
- *Mandates:* The expression `static_cast<T*>((U*)nullptr)` is
7661
- well-formed.
7662
-
7663
- *Returns:*
7664
-
7665
- ``` cpp
7666
- shared_ptr<T>(R, static_cast<typename shared_ptr<T>::element_type*>(r.get()))
7667
- ```
7668
-
7669
- where *`R`* is `r` for the first overload, and `std::move(r)` for the
7670
- second.
7671
-
7672
- [*Note 1*: The seemingly equivalent expression
7673
- `shared_ptr<T>(static_cast<T*>(r.get()))` will eventually result in
7674
- undefined behavior, attempting to delete the same object
7675
- twice. — *end note*]
7676
-
7677
- ``` cpp
7678
- template<class T, class U>
7679
- shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;
7680
- template<class T, class U>
7681
- shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;
7682
- ```
7683
-
7684
- *Mandates:* The expression `dynamic_cast<T*>((U*)nullptr)` is
7685
- well-formed. The expression
7686
- `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` is well
7687
- formed.
7688
-
7689
- *Preconditions:* The expression
7690
- `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` has
7691
- well-defined behavior.
7692
-
7693
- *Returns:*
7694
-
7695
- - When `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())`
7696
- returns a non-null value `p`, `shared_ptr<T>(`*`R`*`, p)`, where *`R`*
7697
- is `r` for the first overload, and `std::move(r)` for the second.
7698
- - Otherwise, `shared_ptr<T>()`.
7699
-
7700
- [*Note 2*: The seemingly equivalent expression
7701
- `shared_ptr<T>(dynamic_cast<T*>(r.get()))` will eventually result in
7702
- undefined behavior, attempting to delete the same object
7703
- twice. — *end note*]
7704
-
7705
- ``` cpp
7706
- template<class T, class U>
7707
- shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;
7708
- template<class T, class U>
7709
- shared_ptr<T> const_pointer_cast(shared_ptr<U>&& r) noexcept;
7710
- ```
7711
-
7712
- *Mandates:* The expression `const_cast<T*>((U*)nullptr)` is well-formed.
7713
-
7714
- *Returns:*
7715
-
7716
- ``` cpp
7717
- shared_ptr<T>(R, const_cast<typename shared_ptr<T>::element_type*>(r.get()))
7718
- ```
7719
-
7720
- where *`R`* is `r` for the first overload, and `std::move(r)` for the
7721
- second.
7722
-
7723
- [*Note 3*: The seemingly equivalent expression
7724
- `shared_ptr<T>(const_cast<T*>(r.get()))` will eventually result in
7725
- undefined behavior, attempting to delete the same object
7726
- twice. — *end note*]
7727
-
7728
- ``` cpp
7729
- template<class T, class U>
7730
- shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;
7731
- template<class T, class U>
7732
- shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U>&& r) noexcept;
7733
- ```
7734
-
7735
- *Mandates:* The expression `reinterpret_cast<T*>((U*)nullptr)` is
7736
- well-formed.
7737
-
7738
- *Returns:*
7739
-
7740
- ``` cpp
7741
- shared_ptr<T>(R, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get()))
7742
- ```
7743
-
7744
- where *`R`* is `r` for the first overload, and `std::move(r)` for the
7745
- second.
7746
-
7747
- [*Note 4*: The seemingly equivalent expression
7748
- `shared_ptr<T>(reinterpret_cast<T*>(r.get()))` will eventually result in
7749
- undefined behavior, attempting to delete the same object
7750
- twice. — *end note*]
7751
-
7752
- #### `get_deleter` <a id="util.smartptr.getdeleter">[[util.smartptr.getdeleter]]</a>
7753
-
7754
- ``` cpp
7755
- template<class D, class T>
7756
- D* get_deleter(const shared_ptr<T>& p) noexcept;
7757
- ```
7758
-
7759
- *Returns:* If `p` owns a deleter `d` of type cv-unqualified `D`, returns
7760
- `addressof(d)`; otherwise returns `nullptr`. The returned pointer
7761
- remains valid as long as there exists a `shared_ptr` instance that owns
7762
- `d`.
7763
-
7764
- [*Note 1*: It is unspecified whether the pointer remains valid longer
7765
- than that. This can happen if the implementation doesn’t destroy the
7766
- deleter until all `weak_ptr` instances that share ownership with `p`
7767
- have been destroyed. — *end note*]
7768
-
7769
- #### I/O <a id="util.smartptr.shared.io">[[util.smartptr.shared.io]]</a>
7770
-
7771
- ``` cpp
7772
- template<class E, class T, class Y>
7773
- basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);
7774
- ```
7775
-
7776
- *Effects:* As if by: `os << p.get();`
7777
-
7778
- *Returns:* `os`.
7779
-
7780
- ### Class template `weak_ptr` <a id="util.smartptr.weak">[[util.smartptr.weak]]</a>
7781
-
7782
- The `weak_ptr` class template stores a weak reference to an object that
7783
- is already managed by a `shared_ptr`. To access the object, a `weak_ptr`
7784
- can be converted to a `shared_ptr` using the member function `lock`.
7785
-
7786
- ``` cpp
7787
- namespace std {
7788
- template<class T> class weak_ptr {
7789
- public:
7790
- using element_type = remove_extent_t<T>;
7791
-
7792
- // [util.smartptr.weak.const], constructors
7793
- constexpr weak_ptr() noexcept;
7794
- template<class Y>
7795
- weak_ptr(const shared_ptr<Y>& r) noexcept;
7796
- weak_ptr(const weak_ptr& r) noexcept;
7797
- template<class Y>
7798
- weak_ptr(const weak_ptr<Y>& r) noexcept;
7799
- weak_ptr(weak_ptr&& r) noexcept;
7800
- template<class Y>
7801
- weak_ptr(weak_ptr<Y>&& r) noexcept;
7802
-
7803
- // [util.smartptr.weak.dest], destructor
7804
- ~weak_ptr();
7805
-
7806
- // [util.smartptr.weak.assign], assignment
7807
- weak_ptr& operator=(const weak_ptr& r) noexcept;
7808
- template<class Y>
7809
- weak_ptr& operator=(const weak_ptr<Y>& r) noexcept;
7810
- template<class Y>
7811
- weak_ptr& operator=(const shared_ptr<Y>& r) noexcept;
7812
- weak_ptr& operator=(weak_ptr&& r) noexcept;
7813
- template<class Y>
7814
- weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;
7815
-
7816
- // [util.smartptr.weak.mod], modifiers
7817
- void swap(weak_ptr& r) noexcept;
7818
- void reset() noexcept;
7819
-
7820
- // [util.smartptr.weak.obs], observers
7821
- long use_count() const noexcept;
7822
- bool expired() const noexcept;
7823
- shared_ptr<T> lock() const noexcept;
7824
- template<class U>
7825
- bool owner_before(const shared_ptr<U>& b) const noexcept;
7826
- template<class U>
7827
- bool owner_before(const weak_ptr<U>& b) const noexcept;
7828
- };
7829
-
7830
- template<class T>
7831
- weak_ptr(shared_ptr<T>) -> weak_ptr<T>;
7832
-
7833
- // [util.smartptr.weak.spec], specialized algorithms
7834
- template<class T>
7835
- void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
7836
- }
7837
- ```
7838
-
7839
- Specializations of `weak_ptr` shall be *Cpp17CopyConstructible* and
7840
- *Cpp17CopyAssignable*, allowing their use in standard containers. The
7841
- template parameter `T` of `weak_ptr` may be an incomplete type.
7842
-
7843
- #### Constructors <a id="util.smartptr.weak.const">[[util.smartptr.weak.const]]</a>
7844
-
7845
- ``` cpp
7846
- constexpr weak_ptr() noexcept;
7847
- ```
7848
-
7849
- *Effects:* Constructs an empty `weak_ptr` object.
7850
-
7851
- *Ensures:* `use_count() == 0`.
7852
-
7853
- ``` cpp
7854
- weak_ptr(const weak_ptr& r) noexcept;
7855
- template<class Y> weak_ptr(const weak_ptr<Y>& r) noexcept;
7856
- template<class Y> weak_ptr(const shared_ptr<Y>& r) noexcept;
7857
- ```
7858
-
7859
- *Constraints:* For the second and third constructors, `Y*` is compatible
7860
- with `T*`.
7861
-
7862
- *Effects:* If `r` is empty, constructs an empty `weak_ptr` object;
7863
- otherwise, constructs a `weak_ptr` object that shares ownership with `r`
7864
- and stores a copy of the pointer stored in `r`.
7865
-
7866
- *Ensures:* `use_count() == r.use_count()`.
7867
-
7868
- ``` cpp
7869
- weak_ptr(weak_ptr&& r) noexcept;
7870
- template<class Y> weak_ptr(weak_ptr<Y>&& r) noexcept;
7871
- ```
7872
-
7873
- *Constraints:* For the second constructor, `Y*` is compatible with `T*`.
7874
-
7875
- *Effects:* Move constructs a `weak_ptr` instance from `r`.
7876
-
7877
- *Ensures:* `*this` shall contain the old value of `r`. `r` shall be
7878
- empty. `r.use_count() == 0`.
7879
-
7880
- #### Destructor <a id="util.smartptr.weak.dest">[[util.smartptr.weak.dest]]</a>
7881
-
7882
- ``` cpp
7883
- ~weak_ptr();
7884
- ```
7885
-
7886
- *Effects:* Destroys this `weak_ptr` object but has no effect on the
7887
- object its stored pointer points to.
7888
-
7889
- #### Assignment <a id="util.smartptr.weak.assign">[[util.smartptr.weak.assign]]</a>
7890
-
7891
- ``` cpp
7892
- weak_ptr& operator=(const weak_ptr& r) noexcept;
7893
- template<class Y> weak_ptr& operator=(const weak_ptr<Y>& r) noexcept;
7894
- template<class Y> weak_ptr& operator=(const shared_ptr<Y>& r) noexcept;
7895
- ```
7896
-
7897
- *Effects:* Equivalent to `weak_ptr(r).swap(*this)`.
7898
-
7899
- *Remarks:* The implementation may meet the effects (and the implied
7900
- guarantees) via different means, without creating a temporary object.
7901
-
7902
- *Returns:* `*this`.
7903
-
7904
- ``` cpp
7905
- weak_ptr& operator=(weak_ptr&& r) noexcept;
7906
- template<class Y> weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;
7907
- ```
7908
-
7909
- *Effects:* Equivalent to `weak_ptr(std::move(r)).swap(*this)`.
7910
-
7911
- *Returns:* `*this`.
7912
-
7913
- #### Modifiers <a id="util.smartptr.weak.mod">[[util.smartptr.weak.mod]]</a>
7914
-
7915
- ``` cpp
7916
- void swap(weak_ptr& r) noexcept;
7917
- ```
7918
-
7919
- *Effects:* Exchanges the contents of `*this` and `r`.
7920
-
7921
- ``` cpp
7922
- void reset() noexcept;
7923
- ```
7924
-
7925
- *Effects:* Equivalent to `weak_ptr().swap(*this)`.
7926
-
7927
- #### Observers <a id="util.smartptr.weak.obs">[[util.smartptr.weak.obs]]</a>
7928
-
7929
- ``` cpp
7930
- long use_count() const noexcept;
7931
- ```
7932
-
7933
- *Returns:* `0` if `*this` is empty; otherwise, the number of
7934
- `shared_ptr` instances that share ownership with `*this`.
7935
-
7936
- ``` cpp
7937
- bool expired() const noexcept;
7938
- ```
7939
-
7940
- *Returns:* `use_count() == 0`.
7941
-
7942
- ``` cpp
7943
- shared_ptr<T> lock() const noexcept;
7944
- ```
7945
-
7946
- *Returns:* `expired() ? shared_ptr<T>() : shared_ptr<T>(*this)`,
7947
- executed atomically.
7948
-
7949
- ``` cpp
7950
- template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
7951
- template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
7952
- ```
7953
-
7954
- *Returns:* An unspecified value such that
7955
-
7956
- - `x.owner_before(y)` defines a strict weak ordering as defined
7957
- in  [[alg.sorting]];
7958
- - under the equivalence relation defined by `owner_before`,
7959
- `!a.owner_before(b) && !b.owner_before(a)`, two `shared_ptr` or
7960
- `weak_ptr` instances are equivalent if and only if they share
7961
- ownership or are both empty.
7962
-
7963
- #### Specialized algorithms <a id="util.smartptr.weak.spec">[[util.smartptr.weak.spec]]</a>
7964
-
7965
- ``` cpp
7966
- template<class T>
7967
- void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
7968
- ```
7969
-
7970
- *Effects:* Equivalent to `a.swap(b)`.
7971
-
7972
- ### Class template `owner_less` <a id="util.smartptr.ownerless">[[util.smartptr.ownerless]]</a>
7973
-
7974
- The class template `owner_less` allows ownership-based mixed comparisons
7975
- of shared and weak pointers.
7976
-
7977
- ``` cpp
7978
- namespace std {
7979
- template<class T = void> struct owner_less;
7980
-
7981
- template<class T> struct owner_less<shared_ptr<T>> {
7982
- bool operator()(const shared_ptr<T>&, const shared_ptr<T>&) const noexcept;
7983
- bool operator()(const shared_ptr<T>&, const weak_ptr<T>&) const noexcept;
7984
- bool operator()(const weak_ptr<T>&, const shared_ptr<T>&) const noexcept;
7985
- };
7986
-
7987
- template<class T> struct owner_less<weak_ptr<T>> {
7988
- bool operator()(const weak_ptr<T>&, const weak_ptr<T>&) const noexcept;
7989
- bool operator()(const shared_ptr<T>&, const weak_ptr<T>&) const noexcept;
7990
- bool operator()(const weak_ptr<T>&, const shared_ptr<T>&) const noexcept;
7991
- };
7992
-
7993
- template<> struct owner_less<void> {
7994
- template<class T, class U>
7995
- bool operator()(const shared_ptr<T>&, const shared_ptr<U>&) const noexcept;
7996
- template<class T, class U>
7997
- bool operator()(const shared_ptr<T>&, const weak_ptr<U>&) const noexcept;
7998
- template<class T, class U>
7999
- bool operator()(const weak_ptr<T>&, const shared_ptr<U>&) const noexcept;
8000
- template<class T, class U>
8001
- bool operator()(const weak_ptr<T>&, const weak_ptr<U>&) const noexcept;
8002
-
8003
- using is_transparent = unspecified;
8004
- };
8005
- }
8006
- ```
8007
-
8008
- `operator()(x, y)` returns `x.owner_before(y)`.
8009
-
8010
- [*Note 1*:
8011
-
8012
- Note that
8013
-
8014
- - `operator()` defines a strict weak ordering as defined in 
8015
- [[alg.sorting]];
8016
- - under the equivalence relation defined by `operator()`,
8017
- `!operator()(a, b) && !operator()(b, a)`, two `shared_ptr` or
8018
- `weak_ptr` instances are equivalent if and only if they share
8019
- ownership or are both empty.
8020
-
8021
- — *end note*]
8022
-
8023
- ### Class template `enable_shared_from_this` <a id="util.smartptr.enab">[[util.smartptr.enab]]</a>
8024
-
8025
- A class `T` can inherit from `enable_shared_from_this<T>` to inherit the
8026
- `shared_from_this` member functions that obtain a `shared_ptr` instance
8027
- pointing to `*this`.
8028
-
8029
- [*Example 1*:
8030
-
8031
- ``` cpp
8032
- struct X: public enable_shared_from_this<X> { };
8033
-
8034
- int main() {
8035
- shared_ptr<X> p(new X);
8036
- shared_ptr<X> q = p->shared_from_this();
8037
- assert(p == q);
8038
- assert(!p.owner_before(q) && !q.owner_before(p)); // p and q share ownership
8039
- }
8040
- ```
8041
-
8042
- — *end example*]
8043
-
8044
- ``` cpp
8045
- namespace std {
8046
- template<class T> class enable_shared_from_this {
8047
- protected:
8048
- constexpr enable_shared_from_this() noexcept;
8049
- enable_shared_from_this(const enable_shared_from_this&) noexcept;
8050
- enable_shared_from_this& operator=(const enable_shared_from_this&) noexcept;
8051
- ~enable_shared_from_this();
8052
-
8053
- public:
8054
- shared_ptr<T> shared_from_this();
8055
- shared_ptr<T const> shared_from_this() const;
8056
- weak_ptr<T> weak_from_this() noexcept;
8057
- weak_ptr<T const> weak_from_this() const noexcept;
8058
-
8059
- private:
8060
- mutable weak_ptr<T> weak_this; // exposition only
8061
- };
8062
- }
8063
- ```
8064
-
8065
- The template parameter `T` of `enable_shared_from_this` may be an
8066
- incomplete type.
8067
-
8068
- ``` cpp
8069
- constexpr enable_shared_from_this() noexcept;
8070
- enable_shared_from_this(const enable_shared_from_this<T>&) noexcept;
8071
- ```
8072
-
8073
- *Effects:* Value-initializes `weak_this`.
8074
-
8075
- ``` cpp
8076
- enable_shared_from_this<T>& operator=(const enable_shared_from_this<T>&) noexcept;
8077
- ```
8078
-
8079
- *Returns:* `*this`.
8080
-
8081
- [*Note 1*: `weak_this` is not changed. — *end note*]
8082
-
8083
- ``` cpp
8084
- shared_ptr<T> shared_from_this();
8085
- shared_ptr<T const> shared_from_this() const;
8086
- ```
8087
-
8088
- *Returns:* `shared_ptr<T>(weak_this)`.
8089
-
8090
- ``` cpp
8091
- weak_ptr<T> weak_from_this() noexcept;
8092
- weak_ptr<T const> weak_from_this() const noexcept;
8093
- ```
8094
-
8095
- *Returns:* `weak_this`.
8096
-
8097
- ### Smart pointer hash support <a id="util.smartptr.hash">[[util.smartptr.hash]]</a>
8098
-
8099
- ``` cpp
8100
- template<class T, class D> struct hash<unique_ptr<T, D>>;
8101
- ```
8102
-
8103
- Letting `UP` be `unique_ptr<T,D>`, the specialization `hash<UP>` is
8104
- enabled [[unord.hash]] if and only if `hash<typename UP::pointer>` is
8105
- enabled. When enabled, for an object `p` of type `UP`, `hash<UP>()(p)`
8106
- evaluates to the same value as `hash<typename UP::pointer>()(p.get())`.
8107
- The member functions are not guaranteed to be `noexcept`.
8108
-
8109
- ``` cpp
8110
- template<class T> struct hash<shared_ptr<T>>;
8111
- ```
8112
-
8113
- For an object `p` of type `shared_ptr<T>`, `hash<shared_ptr<T>>()(p)`
8114
- evaluates to the same value as
8115
- `hash<typename shared_ptr<T>::element_type*>()(p.get())`.
8116
-
8117
- ## Memory resources <a id="mem.res">[[mem.res]]</a>
8118
-
8119
- ### Header `<memory_resource>` synopsis <a id="mem.res.syn">[[mem.res.syn]]</a>
8120
-
8121
- ``` cpp
8122
- namespace std::pmr {
8123
- // [mem.res.class], class memory_resource
8124
- class memory_resource;
8125
-
8126
- bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
8127
-
8128
- // [mem.poly.allocator.class], class template polymorphic_allocator
8129
- template<class Tp> class polymorphic_allocator;
8130
-
8131
- template<class T1, class T2>
8132
- bool operator==(const polymorphic_allocator<T1>& a,
8133
- const polymorphic_allocator<T2>& b) noexcept;
8134
-
8135
- // [mem.res.global], global memory resources
8136
- memory_resource* new_delete_resource() noexcept;
8137
- memory_resource* null_memory_resource() noexcept;
8138
- memory_resource* set_default_resource(memory_resource* r) noexcept;
8139
- memory_resource* get_default_resource() noexcept;
8140
-
8141
- // [mem.res.pool], pool resource classes
8142
- struct pool_options;
8143
- class synchronized_pool_resource;
8144
- class unsynchronized_pool_resource;
8145
- class monotonic_buffer_resource;
8146
- }
8147
- ```
8148
-
8149
- ### Class `memory_resource` <a id="mem.res.class">[[mem.res.class]]</a>
8150
-
8151
- The `memory_resource` class is an abstract interface to an unbounded set
8152
- of classes encapsulating memory resources.
8153
-
8154
- ``` cpp
8155
- namespace std::pmr {
8156
- class memory_resource {
8157
- static constexpr size_t max_align = alignof(max_align_t); // exposition only
8158
-
8159
- public:
8160
- memory_resource() = default;
8161
- memory_resource(const memory_resource&) = default;
8162
- virtual ~memory_resource();
8163
-
8164
- memory_resource& operator=(const memory_resource&) = default;
8165
-
8166
- [[nodiscard]] void* allocate(size_t bytes, size_t alignment = max_align);
8167
- void deallocate(void* p, size_t bytes, size_t alignment = max_align);
8168
-
8169
- bool is_equal(const memory_resource& other) const noexcept;
8170
-
8171
- private:
8172
- virtual void* do_allocate(size_t bytes, size_t alignment) = 0;
8173
- virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0;
8174
-
8175
- virtual bool do_is_equal(const memory_resource& other) const noexcept = 0;
8176
- };
8177
- }
8178
- ```
8179
-
8180
- #### Public member functions <a id="mem.res.public">[[mem.res.public]]</a>
8181
-
8182
- ``` cpp
8183
- ~memory_resource();
8184
- ```
8185
-
8186
- *Effects:* Destroys this `memory_resource`.
8187
-
8188
- ``` cpp
8189
- [[nodiscard]] void* allocate(size_t bytes, size_t alignment = max_align);
8190
- ```
8191
-
8192
- *Effects:* Equivalent to: `return do_allocate(bytes, alignment);`
8193
-
8194
- ``` cpp
8195
- void deallocate(void* p, size_t bytes, size_t alignment = max_align);
8196
- ```
8197
-
8198
- *Effects:* Equivalent to `do_deallocate(p, bytes, alignment)`.
8199
-
8200
- ``` cpp
8201
- bool is_equal(const memory_resource& other) const noexcept;
8202
- ```
8203
-
8204
- *Effects:* Equivalent to: `return do_is_equal(other);`
8205
-
8206
- #### Private virtual member functions <a id="mem.res.private">[[mem.res.private]]</a>
8207
-
8208
- ``` cpp
8209
- virtual void* do_allocate(size_t bytes, size_t alignment) = 0;
8210
- ```
8211
-
8212
- *Preconditions:* `alignment` is a power of two.
8213
-
8214
- *Returns:* A derived class shall implement this function to return a
8215
- pointer to allocated storage [[basic.stc.dynamic.allocation]] with a
8216
- size of at least `bytes`, aligned to the specified `alignment`.
8217
-
8218
- *Throws:* A derived class implementation shall throw an appropriate
8219
- exception if it is unable to allocate memory with the requested size and
8220
- alignment.
8221
-
8222
- ``` cpp
8223
- virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0;
8224
- ```
8225
-
8226
- *Preconditions:* `p` was returned from a prior call to
8227
- `allocate(bytes, alignment)` on a memory resource equal to `*this`, and
8228
- the storage at `p` has not yet been deallocated.
8229
-
8230
- *Effects:* A derived class shall implement this function to dispose of
8231
- allocated storage.
8232
-
8233
- *Throws:* Nothing.
8234
-
8235
- ``` cpp
8236
- virtual bool do_is_equal(const memory_resource& other) const noexcept = 0;
8237
- ```
8238
-
8239
- *Returns:* A derived class shall implement this function to return
8240
- `true` if memory allocated from `this` can be deallocated from `other`
8241
- and vice-versa, otherwise `false`.
8242
-
8243
- [*Note 1*: The most-derived type of `other` might not match the type of
8244
- `this`. For a derived class `D`, an implementation of this function
8245
- could immediately return `false` if
8246
- `dynamic_cast<const D*>(&other) == nullptr`. — *end note*]
8247
-
8248
- #### Equality <a id="mem.res.eq">[[mem.res.eq]]</a>
8249
-
8250
- ``` cpp
8251
- bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
8252
- ```
8253
-
8254
- *Returns:* `&a == &b || a.is_equal(b)`.
8255
-
8256
- ### Class template `polymorphic_allocator` <a id="mem.poly.allocator.class">[[mem.poly.allocator.class]]</a>
8257
-
8258
- A specialization of class template `pmr::polymorphic_allocator` meets
8259
- the *Cpp17Allocator* requirements ([[cpp17.allocator]]). Constructed
8260
- with different memory resources, different instances of the same
8261
- specialization of `pmr::polymorphic_allocator` can exhibit entirely
8262
- different allocation behavior. This runtime polymorphism allows objects
8263
- that use `polymorphic_allocator` to behave as if they used different
8264
- allocator types at run time even though they use the same static
8265
- allocator type.
8266
-
8267
- All specializations of class template `pmr::polymorphic_allocator` meet
8268
- the allocator completeness requirements
8269
- [[allocator.requirements.completeness]].
8270
-
8271
- ``` cpp
8272
- namespace std::pmr {
8273
- template<class Tp = byte> class polymorphic_allocator {
8274
- memory_resource* memory_rsrc; // exposition only
8275
-
8276
- public:
8277
- using value_type = Tp;
8278
-
8279
- // [mem.poly.allocator.ctor], constructors
8280
- polymorphic_allocator() noexcept;
8281
- polymorphic_allocator(memory_resource* r);
8282
-
8283
- polymorphic_allocator(const polymorphic_allocator& other) = default;
8284
-
8285
- template<class U>
8286
- polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
8287
-
8288
- polymorphic_allocator& operator=(const polymorphic_allocator&) = delete;
8289
-
8290
- // [mem.poly.allocator.mem], member functions
8291
- [[nodiscard]] Tp* allocate(size_t n);
8292
- void deallocate(Tp* p, size_t n);
8293
-
8294
- [[nodiscard]] void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
8295
- void deallocate_bytes(void* p, size_t nbytes, size_t alignment = alignof(max_align_t));
8296
- template<class T> [[nodiscard]] T* allocate_object(size_t n = 1);
8297
- template<class T> void deallocate_object(T* p, size_t n = 1);
8298
- template<class T, class... CtorArgs> [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
8299
- template<class T> void delete_object(T* p);
8300
-
8301
- template<class T, class... Args>
8302
- void construct(T* p, Args&&... args);
8303
-
8304
- template<class T>
8305
- void destroy(T* p);
8306
-
8307
- polymorphic_allocator select_on_container_copy_construction() const;
8308
-
8309
- memory_resource* resource() const;
8310
- };
8311
- }
8312
- ```
8313
-
8314
- #### Constructors <a id="mem.poly.allocator.ctor">[[mem.poly.allocator.ctor]]</a>
8315
-
8316
- ``` cpp
8317
- polymorphic_allocator() noexcept;
8318
- ```
8319
-
8320
- *Effects:* Sets `memory_rsrc` to `get_default_resource()`.
8321
-
8322
- ``` cpp
8323
- polymorphic_allocator(memory_resource* r);
8324
- ```
8325
-
8326
- *Preconditions:* `r` is non-null.
8327
-
8328
- *Effects:* Sets `memory_rsrc` to `r`.
8329
-
8330
- *Throws:* Nothing.
8331
-
8332
- [*Note 1*: This constructor provides an implicit conversion from
8333
- `memory_resource*`. — *end note*]
8334
-
8335
- ``` cpp
8336
- template<class U> polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
8337
- ```
8338
-
8339
- *Effects:* Sets `memory_rsrc` to `other.resource()`.
8340
-
8341
- #### Member functions <a id="mem.poly.allocator.mem">[[mem.poly.allocator.mem]]</a>
8342
-
8343
- ``` cpp
8344
- [[nodiscard]] Tp* allocate(size_t n);
8345
- ```
8346
-
8347
- *Effects:* If `numeric_limits<size_t>::max() / sizeof(Tp) < n`, throws
8348
- `bad_array_new_length`. Otherwise equivalent to:
8349
-
8350
- ``` cpp
8351
- return static_cast<Tp*>(memory_rsrc->allocate(n * sizeof(Tp), alignof(Tp)));
8352
- ```
8353
-
8354
- ``` cpp
8355
- void deallocate(Tp* p, size_t n);
8356
- ```
8357
-
8358
- *Preconditions:* `p` was allocated from a memory resource `x`, equal to
8359
- `*memory_rsrc`, using `x.allocate(n * sizeof(Tp), alignof(Tp))`.
8360
-
8361
- *Effects:* Equivalent to
8362
- `memory_rsrc->deallocate(p, n * sizeof(Tp), alignof(Tp))`.
8363
-
8364
- *Throws:* Nothing.
8365
-
8366
- ``` cpp
8367
- [[nodiscard]] void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
8368
- ```
8369
-
8370
- *Effects:* Equivalent to:
8371
- `return memory_rsrc->allocate(nbytes, alignment);`
8372
-
8373
- [*Note 1*: The return type is `void*` (rather than, e.g., `byte*`) to
8374
- support conversion to an arbitrary pointer type `U*` by
8375
- `static_cast<U*>`, thus facilitating construction of a `U` object in the
8376
- allocated memory. — *end note*]
8377
-
8378
- ``` cpp
8379
- void deallocate_bytes(void* p, size_t nbytes, size_t alignment = alignof(max_align_t));
8380
- ```
8381
-
8382
- *Effects:* Equivalent to
8383
- `memory_rsrc->deallocate(p, nbytes, alignment)`.
8384
-
8385
- ``` cpp
8386
- template<class T>
8387
- [[nodiscard]] T* allocate_object(size_t n = 1);
8388
- ```
8389
-
8390
- *Effects:* Allocates memory suitable for holding an array of `n` objects
8391
- of type `T`, as follows:
8392
-
8393
- - if `numeric_limits<size_t>::max() / sizeof(T) < n`, throws
8394
- `bad_array_new_length`,
8395
- - otherwise equivalent to:
8396
- ``` cpp
8397
- return static_cast<T*>(allocate_bytes(n*sizeof(T), alignof(T)));
8398
- ```
8399
-
8400
- [*Note 2*: `T` is not deduced and must therefore be provided as a
8401
- template argument. — *end note*]
8402
-
8403
- ``` cpp
8404
- template<class T>
8405
- void deallocate_object(T* p, size_t n = 1);
8406
- ```
8407
-
8408
- *Effects:* Equivalent to `deallocate_bytes(p, n*sizeof(T), alignof(T))`.
8409
-
8410
- ``` cpp
8411
- template<class T, class CtorArgs...>
8412
- [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
8413
- ```
8414
-
8415
- *Effects:* Allocates and constructs an object of type `T`, as follows.
8416
- Equivalent to:
8417
-
8418
- ``` cpp
8419
- T* p = allocate_object<T>();
8420
- try {
8421
- construct(p, std::forward<CtorArgs>(ctor_args)...);
8422
- } catch (...) {
8423
- deallocate_object(p);
8424
- throw;
8425
- }
8426
- return p;
8427
- ```
8428
-
8429
- [*Note 3*: `T` is not deduced and must therefore be provided as a
8430
- template argument. — *end note*]
8431
-
8432
- ``` cpp
8433
- template<class T>
8434
- void delete_object(T* p);
8435
- ```
8436
-
8437
- *Effects:* Equivalent to:
8438
-
8439
- ``` cpp
8440
- destroy(p);
8441
- deallocate_object(p);
8442
- ```
8443
-
8444
- ``` cpp
8445
- template<class T, class... Args>
8446
- void construct(T* p, Args&&... args);
8447
- ```
8448
-
8449
- *Mandates:* Uses-allocator construction of `T` with allocator `*this`
8450
- (see  [[allocator.uses.construction]]) and constructor arguments
8451
- `std::forward<Args>(args)...` is well-formed.
8452
-
8453
- *Effects:* Construct a `T` object in the storage whose address is
8454
- represented by `p` by uses-allocator construction with allocator `*this`
8455
- and constructor arguments `std::forward<Args>(args)...`.
8456
-
8457
- *Throws:* Nothing unless the constructor for `T` throws.
8458
-
8459
- ``` cpp
8460
- template<class T>
8461
- void destroy(T* p);
8462
- ```
8463
-
8464
- *Effects:* As if by `p->T̃()`.
8465
-
8466
- ``` cpp
8467
- polymorphic_allocator select_on_container_copy_construction() const;
8468
- ```
8469
-
8470
- *Returns:* `polymorphic_allocator()`.
8471
-
8472
- [*Note 4*: The memory resource is not propagated. — *end note*]
8473
-
8474
- ``` cpp
8475
- memory_resource* resource() const;
8476
- ```
8477
-
8478
- *Returns:* `memory_rsrc`.
8479
-
8480
- #### Equality <a id="mem.poly.allocator.eq">[[mem.poly.allocator.eq]]</a>
8481
-
8482
- ``` cpp
8483
- template<class T1, class T2>
8484
- bool operator==(const polymorphic_allocator<T1>& a,
8485
- const polymorphic_allocator<T2>& b) noexcept;
8486
- ```
8487
-
8488
- *Returns:* `*a.resource() == *b.resource()`.
8489
-
8490
- ### Access to program-wide `memory_resource` objects <a id="mem.res.global">[[mem.res.global]]</a>
8491
-
8492
- ``` cpp
8493
- memory_resource* new_delete_resource() noexcept;
8494
- ```
8495
-
8496
- *Returns:* A pointer to a static-duration object of a type derived from
8497
- `memory_resource` that can serve as a resource for allocating memory
8498
- using `::operator new` and `::operator delete`. The same value is
8499
- returned every time this function is called. For a return value `p` and
8500
- a memory resource `r`, `p->is_equal(r)` returns `&r == p`.
8501
-
8502
- ``` cpp
8503
- memory_resource* null_memory_resource() noexcept;
8504
- ```
8505
-
8506
- *Returns:* A pointer to a static-duration object of a type derived from
8507
- `memory_resource` for which `allocate()` always throws `bad_alloc` and
8508
- for which `deallocate()` has no effect. The same value is returned every
8509
- time this function is called. For a return value `p` and a memory
8510
- resource `r`, `p->is_equal(r)` returns `&r == p`.
8511
-
8512
- The *default memory resource pointer* is a pointer to a memory resource
8513
- that is used by certain facilities when an explicit memory resource is
8514
- not supplied through the interface. Its initial value is the return
8515
- value of `new_delete_resource()`.
8516
-
8517
- ``` cpp
8518
- memory_resource* set_default_resource(memory_resource* r) noexcept;
8519
- ```
8520
-
8521
- *Effects:* If `r` is non-null, sets the value of the default memory
8522
- resource pointer to `r`, otherwise sets the default memory resource
8523
- pointer to `new_delete_resource()`.
8524
-
8525
- *Returns:* The previous value of the default memory resource pointer.
8526
-
8527
- *Remarks:* Calling the `set_default_resource` and `get_default_resource`
8528
- functions shall not incur a data race. A call to the
8529
- `set_default_resource` function shall synchronize with subsequent calls
8530
- to the `set_default_resource` and `get_default_resource` functions.
8531
-
8532
- ``` cpp
8533
- memory_resource* get_default_resource() noexcept;
8534
- ```
8535
-
8536
- *Returns:* The current value of the default memory resource pointer.
8537
-
8538
- ### Pool resource classes <a id="mem.res.pool">[[mem.res.pool]]</a>
8539
-
8540
- #### Classes `synchronized_pool_resource` and `unsynchronized_pool_resource` <a id="mem.res.pool.overview">[[mem.res.pool.overview]]</a>
8541
-
8542
- The `synchronized_pool_resource` and `unsynchronized_pool_resource`
8543
- classes (collectively called *pool resource classes*) are
8544
- general-purpose memory resources having the following qualities:
8545
-
8546
- - Each resource frees its allocated memory on destruction, even if
8547
- `deallocate` has not been called for some of the allocated blocks.
8548
- - A pool resource consists of a collection of *pools*, serving requests
8549
- for different block sizes. Each individual pool manages a collection
8550
- of *chunks* that are in turn divided into blocks of uniform size,
8551
- returned via calls to `do_allocate`. Each call to
8552
- `do_allocate(size, alignment)` is dispatched to the pool serving the
8553
- smallest blocks accommodating at least `size` bytes.
8554
- - When a particular pool is exhausted, allocating a block from that pool
8555
- results in the allocation of an additional chunk of memory from the
8556
- *upstream allocator* (supplied at construction), thus replenishing the
8557
- pool. With each successive replenishment, the chunk size obtained
8558
- increases geometrically. \[*Note 1*: By allocating memory in chunks,
8559
- the pooling strategy increases the chance that consecutive allocations
8560
- will be close together in memory. — *end note*]
8561
- - Allocation requests that exceed the largest block size of any pool are
8562
- fulfilled directly from the upstream allocator.
8563
- - A `pool_options` struct may be passed to the pool resource
8564
- constructors to tune the largest block size and the maximum chunk
8565
- size.
8566
-
8567
- A `synchronized_pool_resource` may be accessed from multiple threads
8568
- without external synchronization and may have thread-specific pools to
8569
- reduce synchronization costs. An `unsynchronized_pool_resource` class
8570
- may not be accessed from multiple threads simultaneously and thus avoids
8571
- the cost of synchronization entirely in single-threaded applications.
8572
-
8573
- ``` cpp
8574
- namespace std::pmr {
8575
- struct pool_options {
8576
- size_t max_blocks_per_chunk = 0;
8577
- size_t largest_required_pool_block = 0;
8578
- };
8579
-
8580
- class synchronized_pool_resource : public memory_resource {
8581
- public:
8582
- synchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
8583
-
8584
- synchronized_pool_resource()
8585
- : synchronized_pool_resource(pool_options(), get_default_resource()) {}
8586
- explicit synchronized_pool_resource(memory_resource* upstream)
8587
- : synchronized_pool_resource(pool_options(), upstream) {}
8588
- explicit synchronized_pool_resource(const pool_options& opts)
8589
- : synchronized_pool_resource(opts, get_default_resource()) {}
8590
-
8591
- synchronized_pool_resource(const synchronized_pool_resource&) = delete;
8592
- virtual ~synchronized_pool_resource();
8593
-
8594
- synchronized_pool_resource& operator=(const synchronized_pool_resource&) = delete;
8595
-
8596
- void release();
8597
- memory_resource* upstream_resource() const;
8598
- pool_options options() const;
8599
-
8600
- protected:
8601
- void* do_allocate(size_t bytes, size_t alignment) override;
8602
- void do_deallocate(void* p, size_t bytes, size_t alignment) override;
8603
-
8604
- bool do_is_equal(const memory_resource& other) const noexcept override;
8605
- };
8606
-
8607
- class unsynchronized_pool_resource : public memory_resource {
8608
- public:
8609
- unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
8610
-
8611
- unsynchronized_pool_resource()
8612
- : unsynchronized_pool_resource(pool_options(), get_default_resource()) {}
8613
- explicit unsynchronized_pool_resource(memory_resource* upstream)
8614
- : unsynchronized_pool_resource(pool_options(), upstream) {}
8615
- explicit unsynchronized_pool_resource(const pool_options& opts)
8616
- : unsynchronized_pool_resource(opts, get_default_resource()) {}
8617
-
8618
- unsynchronized_pool_resource(const unsynchronized_pool_resource&) = delete;
8619
- virtual ~unsynchronized_pool_resource();
8620
-
8621
- unsynchronized_pool_resource& operator=(const unsynchronized_pool_resource&) = delete;
8622
-
8623
- void release();
8624
- memory_resource* upstream_resource() const;
8625
- pool_options options() const;
8626
-
8627
- protected:
8628
- void* do_allocate(size_t bytes, size_t alignment) override;
8629
- void do_deallocate(void* p, size_t bytes, size_t alignment) override;
8630
-
8631
- bool do_is_equal(const memory_resource& other) const noexcept override;
8632
- };
8633
- }
8634
- ```
8635
-
8636
- #### `pool_options` data members <a id="mem.res.pool.options">[[mem.res.pool.options]]</a>
8637
-
8638
- The members of `pool_options` comprise a set of constructor options for
8639
- pool resources. The effect of each option on the pool resource behavior
8640
- is described below:
8641
-
8642
- ``` cpp
8643
- size_t max_blocks_per_chunk;
8644
- ```
8645
-
8646
- The maximum number of blocks that will be allocated at once from the
8647
- upstream memory resource [[mem.res.monotonic.buffer]] to replenish a
8648
- pool. If the value of `max_blocks_per_chunk` is zero or is greater than
8649
- an *implementation-defined* limit, that limit is used instead. The
8650
- implementation may choose to use a smaller value than is specified in
8651
- this field and may use different values for different pools.
8652
-
8653
- ``` cpp
8654
- size_t largest_required_pool_block;
8655
- ```
8656
-
8657
- The largest allocation size that is required to be fulfilled using the
8658
- pooling mechanism. Attempts to allocate a single block larger than this
8659
- threshold will be allocated directly from the upstream memory resource.
8660
- If `largest_required_pool_block` is zero or is greater than an
8661
- *implementation-defined* limit, that limit is used instead. The
8662
- implementation may choose a pass-through threshold larger than specified
8663
- in this field.
8664
-
8665
- #### Constructors and destructors <a id="mem.res.pool.ctor">[[mem.res.pool.ctor]]</a>
8666
-
8667
- ``` cpp
8668
- synchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
8669
- unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
8670
- ```
8671
-
8672
- *Preconditions:* `upstream` is the address of a valid memory resource.
8673
-
8674
- *Effects:* Constructs a pool resource object that will obtain memory
8675
- from `upstream` whenever the pool resource is unable to satisfy a memory
8676
- request from its own internal data structures. The resulting object will
8677
- hold a copy of `upstream`, but will not own the resource to which
8678
- `upstream` points.
8679
-
8680
- [*Note 1*: The intention is that calls to `upstream->allocate()` will
8681
- be substantially fewer than calls to `this->allocate()` in most
8682
- cases. — *end note*]
8683
-
8684
- The behavior of the pooling mechanism is tuned according to the value of
8685
- the `opts` argument.
8686
-
8687
- *Throws:* Nothing unless `upstream->allocate()` throws. It is
8688
- unspecified if, or under what conditions, this constructor calls
8689
- `upstream->allocate()`.
8690
-
8691
- ``` cpp
8692
- virtual ~synchronized_pool_resource();
8693
- virtual ~unsynchronized_pool_resource();
8694
- ```
8695
-
8696
- *Effects:* Calls `release()`.
8697
-
8698
- #### Members <a id="mem.res.pool.mem">[[mem.res.pool.mem]]</a>
8699
-
8700
- ``` cpp
8701
- void release();
8702
- ```
8703
-
8704
- *Effects:* Calls `upstream_resource()->deallocate()` as necessary to
8705
- release all allocated memory.
8706
-
8707
- [*Note 1*: The memory is released back to `upstream_resource()` even if
8708
- `deallocate` has not been called for some of the allocated
8709
- blocks. — *end note*]
8710
-
8711
- ``` cpp
8712
- memory_resource* upstream_resource() const;
8713
- ```
8714
-
8715
- *Returns:* The value of the `upstream` argument provided to the
8716
- constructor of this object.
8717
-
8718
- ``` cpp
8719
- pool_options options() const;
8720
- ```
8721
-
8722
- *Returns:* The options that control the pooling behavior of this
8723
- resource. The values in the returned struct may differ from those
8724
- supplied to the pool resource constructor in that values of zero will be
8725
- replaced with *implementation-defined* defaults, and sizes may be
8726
- rounded to unspecified granularity.
8727
-
8728
- ``` cpp
8729
- void* do_allocate(size_t bytes, size_t alignment) override;
8730
- ```
8731
-
8732
- *Returns:* A pointer to allocated
8733
- storage [[basic.stc.dynamic.allocation]] with a size of at least
8734
- `bytes`. The size and alignment of the allocated memory shall meet the
8735
- requirements for a class derived from `memory_resource`
8736
- [[mem.res.class]].
8737
-
8738
- *Effects:* If the pool selected for a block of size `bytes` is unable to
8739
- satisfy the memory request from its own internal data structures, it
8740
- will call `upstream_resource()->allocate()` to obtain more memory. If
8741
- `bytes` is larger than that which the largest pool can handle, then
8742
- memory will be allocated using `upstream_resource()->allocate()`.
8743
-
8744
- *Throws:* Nothing unless `upstream_resource()->allocate()` throws.
8745
-
8746
- ``` cpp
8747
- void do_deallocate(void* p, size_t bytes, size_t alignment) override;
8748
- ```
8749
-
8750
- *Effects:* Returns the memory at `p` to the pool. It is unspecified if,
8751
- or under what circumstances, this operation will result in a call to
8752
- `upstream_resource()->deallocate()`.
8753
-
8754
- *Throws:* Nothing.
8755
-
8756
- ``` cpp
8757
- bool do_is_equal(const memory_resource& other) const noexcept override;
8758
- ```
8759
-
8760
- *Returns:* `this == &other`.
8761
-
8762
- ### Class `monotonic_buffer_resource` <a id="mem.res.monotonic.buffer">[[mem.res.monotonic.buffer]]</a>
8763
-
8764
- A `monotonic_buffer_resource` is a special-purpose memory resource
8765
- intended for very fast memory allocations in situations where memory is
8766
- used to build up a few objects and then is released all at once when the
8767
- memory resource object is destroyed. It has the following qualities:
8768
-
8769
- - A call to `deallocate` has no effect, thus the amount of memory
8770
- consumed increases monotonically until the resource is destroyed.
8771
- - The program can supply an initial buffer, which the allocator uses to
8772
- satisfy memory requests.
8773
- - When the initial buffer (if any) is exhausted, it obtains additional
8774
- buffers from an *upstream* memory resource supplied at construction.
8775
- Each additional buffer is larger than the previous one, following a
8776
- geometric progression.
8777
- - It is intended for access from one thread of control at a time.
8778
- Specifically, calls to `allocate` and `deallocate` do not synchronize
8779
- with one another.
8780
- - It frees the allocated memory on destruction, even if `deallocate` has
8781
- not been called for some of the allocated blocks.
8782
-
8783
- ``` cpp
8784
- namespace std::pmr {
8785
- class monotonic_buffer_resource : public memory_resource {
8786
- memory_resource* upstream_rsrc; // exposition only
8787
- void* current_buffer; // exposition only
8788
- size_t next_buffer_size; // exposition only
8789
-
8790
- public:
8791
- explicit monotonic_buffer_resource(memory_resource* upstream);
8792
- monotonic_buffer_resource(size_t initial_size, memory_resource* upstream);
8793
- monotonic_buffer_resource(void* buffer, size_t buffer_size, memory_resource* upstream);
8794
-
8795
- monotonic_buffer_resource()
8796
- : monotonic_buffer_resource(get_default_resource()) {}
8797
- explicit monotonic_buffer_resource(size_t initial_size)
8798
- : monotonic_buffer_resource(initial_size, get_default_resource()) {}
8799
- monotonic_buffer_resource(void* buffer, size_t buffer_size)
8800
- : monotonic_buffer_resource(buffer, buffer_size, get_default_resource()) {}
8801
-
8802
- monotonic_buffer_resource(const monotonic_buffer_resource&) = delete;
8803
-
8804
- virtual ~monotonic_buffer_resource();
8805
-
8806
- monotonic_buffer_resource& operator=(const monotonic_buffer_resource&) = delete;
8807
-
8808
- void release();
8809
- memory_resource* upstream_resource() const;
8810
-
8811
- protected:
8812
- void* do_allocate(size_t bytes, size_t alignment) override;
8813
- void do_deallocate(void* p, size_t bytes, size_t alignment) override;
8814
-
8815
- bool do_is_equal(const memory_resource& other) const noexcept override;
8816
- };
8817
- }
8818
- ```
8819
-
8820
- #### Constructors and destructor <a id="mem.res.monotonic.buffer.ctor">[[mem.res.monotonic.buffer.ctor]]</a>
8821
-
8822
- ``` cpp
8823
- explicit monotonic_buffer_resource(memory_resource* upstream);
8824
- monotonic_buffer_resource(size_t initial_size, memory_resource* upstream);
8825
- ```
8826
-
8827
- *Preconditions:* `upstream` is the address of a valid memory resource.
8828
- `initial_size`, if specified, is greater than zero.
8829
-
8830
- *Effects:* Sets `upstream_rsrc` to `upstream` and `current_buffer` to
8831
- `nullptr`. If `initial_size` is specified, sets `next_buffer_size` to at
8832
- least `initial_size`; otherwise sets `next_buffer_size` to an
8833
- *implementation-defined* size.
8834
-
8835
- ``` cpp
8836
- monotonic_buffer_resource(void* buffer, size_t buffer_size, memory_resource* upstream);
8837
- ```
8838
-
8839
- *Preconditions:* `upstream` is the address of a valid memory resource.
8840
- `buffer_size` is no larger than the number of bytes in `buffer`.
8841
-
8842
- *Effects:* Sets `upstream_rsrc` to `upstream`, `current_buffer` to
8843
- `buffer`, and `next_buffer_size` to `buffer_size` (but not less than 1),
8844
- then increases `next_buffer_size` by an *implementation-defined* growth
8845
- factor (which need not be integral).
8846
-
8847
- ``` cpp
8848
- ~monotonic_buffer_resource();
8849
- ```
8850
-
8851
- *Effects:* Calls `release()`.
8852
-
8853
- #### Members <a id="mem.res.monotonic.buffer.mem">[[mem.res.monotonic.buffer.mem]]</a>
8854
-
8855
- ``` cpp
8856
- void release();
8857
- ```
8858
-
8859
- *Effects:* Calls `upstream_rsrc->deallocate()` as necessary to release
8860
- all allocated memory.
8861
-
8862
- [*Note 1*: The memory is released back to `upstream_rsrc` even if some
8863
- blocks that were allocated from `this` have not been deallocated from
8864
- `this`. — *end note*]
8865
-
8866
- ``` cpp
8867
- memory_resource* upstream_resource() const;
8868
- ```
8869
-
8870
- *Returns:* The value of `upstream_rsrc`.
8871
-
8872
- ``` cpp
8873
- void* do_allocate(size_t bytes, size_t alignment) override;
8874
- ```
8875
-
8876
- *Returns:* A pointer to allocated
8877
- storage [[basic.stc.dynamic.allocation]] with a size of at least
8878
- `bytes`. The size and alignment of the allocated memory shall meet the
8879
- requirements for a class derived from `memory_resource`
8880
- [[mem.res.class]].
8881
-
8882
- *Effects:* If the unused space in `current_buffer` can fit a block with
8883
- the specified `bytes` and `alignment`, then allocate the return block
8884
- from `current_buffer`; otherwise set `current_buffer` to
8885
- `upstream_rsrc->allocate(n, m)`, where `n` is not less than
8886
- `max(bytes, next_buffer_size)` and `m` is not less than `alignment`, and
8887
- increase `next_buffer_size` by an *implementation-defined* growth factor
8888
- (which need not be integral), then allocate the return block from the
8889
- newly-allocated `current_buffer`.
8890
-
8891
- *Throws:* Nothing unless `upstream_rsrc->allocate()` throws.
8892
-
8893
- ``` cpp
8894
- void do_deallocate(void* p, size_t bytes, size_t alignment) override;
8895
- ```
8896
-
8897
- *Effects:* None.
8898
-
8899
- *Throws:* Nothing.
8900
-
8901
- *Remarks:* Memory used by this resource increases monotonically until
8902
- its destruction.
8903
-
8904
- ``` cpp
8905
- bool do_is_equal(const memory_resource& other) const noexcept override;
8906
- ```
8907
-
8908
- *Returns:* `this == &other`.
8909
-
8910
- ## Class template `scoped_allocator_adaptor` <a id="allocator.adaptor">[[allocator.adaptor]]</a>
8911
-
8912
- ### Header `<scoped_allocator>` synopsis <a id="allocator.adaptor.syn">[[allocator.adaptor.syn]]</a>
8913
-
8914
- ``` cpp
8915
- namespace std {
8916
- // class template scoped allocator adaptor
8917
- template<class OuterAlloc, class... InnerAlloc>
8918
- class scoped_allocator_adaptor;
8919
-
8920
- // [scoped.adaptor.operators], scoped allocator operators
8921
- template<class OuterA1, class OuterA2, class... InnerAllocs>
8922
- bool operator==(const scoped_allocator_adaptor<OuterA1, InnerAllocs...>& a,
8923
- const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& b) noexcept;
8924
- }
8925
- ```
8926
-
8927
- The class template `scoped_allocator_adaptor` is an allocator template
8928
- that specifies an allocator resource (the outer allocator) to be used by
8929
- a container (as any other allocator does) and also specifies an inner
8930
- allocator resource to be passed to the constructor of every element
8931
- within the container. This adaptor is instantiated with one outer and
8932
- zero or more inner allocator types. If instantiated with only one
8933
- allocator type, the inner allocator becomes the
8934
- `scoped_allocator_adaptor` itself, thus using the same allocator
8935
- resource for the container and every element within the container and,
8936
- if the elements themselves are containers, each of their elements
8937
- recursively. If instantiated with more than one allocator, the first
8938
- allocator is the outer allocator for use by the container, the second
8939
- allocator is passed to the constructors of the container’s elements,
8940
- and, if the elements themselves are containers, the third allocator is
8941
- passed to the elements’ elements, and so on. If containers are nested to
8942
- a depth greater than the number of allocators, the last allocator is
8943
- used repeatedly, as in the single-allocator case, for any remaining
8944
- recursions.
8945
-
8946
- [*Note 1*: The `scoped_allocator_adaptor` is derived from the outer
8947
- allocator type so it can be substituted for the outer allocator type in
8948
- most expressions. — *end note*]
8949
-
8950
- ``` cpp
8951
- namespace std {
8952
- template<class OuterAlloc, class... InnerAllocs>
8953
- class scoped_allocator_adaptor : public OuterAlloc {
8954
- private:
8955
- using OuterTraits = allocator_traits<OuterAlloc>; // exposition only
8956
- scoped_allocator_adaptor<InnerAllocs...> inner; // exposition only
8957
-
8958
- public:
8959
- using outer_allocator_type = OuterAlloc;
8960
- using inner_allocator_type = see below;
8961
-
8962
- using value_type = typename OuterTraits::value_type;
8963
- using size_type = typename OuterTraits::size_type;
8964
- using difference_type = typename OuterTraits::difference_type;
8965
- using pointer = typename OuterTraits::pointer;
8966
- using const_pointer = typename OuterTraits::const_pointer;
8967
- using void_pointer = typename OuterTraits::void_pointer;
8968
- using const_void_pointer = typename OuterTraits::const_void_pointer;
8969
-
8970
- using propagate_on_container_copy_assignment = see below;
8971
- using propagate_on_container_move_assignment = see below;
8972
- using propagate_on_container_swap = see below;
8973
- using is_always_equal = see below;
8974
-
8975
- template<class Tp> struct rebind {
8976
- using other = scoped_allocator_adaptor<
8977
- OuterTraits::template rebind_alloc<Tp>, InnerAllocs...>;
8978
- };
8979
-
8980
- scoped_allocator_adaptor();
8981
- template<class OuterA2>
8982
- scoped_allocator_adaptor(OuterA2&& outerAlloc,
8983
- const InnerAllocs&... innerAllocs) noexcept;
8984
-
8985
- scoped_allocator_adaptor(const scoped_allocator_adaptor& other) noexcept;
8986
- scoped_allocator_adaptor(scoped_allocator_adaptor&& other) noexcept;
8987
-
8988
- template<class OuterA2>
8989
- scoped_allocator_adaptor(
8990
- const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& other) noexcept;
8991
- template<class OuterA2>
8992
- scoped_allocator_adaptor(
8993
- scoped_allocator_adaptor<OuterA2, InnerAllocs...>&& other) noexcept;
8994
-
8995
- scoped_allocator_adaptor& operator=(const scoped_allocator_adaptor&) = default;
8996
- scoped_allocator_adaptor& operator=(scoped_allocator_adaptor&&) = default;
8997
-
8998
- ~scoped_allocator_adaptor();
8999
-
9000
- inner_allocator_type& inner_allocator() noexcept;
9001
- const inner_allocator_type& inner_allocator() const noexcept;
9002
- outer_allocator_type& outer_allocator() noexcept;
9003
- const outer_allocator_type& outer_allocator() const noexcept;
9004
-
9005
- [[nodiscard]] pointer allocate(size_type n);
9006
- [[nodiscard]] pointer allocate(size_type n, const_void_pointer hint);
9007
- void deallocate(pointer p, size_type n);
9008
- size_type max_size() const;
9009
-
9010
- template<class T, class... Args>
9011
- void construct(T* p, Args&&... args);
9012
-
9013
- template<class T>
9014
- void destroy(T* p);
9015
-
9016
- scoped_allocator_adaptor select_on_container_copy_construction() const;
9017
- };
9018
-
9019
- template<class OuterAlloc, class... InnerAllocs>
9020
- scoped_allocator_adaptor(OuterAlloc, InnerAllocs...)
9021
- -> scoped_allocator_adaptor<OuterAlloc, InnerAllocs...>;
9022
- }
9023
- ```
9024
-
9025
- ### Member types <a id="allocator.adaptor.types">[[allocator.adaptor.types]]</a>
9026
-
9027
- ``` cpp
9028
- using inner_allocator_type = see below;
9029
- ```
9030
-
9031
- *Type:* `scoped_allocator_adaptor<OuterAlloc>` if
9032
- `sizeof...(InnerAllocs)` is zero; otherwise,
9033
- `scoped_allocator_adaptor<InnerAllocs...>`.
9034
-
9035
- ``` cpp
9036
- using propagate_on_container_copy_assignment = see below;
9037
- ```
9038
-
9039
- *Type:* `true_type` if
9040
- `allocator_traits<A>::propagate_on_container_copy_assignment::value` is
9041
- `true` for any `A` in the set of `OuterAlloc` and `InnerAllocs...`;
9042
- otherwise, `false_type`.
9043
-
9044
- ``` cpp
9045
- using propagate_on_container_move_assignment = see below;
9046
- ```
9047
-
9048
- *Type:* `true_type` if
9049
- `allocator_traits<A>::propagate_on_container_move_assignment::value` is
9050
- `true` for any `A` in the set of `OuterAlloc` and `InnerAllocs...`;
9051
- otherwise, `false_type`.
9052
-
9053
- ``` cpp
9054
- using propagate_on_container_swap = see below;
9055
- ```
9056
-
9057
- *Type:* `true_type` if
9058
- `allocator_traits<A>::propagate_on_container_swap::value` is `true` for
9059
- any `A` in the set of `OuterAlloc` and `InnerAllocs...`; otherwise,
9060
- `false_type`.
9061
-
9062
- ``` cpp
9063
- using is_always_equal = see below;
9064
- ```
9065
-
9066
- *Type:* `true_type` if `allocator_traits<A>::is_always_equal::value` is
9067
- `true` for every `A` in the set of `OuterAlloc` and `InnerAllocs...`;
9068
- otherwise, `false_type`.
9069
-
9070
- ### Constructors <a id="allocator.adaptor.cnstr">[[allocator.adaptor.cnstr]]</a>
9071
-
9072
- ``` cpp
9073
- scoped_allocator_adaptor();
9074
- ```
9075
-
9076
- *Effects:* Value-initializes the `OuterAlloc` base class and the `inner`
9077
- allocator object.
9078
-
9079
- ``` cpp
9080
- template<class OuterA2>
9081
- scoped_allocator_adaptor(OuterA2&& outerAlloc, const InnerAllocs&... innerAllocs) noexcept;
9082
- ```
9083
-
9084
- *Constraints:* `is_constructible_v<OuterAlloc, OuterA2>` is `true`.
9085
-
9086
- *Effects:* Initializes the `OuterAlloc` base class with
9087
- `std::forward<OuterA2>(outerAlloc)` and `inner` with `innerAllocs...`
9088
- (hence recursively initializing each allocator within the adaptor with
9089
- the corresponding allocator from the argument list).
9090
-
9091
- ``` cpp
9092
- scoped_allocator_adaptor(const scoped_allocator_adaptor& other) noexcept;
9093
- ```
9094
-
9095
- *Effects:* Initializes each allocator within the adaptor with the
9096
- corresponding allocator from `other`.
9097
-
9098
- ``` cpp
9099
- scoped_allocator_adaptor(scoped_allocator_adaptor&& other) noexcept;
9100
- ```
9101
-
9102
- *Effects:* Move constructs each allocator within the adaptor with the
9103
- corresponding allocator from `other`.
9104
-
9105
- ``` cpp
9106
- template<class OuterA2>
9107
- scoped_allocator_adaptor(
9108
- const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& other) noexcept;
9109
- ```
9110
-
9111
- *Constraints:* `is_constructible_v<OuterAlloc, const OuterA2&>` is
9112
- `true`.
9113
-
9114
- *Effects:* Initializes each allocator within the adaptor with the
9115
- corresponding allocator from `other`.
9116
-
9117
- ``` cpp
9118
- template<class OuterA2>
9119
- scoped_allocator_adaptor(scoped_allocator_adaptor<OuterA2, InnerAllocs...>&& other) noexcept;
9120
- ```
9121
-
9122
- *Constraints:* `is_constructible_v<OuterAlloc, OuterA2>` is `true`.
9123
-
9124
- *Effects:* Initializes each allocator within the adaptor with the
9125
- corresponding allocator rvalue from `other`.
9126
-
9127
- ### Members <a id="allocator.adaptor.members">[[allocator.adaptor.members]]</a>
9128
-
9129
- In the `construct` member functions, `OUTERMOST(x)` is
9130
- `OUTERMOST(x.outer_allocator())` if the expression `x.outer_allocator()`
9131
- is valid  [[temp.deduct]] and `x` otherwise; `OUTERMOST_ALLOC_TRAITS(x)`
9132
- is `allocator_traits<remove_reference_t<decltype(OUTERMOST(x))>>`.
9133
-
9134
- [*Note 1*: `OUTERMOST(x)` and `OUTERMOST_ALLOC_TRAITS(x)` are recursive
9135
- operations. It is incumbent upon the definition of `outer_allocator()`
9136
- to ensure that the recursion terminates. It will terminate for all
9137
- instantiations of `scoped_allocator_adaptor`. — *end note*]
9138
-
9139
- ``` cpp
9140
- inner_allocator_type& inner_allocator() noexcept;
9141
- const inner_allocator_type& inner_allocator() const noexcept;
9142
- ```
9143
-
9144
- *Returns:* `*this` if `sizeof...(InnerAllocs)` is zero; otherwise,
9145
- `inner`.
9146
-
9147
- ``` cpp
9148
- outer_allocator_type& outer_allocator() noexcept;
9149
- ```
9150
-
9151
- *Returns:* `static_cast<OuterAlloc&>(*this)`.
9152
-
9153
- ``` cpp
9154
- const outer_allocator_type& outer_allocator() const noexcept;
9155
- ```
9156
-
9157
- *Returns:* `static_cast<const OuterAlloc&>(*this)`.
9158
-
9159
- ``` cpp
9160
- [[nodiscard]] pointer allocate(size_type n);
9161
- ```
9162
-
9163
- *Returns:*
9164
- `allocator_traits<OuterAlloc>::allocate(outer_allocator(), n)`.
9165
-
9166
- ``` cpp
9167
- [[nodiscard]] pointer allocate(size_type n, const_void_pointer hint);
9168
- ```
9169
-
9170
- *Returns:*
9171
- `allocator_traits<OuterAlloc>::allocate(outer_allocator(), n, hint)`.
9172
-
9173
- ``` cpp
9174
- void deallocate(pointer p, size_type n) noexcept;
9175
- ```
9176
-
9177
- *Effects:* As if by:
9178
- `allocator_traits<OuterAlloc>::deallocate(outer_allocator(), p, n);`
9179
-
9180
- ``` cpp
9181
- size_type max_size() const;
9182
- ```
9183
-
9184
- *Returns:* `allocator_traits<OuterAlloc>::max_size(outer_allocator())`.
9185
-
9186
- ``` cpp
9187
- template<class T, class... Args>
9188
- void construct(T* p, Args&&... args);
9189
- ```
9190
-
9191
- *Effects:* Equivalent to:
9192
-
9193
- ``` cpp
9194
- apply([p, this](auto&&... newargs) {
9195
- OUTERMOST_ALLOC_TRAITS(*this)::construct(
9196
- OUTERMOST(*this), p,
9197
- std::forward<decltype(newargs)>(newargs)...);
9198
- },
9199
- uses_allocator_construction_args<T>(inner_allocator(),
9200
- std::forward<Args>(args)...));
9201
- ```
9202
-
9203
- ``` cpp
9204
- template<class T>
9205
- void destroy(T* p);
9206
- ```
9207
-
9208
- *Effects:* Calls
9209
- *OUTERMOST_ALLOC_TRAITS*(\*this)::destroy(*OUTERMOST*(\*this), p).
9210
-
9211
- ``` cpp
9212
- scoped_allocator_adaptor select_on_container_copy_construction() const;
9213
- ```
9214
-
9215
- *Returns:* A new `scoped_allocator_adaptor` object where each allocator
9216
- `A` in the adaptor is initialized from the result of calling
9217
- `allocator_traits<A>::select_on_container_copy_construction()` on the
9218
- corresponding allocator in `*this`.
9219
-
9220
- ### Operators <a id="scoped.adaptor.operators">[[scoped.adaptor.operators]]</a>
9221
-
9222
- ``` cpp
9223
- template<class OuterA1, class OuterA2, class... InnerAllocs>
9224
- bool operator==(const scoped_allocator_adaptor<OuterA1, InnerAllocs...>& a,
9225
- const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& b) noexcept;
9226
- ```
9227
-
9228
- *Returns:* If `sizeof...(InnerAllocs)` is zero,
9229
-
9230
- ``` cpp
9231
- a.outer_allocator() == b.outer_allocator()
9232
- ```
9233
-
9234
- otherwise
9235
-
9236
- ``` cpp
9237
- a.outer_allocator() == b.outer_allocator() && a.inner_allocator() == b.inner_allocator()
9238
- ```
9239
-
9240
  ## Function objects <a id="function.objects">[[function.objects]]</a>
9241
 
9242
- A *function object type* is an object type [[basic.types]] that can be
9243
- the type of the *postfix-expression* in a function call ([[expr.call]],
9244
- [[over.match.call]]).[^2] A *function object* is an object of a function
9245
- object type. In the places where one would expect to pass a pointer to a
9246
- function to an algorithmic template [[algorithms]], the interface is
9247
- specified to accept a function object. This not only makes algorithmic
9248
- templates work with pointers to functions, but also enables them to work
9249
- with arbitrary function objects.
 
 
 
 
9250
 
9251
  ### Header `<functional>` synopsis <a id="functional.syn">[[functional.syn]]</a>
9252
 
9253
  ``` cpp
9254
  namespace std {
9255
  // [func.invoke], invoke
9256
  template<class F, class... Args>
9257
- constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args)
9258
  noexcept(is_nothrow_invocable_v<F, Args...>);
9259
 
 
 
 
 
9260
  // [refwrap], reference_wrapper
9261
- template<class T> class reference_wrapper;
9262
 
9263
- template<class T> constexpr reference_wrapper<T> ref(T&) noexcept;
9264
- template<class T> constexpr reference_wrapper<const T> cref(const T&) noexcept;
9265
- template<class T> void ref(const T&&) = delete;
9266
- template<class T> void cref(const T&&) = delete;
9267
 
9268
- template<class T> constexpr reference_wrapper<T> ref(reference_wrapper<T>) noexcept;
9269
- template<class T> constexpr reference_wrapper<const T> cref(reference_wrapper<T>) noexcept;
 
 
 
 
 
 
 
 
 
 
 
9270
 
9271
  // [arithmetic.operations], arithmetic operations
9272
- template<class T = void> struct plus;
9273
- template<class T = void> struct minus;
9274
- template<class T = void> struct multiplies;
9275
- template<class T = void> struct divides;
9276
- template<class T = void> struct modulus;
9277
- template<class T = void> struct negate;
9278
- template<> struct plus<void>;
9279
- template<> struct minus<void>;
9280
- template<> struct multiplies<void>;
9281
- template<> struct divides<void>;
9282
- template<> struct modulus<void>;
9283
- template<> struct negate<void>;
9284
 
9285
  // [comparisons], comparisons
9286
- template<class T = void> struct equal_to;
9287
- template<class T = void> struct not_equal_to;
9288
- template<class T = void> struct greater;
9289
- template<class T = void> struct less;
9290
- template<class T = void> struct greater_equal;
9291
- template<class T = void> struct less_equal;
9292
- template<> struct equal_to<void>;
9293
- template<> struct not_equal_to<void>;
9294
- template<> struct greater<void>;
9295
- template<> struct less<void>;
9296
- template<> struct greater_equal<void>;
9297
- template<> struct less_equal<void>;
9298
 
9299
  // [comparisons.three.way], class compare_three_way
9300
- struct compare_three_way;
9301
 
9302
  // [logical.operations], logical operations
9303
- template<class T = void> struct logical_and;
9304
- template<class T = void> struct logical_or;
9305
- template<class T = void> struct logical_not;
9306
- template<> struct logical_and<void>;
9307
- template<> struct logical_or<void>;
9308
- template<> struct logical_not<void>;
9309
 
9310
  // [bitwise.operations], bitwise operations
9311
- template<class T = void> struct bit_and;
9312
- template<class T = void> struct bit_or;
9313
- template<class T = void> struct bit_xor;
9314
- template<class T = void> struct bit_not;
9315
- template<> struct bit_and<void>;
9316
- template<> struct bit_or<void>;
9317
- template<> struct bit_xor<void>;
9318
- template<> struct bit_not<void>;
9319
 
9320
  // [func.identity], identity
9321
- struct identity;
9322
 
9323
  // [func.not.fn], function template not_fn
9324
- template<class F> constexpr unspecified not_fn(F&& f);
9325
 
9326
- // [func.bind.front], function template bind_front
9327
- template<class F, class... Args> constexpr unspecified bind_front(F&&, Args&&...);
 
 
 
9328
 
9329
  // [func.bind], bind
9330
- template<class T> struct is_bind_expression;
9331
  template<class T>
9332
- inline constexpr bool is_bind_expression_v = is_bind_expression<T>::value;
9333
- template<class T> struct is_placeholder;
 
9334
  template<class T>
9335
- inline constexpr int is_placeholder_v = is_placeholder<T>::value;
 
9336
 
9337
  template<class F, class... BoundArgs>
9338
- constexpr unspecified bind(F&&, BoundArgs&&...);
9339
  template<class R, class F, class... BoundArgs>
9340
- constexpr unspecified bind(F&&, BoundArgs&&...);
9341
 
9342
  namespace placeholders {
9343
  // M is the implementation-defined number of placeholders
9344
- see belownc _1;
9345
- see belownc _2;
9346
  .
9347
  .
9348
  .
9349
- see belownc _M;
9350
  }
9351
 
9352
  // [func.memfn], member function adaptors
9353
  template<class R, class T>
9354
- constexpr unspecified mem_fn(R T::*) noexcept;
9355
 
9356
  // [func.wrap], polymorphic function wrappers
9357
  class bad_function_call;
9358
 
9359
  template<class> class function; // not defined
9360
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;
9361
 
 
9362
  template<class R, class... ArgTypes>
9363
  void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
9364
 
 
9365
  template<class R, class... ArgTypes>
9366
  bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
9367
 
 
 
 
 
 
9368
  // [func.search], searchers
9369
- template<class ForwardIterator, class BinaryPredicate = equal_to<>>
9370
- class default_searcher;
9371
 
9372
  template<class RandomAccessIterator,
9373
  class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
9374
  class BinaryPredicate = equal_to<>>
9375
  class boyer_moore_searcher;
@@ -9379,20 +7467,20 @@ namespace std {
9379
  class BinaryPredicate = equal_to<>>
9380
  class boyer_moore_horspool_searcher;
9381
 
9382
  // [unord.hash], class template hash
9383
  template<class T>
9384
- struct hash;
9385
 
9386
  namespace ranges {
9387
  // [range.cmp], concept-constrained comparisons
9388
- struct equal_to;
9389
- struct not_equal_to;
9390
- struct greater;
9391
- struct less;
9392
- struct greater_equal;
9393
- struct less_equal;
9394
  }
9395
  }
9396
  ```
9397
 
9398
  [*Example 1*:
@@ -9445,35 +7533,38 @@ collectively referred to as *state entities*.
9445
  ### Requirements <a id="func.require">[[func.require]]</a>
9446
 
9447
  Define `INVOKE(f, t₁, t₂, …, t_N)` as follows:
9448
 
9449
  - `(t₁.*f)(t₂, …, t_N)` when `f` is a pointer to a member function of a
9450
- class `T` and `is_base_of_v<T, remove_reference_t<decltype(t₁)>>` is
9451
- `true`;
9452
  - `(t₁.get().*f)(t₂, …, t_N)` when `f` is a pointer to a member function
9453
  of a class `T` and `remove_cvref_t<decltype(t₁)>` is a specialization
9454
  of `reference_wrapper`;
9455
  - `((*t₁).*f)(t₂, …, t_N)` when `f` is a pointer to a member function of
9456
  a class `T` and `t₁` does not satisfy the previous two items;
9457
- - `t₁.*f` when `N == 1` and `f` is a pointer to data member of a class
9458
- `T` and `is_base_of_v<T, remove_reference_t<decltype(t₁)>>` is `true`;
9459
- - `t₁.get().*f` when `N == 1` and `f` is a pointer to data member of a
 
9460
  class `T` and `remove_cvref_t<decltype(t₁)>` is a specialization of
9461
  `reference_wrapper`;
9462
- - `(*t₁).*f` when `N == 1` and `f` is a pointer to data member of a
9463
- class `T` and `t₁` does not satisfy the previous two items;
9464
  - `f(t₁, t₂, …, t_N)` in all other cases.
9465
 
9466
  Define `INVOKE<R>(f, t₁, t₂, …, t_N)` as
9467
  `static_cast<void>(INVOKE(f, t₁, t₂, …, t_N))` if `R` is cv `void`,
9468
- otherwise `INVOKE(f, t₁, t₂, …, t_N)` implicitly converted to `R`.
 
 
9469
 
9470
  Every call wrapper [[func.def]] meets the *Cpp17MoveConstructible* and
9471
  *Cpp17Destructible* requirements. An *argument forwarding call wrapper*
9472
  is a call wrapper that can be called with an arbitrary argument list and
9473
- delivers the arguments to the wrapped callable object as references.
9474
- This forwarding step delivers rvalue arguments as rvalue references and
9475
  lvalue arguments as lvalue references.
9476
 
9477
  [*Note 1*:
9478
 
9479
  In a typical implementation, argument forwarding call wrappers have an
@@ -9494,11 +7585,11 @@ and as cv `T&&` otherwise, where cv represents the cv-qualifiers of the
9494
  call wrapper and where cv shall be neither `volatile` nor
9495
  `const volatile`.
9496
 
9497
  A *call pattern* defines the semantics of invoking a perfect forwarding
9498
  call wrapper. A postfix call performed on a perfect forwarding call
9499
- wrapper is expression-equivalent [[defns.expression-equivalent]] to an
9500
  expression `e` determined from its call pattern `cp` by replacing all
9501
  occurrences of the arguments of the call wrapper and its state entities
9502
  with references as described in the corresponding forwarding steps.
9503
 
9504
  A *simple call wrapper* is a perfect forwarding call wrapper that meets
@@ -9517,61 +7608,79 @@ would be considered to be constexpr. — *end note*]
9517
 
9518
  Argument forwarding call wrappers returned by a given standard library
9519
  function template have the same type if the types of their corresponding
9520
  state entities are the same.
9521
 
9522
- ### Function template `invoke` <a id="func.invoke">[[func.invoke]]</a>
9523
 
9524
  ``` cpp
9525
  template<class F, class... Args>
9526
  constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args)
9527
  noexcept(is_nothrow_invocable_v<F, Args...>);
9528
  ```
9529
 
 
 
9530
  *Returns:* *INVOKE*(std::forward\<F\>(f),
9531
  std::forward\<Args\>(args)...) [[func.require]].
9532
 
 
 
 
 
 
 
 
 
 
 
 
9533
  ### Class template `reference_wrapper` <a id="refwrap">[[refwrap]]</a>
9534
 
 
 
9535
  ``` cpp
9536
  namespace std {
9537
  template<class T> class reference_wrapper {
9538
  public:
9539
  // types
9540
  using type = T;
9541
 
9542
- // construct/copy/destroy
9543
  template<class U>
9544
  constexpr reference_wrapper(U&&) noexcept(see below);
9545
  constexpr reference_wrapper(const reference_wrapper& x) noexcept;
9546
 
9547
- // assignment
9548
  constexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept;
9549
 
9550
- // access
9551
  constexpr operator T& () const noexcept;
9552
  constexpr T& get() const noexcept;
9553
 
9554
- // invocation
9555
  template<class... ArgTypes>
9556
- constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) const;
 
9557
  };
 
9558
  template<class T>
9559
  reference_wrapper(T&) -> reference_wrapper<T>;
9560
  }
9561
  ```
9562
 
9563
  `reference_wrapper<T>` is a *Cpp17CopyConstructible* and
9564
  *Cpp17CopyAssignable* wrapper around a reference to an object or
9565
  function of type `T`.
9566
 
9567
- `reference_wrapper<T>` is a trivially copyable type [[basic.types]].
 
9568
 
9569
  The template parameter `T` of `reference_wrapper` may be an incomplete
9570
  type.
9571
 
9572
- #### Constructors and destructor <a id="refwrap.const">[[refwrap.const]]</a>
9573
 
9574
  ``` cpp
9575
  template<class U>
9576
  constexpr reference_wrapper(U&& u) noexcept(see below);
9577
  ```
@@ -9588,11 +7697,11 @@ void FUN(T&&) = delete;
9588
 
9589
  *Effects:* Creates a variable `r` as if by `T& r = std::forward<U>(u)`,
9590
  then constructs a `reference_wrapper` object that stores a reference to
9591
  `r`.
9592
 
9593
- *Remarks:* The expression inside `noexcept` is equivalent to
9594
  `noexcept(`*`FUN`*`(declval<U>()))`.
9595
 
9596
  ``` cpp
9597
  constexpr reference_wrapper(const reference_wrapper& x) noexcept;
9598
  ```
@@ -9625,11 +7734,11 @@ constexpr T& get() const noexcept;
9625
  #### Invocation <a id="refwrap.invoke">[[refwrap.invoke]]</a>
9626
 
9627
  ``` cpp
9628
  template<class... ArgTypes>
9629
  constexpr invoke_result_t<T&, ArgTypes...>
9630
- operator()(ArgTypes&&... args) const;
9631
  ```
9632
 
9633
  *Mandates:* `T` is a complete type.
9634
 
9635
  *Returns:* *INVOKE*(get(),
@@ -9648,11 +7757,11 @@ template<class T> constexpr reference_wrapper<T> ref(T& t) noexcept;
9648
 
9649
  ``` cpp
9650
  template<class T> constexpr reference_wrapper<T> ref(reference_wrapper<T> t) noexcept;
9651
  ```
9652
 
9653
- *Returns:* `ref(t.get())`.
9654
 
9655
  ``` cpp
9656
  template<class T> constexpr reference_wrapper<const T> cref(const T& t) noexcept;
9657
  ```
9658
 
@@ -9660,16 +7769,50 @@ template<class T> constexpr reference_wrapper<const T> cref(const T& t) noexcept
9660
 
9661
  ``` cpp
9662
  template<class T> constexpr reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
9663
  ```
9664
 
9665
- *Returns:* `cref(t.get())`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9666
 
9667
  ### Arithmetic operations <a id="arithmetic.operations">[[arithmetic.operations]]</a>
9668
 
 
 
9669
  The library provides basic function object classes for all of the
9670
- arithmetic operators in the language ([[expr.mul]], [[expr.add]]).
9671
 
9672
  #### Class template `plus` <a id="arithmetic.operations.plus">[[arithmetic.operations.plus]]</a>
9673
 
9674
  ``` cpp
9675
  template<class T = void> struct plus {
@@ -9849,12 +7992,14 @@ template<class T> constexpr auto operator()(T&& t) const
9849
 
9850
  *Returns:* `-std::forward<T>(t)`.
9851
 
9852
  ### Comparisons <a id="comparisons">[[comparisons]]</a>
9853
 
 
 
9854
  The library provides basic function object classes for all of the
9855
- comparison operators in the language ([[expr.rel]], [[expr.eq]]).
9856
 
9857
  For templates `less`, `greater`, `less_equal`, and `greater_equal`, the
9858
  specializations for any pointer type yield a result consistent with the
9859
  implementation-defined strict total order over pointers
9860
  [[defns.order.ptr]].
@@ -10049,41 +8194,34 @@ template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
10049
 
10050
  *Returns:* `std::forward<T>(t) <= std::forward<U>(u)`.
10051
 
10052
  #### Class `compare_three_way` <a id="comparisons.three.way">[[comparisons.three.way]]</a>
10053
 
10054
- In this subclause, `BUILTIN-PTR-THREE-WAY(T, U)` for types `T` and `U`
10055
- is a boolean constant expression. `BUILTIN-PTR-THREE-WAY(T, U)` is
10056
- `true` if and only if `<=>` in the expression
10057
-
10058
- ``` cpp
10059
- declval<T>() <=> declval<U>()
10060
- ```
10061
-
10062
- resolves to a built-in operator comparing pointers.
10063
-
10064
  ``` cpp
 
10065
  struct compare_three_way {
10066
  template<class T, class U>
10067
- requires three_way_comparable_with<T, U> || BUILTIN-PTR-THREE-WAY(T, U)
10068
  constexpr auto operator()(T&& t, U&& u) const;
10069
 
10070
  using is_transparent = unspecified;
10071
  };
 
10072
  ```
10073
 
10074
  ``` cpp
10075
  template<class T, class U>
10076
- requires three_way_comparable_with<T, U> || BUILTIN-PTR-THREE-WAY(T, U)
10077
  constexpr auto operator()(T&& t, U&& u) const;
10078
  ```
10079
 
 
 
10080
  *Preconditions:* If the expression
10081
  `std::forward<T>(t) <=> std::forward<U>(u)` results in a call to a
10082
  built-in operator `<=>` comparing pointers of type `P`, the conversion
10083
  sequences from both `T` and `U` to `P` are
10084
- equality-preserving [[concepts.equality]].
 
10085
 
10086
  *Effects:*
10087
 
10088
  - If the expression `std::forward<T>(t) <=> std::forward<U>(u)` results
10089
  in a call to a built-in operator `<=>` comparing pointers of type `P`,
@@ -10094,31 +8232,32 @@ equality-preserving [[concepts.equality]].
10094
  - Otherwise, equivalent to:
10095
  `return std::forward<T>(t) <=> std::forward<U>(u);`
10096
 
10097
  ### Concept-constrained comparisons <a id="range.cmp">[[range.cmp]]</a>
10098
 
10099
- In this subclause, `BUILTIN-PTR-CMP(T, op, U)` for types `T` and `U` and
10100
- where op is an equality [[expr.eq]] or relational operator [[expr.rel]]
10101
- is a boolean constant expression. `BUILTIN-PTR-CMP(T, op, U)` is `true`
10102
- if and only if op in the expression `declval<T>() op declval<U>()`
10103
- resolves to a built-in operator comparing pointers.
10104
-
10105
  ``` cpp
10106
  struct ranges::equal_to {
10107
  template<class T, class U>
10108
- requires equality_comparable_with<T, U> || BUILTIN-PTR-CMP(T, ==, U)
10109
  constexpr bool operator()(T&& t, U&& u) const;
10110
 
10111
  using is_transparent = unspecified;
10112
  };
10113
  ```
10114
 
 
 
 
 
 
 
 
10115
  *Preconditions:* If the expression
10116
  `std::forward<T>(t) == std::forward<U>(u)` results in a call to a
10117
  built-in operator `==` comparing pointers of type `P`, the conversion
10118
  sequences from both `T` and `U` to `P` are
10119
- equality-preserving [[concepts.equality]].
 
10120
 
10121
  *Effects:*
10122
 
10123
  - If the expression `std::forward<T>(t) == std::forward<U>(u)` results
10124
  in a call to a built-in operator `==` comparing pointers: returns
@@ -10129,56 +8268,75 @@ equality-preserving [[concepts.equality]].
10129
  `return std::forward<T>(t) == std::forward<U>(u);`
10130
 
10131
  ``` cpp
10132
  struct ranges::not_equal_to {
10133
  template<class T, class U>
10134
- requires equality_comparable_with<T, U> || BUILTIN-PTR-CMP(T, ==, U)
10135
  constexpr bool operator()(T&& t, U&& u) const;
10136
 
10137
  using is_transparent = unspecified;
10138
  };
10139
  ```
10140
 
10141
- `operator()` has effects equivalent to:
 
 
 
 
 
 
 
10142
 
10143
  ``` cpp
10144
  return !ranges::equal_to{}(std::forward<T>(t), std::forward<U>(u));
10145
  ```
10146
 
10147
  ``` cpp
10148
  struct ranges::greater {
10149
  template<class T, class U>
10150
- requires totally_ordered_with<T, U> || BUILTIN-PTR-CMP(U, <, T)
10151
  constexpr bool operator()(T&& t, U&& u) const;
10152
 
10153
  using is_transparent = unspecified;
10154
  };
10155
  ```
10156
 
10157
- `operator()` has effects equivalent to:
 
 
 
 
 
 
 
10158
 
10159
  ``` cpp
10160
  return ranges::less{}(std::forward<U>(u), std::forward<T>(t));
10161
  ```
10162
 
10163
  ``` cpp
10164
  struct ranges::less {
10165
  template<class T, class U>
10166
- requires totally_ordered_with<T, U> || BUILTIN-PTR-CMP(T, <, U)
10167
  constexpr bool operator()(T&& t, U&& u) const;
10168
 
10169
  using is_transparent = unspecified;
10170
  };
10171
  ```
10172
 
 
 
 
 
 
 
 
10173
  *Preconditions:* If the expression
10174
  `std::forward<T>(t) < std::forward<U>(u)` results in a call to a
10175
  built-in operator `<` comparing pointers of type `P`, the conversion
10176
  sequences from both `T` and `U` to `P` are
10177
- equality-preserving [[concepts.equality]]. For any expressions `ET` and
10178
- `EU` such that `decltype((ET))` is `T` and `decltype((EU))` is `U`,
10179
- exactly one of `ranges::less{}(ET, EU)`, `ranges::less{}(EU, ET)`, or
 
10180
  `ranges::equal_to{}(ET, EU)` is `true`.
10181
 
10182
  *Effects:*
10183
 
10184
  - If the expression `std::forward<T>(t) < std::forward<U>(u)` results in
@@ -10190,44 +8348,58 @@ exactly one of `ranges::less{}(ET, EU)`, `ranges::less{}(EU, ET)`, or
10190
  `return std::forward<T>(t) < std::forward<U>(u);`
10191
 
10192
  ``` cpp
10193
  struct ranges::greater_equal {
10194
  template<class T, class U>
10195
- requires totally_ordered_with<T, U> || BUILTIN-PTR-CMP(T, <, U)
10196
  constexpr bool operator()(T&& t, U&& u) const;
10197
 
10198
  using is_transparent = unspecified;
10199
  };
10200
  ```
10201
 
10202
- `operator()` has effects equivalent to:
 
 
 
 
 
 
 
10203
 
10204
  ``` cpp
10205
  return !ranges::less{}(std::forward<T>(t), std::forward<U>(u));
10206
  ```
10207
 
10208
  ``` cpp
10209
  struct ranges::less_equal {
10210
  template<class T, class U>
10211
- requires totally_ordered_with<T, U> || BUILTIN-PTR-CMP(U, <, T)
10212
  constexpr bool operator()(T&& t, U&& u) const;
10213
 
10214
  using is_transparent = unspecified;
10215
  };
10216
  ```
10217
 
10218
- `operator()` has effects equivalent to:
 
 
 
 
 
 
 
10219
 
10220
  ``` cpp
10221
  return !ranges::less{}(std::forward<U>(u), std::forward<T>(t));
10222
  ```
10223
 
10224
  ### Logical operations <a id="logical.operations">[[logical.operations]]</a>
10225
 
 
 
10226
  The library provides basic function object classes for all of the
10227
- logical operators in the language ([[expr.log.and]], [[expr.log.or]],
10228
- [[expr.unary.op]]).
10229
 
10230
  #### Class template `logical_and` <a id="logical.operations.and">[[logical.operations.and]]</a>
10231
 
10232
  ``` cpp
10233
  template<class T = void> struct logical_and {
@@ -10317,13 +8489,15 @@ template<class T> constexpr auto operator()(T&& t) const
10317
 
10318
  *Returns:* `!std::forward<T>(t)`.
10319
 
10320
  ### Bitwise operations <a id="bitwise.operations">[[bitwise.operations]]</a>
10321
 
 
 
10322
  The library provides basic function object classes for all of the
10323
- bitwise operators in the language ([[expr.bit.and]], [[expr.or]],
10324
- [[expr.xor]], [[expr.unary.op]]).
10325
 
10326
  #### Class template `bit_and` <a id="bitwise.operations.and">[[bitwise.operations.and]]</a>
10327
 
10328
  ``` cpp
10329
  template<class T = void> struct bit_and {
@@ -10435,11 +8609,11 @@ template<> struct bit_not<void> {
10435
  using is_transparent = unspecified;
10436
  };
10437
  ```
10438
 
10439
  ``` cpp
10440
- template<class T> constexpr auto operator()(T&&) const
10441
  -> decltype(~std::forward<T>(t));
10442
  ```
10443
 
10444
  *Returns:* `~std::forward<T>(t)`.
10445
 
@@ -10477,25 +8651,29 @@ In the text that follows:
10477
  *Mandates:* `is_constructible_v<FD, F> && is_move_constructible_v<FD>`
10478
  is `true`.
10479
 
10480
  *Preconditions:* `FD` meets the *Cpp17MoveConstructible* requirements.
10481
 
10482
- *Returns:* A perfect forwarding call wrapper `g` with call pattern
 
10483
  `!invoke(fd, call_args...)`.
10484
 
10485
  *Throws:* Any exception thrown by the initialization of `fd`.
10486
 
10487
- ### Function template `bind_front` <a id="func.bind.front">[[func.bind.front]]</a>
10488
 
10489
  ``` cpp
10490
  template<class F, class... Args>
10491
  constexpr unspecified bind_front(F&& f, Args&&... args);
 
 
10492
  ```
10493
 
10494
- In the text that follows:
10495
 
10496
- - `g` is a value of the result of a `bind_front` invocation,
 
10497
  - `FD` is the type `decay_t<F>`,
10498
  - `fd` is the target object of `g` [[func.def]] of type `FD`,
10499
  direct-non-list-initialized with `std::forward<F>(f)`,
10500
  - `BoundArgs` is a pack that denotes `decay_t<Args>...`,
10501
  - `bound_args` is a pack of bound argument entities of `g` [[func.def]]
@@ -10517,20 +8695,27 @@ is `true`.
10517
 
10518
  *Preconditions:* `FD` meets the *Cpp17MoveConstructible* requirements.
10519
  For each `Tᵢ` in `BoundArgs`, if `Tᵢ` is an object type, `Tᵢ` meets the
10520
  *Cpp17MoveConstructible* requirements.
10521
 
10522
- *Returns:* A perfect forwarding call wrapper `g` with call pattern
10523
- `invoke(fd, bound_args..., call_args...)`.
 
 
 
 
 
10524
 
10525
  *Throws:* Any exception thrown by the initialization of the state
10526
  entities of `g` [[func.def]].
10527
 
10528
  ### Function object binders <a id="func.bind">[[func.bind]]</a>
10529
 
10530
- This subclause describes a uniform mechanism for binding arguments of
10531
- callable objects.
 
 
10532
 
10533
  #### Class template `is_bind_expression` <a id="func.bind.isbind">[[func.bind.isbind]]</a>
10534
 
10535
  ``` cpp
10536
  namespace std {
@@ -10558,12 +8743,12 @@ namespace std {
10558
  template<class T> struct is_placeholder; // see below
10559
  }
10560
  ```
10561
 
10562
  The class template `is_placeholder` can be used to detect the standard
10563
- placeholders `_1`, `_2`, and so on. The function template `bind` uses
10564
- `is_placeholder` to detect placeholders.
10565
 
10566
  Specializations of the `is_placeholder` template shall meet the
10567
  *Cpp17UnaryTypeTrait* requirements [[meta.rqmts]]. The implementation
10568
  provides a definition that has the base characteristic of
10569
  `integral_constant<int, J>` if `T` is the type of
@@ -10607,11 +8792,11 @@ $w_N$) [[func.require]] is a valid expression for some values `w₁`,
10607
 
10608
  *Returns:* An argument forwarding call wrapper `g` [[func.require]]. A
10609
  program that attempts to invoke a volatile-qualified `g` is ill-formed.
10610
  When `g` is not volatile-qualified, invocation of
10611
  `g(``u₁``, ``u₂``, `…`, ``u_M``)` is
10612
- expression-equivalent [[defns.expression-equivalent]] to
10613
 
10614
  ``` cpp
10615
  INVOKE(static_cast<$V_fd$>($v_fd$),
10616
  static_cast<$V_1$>($v_1$), static_cast<$V_2$>($v_2$), …, static_cast<$V_N$>($v_N$))
10617
  ```
@@ -10656,20 +8841,22 @@ type `V`_`fd` is `cv FD&`.
10656
 
10657
  #### Placeholders <a id="func.bind.place">[[func.bind.place]]</a>
10658
 
10659
  ``` cpp
10660
  namespace std::placeholders {
10661
- // M is the implementation-defined number of placeholders
10662
  see below _1;
10663
  see below _2;
10664
  .
10665
  .
10666
  .
10667
  see below _M;
10668
  }
10669
  ```
10670
 
 
 
10671
  All placeholder types meet the *Cpp17DefaultConstructible* and
10672
  *Cpp17CopyConstructible* requirements, and their default constructors
10673
  and copy/move constructors are constexpr functions that do not throw
10674
  exceptions. It is *implementation-defined* whether placeholder types
10675
  meet the *Cpp17CopyAssignable* requirements, but if so, their copy
@@ -10686,26 +8873,30 @@ If they are not, they are declared as:
10686
 
10687
  ``` cpp
10688
  extern unspecified _1;
10689
  ```
10690
 
 
 
10691
  ### Function template `mem_fn` <a id="func.memfn">[[func.memfn]]</a>
10692
 
10693
  ``` cpp
10694
  template<class R, class T> constexpr unspecified mem_fn(R T::* pm) noexcept;
10695
  ```
10696
 
10697
- *Returns:* A simple call wrapper [[func.def]] `fn` with call pattern
10698
- `invoke(pmd, call_args...)`, where `pmd` is the target object of `fn` of
10699
- type `R T::*` direct-non-list-initialized with `pm`, and `call_args` is
10700
- an argument pack used in a function call expression [[expr.call]] of
10701
- `pm`.
10702
 
10703
  ### Polymorphic function wrappers <a id="func.wrap">[[func.wrap]]</a>
10704
 
10705
- This subclause describes a polymorphic wrapper class that encapsulates
10706
- arbitrary callable objects.
 
 
10707
 
10708
  #### Class `bad_function_call` <a id="func.wrap.badcall">[[func.wrap.badcall]]</a>
10709
 
10710
  An exception of type `bad_function_call` is thrown by
10711
  `function::operator()` [[func.wrap.func.inv]] when the function wrapper
@@ -10727,10 +8918,12 @@ const char* what() const noexcept override;
10727
 
10728
  *Returns:* An *implementation-defined* NTBS.
10729
 
10730
  #### Class template `function` <a id="func.wrap.func">[[func.wrap.func]]</a>
10731
 
 
 
10732
  ``` cpp
10733
  namespace std {
10734
  template<class> class function; // not defined
10735
 
10736
  template<class R, class... ArgTypes>
@@ -10741,11 +8934,11 @@ namespace std {
10741
  // [func.wrap.func.con], construct/copy/destroy
10742
  function() noexcept;
10743
  function(nullptr_t) noexcept;
10744
  function(const function&);
10745
  function(function&&) noexcept;
10746
- template<class F> function(F);
10747
 
10748
  function& operator=(const function&);
10749
  function& operator=(function&&);
10750
  function& operator=(nullptr_t) noexcept;
10751
  template<class F> function& operator=(F&&);
@@ -10770,36 +8963,29 @@ namespace std {
10770
 
10771
  template<class R, class... ArgTypes>
10772
  function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;
10773
 
10774
  template<class F> function(F) -> function<see below>;
10775
-
10776
- // [func.wrap.func.nullptr], null pointer comparison functions
10777
- template<class R, class... ArgTypes>
10778
- bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
10779
-
10780
- // [func.wrap.func.alg], specialized algorithms
10781
- template<class R, class... ArgTypes>
10782
- void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
10783
  }
10784
  ```
10785
 
10786
  The `function` class template provides polymorphic wrappers that
10787
  generalize the notion of a function pointer. Wrappers can store, copy,
10788
  and call arbitrary callable objects [[func.def]], given a call signature
10789
- [[func.def]], allowing functions to be first-class objects.
10790
 
10791
  A callable type [[func.def]] `F` is *Lvalue-Callable* for argument types
10792
  `ArgTypes` and return type `R` if the expression
10793
  `INVOKE<R>(declval<F&>(), declval<ArgTypes>()...)`, considered as an
10794
- unevaluated operand [[expr.prop]], is well-formed [[func.require]].
 
10795
 
10796
  The `function` class template is a call wrapper [[func.def]] whose call
10797
  signature [[func.def]] is `R(ArgTypes...)`.
10798
 
10799
- [*Note 1*: The types deduced by the deduction guides for `function` may
10800
- change in future versions of this International Standard. — *end note*]
10801
 
10802
  ##### Constructors and destructor <a id="func.wrap.func.con">[[func.wrap.func.con]]</a>
10803
 
10804
  ``` cpp
10805
  function() noexcept;
@@ -10815,70 +9001,87 @@ function(nullptr_t) noexcept;
10815
 
10816
  ``` cpp
10817
  function(const function& f);
10818
  ```
10819
 
10820
- *Ensures:* `!*this` if `!f`; otherwise, `*this` targets a copy of
10821
- `f.target()`.
10822
 
10823
  *Throws:* Nothing if `f`’s target is a specialization of
10824
  `reference_wrapper` or a function pointer. Otherwise, may throw
10825
  `bad_alloc` or any exception thrown by the copy constructor of the
10826
  stored callable object.
10827
 
10828
- [*Note 1*: Implementations should avoid the use of dynamically
10829
- allocated memory for small callable objects, for example, where `f`’s
10830
- target is an object holding only a pointer or reference to an object and
10831
- a member function pointer. — *end note*]
10832
 
10833
  ``` cpp
10834
  function(function&& f) noexcept;
10835
  ```
10836
 
10837
  *Ensures:* If `!f`, `*this` has no target; otherwise, the target of
10838
  `*this` is equivalent to the target of `f` before the construction, and
10839
  `f` is in a valid state with an unspecified value.
10840
 
10841
- [*Note 2*: Implementations should avoid the use of dynamically
10842
- allocated memory for small callable objects, for example, where `f`’s
10843
- target is an object holding only a pointer or reference to an object and
10844
- a member function pointer. — *end note*]
10845
 
10846
  ``` cpp
10847
- template<class F> function(F f);
10848
  ```
10849
 
10850
- *Constraints:* `F` is Lvalue-Callable [[func.wrap.func]] for argument
10851
- types `ArgTypes...` and return type `R`.
10852
 
10853
- *Preconditions:* `F` meets the *Cpp17CopyConstructible* requirements.
10854
 
10855
- *Ensures:* `!*this` if any of the following hold:
 
 
 
 
 
 
 
 
 
 
 
10856
 
10857
  - `f` is a null function pointer value.
10858
  - `f` is a null member pointer value.
10859
- - `F` is an instance of the `function` class template, and `!f`.
 
10860
 
10861
- Otherwise, `*this` targets a copy of `f` initialized with
10862
- `std::move(f)`.
10863
 
10864
- [*Note 3*: Implementations should avoid the use of dynamically
10865
- allocated memory for small callable objects, for example, where `f` is
10866
- an object holding only a pointer or reference to an object and a member
10867
- function pointer. — *end note*]
10868
 
10869
- *Throws:* Nothing if `f` is a specialization of `reference_wrapper` or a
10870
- function pointer. Otherwise, may throw `bad_alloc` or any exception
10871
- thrown by `F`’s copy or move constructor.
 
10872
 
10873
  ``` cpp
10874
  template<class F> function(F) -> function<see below>;
10875
  ```
10876
 
10877
  *Constraints:* `&F::operator()` is well-formed when treated as an
10878
- unevaluated operand and `decltype(&F::operator())` is of the form
10879
- `R(G::*)(A...)` cv \\ₒₚₜ ` `noexceptₒₚₜ for a class type `G`.
 
 
 
 
 
 
10880
 
10881
  *Remarks:* The deduced type is `function<R(A...)>`.
10882
 
10883
  [*Example 1*:
10884
 
@@ -10946,11 +9149,11 @@ template<class F> function& operator=(reference_wrapper<F> f) noexcept;
10946
 
10947
  ``` cpp
10948
  void swap(function& other) noexcept;
10949
  ```
10950
 
10951
- *Effects:* Interchanges the targets of `*this` and `other`.
10952
 
10953
  ##### Capacity <a id="func.wrap.func.cap">[[func.wrap.func.cap]]</a>
10954
 
10955
  ``` cpp
10956
  explicit operator bool() const noexcept;
@@ -10967,11 +9170,11 @@ R operator()(ArgTypes... args) const;
10967
  *Returns:* *INVOKE*\<R\>(f,
10968
  std::forward\<ArgTypes\>(args)...) [[func.require]], where `f` is the
10969
  target object [[func.def]] of `*this`.
10970
 
10971
  *Throws:* `bad_function_call` if `!*this`; otherwise, any exception
10972
- thrown by the wrapped callable object.
10973
 
10974
  ##### Target access <a id="func.wrap.func.targ">[[func.wrap.func.targ]]</a>
10975
 
10976
  ``` cpp
10977
  const type_info& target_type() const noexcept;
@@ -10986,11 +9189,11 @@ template<class T> const T* target() const noexcept;
10986
  ```
10987
 
10988
  *Returns:* If `target_type() == typeid(T)` a pointer to the stored
10989
  function target; otherwise a null pointer.
10990
 
10991
- ##### Null pointer comparison functions <a id="func.wrap.func.nullptr">[[func.wrap.func.nullptr]]</a>
10992
 
10993
  ``` cpp
10994
  template<class R, class... ArgTypes>
10995
  bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
10996
  ```
@@ -11004,33 +9207,302 @@ template<class R, class... ArgTypes>
11004
  void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
11005
  ```
11006
 
11007
  *Effects:* As if by: `f1.swap(f2);`
11008
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11009
  ### Searchers <a id="func.search">[[func.search]]</a>
11010
 
11011
- This subclause provides function object types [[function.objects]] for
11012
- operations that search for a sequence \[`pat``first`, `pat_last`) in
11013
- another sequence \[`first`, `last`) that is provided to the object’s
11014
- function call operator. The first sequence (the pattern to be searched
11015
- for) is provided to the object’s constructor, and the second (the
11016
- sequence to be searched) is provided to the function call operator.
11017
 
11018
- Each specialization of a class template specified in this subclause
11019
- [[func.search]] shall meet the *Cpp17CopyConstructible* and
11020
- *Cpp17CopyAssignable* requirements. Template parameters named
 
 
 
 
 
 
 
 
11021
 
11022
  - `ForwardIterator`,
11023
  - `ForwardIterator1`,
11024
  - `ForwardIterator2`,
11025
  - `RandomAccessIterator`,
11026
  - `RandomAccessIterator1`,
11027
  - `RandomAccessIterator2`, and
11028
  - `BinaryPredicate`
11029
 
11030
- of templates specified in this subclause [[func.search]] shall meet the
11031
- same requirements and semantics as specified in [[algorithms.general]].
11032
  Template parameters named `Hash` shall meet the *Cpp17Hash* requirements
11033
  ([[cpp17.hash]]).
11034
 
11035
  The Boyer-Moore searcher implements the Boyer-Moore search algorithm.
11036
  The Boyer-Moore-Horspool searcher implements the Boyer-Moore-Horspool
@@ -11038,10 +9510,11 @@ search algorithm. In general, the Boyer-Moore searcher will use more
11038
  memory and give better runtime performance than Boyer-Moore-Horspool.
11039
 
11040
  #### Class template `default_searcher` <a id="func.search.default">[[func.search.default]]</a>
11041
 
11042
  ``` cpp
 
11043
  template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
11044
  class default_searcher {
11045
  public:
11046
  constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
11047
  BinaryPredicate pred = BinaryPredicate());
@@ -11053,14 +9526,15 @@ template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
11053
  private:
11054
  ForwardIterator1 pat_first_; // exposition only
11055
  ForwardIterator1 pat_last_; // exposition only
11056
  BinaryPredicate pred_; // exposition only
11057
  };
 
11058
  ```
11059
 
11060
  ``` cpp
11061
- constexpr default_searcher(ForwardIterator pat_first, ForwardIterator pat_last,
11062
  BinaryPredicate pred = BinaryPredicate());
11063
  ```
11064
 
11065
  *Effects:* Constructs a `default_searcher` object, initializing
11066
  `pat_first_` with `pat_first`, \texttt{pat_last\_} with `pat_last`, and
@@ -11082,10 +9556,11 @@ template<class ForwardIterator2>
11082
  `j == next(i, distance(pat_first_, pat_last_))`.
11083
 
11084
  #### Class template `boyer_moore_searcher` <a id="func.search.bm">[[func.search.bm]]</a>
11085
 
11086
  ``` cpp
 
11087
  template<class RandomAccessIterator1,
11088
  class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
11089
  class BinaryPredicate = equal_to<>>
11090
  class boyer_moore_searcher {
11091
  public:
@@ -11102,30 +9577,30 @@ template<class RandomAccessIterator1,
11102
  RandomAccessIterator1 pat_first_; // exposition only
11103
  RandomAccessIterator1 pat_last_; // exposition only
11104
  Hash hash_; // exposition only
11105
  BinaryPredicate pred_; // exposition only
11106
  };
 
11107
  ```
11108
 
11109
  ``` cpp
11110
  boyer_moore_searcher(RandomAccessIterator1 pat_first,
11111
  RandomAccessIterator1 pat_last,
11112
  Hash hf = Hash(),
11113
  BinaryPredicate pred = BinaryPredicate());
11114
  ```
11115
 
11116
  *Preconditions:* The value type of `RandomAccessIterator1` meets the
11117
- *Cpp17DefaultConstructible* requirements, the *Cpp17CopyConstructible*
11118
- requirements, and the *Cpp17CopyAssignable* requirements.
11119
 
11120
- *Preconditions:* Let `V` be
11121
- `iterator_traits<RandomAccessIterator1>::value_type`. For any two values
11122
- `A` and `B` of type `V`, if `pred(A, B) == true`, then `hf(A) == hf(B)`
11123
- is `true`.
11124
 
11125
  *Effects:* Initializes `pat_first_` with `pat_first`, `pat_last_` with
11126
- `pat_last`, `hash_` with `hf`, and `pred_` with `pred`.
11127
 
11128
  *Throws:* Any exception thrown by the copy constructor of
11129
  `RandomAccessIterator1`, or by the default constructor, copy
11130
  constructor, or the copy assignment operator of the value type of
11131
  `RandomAccessIterator1`, or the copy constructor or `operator()` of
@@ -11159,10 +9634,11 @@ found.
11159
  applications of the predicate.
11160
 
11161
  #### Class template `boyer_moore_horspool_searcher` <a id="func.search.bmh">[[func.search.bmh]]</a>
11162
 
11163
  ``` cpp
 
11164
  template<class RandomAccessIterator1,
11165
  class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
11166
  class BinaryPredicate = equal_to<>>
11167
  class boyer_moore_horspool_searcher {
11168
  public:
@@ -11179,10 +9655,11 @@ template<class RandomAccessIterator1,
11179
  RandomAccessIterator1 pat_first_; // exposition only
11180
  RandomAccessIterator1 pat_last_; // exposition only
11181
  Hash hash_; // exposition only
11182
  BinaryPredicate pred_; // exposition only
11183
  };
 
11184
  ```
11185
 
11186
  ``` cpp
11187
  boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first,
11188
  RandomAccessIterator1 pat_last,
@@ -11192,22 +9669,21 @@ boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first,
11192
 
11193
  *Preconditions:* The value type of `RandomAccessIterator1` meets the
11194
  *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*, and
11195
  *Cpp17CopyAssignable* requirements.
11196
 
11197
- *Preconditions:* Let `V` be
11198
- `iterator_traits<RandomAccessIterator1>::value_type`. For any two values
11199
- `A` and `B` of type `V`, if `pred(A, B) == true`, then `hf(A) == hf(B)`
11200
- is `true`.
11201
 
11202
  *Effects:* Initializes `pat_first_` with `pat_first`, `pat_last_` with
11203
- `pat_last`, `hash_` with `hf`, and `pred_` with `pred`.
11204
 
11205
  *Throws:* Any exception thrown by the copy constructor of
11206
  `RandomAccessIterator1`, or by the default constructor, copy
11207
  constructor, or the copy assignment operator of the value type of
11208
- `RandomAccessIterator1` or the copy constructor or `operator()` of
11209
  `BinaryPredicate` or `Hash`. May throw `bad_alloc` if additional memory
11210
  needed for internal data structures cannot be allocated.
11211
 
11212
  ``` cpp
11213
  template<class RandomAccessIterator2>
@@ -11220,11 +9696,11 @@ same value type.
11220
 
11221
  *Effects:* Finds a subsequence of equal values in a sequence.
11222
 
11223
  *Returns:* A pair of iterators `i` and `j` such that
11224
 
11225
- - `i` is the first iterator `i` in the range \[`first`,
11226
  `last - (pat_last_ - pat_first_)`) such that for every non-negative
11227
  integer `n` less than `pat_last_ - pat_first_` the following condition
11228
  holds: `pred(*(i + n), *(pat_first_ + n)) != false`, and
11229
  - `j == next(i, distance(pat_first_, pat_last_))`.
11230
 
@@ -11269,1365 +9745,19 @@ attempts to use it as a *Cpp17Hash* will be ill-formed. — *end note*]
11269
  An enabled specialization `hash<Key>` will:
11270
 
11271
  - meet the *Cpp17Hash* requirements ([[cpp17.hash]]), with `Key` as the
11272
  function call argument type, the *Cpp17DefaultConstructible*
11273
  requirements ([[cpp17.defaultconstructible]]), the
11274
- *Cpp17CopyAssignable* requirements ([[cpp17.copyassignable]]),
11275
- - be swappable [[swappable.requirements]] for lvalues,
11276
  - meet the requirement that if `k1 == k2` is `true`, `h(k1) == h(k2)` is
11277
  also `true`, where `h` is an object of type `hash<Key>` and `k1` and
11278
  `k2` are objects of type `Key`;
11279
  - meet the requirement that the expression `h(k)`, where `h` is an
11280
  object of type `hash<Key>` and `k` is an object of type `Key`, shall
11281
  not throw an exception unless `hash<Key>` is a program-defined
11282
- specialization that depends on at least one program-defined type.
11283
-
11284
- ## Metaprogramming and type traits <a id="meta">[[meta]]</a>
11285
-
11286
- This subclause describes components used by C++ programs, particularly
11287
- in templates, to support the widest possible range of types, optimise
11288
- template code usage, detect type related user errors, and perform type
11289
- inference and transformation at compile time. It includes type
11290
- classification traits, type property inspection traits, and type
11291
- transformations. The type classification traits describe a complete
11292
- taxonomy of all possible C++ types, and state where in that taxonomy a
11293
- given type belongs. The type property inspection traits allow important
11294
- characteristics of types or of combinations of types to be inspected.
11295
- The type transformations allow certain properties of types to be
11296
- manipulated.
11297
-
11298
- All functions specified in this subclause are signal-safe
11299
- [[support.signal]].
11300
-
11301
- ### Requirements <a id="meta.rqmts">[[meta.rqmts]]</a>
11302
-
11303
- A describes a property of a type. It shall be a class template that
11304
- takes one template type argument and, optionally, additional arguments
11305
- that help define the property being described. It shall be
11306
- *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*, and publicly and
11307
- unambiguously derived, directly or indirectly, from its *base
11308
- characteristic*, which is a specialization of the template
11309
- `integral_constant` [[meta.help]], with the arguments to the template
11310
- `integral_constant` determined by the requirements for the particular
11311
- property being described. The member names of the base characteristic
11312
- shall not be hidden and shall be unambiguously available in the
11313
- *Cpp17UnaryTypeTrait*.
11314
-
11315
- A describes a relationship between two types. It shall be a class
11316
- template that takes two template type arguments and, optionally,
11317
- additional arguments that help define the relationship being described.
11318
- It shall be *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*, and
11319
- publicly and unambiguously derived, directly or indirectly, from its
11320
- *base characteristic*, which is a specialization of the template
11321
- `integral_constant` [[meta.help]], with the arguments to the template
11322
- `integral_constant` determined by the requirements for the particular
11323
- relationship being described. The member names of the base
11324
- characteristic shall not be hidden and shall be unambiguously available
11325
- in the *Cpp17BinaryTypeTrait*.
11326
-
11327
- A modifies a property of a type. It shall be a class template that takes
11328
- one template type argument and, optionally, additional arguments that
11329
- help define the modification. It shall define a publicly accessible
11330
- nested type named `type`, which shall be a synonym for the modified
11331
- type.
11332
-
11333
- Unless otherwise specified, the behavior of a program that adds
11334
- specializations for any of the templates specified in this subclause 
11335
- [[meta]] is undefined.
11336
-
11337
- Unless otherwise specified, an incomplete type may be used to
11338
- instantiate a template specified in this subclause. The behavior of a
11339
- program is undefined if:
11340
-
11341
- - an instantiation of a template specified in subclause  [[meta]]
11342
- directly or indirectly depends on an incompletely-defined object type
11343
- `T`, and
11344
- - that instantiation could yield a different result were `T`
11345
- hypothetically completed.
11346
-
11347
- ### Header `<type_traits>` synopsis <a id="meta.type.synop">[[meta.type.synop]]</a>
11348
-
11349
- ``` cpp
11350
- namespace std {
11351
- // [meta.help], helper class
11352
- template<class T, T v> struct integral_constant;
11353
-
11354
- template<bool B>
11355
- using bool_constant = integral_constant<bool, B>;
11356
- using true_type = bool_constant<true>;
11357
- using false_type = bool_constant<false>;
11358
-
11359
- // [meta.unary.cat], primary type categories
11360
- template<class T> struct is_void;
11361
- template<class T> struct is_null_pointer;
11362
- template<class T> struct is_integral;
11363
- template<class T> struct is_floating_point;
11364
- template<class T> struct is_array;
11365
- template<class T> struct is_pointer;
11366
- template<class T> struct is_lvalue_reference;
11367
- template<class T> struct is_rvalue_reference;
11368
- template<class T> struct is_member_object_pointer;
11369
- template<class T> struct is_member_function_pointer;
11370
- template<class T> struct is_enum;
11371
- template<class T> struct is_union;
11372
- template<class T> struct is_class;
11373
- template<class T> struct is_function;
11374
-
11375
- // [meta.unary.comp], composite type categories
11376
- template<class T> struct is_reference;
11377
- template<class T> struct is_arithmetic;
11378
- template<class T> struct is_fundamental;
11379
- template<class T> struct is_object;
11380
- template<class T> struct is_scalar;
11381
- template<class T> struct is_compound;
11382
- template<class T> struct is_member_pointer;
11383
-
11384
- // [meta.unary.prop], type properties
11385
- template<class T> struct is_const;
11386
- template<class T> struct is_volatile;
11387
- template<class T> struct is_trivial;
11388
- template<class T> struct is_trivially_copyable;
11389
- template<class T> struct is_standard_layout;
11390
- template<class T> struct is_empty;
11391
- template<class T> struct is_polymorphic;
11392
- template<class T> struct is_abstract;
11393
- template<class T> struct is_final;
11394
- template<class T> struct is_aggregate;
11395
-
11396
- template<class T> struct is_signed;
11397
- template<class T> struct is_unsigned;
11398
- template<class T> struct is_bounded_array;
11399
- template<class T> struct is_unbounded_array;
11400
-
11401
- template<class T, class... Args> struct is_constructible;
11402
- template<class T> struct is_default_constructible;
11403
- template<class T> struct is_copy_constructible;
11404
- template<class T> struct is_move_constructible;
11405
-
11406
- template<class T, class U> struct is_assignable;
11407
- template<class T> struct is_copy_assignable;
11408
- template<class T> struct is_move_assignable;
11409
-
11410
- template<class T, class U> struct is_swappable_with;
11411
- template<class T> struct is_swappable;
11412
-
11413
- template<class T> struct is_destructible;
11414
-
11415
- template<class T, class... Args> struct is_trivially_constructible;
11416
- template<class T> struct is_trivially_default_constructible;
11417
- template<class T> struct is_trivially_copy_constructible;
11418
- template<class T> struct is_trivially_move_constructible;
11419
-
11420
- template<class T, class U> struct is_trivially_assignable;
11421
- template<class T> struct is_trivially_copy_assignable;
11422
- template<class T> struct is_trivially_move_assignable;
11423
- template<class T> struct is_trivially_destructible;
11424
-
11425
- template<class T, class... Args> struct is_nothrow_constructible;
11426
- template<class T> struct is_nothrow_default_constructible;
11427
- template<class T> struct is_nothrow_copy_constructible;
11428
- template<class T> struct is_nothrow_move_constructible;
11429
-
11430
- template<class T, class U> struct is_nothrow_assignable;
11431
- template<class T> struct is_nothrow_copy_assignable;
11432
- template<class T> struct is_nothrow_move_assignable;
11433
-
11434
- template<class T, class U> struct is_nothrow_swappable_with;
11435
- template<class T> struct is_nothrow_swappable;
11436
-
11437
- template<class T> struct is_nothrow_destructible;
11438
-
11439
- template<class T> struct has_virtual_destructor;
11440
-
11441
- template<class T> struct has_unique_object_representations;
11442
-
11443
- // [meta.unary.prop.query], type property queries
11444
- template<class T> struct alignment_of;
11445
- template<class T> struct rank;
11446
- template<class T, unsigned I = 0> struct extent;
11447
-
11448
- // [meta.rel], type relations
11449
- template<class T, class U> struct is_same;
11450
- template<class Base, class Derived> struct is_base_of;
11451
- template<class From, class To> struct is_convertible;
11452
- template<class From, class To> struct is_nothrow_convertible;
11453
- template<class T, class U> struct is_layout_compatible;
11454
- template<class Base, class Derived> struct is_pointer_interconvertible_base_of;
11455
-
11456
- template<class Fn, class... ArgTypes> struct is_invocable;
11457
- template<class R, class Fn, class... ArgTypes> struct is_invocable_r;
11458
-
11459
- template<class Fn, class... ArgTypes> struct is_nothrow_invocable;
11460
- template<class R, class Fn, class... ArgTypes> struct is_nothrow_invocable_r;
11461
-
11462
- // [meta.trans.cv], const-volatile modifications
11463
- template<class T> struct remove_const;
11464
- template<class T> struct remove_volatile;
11465
- template<class T> struct remove_cv;
11466
- template<class T> struct add_const;
11467
- template<class T> struct add_volatile;
11468
- template<class T> struct add_cv;
11469
-
11470
- template<class T>
11471
- using remove_const_t = typename remove_const<T>::type;
11472
- template<class T>
11473
- using remove_volatile_t = typename remove_volatile<T>::type;
11474
- template<class T>
11475
- using remove_cv_t = typename remove_cv<T>::type;
11476
- template<class T>
11477
- using add_const_t = typename add_const<T>::type;
11478
- template<class T>
11479
- using add_volatile_t = typename add_volatile<T>::type;
11480
- template<class T>
11481
- using add_cv_t = typename add_cv<T>::type;
11482
-
11483
- // [meta.trans.ref], reference modifications
11484
- template<class T> struct remove_reference;
11485
- template<class T> struct add_lvalue_reference;
11486
- template<class T> struct add_rvalue_reference;
11487
-
11488
- template<class T>
11489
- using remove_reference_t = typename remove_reference<T>::type;
11490
- template<class T>
11491
- using add_lvalue_reference_t = typename add_lvalue_reference<T>::type;
11492
- template<class T>
11493
- using add_rvalue_reference_t = typename add_rvalue_reference<T>::type;
11494
-
11495
- // [meta.trans.sign], sign modifications
11496
- template<class T> struct make_signed;
11497
- template<class T> struct make_unsigned;
11498
-
11499
- template<class T>
11500
- using make_signed_t = typename make_signed<T>::type;
11501
- template<class T>
11502
- using make_unsigned_t = typename make_unsigned<T>::type;
11503
-
11504
- // [meta.trans.arr], array modifications
11505
- template<class T> struct remove_extent;
11506
- template<class T> struct remove_all_extents;
11507
-
11508
- template<class T>
11509
- using remove_extent_t = typename remove_extent<T>::type;
11510
- template<class T>
11511
- using remove_all_extents_t = typename remove_all_extents<T>::type;
11512
-
11513
- // [meta.trans.ptr], pointer modifications
11514
- template<class T> struct remove_pointer;
11515
- template<class T> struct add_pointer;
11516
-
11517
- template<class T>
11518
- using remove_pointer_t = typename remove_pointer<T>::type;
11519
- template<class T>
11520
- using add_pointer_t = typename add_pointer<T>::type;
11521
-
11522
- // [meta.trans.other], other transformations
11523
- template<class T> struct type_identity;
11524
- template<size_t Len, size_t Align = default-alignment> // see [meta.trans.other]
11525
- struct aligned_storage;
11526
- template<size_t Len, class... Types> struct aligned_union;
11527
- template<class T> struct remove_cvref;
11528
- template<class T> struct decay;
11529
- template<bool, class T = void> struct enable_if;
11530
- template<bool, class T, class F> struct conditional;
11531
- template<class... T> struct common_type;
11532
- template<class T, class U, template<class> class TQual, template<class> class UQual>
11533
- struct basic_common_reference { };
11534
- template<class... T> struct common_reference;
11535
- template<class T> struct underlying_type;
11536
- template<class Fn, class... ArgTypes> struct invoke_result;
11537
- template<class T> struct unwrap_reference;
11538
- template<class T> struct unwrap_ref_decay;
11539
-
11540
- template<class T>
11541
- using type_identity_t = typename type_identity<T>::type;
11542
- template<size_t Len, size_t Align = default-alignment> // see [meta.trans.other]
11543
- using aligned_storage_t = typename aligned_storage<Len, Align>::type;
11544
- template<size_t Len, class... Types>
11545
- using aligned_union_t = typename aligned_union<Len, Types...>::type;
11546
- template<class T>
11547
- using remove_cvref_t = typename remove_cvref<T>::type;
11548
- template<class T>
11549
- using decay_t = typename decay<T>::type;
11550
- template<bool b, class T = void>
11551
- using enable_if_t = typename enable_if<b, T>::type;
11552
- template<bool b, class T, class F>
11553
- using conditional_t = typename conditional<b, T, F>::type;
11554
- template<class... T>
11555
- using common_type_t = typename common_type<T...>::type;
11556
- template<class... T>
11557
- using common_reference_t = typename common_reference<T...>::type;
11558
- template<class T>
11559
- using underlying_type_t = typename underlying_type<T>::type;
11560
- template<class Fn, class... ArgTypes>
11561
- using invoke_result_t = typename invoke_result<Fn, ArgTypes...>::type;
11562
- template<class T>
11563
- using unwrap_reference_t = typename unwrap_reference<T>::type;
11564
- template<class T>
11565
- using unwrap_ref_decay_t = typename unwrap_ref_decay<T>::type;
11566
- template<class...>
11567
- using void_t = void;
11568
-
11569
- // [meta.logical], logical operator traits
11570
- template<class... B> struct conjunction;
11571
- template<class... B> struct disjunction;
11572
- template<class B> struct negation;
11573
-
11574
- // [meta.unary.cat], primary type categories
11575
- template<class T>
11576
- inline constexpr bool is_void_v = is_void<T>::value;
11577
- template<class T>
11578
- inline constexpr bool is_null_pointer_v = is_null_pointer<T>::value;
11579
- template<class T>
11580
- inline constexpr bool is_integral_v = is_integral<T>::value;
11581
- template<class T>
11582
- inline constexpr bool is_floating_point_v = is_floating_point<T>::value;
11583
- template<class T>
11584
- inline constexpr bool is_array_v = is_array<T>::value;
11585
- template<class T>
11586
- inline constexpr bool is_pointer_v = is_pointer<T>::value;
11587
- template<class T>
11588
- inline constexpr bool is_lvalue_reference_v = is_lvalue_reference<T>::value;
11589
- template<class T>
11590
- inline constexpr bool is_rvalue_reference_v = is_rvalue_reference<T>::value;
11591
- template<class T>
11592
- inline constexpr bool is_member_object_pointer_v = is_member_object_pointer<T>::value;
11593
- template<class T>
11594
- inline constexpr bool is_member_function_pointer_v = is_member_function_pointer<T>::value;
11595
- template<class T>
11596
- inline constexpr bool is_enum_v = is_enum<T>::value;
11597
- template<class T>
11598
- inline constexpr bool is_union_v = is_union<T>::value;
11599
- template<class T>
11600
- inline constexpr bool is_class_v = is_class<T>::value;
11601
- template<class T>
11602
- inline constexpr bool is_function_v = is_function<T>::value;
11603
-
11604
- // [meta.unary.comp], composite type categories
11605
- template<class T>
11606
- inline constexpr bool is_reference_v = is_reference<T>::value;
11607
- template<class T>
11608
- inline constexpr bool is_arithmetic_v = is_arithmetic<T>::value;
11609
- template<class T>
11610
- inline constexpr bool is_fundamental_v = is_fundamental<T>::value;
11611
- template<class T>
11612
- inline constexpr bool is_object_v = is_object<T>::value;
11613
- template<class T>
11614
- inline constexpr bool is_scalar_v = is_scalar<T>::value;
11615
- template<class T>
11616
- inline constexpr bool is_compound_v = is_compound<T>::value;
11617
- template<class T>
11618
- inline constexpr bool is_member_pointer_v = is_member_pointer<T>::value;
11619
-
11620
- // [meta.unary.prop], type properties
11621
- template<class T>
11622
- inline constexpr bool is_const_v = is_const<T>::value;
11623
- template<class T>
11624
- inline constexpr bool is_volatile_v = is_volatile<T>::value;
11625
- template<class T>
11626
- inline constexpr bool is_trivial_v = is_trivial<T>::value;
11627
- template<class T>
11628
- inline constexpr bool is_trivially_copyable_v = is_trivially_copyable<T>::value;
11629
- template<class T>
11630
- inline constexpr bool is_standard_layout_v = is_standard_layout<T>::value;
11631
- template<class T>
11632
- inline constexpr bool is_empty_v = is_empty<T>::value;
11633
- template<class T>
11634
- inline constexpr bool is_polymorphic_v = is_polymorphic<T>::value;
11635
- template<class T>
11636
- inline constexpr bool is_abstract_v = is_abstract<T>::value;
11637
- template<class T>
11638
- inline constexpr bool is_final_v = is_final<T>::value;
11639
- template<class T>
11640
- inline constexpr bool is_aggregate_v = is_aggregate<T>::value;
11641
- template<class T>
11642
- inline constexpr bool is_signed_v = is_signed<T>::value;
11643
- template<class T>
11644
- inline constexpr bool is_unsigned_v = is_unsigned<T>::value;
11645
- template<class T>
11646
- inline constexpr bool is_bounded_array_v = is_bounded_array<T>::value;
11647
- template<class T>
11648
- inline constexpr bool is_unbounded_array_v = is_unbounded_array<T>::value;
11649
- template<class T, class... Args>
11650
- inline constexpr bool is_constructible_v = is_constructible<T, Args...>::value;
11651
- template<class T>
11652
- inline constexpr bool is_default_constructible_v = is_default_constructible<T>::value;
11653
- template<class T>
11654
- inline constexpr bool is_copy_constructible_v = is_copy_constructible<T>::value;
11655
- template<class T>
11656
- inline constexpr bool is_move_constructible_v = is_move_constructible<T>::value;
11657
- template<class T, class U>
11658
- inline constexpr bool is_assignable_v = is_assignable<T, U>::value;
11659
- template<class T>
11660
- inline constexpr bool is_copy_assignable_v = is_copy_assignable<T>::value;
11661
- template<class T>
11662
- inline constexpr bool is_move_assignable_v = is_move_assignable<T>::value;
11663
- template<class T, class U>
11664
- inline constexpr bool is_swappable_with_v = is_swappable_with<T, U>::value;
11665
- template<class T>
11666
- inline constexpr bool is_swappable_v = is_swappable<T>::value;
11667
- template<class T>
11668
- inline constexpr bool is_destructible_v = is_destructible<T>::value;
11669
- template<class T, class... Args>
11670
- inline constexpr bool is_trivially_constructible_v
11671
- = is_trivially_constructible<T, Args...>::value;
11672
- template<class T>
11673
- inline constexpr bool is_trivially_default_constructible_v
11674
- = is_trivially_default_constructible<T>::value;
11675
- template<class T>
11676
- inline constexpr bool is_trivially_copy_constructible_v
11677
- = is_trivially_copy_constructible<T>::value;
11678
- template<class T>
11679
- inline constexpr bool is_trivially_move_constructible_v
11680
- = is_trivially_move_constructible<T>::value;
11681
- template<class T, class U>
11682
- inline constexpr bool is_trivially_assignable_v = is_trivially_assignable<T, U>::value;
11683
- template<class T>
11684
- inline constexpr bool is_trivially_copy_assignable_v
11685
- = is_trivially_copy_assignable<T>::value;
11686
- template<class T>
11687
- inline constexpr bool is_trivially_move_assignable_v
11688
- = is_trivially_move_assignable<T>::value;
11689
- template<class T>
11690
- inline constexpr bool is_trivially_destructible_v = is_trivially_destructible<T>::value;
11691
- template<class T, class... Args>
11692
- inline constexpr bool is_nothrow_constructible_v
11693
- = is_nothrow_constructible<T, Args...>::value;
11694
- template<class T>
11695
- inline constexpr bool is_nothrow_default_constructible_v
11696
- = is_nothrow_default_constructible<T>::value;
11697
- template<class T>
11698
- inline constexpr bool is_nothrow_copy_constructible_v
11699
- = is_nothrow_copy_constructible<T>::value;
11700
- template<class T>
11701
- inline constexpr bool is_nothrow_move_constructible_v
11702
- = is_nothrow_move_constructible<T>::value;
11703
- template<class T, class U>
11704
- inline constexpr bool is_nothrow_assignable_v = is_nothrow_assignable<T, U>::value;
11705
- template<class T>
11706
- inline constexpr bool is_nothrow_copy_assignable_v = is_nothrow_copy_assignable<T>::value;
11707
- template<class T>
11708
- inline constexpr bool is_nothrow_move_assignable_v = is_nothrow_move_assignable<T>::value;
11709
- template<class T, class U>
11710
- inline constexpr bool is_nothrow_swappable_with_v = is_nothrow_swappable_with<T, U>::value;
11711
- template<class T>
11712
- inline constexpr bool is_nothrow_swappable_v = is_nothrow_swappable<T>::value;
11713
- template<class T>
11714
- inline constexpr bool is_nothrow_destructible_v = is_nothrow_destructible<T>::value;
11715
- template<class T>
11716
- inline constexpr bool has_virtual_destructor_v = has_virtual_destructor<T>::value;
11717
- template<class T>
11718
- inline constexpr bool has_unique_object_representations_v
11719
- = has_unique_object_representations<T>::value;
11720
-
11721
- // [meta.unary.prop.query], type property queries
11722
- template<class T>
11723
- inline constexpr size_t alignment_of_v = alignment_of<T>::value;
11724
- template<class T>
11725
- inline constexpr size_t rank_v = rank<T>::value;
11726
- template<class T, unsigned I = 0>
11727
- inline constexpr size_t extent_v = extent<T, I>::value;
11728
-
11729
- // [meta.rel], type relations
11730
- template<class T, class U>
11731
- inline constexpr bool is_same_v = is_same<T, U>::value;
11732
- template<class Base, class Derived>
11733
- inline constexpr bool is_base_of_v = is_base_of<Base, Derived>::value;
11734
- template<class From, class To>
11735
- inline constexpr bool is_convertible_v = is_convertible<From, To>::value;
11736
- template<class From, class To>
11737
- inline constexpr bool is_nothrow_convertible_v = is_nothrow_convertible<From, To>::value;
11738
- template<class T, class U>
11739
- inline constexpr bool is_layout_compatible_v = is_layout_compatible<T, U>::value;
11740
- template<class Base, class Derived>
11741
- inline constexpr bool is_pointer_interconvertible_base_of_v
11742
- = is_pointer_interconvertible_base_of<Base, Derived>::value;
11743
- template<class Fn, class... ArgTypes>
11744
- inline constexpr bool is_invocable_v = is_invocable<Fn, ArgTypes...>::value;
11745
- template<class R, class Fn, class... ArgTypes>
11746
- inline constexpr bool is_invocable_r_v = is_invocable_r<R, Fn, ArgTypes...>::value;
11747
- template<class Fn, class... ArgTypes>
11748
- inline constexpr bool is_nothrow_invocable_v = is_nothrow_invocable<Fn, ArgTypes...>::value;
11749
- template<class R, class Fn, class... ArgTypes>
11750
- inline constexpr bool is_nothrow_invocable_r_v
11751
- = is_nothrow_invocable_r<R, Fn, ArgTypes...>::value;
11752
-
11753
- // [meta.logical], logical operator traits
11754
- template<class... B>
11755
- inline constexpr bool conjunction_v = conjunction<B...>::value;
11756
- template<class... B>
11757
- inline constexpr bool disjunction_v = disjunction<B...>::value;
11758
- template<class B>
11759
- inline constexpr bool negation_v = negation<B>::value;
11760
-
11761
- // [meta.member], member relationships
11762
- template<class S, class M>
11763
- constexpr bool is_pointer_interconvertible_with_class(M S::*m) noexcept;
11764
- template<class S1, class S2, class M1, class M2>
11765
- constexpr bool is_corresponding_member(M1 S1::*m1, M2 S2::*m2) noexcept;
11766
-
11767
- // [meta.const.eval], constant evaluation context
11768
- constexpr bool is_constant_evaluated() noexcept;
11769
- }
11770
- ```
11771
-
11772
- ### Helper classes <a id="meta.help">[[meta.help]]</a>
11773
-
11774
- ``` cpp
11775
- namespace std {
11776
- template<class T, T v> struct integral_constant {
11777
- static constexpr T value = v;
11778
-
11779
- using value_type = T;
11780
- using type = integral_constant<T, v>;
11781
-
11782
- constexpr operator value_type() const noexcept { return value; }
11783
- constexpr value_type operator()() const noexcept { return value; }
11784
- };
11785
- }
11786
- ```
11787
-
11788
- The class template `integral_constant`, alias template `bool_constant`,
11789
- and its associated *typedef-name*s `true_type` and `false_type` are used
11790
- as base classes to define the interface for various type traits.
11791
-
11792
- ### Unary type traits <a id="meta.unary">[[meta.unary]]</a>
11793
-
11794
- This subclause contains templates that may be used to query the
11795
- properties of a type at compile time.
11796
-
11797
- Each of these templates shall be a *Cpp17UnaryTypeTrait* [[meta.rqmts]]
11798
- with a base characteristic of `true_type` if the corresponding condition
11799
- is `true`, otherwise `false_type`.
11800
-
11801
- #### Primary type categories <a id="meta.unary.cat">[[meta.unary.cat]]</a>
11802
-
11803
- The primary type categories correspond to the descriptions given in
11804
- subclause  [[basic.types]] of the C++ standard.
11805
-
11806
- For any given type `T`, the result of applying one of these templates to
11807
- `T` and to cv `T` shall yield the same result.
11808
-
11809
- [*Note 1*: For any given type `T`, exactly one of the primary type
11810
- categories has a `value` member that evaluates to `true`. — *end note*]
11811
-
11812
- #### Composite type traits <a id="meta.unary.comp">[[meta.unary.comp]]</a>
11813
-
11814
- These templates provide convenient compositions of the primary type
11815
- categories, corresponding to the descriptions given in subclause 
11816
- [[basic.types]].
11817
-
11818
- For any given type `T`, the result of applying one of these templates to
11819
- `T` and to cv `T` shall yield the same result.
11820
-
11821
- #### Type properties <a id="meta.unary.prop">[[meta.unary.prop]]</a>
11822
-
11823
- These templates provide access to some of the more important properties
11824
- of types.
11825
-
11826
- It is unspecified whether the library defines any full or partial
11827
- specializations of any of these templates.
11828
-
11829
- For all of the class templates `X` declared in this subclause,
11830
- instantiating that template with a template-argument that is a class
11831
- template specialization may result in the implicit instantiation of the
11832
- template argument if and only if the semantics of `X` require that the
11833
- argument is a complete type.
11834
-
11835
- For the purpose of defining the templates in this subclause, a function
11836
- call expression `declval<T>()` for any type `T` is considered to be a
11837
- trivial ([[basic.types]], [[special]]) function call that is not an
11838
- odr-use [[basic.def.odr]] of `declval` in the context of the
11839
- corresponding definition notwithstanding the restrictions of 
11840
- [[declval]].
11841
-
11842
- [*Note 1*: A union is a class type that can be marked with
11843
- `final`. — *end note*]
11844
-
11845
- [*Example 1*:
11846
-
11847
- ``` cpp
11848
- is_const_v<const volatile int> // true
11849
- is_const_v<const int*> // false
11850
- is_const_v<const int&> // false
11851
- is_const_v<int[3]> // false
11852
- is_const_v<const int[3]> // true
11853
- ```
11854
-
11855
- — *end example*]
11856
-
11857
- [*Example 2*:
11858
-
11859
- ``` cpp
11860
- remove_const_t<const volatile int> // volatile int
11861
- remove_const_t<const int* const> // const int*
11862
- remove_const_t<const int&> // const int&
11863
- remove_const_t<const int[3]> // int[3]
11864
- ```
11865
-
11866
- — *end example*]
11867
-
11868
- [*Example 3*:
11869
-
11870
- ``` cpp
11871
- // Given:
11872
- struct P final { };
11873
- union U1 { };
11874
- union U2 final { };
11875
-
11876
- // the following assertions hold:
11877
- static_assert(!is_final_v<int>);
11878
- static_assert(is_final_v<P>);
11879
- static_assert(!is_final_v<U1>);
11880
- static_assert(is_final_v<U2>);
11881
- ```
11882
-
11883
- — *end example*]
11884
-
11885
- The predicate condition for a template specialization
11886
- `is_constructible<T, Args...>` shall be satisfied if and only if the
11887
- following variable definition would be well-formed for some invented
11888
- variable `t`:
11889
-
11890
- ``` cpp
11891
- T t(declval<Args>()...);
11892
- ```
11893
-
11894
- [*Note 2*: These tokens are never interpreted as a function
11895
- declaration. — *end note*]
11896
-
11897
- Access checking is performed as if in a context unrelated to `T` and any
11898
- of the `Args`. Only the validity of the immediate context of the
11899
- variable initialization is considered.
11900
-
11901
- [*Note 3*: The evaluation of the initialization can result in side
11902
- effects such as the instantiation of class template specializations and
11903
- function template specializations, the generation of implicitly-defined
11904
- functions, and so on. Such side effects are not in the “immediate
11905
- context” and can result in the program being ill-formed. — *end note*]
11906
-
11907
- The predicate condition for a template specialization
11908
- `has_unique_object_representations<T>` shall be satisfied if and only
11909
- if:
11910
-
11911
- - `T` is trivially copyable, and
11912
- - any two objects of type `T` with the same value have the same object
11913
- representation, where two objects of array or non-union class type are
11914
- considered to have the same value if their respective sequences of
11915
- direct subobjects have the same values, and two objects of union type
11916
- are considered to have the same value if they have the same active
11917
- member and the corresponding members have the same value.
11918
-
11919
- The set of scalar types for which this condition holds is
11920
- *implementation-defined*.
11921
-
11922
- [*Note 4*: If a type has padding bits, the condition does not hold;
11923
- otherwise, the condition holds true for integral types. — *end note*]
11924
-
11925
- ### Type property queries <a id="meta.unary.prop.query">[[meta.unary.prop.query]]</a>
11926
-
11927
- This subclause contains templates that may be used to query properties
11928
- of types at compile time.
11929
-
11930
- Each of these templates shall be a *Cpp17UnaryTypeTrait* [[meta.rqmts]]
11931
- with a base characteristic of `integral_constant<size_t, Value>`.
11932
-
11933
- [*Example 1*:
11934
-
11935
- ``` cpp
11936
- // the following assertions hold:
11937
- assert(rank_v<int> == 0);
11938
- assert(rank_v<int[2]> == 1);
11939
- assert(rank_v<int[][4]> == 2);
11940
- ```
11941
-
11942
- — *end example*]
11943
-
11944
- [*Example 2*:
11945
-
11946
- ``` cpp
11947
- // the following assertions hold:
11948
- assert(extent_v<int> == 0);
11949
- assert(extent_v<int[2]> == 2);
11950
- assert(extent_v<int[2][4]> == 2);
11951
- assert(extent_v<int[][4]> == 0);
11952
- assert((extent_v<int, 1>) == 0);
11953
- assert((extent_v<int[2], 1>) == 0);
11954
- assert((extent_v<int[2][4], 1>) == 4);
11955
- assert((extent_v<int[][4], 1>) == 4);
11956
- ```
11957
-
11958
- — *end example*]
11959
-
11960
- ### Relationships between types <a id="meta.rel">[[meta.rel]]</a>
11961
-
11962
- This subclause contains templates that may be used to query
11963
- relationships between types at compile time.
11964
-
11965
- Each of these templates shall be a *Cpp17BinaryTypeTrait* [[meta.rqmts]]
11966
- with a base characteristic of `true_type` if the corresponding condition
11967
- is true, otherwise `false_type`.
11968
-
11969
- [*Note 1*: Base classes that are private, protected, or ambiguous are,
11970
- nonetheless, base classes. — *end note*]
11971
-
11972
- For the purpose of defining the templates in this subclause, a function
11973
- call expression `declval<T>()` for any type `T` is considered to be a
11974
- trivial ([[basic.types]], [[special]]) function call that is not an
11975
- odr-use [[basic.def.odr]] of `declval` in the context of the
11976
- corresponding definition notwithstanding the restrictions of 
11977
- [[declval]].
11978
-
11979
- [*Example 1*:
11980
-
11981
- ``` cpp
11982
- struct B {};
11983
- struct B1 : B {};
11984
- struct B2 : B {};
11985
- struct D : private B1, private B2 {};
11986
-
11987
- is_base_of_v<B, D> // true
11988
- is_base_of_v<const B, D> // true
11989
- is_base_of_v<B, const D> // true
11990
- is_base_of_v<B, const B> // true
11991
- is_base_of_v<D, B> // false
11992
- is_base_of_v<B&, D&> // false
11993
- is_base_of_v<B[3], D[3]> // false
11994
- is_base_of_v<int, int> // false
11995
- ```
11996
-
11997
- — *end example*]
11998
-
11999
- The predicate condition for a template specialization
12000
- `is_convertible<From, To>` shall be satisfied if and only if the return
12001
- expression in the following code would be well-formed, including any
12002
- implicit conversions to the return type of the function:
12003
-
12004
- ``` cpp
12005
- To test() {
12006
- return declval<From>();
12007
- }
12008
- ```
12009
-
12010
- [*Note 2*: This requirement gives well-defined results for reference
12011
- types, void types, array types, and function types. — *end note*]
12012
-
12013
- Access checking is performed in a context unrelated to `To` and `From`.
12014
- Only the validity of the immediate context of the *expression* of the
12015
- `return` statement [[stmt.return]] (including initialization of the
12016
- returned object or reference) is considered.
12017
-
12018
- [*Note 3*: The initialization can result in side effects such as the
12019
- instantiation of class template specializations and function template
12020
- specializations, the generation of implicitly-defined functions, and so
12021
- on. Such side effects are not in the “immediate context” and can result
12022
- in the program being ill-formed. — *end note*]
12023
-
12024
- ### Transformations between types <a id="meta.trans">[[meta.trans]]</a>
12025
-
12026
- This subclause contains templates that may be used to transform one type
12027
- to another following some predefined rule.
12028
-
12029
- Each of the templates in this subclause shall be a
12030
- *Cpp17TransformationTrait* [[meta.rqmts]].
12031
-
12032
- #### Const-volatile modifications <a id="meta.trans.cv">[[meta.trans.cv]]</a>
12033
-
12034
- [*Example 1*: `remove_const_t<const volatile int>` evaluates to
12035
- `volatile int`, whereas `remove_const_t<const int*>` evaluates to
12036
- `const int*`. — *end example*]
12037
-
12038
- #### Reference modifications <a id="meta.trans.ref">[[meta.trans.ref]]</a>
12039
-
12040
- [*Note 1*: This rule reflects the semantics of reference collapsing
12041
- [[dcl.ref]]. — *end note*]
12042
-
12043
- #### Sign modifications <a id="meta.trans.sign">[[meta.trans.sign]]</a>
12044
-
12045
- #### Array modifications <a id="meta.trans.arr">[[meta.trans.arr]]</a>
12046
-
12047
- [*Note 1*: For multidimensional arrays, only the first array dimension
12048
- is removed. For a type “array of `const U`”, the resulting type is
12049
- `const U`. — *end note*]
12050
-
12051
- [*Example 1*:
12052
-
12053
- ``` cpp
12054
- // the following assertions hold:
12055
- assert((is_same_v<remove_extent_t<int>, int>));
12056
- assert((is_same_v<remove_extent_t<int[2]>, int>));
12057
- assert((is_same_v<remove_extent_t<int[2][3]>, int[3]>));
12058
- assert((is_same_v<remove_extent_t<int[][3]>, int[3]>));
12059
- ```
12060
-
12061
- — *end example*]
12062
-
12063
- [*Example 2*:
12064
-
12065
- ``` cpp
12066
- // the following assertions hold:
12067
- assert((is_same_v<remove_all_extents_t<int>, int>));
12068
- assert((is_same_v<remove_all_extents_t<int[2]>, int>));
12069
- assert((is_same_v<remove_all_extents_t<int[2][3]>, int>));
12070
- assert((is_same_v<remove_all_extents_t<int[][3]>, int>));
12071
- ```
12072
-
12073
- — *end example*]
12074
-
12075
- #### Pointer modifications <a id="meta.trans.ptr">[[meta.trans.ptr]]</a>
12076
-
12077
- #### Other transformations <a id="meta.trans.other">[[meta.trans.other]]</a>
12078
-
12079
- [*Note 1*: This behavior is similar to the lvalue-to-rvalue
12080
- [[conv.lval]], array-to-pointer [[conv.array]], and function-to-pointer
12081
- [[conv.func]] conversions applied when an lvalue is used as an rvalue,
12082
- but also strips cv-qualifiers from class types in order to more closely
12083
- model by-value argument passing. — *end note*]
12084
-
12085
- [*Note 2*:
12086
-
12087
- A typical implementation would define `aligned_storage` as:
12088
-
12089
- ``` cpp
12090
- template<size_t Len, size_t Alignment>
12091
- struct aligned_storage {
12092
- typedef struct {
12093
- alignas(Alignment) unsigned char __data[Len];
12094
- } type;
12095
- };
12096
- ```
12097
-
12098
- — *end note*]
12099
-
12100
- In addition to being available via inclusion of the `<type_traits>`
12101
- header, the templates `unwrap_reference`, `unwrap_ref_decay`,
12102
- `unwrap_reference_t`, and `unwrap_ref_decay_t` are available when the
12103
- header `<functional>` [[functional.syn]] is included.
12104
-
12105
- Let:
12106
-
12107
- - `CREF(A)` be `add_lvalue_reference_t<const remove_reference_t<A>{}>`,
12108
- - `XREF(A)` denote a unary alias template `T` such that `T<U>` denotes
12109
- the same type as `U` with the addition of `A`’s cv and reference
12110
- qualifiers, for a non-reference cv-unqualified type `U`,
12111
- - `COPYCV(FROM, TO)` be an alias for type `TO` with the addition of
12112
- `FROM`’s top-level cv-qualifiers,
12113
- \[*Example 1*: `COPYCV(const int, volatile short)` is an alias for
12114
- `const volatile short`. — *end example*]
12115
- - `COND-RES(X, Y)` be
12116
- `decltype(false ? declval<X(&)()>()() : declval<Y(&)()>()())`.
12117
-
12118
- Given types `A` and `B`, let `X` be `remove_reference_t<A>`, let `Y` be
12119
- `remove_reference_t<B>`, and let `COMMON-{REF}(A, B)` be:
12120
-
12121
- - If `A` and `B` are both lvalue reference types, `COMMON-REF(A, B)` is
12122
- `COND-RES(COPYCV(X, Y) &,
12123
- COPYCV({}Y, X) &)` if that type exists and is a reference type.
12124
- - Otherwise, let `C` be `remove_reference_t<COMMON-REF(X&, Y&)>&&`. If
12125
- `A` and `B` are both rvalue reference types, `C` is well-formed, and
12126
- `is_convertible_v<A, C> && is_convertible_v<B, C>` is `true`, then
12127
- `COMMON-REF(A, B)` is `C`.
12128
- - Otherwise, let `D` be `COMMON-REF(const X&, Y&)`. If `A` is an rvalue
12129
- reference and `B` is an lvalue reference and `D` is well-formed and
12130
- `is_convertible_v<A, D>` is `true`, then `COMMON-REF(A, B)` is `D`.
12131
- - Otherwise, if `A` is an lvalue reference and `B` is an rvalue
12132
- reference, then `COMMON-REF(A, B)` is `COMMON-REF(B, A)`.
12133
- - Otherwise, `COMMON-REF(A, B)` is ill-formed.
12134
-
12135
- If any of the types computed above is ill-formed, then
12136
- `COMMON-REF(A, B)` is ill-formed.
12137
-
12138
- Note A: For the `common_type` trait applied to a template parameter pack
12139
- `T` of types, the member `type` shall be either defined or not present
12140
- as follows:
12141
-
12142
- - If `sizeof...(T)` is zero, there shall be no member `type`.
12143
- - If `sizeof...(T)` is one, let `T0` denote the sole type constituting
12144
- the pack `T`. The member *typedef-name* `type` shall denote the same
12145
- type, if any, as `common_type_t<T0, T0>`; otherwise there shall be no
12146
- member `type`.
12147
- - If `sizeof...(T)` is two, let the first and second types constituting
12148
- `T` be denoted by `T1` and `T2`, respectively, and let `D1` and `D2`
12149
- denote the same types as `decay_t<T1>` and `decay_t<T2>`,
12150
- respectively.
12151
- - If `is_same_v<T1, D1>` is `false` or `is_same_v<T2, D2>` is `false`,
12152
- let `C` denote the same type, if any, as `common_type_t<D1, D2>`.
12153
- - \[*Note 3*: None of the following will apply if there is a
12154
- specialization `common_type<D1, D2>`. — *end note*]
12155
- - Otherwise, if
12156
- ``` cpp
12157
- decay_t<decltype(false ? declval<D1>() : declval<D2>())>
12158
- ```
12159
-
12160
- denotes a valid type, let `C` denote that type.
12161
- - Otherwise, if `COND-RES(CREF(D1),
12162
- CREF(D2))` denotes a type, let `C` denote the type
12163
- `decay_t<COND-RES(CREF(D1),
12164
- CREF(D2))>`.
12165
-
12166
- In either case, the member *typedef-name* `type` shall denote the same
12167
- type, if any, as `C`. Otherwise, there shall be no member `type`.
12168
- - If `sizeof...(T)` is greater than two, let `T1`, `T2`, and `R`,
12169
- respectively, denote the first, second, and (pack of) remaining types
12170
- constituting `T`. Let `C` denote the same type, if any, as
12171
- `common_type_t<T1, T2>`. If there is such a type `C`, the member
12172
- *typedef-name* `type` shall denote the same type, if any, as
12173
- `common_type_t<C, R...>`. Otherwise, there shall be no member `type`.
12174
-
12175
- Note B: Notwithstanding the provisions of [[meta.type.synop]], and
12176
- pursuant to [[namespace.std]], a program may specialize
12177
- `common_type<T1, T2>` for types `T1` and `T2` such that
12178
- `is_same_v<T1, decay_t<T1>>` and `is_same_v<T2, decay_t<T2>>` are each
12179
- `true`.
12180
-
12181
- [*Note 4*: Such specializations are needed when only explicit
12182
- conversions are desired between the template arguments. — *end note*]
12183
-
12184
- Such a specialization need not have a member named `type`, but if it
12185
- does, that member shall be a *typedef-name* for an accessible and
12186
- unambiguous cv-unqualified non-reference type `C` to which each of the
12187
- types `T1` and `T2` is explicitly convertible. Moreover,
12188
- `common_type_t<T1, T2>` shall denote the same type, if any, as does
12189
- `common_type_t<T2, T1>`. No diagnostic is required for a violation of
12190
- this Note’s rules.
12191
-
12192
- Note C: For the `common_reference` trait applied to a parameter pack `T`
12193
- of types, the member `type` shall be either defined or not present as
12194
- follows:
12195
-
12196
- - If `sizeof...(T)` is zero, there shall be no member `type`.
12197
- - Otherwise, if `sizeof...(T)` is one, let `T0` denote the sole type in
12198
- the pack `T`. The member typedef `type` shall denote the same type as
12199
- `T0`.
12200
- - Otherwise, if `sizeof...(T)` is two, let `T1` and `T2` denote the two
12201
- types in the pack `T`. Then
12202
- - If `T1` and `T2` are reference types and `COMMON-REF(T1, T2)` is
12203
- well-formed, then the member typedef `type` denotes that type.
12204
- - Otherwise, if
12205
- `basic_common_reference<remove_cvref_t<T1>, remove_cvref_t<T2>,
12206
- {}XREF({}T1), XREF(T2)>::type` is well-formed, then the member
12207
- typedef `type` denotes that type.
12208
- - Otherwise, if `COND-RES(T1, T2)` is well-formed, then the member
12209
- typedef `type` denotes that type.
12210
- - Otherwise, if `common_type_t<T1, T2>` is well-formed, then the
12211
- member typedef `type` denotes that type.
12212
- - Otherwise, there shall be no member `type`.
12213
- - Otherwise, if `sizeof...(T)` is greater than two, let `T1`, `T2`, and
12214
- `Rest`, respectively, denote the first, second, and (pack of)
12215
- remaining types comprising `T`. Let `C` be the type
12216
- `common_reference_t<T1, T2>`. Then:
12217
- - If there is such a type `C`, the member typedef `type` shall denote
12218
- the same type, if any, as `common_reference_t<C, Rest...>`.
12219
- - Otherwise, there shall be no member `type`.
12220
-
12221
- Note D: Notwithstanding the provisions of [[meta.type.synop]], and
12222
- pursuant to [[namespace.std]], a program may partially specialize
12223
- `basic_common_reference<T, U, TQual, UQual>` for types `T` and `U` such
12224
- that `is_same_v<T, decay_t<T>{>}` and `is_same_v<U, decay_t<U>{>}` are
12225
- each `true`.
12226
-
12227
- [*Note 5*: Such specializations can be used to influence the result of
12228
- `common_reference`, and are needed when only explicit conversions are
12229
- desired between the template arguments. — *end note*]
12230
-
12231
- Such a specialization need not have a member named `type`, but if it
12232
- does, that member shall be a *typedef-name* for an accessible and
12233
- unambiguous type `C` to which each of the types `TQual<T>` and
12234
- `UQual<U>` is convertible. Moreover,
12235
- `basic_common_reference<T, U, TQual, UQual>::type` shall denote the same
12236
- type, if any, as does
12237
- `basic_common_reference<U, T, UQual, TQual>::type`. No diagnostic is
12238
- required for a violation of these rules.
12239
-
12240
- [*Example 2*:
12241
-
12242
- Given these definitions:
12243
-
12244
- ``` cpp
12245
- using PF1 = bool (&)();
12246
- using PF2 = short (*)(long);
12247
-
12248
- struct S {
12249
- operator PF2() const;
12250
- double operator()(char, int&);
12251
- void fn(long) const;
12252
- char data;
12253
- };
12254
-
12255
- using PMF = void (S::*)(long) const;
12256
- using PMD = char S::*;
12257
- ```
12258
-
12259
- the following assertions will hold:
12260
-
12261
- ``` cpp
12262
- static_assert(is_same_v<invoke_result_t<S, int>, short>);
12263
- static_assert(is_same_v<invoke_result_t<S&, unsigned char, int&>, double>);
12264
- static_assert(is_same_v<invoke_result_t<PF1>, bool>);
12265
- static_assert(is_same_v<invoke_result_t<PMF, unique_ptr<S>, int>, void>);
12266
- static_assert(is_same_v<invoke_result_t<PMD, S>, char&&>);
12267
- static_assert(is_same_v<invoke_result_t<PMD, const S*>, const char&>);
12268
- ```
12269
-
12270
- — *end example*]
12271
-
12272
- ### Logical operator traits <a id="meta.logical">[[meta.logical]]</a>
12273
-
12274
- This subclause describes type traits for applying logical operators to
12275
- other type traits.
12276
-
12277
- ``` cpp
12278
- template<class... B> struct conjunction : see below { };
12279
- ```
12280
-
12281
- The class template `conjunction` forms the logical conjunction of its
12282
- template type arguments.
12283
-
12284
- For a specialization `conjunction<``B₁``, `…`, ``B_N``>`, if there is a
12285
- template type argument `Bᵢ` for which `bool(``Bᵢ``::value)` is `false`,
12286
- then instantiating `conjunction<``B₁``, `…`, ``B_N``>::value` does not
12287
- require the instantiation of `Bⱼ``::value` for j > i.
12288
-
12289
- [*Note 1*: This is analogous to the short-circuiting behavior of the
12290
- built-in operator `&&`. — *end note*]
12291
-
12292
- Every template type argument for which `Bᵢ``::value` is instantiated
12293
- shall be usable as a base class and shall have a member `value` which is
12294
- convertible to `bool`, is not hidden, and is unambiguously available in
12295
- the type.
12296
-
12297
- The specialization `conjunction<``B₁``, `…`, ``B_N``>` has a public and
12298
- unambiguous base that is either
12299
-
12300
- - the first type `Bᵢ` in the list `true_type, ``B₁``, `…`, ``B_N` for
12301
- which `bool(``Bᵢ``::value)` is `false`, or
12302
- - if there is no such `Bᵢ`, the last type in the list.
12303
-
12304
- [*Note 2*: This means a specialization of `conjunction` does not
12305
- necessarily inherit from either `true_type` or
12306
- `false_type`. — *end note*]
12307
-
12308
- The member names of the base class, other than `conjunction` and
12309
- `operator=`, shall not be hidden and shall be unambiguously available in
12310
- `conjunction`.
12311
-
12312
- ``` cpp
12313
- template<class... B> struct disjunction : see below { };
12314
- ```
12315
-
12316
- The class template `disjunction` forms the logical disjunction of its
12317
- template type arguments.
12318
-
12319
- For a specialization `disjunction<``B₁``, `…`, ``B_N``>`, if there is a
12320
- template type argument `Bᵢ` for which `bool(``Bᵢ``::value)` is `true`,
12321
- then instantiating `disjunction<``B₁``, `…`, ``B_N``>::value` does not
12322
- require the instantiation of `Bⱼ``::value` for j > i.
12323
-
12324
- [*Note 3*: This is analogous to the short-circuiting behavior of the
12325
- built-in operator `||`. — *end note*]
12326
-
12327
- Every template type argument for which `Bᵢ``::value` is instantiated
12328
- shall be usable as a base class and shall have a member `value` which is
12329
- convertible to `bool`, is not hidden, and is unambiguously available in
12330
- the type.
12331
-
12332
- The specialization `disjunction<``B₁``, `…`, ``B_N``>` has a public and
12333
- unambiguous base that is either
12334
-
12335
- - the first type `Bᵢ` in the list `false_type, ``B₁``, `…`, ``B_N` for
12336
- which `bool(``Bᵢ``::value)` is `true`, or
12337
- - if there is no such `Bᵢ`, the last type in the list.
12338
-
12339
- [*Note 4*: This means a specialization of `disjunction` does not
12340
- necessarily inherit from either `true_type` or
12341
- `false_type`. — *end note*]
12342
-
12343
- The member names of the base class, other than `disjunction` and
12344
- `operator=`, shall not be hidden and shall be unambiguously available in
12345
- `disjunction`.
12346
-
12347
- ``` cpp
12348
- template<class B> struct negation : see below { };
12349
- ```
12350
-
12351
- The class template `negation` forms the logical negation of its template
12352
- type argument. The type `negation<B>` is a *Cpp17UnaryTypeTrait* with a
12353
- base characteristic of `bool_constant<!bool(B::value)>`.
12354
-
12355
- ### Member relationships <a id="meta.member">[[meta.member]]</a>
12356
-
12357
- ``` cpp
12358
- template<class S, class M>
12359
- constexpr bool is_pointer_interconvertible_with_class(M S::*m) noexcept;
12360
- ```
12361
-
12362
- *Mandates:* `S` is a complete type.
12363
-
12364
- *Returns:* `true` if and only if `S` is a standard-layout type, `M` is
12365
- an object type, `m` is not null, and each object `s` of type `S` is
12366
- pointer-interconvertible [[basic.compound]] with its subobject `s.*m`.
12367
-
12368
- ``` cpp
12369
- template<class S1, class S2, class M1, class M2>
12370
- constexpr bool is_corresponding_member(M1 S1::*m1, M2 S2::*m2) noexcept;
12371
- ```
12372
-
12373
- *Mandates:* `S1` and `S2` are complete types.
12374
-
12375
- *Returns:* `true` if and only if `S1` and `S2` are standard-layout
12376
- types, `M1` and `M2` are object types, `m1` and `m2` are not null, and
12377
- `m1` and `m2` point to corresponding members of the common initial
12378
- sequence [[class.mem]] of `S1` and `S2`.
12379
-
12380
- [*Note 1*:
12381
-
12382
- The type of a pointer-to-member expression `&C::b` is not always a
12383
- pointer to member of `C`, leading to potentially surprising results when
12384
- using these functions in conjunction with inheritance.
12385
-
12386
- [*Example 1*:
12387
-
12388
- ``` cpp
12389
- struct A { int a; }; // a standard-layout class
12390
- struct B { int b; }; // a standard-layout class
12391
- struct C: public A, public B { }; // not a standard-layout class
12392
-
12393
- static_assert( is_pointer_interconvertible_with_class( &C::b ) );
12394
- // Succeeds because, despite its appearance, &C::b has type
12395
- // ``pointer to member of B of type int''.
12396
- static_assert( is_pointer_interconvertible_with_class<C>( &C::b ) );
12397
- // Forces the use of class C, and fails.
12398
-
12399
- static_assert( is_corresponding_member( &C::a, &C::b ) );
12400
- // Succeeds because, despite its appearance, &C::a and &C::b have types
12401
- // ``pointer to member of A of type int'' and
12402
- // ``pointer to member of B of type int'', respectively.
12403
- static_assert( is_corresponding_member<C, C>( &C::a, &C::b ) );
12404
- // Forces the use of class C, and fails.
12405
- ```
12406
-
12407
- — *end example*]
12408
-
12409
- — *end note*]
12410
-
12411
- ### Constant evaluation context <a id="meta.const.eval">[[meta.const.eval]]</a>
12412
-
12413
- ``` cpp
12414
- constexpr bool is_constant_evaluated() noexcept;
12415
- ```
12416
-
12417
- *Returns:* `true` if and only if evaluation of the call occurs within
12418
- the evaluation of an expression or conversion that is manifestly
12419
- constant-evaluated [[expr.const]].
12420
-
12421
- [*Example 1*:
12422
-
12423
- ``` cpp
12424
- constexpr void f(unsigned char *p, int n) {
12425
- if (std::is_constant_evaluated()) { // should not be a constexpr if statement
12426
- for (int k = 0; k<n; ++k) p[k] = 0;
12427
- } else {
12428
- memset(p, 0, n); // not a core constant expression
12429
- }
12430
- }
12431
- ```
12432
-
12433
- — *end example*]
12434
-
12435
- ## Compile-time rational arithmetic <a id="ratio">[[ratio]]</a>
12436
-
12437
- ### In general <a id="ratio.general">[[ratio.general]]</a>
12438
-
12439
- Subclause  [[ratio]] describes the ratio library. It provides a class
12440
- template `ratio` which exactly represents any finite rational number
12441
- with a numerator and denominator representable by compile-time constants
12442
- of type `intmax_t`.
12443
-
12444
- Throughout subclause  [[ratio]], the names of template parameters are
12445
- used to express type requirements. If a template parameter is named `R1`
12446
- or `R2`, and the template argument is not a specialization of the
12447
- `ratio` template, the program is ill-formed.
12448
-
12449
- ### Header `<ratio>` synopsis <a id="ratio.syn">[[ratio.syn]]</a>
12450
-
12451
- ``` cpp
12452
- namespace std {
12453
- // [ratio.ratio], class template ratio
12454
- template<intmax_t N, intmax_t D = 1> class ratio;
12455
-
12456
- // [ratio.arithmetic], ratio arithmetic
12457
- template<class R1, class R2> using ratio_add = see below;
12458
- template<class R1, class R2> using ratio_subtract = see below;
12459
- template<class R1, class R2> using ratio_multiply = see below;
12460
- template<class R1, class R2> using ratio_divide = see below;
12461
-
12462
- // [ratio.comparison], ratio comparison
12463
- template<class R1, class R2> struct ratio_equal;
12464
- template<class R1, class R2> struct ratio_not_equal;
12465
- template<class R1, class R2> struct ratio_less;
12466
- template<class R1, class R2> struct ratio_less_equal;
12467
- template<class R1, class R2> struct ratio_greater;
12468
- template<class R1, class R2> struct ratio_greater_equal;
12469
-
12470
- template<class R1, class R2>
12471
- inline constexpr bool ratio_equal_v = ratio_equal<R1, R2>::value;
12472
- template<class R1, class R2>
12473
- inline constexpr bool ratio_not_equal_v = ratio_not_equal<R1, R2>::value;
12474
- template<class R1, class R2>
12475
- inline constexpr bool ratio_less_v = ratio_less<R1, R2>::value;
12476
- template<class R1, class R2>
12477
- inline constexpr bool ratio_less_equal_v = ratio_less_equal<R1, R2>::value;
12478
- template<class R1, class R2>
12479
- inline constexpr bool ratio_greater_v = ratio_greater<R1, R2>::value;
12480
- template<class R1, class R2>
12481
- inline constexpr bool ratio_greater_equal_v = ratio_greater_equal<R1, R2>::value;
12482
-
12483
- // [ratio.si], convenience SI typedefs
12484
- using yocto = ratio<1, 1'000'000'000'000'000'000'000'000>; // see below
12485
- using zepto = ratio<1, 1'000'000'000'000'000'000'000>; // see below
12486
- using atto = ratio<1, 1'000'000'000'000'000'000>;
12487
- using femto = ratio<1, 1'000'000'000'000'000>;
12488
- using pico = ratio<1, 1'000'000'000'000>;
12489
- using nano = ratio<1, 1'000'000'000>;
12490
- using micro = ratio<1, 1'000'000>;
12491
- using milli = ratio<1, 1'000>;
12492
- using centi = ratio<1, 100>;
12493
- using deci = ratio<1, 10>;
12494
- using deca = ratio< 10, 1>;
12495
- using hecto = ratio< 100, 1>;
12496
- using kilo = ratio< 1'000, 1>;
12497
- using mega = ratio< 1'000'000, 1>;
12498
- using giga = ratio< 1'000'000'000, 1>;
12499
- using tera = ratio< 1'000'000'000'000, 1>;
12500
- using peta = ratio< 1'000'000'000'000'000, 1>;
12501
- using exa = ratio< 1'000'000'000'000'000'000, 1>;
12502
- using zetta = ratio< 1'000'000'000'000'000'000'000, 1>; // see below
12503
- using yotta = ratio<1'000'000'000'000'000'000'000'000, 1>; // see below
12504
- }
12505
- ```
12506
-
12507
- ### Class template `ratio` <a id="ratio.ratio">[[ratio.ratio]]</a>
12508
-
12509
- ``` cpp
12510
- namespace std {
12511
- template<intmax_t N, intmax_t D = 1> class ratio {
12512
- public:
12513
- static constexpr intmax_t num;
12514
- static constexpr intmax_t den;
12515
- using type = ratio<num, den>;
12516
- };
12517
- }
12518
- ```
12519
-
12520
- If the template argument `D` is zero or the absolute values of either of
12521
- the template arguments `N` and `D` is not representable by type
12522
- `intmax_t`, the program is ill-formed.
12523
-
12524
- [*Note 1*: These rules ensure that infinite ratios are avoided and that
12525
- for any negative input, there exists a representable value of its
12526
- absolute value which is positive. This excludes the most negative
12527
- value. — *end note*]
12528
-
12529
- The static data members `num` and `den` shall have the following values,
12530
- where `gcd` represents the greatest common divisor of the absolute
12531
- values of `N` and `D`:
12532
-
12533
- - `num` shall have the value `sign(N) * sign(D) * abs(N) / gcd`.
12534
- - `den` shall have the value `abs(D) / gcd`.
12535
-
12536
- ### Arithmetic on `ratio`s <a id="ratio.arithmetic">[[ratio.arithmetic]]</a>
12537
-
12538
- Each of the alias templates `ratio_add`, `ratio_subtract`,
12539
- `ratio_multiply`, and `ratio_divide` denotes the result of an arithmetic
12540
- computation on two `ratio`s `R1` and `R2`. With `X` and `Y` computed (in
12541
- the absence of arithmetic overflow) as specified by
12542
- [[ratio.arithmetic]], each alias denotes a `ratio<U, V>` such that `U`
12543
- is the same as `ratio<X, Y>::num` and `V` is the same as
12544
- `ratio<X, Y>::den`.
12545
-
12546
- If it is not possible to represent `U` or `V` with `intmax_t`, the
12547
- program is ill-formed. Otherwise, an implementation should yield correct
12548
- values of `U` and `V`. If it is not possible to represent `X` or `Y`
12549
- with `intmax_t`, the program is ill-formed unless the implementation
12550
- yields correct values of `U` and `V`.
12551
-
12552
- **Table: Expressions used to perform ratio arithmetic** <a id="ratio.arithmetic">[ratio.arithmetic]</a>
12553
-
12554
- | Type | Value of `X` | Value of `Y` |
12555
- | ------------------------ | --------------------- | ------------------- |
12556
- | `ratio_add<R1, R2>` | `R1::num * R2::den +` | `R1::den * R2::den` |
12557
- | | `R2::num * R1::den` | |
12558
- | `ratio_subtract<R1, R2>` | `R1::num * R2::den -` | `R1::den * R2::den` |
12559
- | | `R2::num * R1::den` | |
12560
- | `ratio_multiply<R1, R2>` | `R1::num * R2::num` | `R1::den * R2::den` |
12561
- | `ratio_divide<R1, R2>` | `R1::num * R2::den` | `R1::den * R2::num` |
12562
-
12563
-
12564
- [*Example 1*:
12565
-
12566
- ``` cpp
12567
- static_assert(ratio_add<ratio<1, 3>, ratio<1, 6>>::num == 1, "1/3+1/6 == 1/2");
12568
- static_assert(ratio_add<ratio<1, 3>, ratio<1, 6>>::den == 2, "1/3+1/6 == 1/2");
12569
- static_assert(ratio_multiply<ratio<1, 3>, ratio<3, 2>>::num == 1, "1/3*3/2 == 1/2");
12570
- static_assert(ratio_multiply<ratio<1, 3>, ratio<3, 2>>::den == 2, "1/3*3/2 == 1/2");
12571
-
12572
- // The following cases may cause the program to be ill-formed under some implementations
12573
- static_assert(ratio_add<ratio<1, INT_MAX>, ratio<1, INT_MAX>>::num == 2,
12574
- "1/MAX+1/MAX == 2/MAX");
12575
- static_assert(ratio_add<ratio<1, INT_MAX>, ratio<1, INT_MAX>>::den == INT_MAX,
12576
- "1/MAX+1/MAX == 2/MAX");
12577
- static_assert(ratio_multiply<ratio<1, INT_MAX>, ratio<INT_MAX, 2>>::num == 1,
12578
- "1/MAX * MAX/2 == 1/2");
12579
- static_assert(ratio_multiply<ratio<1, INT_MAX>, ratio<INT_MAX, 2>>::den == 2,
12580
- "1/MAX * MAX/2 == 1/2");
12581
- ```
12582
-
12583
- — *end example*]
12584
-
12585
- ### Comparison of `ratio`s <a id="ratio.comparison">[[ratio.comparison]]</a>
12586
-
12587
- ``` cpp
12588
- template<class R1, class R2>
12589
- struct ratio_equal : bool_constant<R1::num == R2::num && R1::den == R2::den> { };
12590
- ```
12591
-
12592
- ``` cpp
12593
- template<class R1, class R2>
12594
- struct ratio_not_equal : bool_constant<!ratio_equal_v<R1, R2>> { };
12595
- ```
12596
-
12597
- ``` cpp
12598
- template<class R1, class R2>
12599
- struct ratio_less : bool_constant<see below> { };
12600
- ```
12601
-
12602
- If `R1::num` × `R2::den` is less than `R2::num` × `R1::den`,
12603
- `ratio_less<R1, R2>` shall be derived from `bool_constant<true>`;
12604
- otherwise it shall be derived from `bool_constant<false>`.
12605
- Implementations may use other algorithms to compute this relationship to
12606
- avoid overflow. If overflow occurs, the program is ill-formed.
12607
-
12608
- ``` cpp
12609
- template<class R1, class R2>
12610
- struct ratio_less_equal : bool_constant<!ratio_less_v<R2, R1>> { };
12611
- ```
12612
-
12613
- ``` cpp
12614
- template<class R1, class R2>
12615
- struct ratio_greater : bool_constant<ratio_less_v<R2, R1>> { };
12616
- ```
12617
-
12618
- ``` cpp
12619
- template<class R1, class R2>
12620
- struct ratio_greater_equal : bool_constant<!ratio_less_v<R1, R2>> { };
12621
- ```
12622
-
12623
- ### SI types for `ratio` <a id="ratio.si">[[ratio.si]]</a>
12624
-
12625
- For each of the *typedef-name*s `yocto`, `zepto`, `zetta`, and `yotta`,
12626
- if both of the constants used in its specification are representable by
12627
- `intmax_t`, the typedef is defined; if either of the constants is not
12628
- representable by `intmax_t`, the typedef is not defined.
12629
 
12630
  ## Class `type_index` <a id="type.index">[[type.index]]</a>
12631
 
12632
  ### Header `<typeindex>` synopsis <a id="type.index.synopsis">[[type.index.synopsis]]</a>
12633
 
@@ -12770,22 +9900,22 @@ sort(execution::par, v.begin(), v.end());
12770
  sort(execution::par_unseq, v.begin(), v.end());
12771
  ```
12772
 
12773
  — *end example*]
12774
 
12775
- [*Note 1*: Because different parallel architectures may require
12776
- idiosyncratic parameters for efficient execution, implementations may
12777
- provide additional execution policies to those described in this
12778
- standard as extensions. — *end note*]
12779
 
12780
  ### Header `<execution>` synopsis <a id="execution.syn">[[execution.syn]]</a>
12781
 
12782
  ``` cpp
12783
  namespace std {
12784
  // [execpol.type], execution policy type trait
12785
  template<class T> struct is_execution_policy;
12786
- template<class T> inline constexpr bool is_execution_policy_v = is_execution_policy<T>::value;
12787
  }
12788
 
12789
  namespace std::execution {
12790
  // [execpol.seq], sequenced execution policy
12791
  class sequenced_policy;
@@ -12838,12 +9968,12 @@ The class `execution::sequenced_policy` is an execution policy type used
12838
  as a unique type to disambiguate parallel algorithm overloading and
12839
  require that a parallel algorithm’s execution may not be parallelized.
12840
 
12841
  During the execution of a parallel algorithm with the
12842
  `execution::sequenced_policy` policy, if the invocation of an element
12843
- access function exits via an uncaught exception, `terminate()` is
12844
- called.
12845
 
12846
  ### Parallel execution policy <a id="execpol.par">[[execpol.par]]</a>
12847
 
12848
  ``` cpp
12849
  class execution::parallel_policy { unspecified };
@@ -12853,12 +9983,12 @@ The class `execution::parallel_policy` is an execution policy type used
12853
  as a unique type to disambiguate parallel algorithm overloading and
12854
  indicate that a parallel algorithm’s execution may be parallelized.
12855
 
12856
  During the execution of a parallel algorithm with the
12857
  `execution::parallel_policy` policy, if the invocation of an element
12858
- access function exits via an uncaught exception, `terminate()` is
12859
- called.
12860
 
12861
  ### Parallel and unsequenced execution policy <a id="execpol.parunseq">[[execpol.parunseq]]</a>
12862
 
12863
  ``` cpp
12864
  class execution::parallel_unsequenced_policy { unspecified };
@@ -12869,12 +9999,12 @@ policy type used as a unique type to disambiguate parallel algorithm
12869
  overloading and indicate that a parallel algorithm’s execution may be
12870
  parallelized and vectorized.
12871
 
12872
  During the execution of a parallel algorithm with the
12873
  `execution::parallel_unsequenced_policy` policy, if the invocation of an
12874
- element access function exits via an uncaught exception, `terminate()`
12875
- is called.
12876
 
12877
  ### Unsequenced execution policy <a id="execpol.unseq">[[execpol.unseq]]</a>
12878
 
12879
  ``` cpp
12880
  class execution::unsequenced_policy { unspecified };
@@ -12886,12 +10016,12 @@ that a parallel algorithm’s execution may be vectorized, e.g., executed
12886
  on a single thread using instructions that operate on multiple data
12887
  items.
12888
 
12889
  During the execution of a parallel algorithm with the
12890
  `execution::unsequenced_policy` policy, if the invocation of an element
12891
- access function exits via an uncaught exception, `terminate()` is
12892
- called.
12893
 
12894
  ### Execution policy objects <a id="execpol.objects">[[execpol.objects]]</a>
12895
 
12896
  ``` cpp
12897
  inline constexpr execution::sequenced_policy execution::seq{ unspecified };
@@ -12905,10 +10035,18 @@ type of execution policy.
12905
 
12906
  ## Primitive numeric conversions <a id="charconv">[[charconv]]</a>
12907
 
12908
  ### Header `<charconv>` synopsis <a id="charconv.syn">[[charconv.syn]]</a>
12909
 
 
 
 
 
 
 
 
 
12910
  ``` cpp
12911
  %
12912
  %
12913
  {chars_format{chars_format{chars_format{chars_formatnamespace std {
12914
  // floating-point format for primitive numerical conversion
@@ -12927,26 +10065,16 @@ type of execution policy.
12927
  char* ptr;
12928
  errc ec;
12929
  friend bool operator==(const to_chars_result&, const to_chars_result&) = default;
12930
  };
12931
 
12932
- to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
12933
  to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;
12934
 
12935
- to_chars_result to_chars(char* first, char* last, float value);
12936
- to_chars_result to_chars(char* first, char* last, double value);
12937
- to_chars_result to_chars(char* first, char* last, long double value);
12938
-
12939
- to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
12940
- to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
12941
- to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
12942
-
12943
- to_chars_result to_chars(char* first, char* last, float value,
12944
- chars_format fmt, int precision);
12945
- to_chars_result to_chars(char* first, char* last, double value,
12946
- chars_format fmt, int precision);
12947
- to_chars_result to_chars(char* first, char* last, long double value,
12948
  chars_format fmt, int precision);
12949
  %
12950
  %
12951
  {from_chars_result{from_chars_result}
12952
 
@@ -12955,18 +10083,14 @@ type of execution policy.
12955
  const char* ptr;
12956
  errc ec;
12957
  friend bool operator==(const from_chars_result&, const from_chars_result&) = default;
12958
  };
12959
 
12960
- from_chars_result from_chars(const char* first, const char* last,
12961
- see below& value, int base = 10);
12962
 
12963
- from_chars_result from_chars(const char* first, const char* last, float& value,
12964
- chars_format fmt = chars_format::general);
12965
- from_chars_result from_chars(const char* first, const char* last, double& value,
12966
- chars_format fmt = chars_format::general);
12967
- from_chars_result from_chars(const char* first, const char* last, long double& value,
12968
  chars_format fmt = chars_format::general);
12969
  }
12970
  ```
12971
 
12972
  The type `chars_format` is a bitmask type [[bitmask.types]] with
@@ -13008,11 +10132,11 @@ specifier for `printf` as follows: The conversion specifier is `f` if
13008
  `chars_format::scientific`, `a` (without leading `"0x"` in the result)
13009
  if `fmt` is `chars_format::hex`, and `g` if `fmt` is
13010
  `chars_format::general`.
13011
 
13012
  ``` cpp
13013
- to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
13014
  ```
13015
 
13016
  *Preconditions:* `base` has a value between 2 and 36 (inclusive).
13017
 
13018
  *Effects:* The value of `value` is converted to a string of digits in
@@ -13020,30 +10144,23 @@ the given base (with no redundant leading zeroes). Digits in the range
13020
  10..35 (inclusive) are represented as lowercase characters `a`..`z`. If
13021
  `value` is less than zero, the representation starts with `’-’`.
13022
 
13023
  *Throws:* Nothing.
13024
 
13025
- *Remarks:* The implementation shall provide overloads for all signed and
13026
- unsigned integer types and `char` as the type of the parameter `value`.
13027
-
13028
  ``` cpp
13029
- to_chars_result to_chars(char* first, char* last, float value);
13030
- to_chars_result to_chars(char* first, char* last, double value);
13031
- to_chars_result to_chars(char* first, char* last, long double value);
13032
  ```
13033
 
13034
  *Effects:* `value` is converted to a string in the style of `printf` in
13035
  the `"C"` locale. The conversion specifier is `f` or `e`, chosen
13036
  according to the requirement for a shortest representation (see above);
13037
  a tie is resolved in favor of `f`.
13038
 
13039
  *Throws:* Nothing.
13040
 
13041
  ``` cpp
13042
- to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
13043
- to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
13044
- to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
13045
  ```
13046
 
13047
  *Preconditions:* `fmt` has the value of one of the enumerators of
13048
  `chars_format`.
13049
 
@@ -13051,15 +10168,11 @@ to_chars_result to_chars(char* first, char* last, long double value, chars_forma
13051
  the `"C"` locale.
13052
 
13053
  *Throws:* Nothing.
13054
 
13055
  ``` cpp
13056
- to_chars_result to_chars(char* first, char* last, float value,
13057
- chars_format fmt, int precision);
13058
- to_chars_result to_chars(char* first, char* last, double value,
13059
- chars_format fmt, int precision);
13060
- to_chars_result to_chars(char* first, char* last, long double value,
13061
  chars_format fmt, int precision);
13062
  ```
13063
 
13064
  *Preconditions:* `fmt` has the value of one of the enumerators of
13065
  `chars_format`.
@@ -13092,12 +10205,12 @@ unmodified and the member `ec` of the return value is equal to
13092
  `errc::result_out_of_range`. Otherwise, `value` is set to the parsed
13093
  value, after rounding according to `round_to_nearest` [[round.style]],
13094
  and the member `ec` is value-initialized.
13095
 
13096
  ``` cpp
13097
- from_chars_result from_chars(const char* first, const char* last,
13098
- see below& value, int base = 10);
13099
  ```
13100
 
13101
  *Preconditions:* `base` has a value between 2 and 36 (inclusive).
13102
 
13103
  *Effects:* The pattern is the expected form of the subject sequence in
@@ -13106,20 +10219,12 @@ except that no `"0x"` or `"0X"` prefix shall appear if the value of
13106
  `base` is 16, and except that `’-’` is the only sign that may appear,
13107
  and only if `value` has a signed type.
13108
 
13109
  *Throws:* Nothing.
13110
 
13111
- *Remarks:* The implementation shall provide overloads for all signed and
13112
- unsigned integer types and `char` as the referenced type of the
13113
- parameter `value`.
13114
-
13115
  ``` cpp
13116
- from_chars_result from_chars(const char* first, const char* last, float& value,
13117
- chars_format fmt = chars_format::general);
13118
- from_chars_result from_chars(const char* first, const char* last, double& value,
13119
- chars_format fmt = chars_format::general);
13120
- from_chars_result from_chars(const char* first, const char* last, long double& value,
13121
  chars_format fmt = chars_format::general);
13122
  ```
13123
 
13124
  *Preconditions:* `fmt` has the value of one of the enumerators of
13125
  `chars_format`.
@@ -13149,111 +10254,160 @@ See also: ISO C 7.22.1.3, 7.22.1.4
13149
 
13150
  ### Header `<format>` synopsis <a id="format.syn">[[format.syn]]</a>
13151
 
13152
  ``` cpp
13153
  namespace std {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13154
  // [format.functions], formatting functions
13155
  template<class... Args>
13156
- string format(string_view fmt, const Args&... args);
13157
  template<class... Args>
13158
- wstring format(wstring_view fmt, const Args&... args);
13159
  template<class... Args>
13160
- string format(const locale& loc, string_view fmt, const Args&... args);
13161
  template<class... Args>
13162
- wstring format(const locale& loc, wstring_view fmt, const Args&... args);
13163
 
13164
  string vformat(string_view fmt, format_args args);
13165
  wstring vformat(wstring_view fmt, wformat_args args);
13166
  string vformat(const locale& loc, string_view fmt, format_args args);
13167
  wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
13168
 
13169
  template<class Out, class... Args>
13170
- Out format_to(Out out, string_view fmt, const Args&... args);
13171
  template<class Out, class... Args>
13172
- Out format_to(Out out, wstring_view fmt, const Args&... args);
13173
  template<class Out, class... Args>
13174
- Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
13175
  template<class Out, class... Args>
13176
- Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
13177
 
13178
  template<class Out>
13179
- Out vformat_to(Out out, string_view fmt,
13180
- format_args_t<type_identity_t<Out>, char> args);
13181
  template<class Out>
13182
- Out vformat_to(Out out, wstring_view fmt,
13183
- format_args_t<type_identity_t<Out>, wchar_t> args);
13184
  template<class Out>
13185
- Out vformat_to(Out out, const locale& loc, string_view fmt,
13186
- format_args_t<type_identity_t<Out>, char> args);
13187
  template<class Out>
13188
- Out vformat_to(Out out, const locale& loc, wstring_view fmt,
13189
- format_args_t<type_identity_t<Out>, wchar_t> args);
13190
 
13191
  template<class Out> struct format_to_n_result {
13192
  Out out;
13193
  iter_difference_t<Out> size;
13194
  };
13195
  template<class Out, class... Args>
13196
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13197
- string_view fmt, const Args&... args);
13198
  template<class Out, class... Args>
13199
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13200
- wstring_view fmt, const Args&... args);
13201
  template<class Out, class... Args>
13202
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13203
- const locale& loc, string_view fmt,
13204
- const Args&... args);
13205
  template<class Out, class... Args>
13206
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13207
- const locale& loc, wstring_view fmt,
13208
- const Args&... args);
13209
 
13210
  template<class... Args>
13211
- size_t formatted_size(string_view fmt, const Args&... args);
13212
  template<class... Args>
13213
- size_t formatted_size(wstring_view fmt, const Args&... args);
13214
  template<class... Args>
13215
- size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
13216
  template<class... Args>
13217
- size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
13218
 
13219
  // [format.formatter], formatter
13220
  template<class T, class charT = char> struct formatter;
13221
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13222
  // [format.parse.ctx], class template basic_format_parse_context
13223
  template<class charT> class basic_format_parse_context;
13224
  using format_parse_context = basic_format_parse_context<char>;
13225
  using wformat_parse_context = basic_format_parse_context<wchar_t>;
13226
 
13227
- template<class Out, class charT> class basic_format_context;
13228
- using format_context = basic_format_context<unspecified, char>;
13229
- using wformat_context = basic_format_context<unspecified, wchar_t>;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13230
 
13231
  // [format.arguments], arguments
13232
  // [format.arg], class template basic_format_arg
13233
  template<class Context> class basic_format_arg;
13234
 
13235
  template<class Visitor, class Context>
13236
- see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
13237
 
13238
  // [format.arg.store], class template format-arg-store
13239
- template<class Context, class... Args> struct format-arg-store; // exposition only
13240
 
13241
  template<class Context = format_context, class... Args>
13242
  format-arg-store<Context, Args...>
13243
- make_format_args(const Args&... args);
13244
  template<class... Args>
13245
  format-arg-store<wformat_context, Args...>
13246
- make_wformat_args(const Args&... args);
13247
-
13248
- // [format.args], class template basic_format_args
13249
- template<class Context> class basic_format_args;
13250
- using format_args = basic_format_args<format_context>;
13251
- using wformat_args = basic_format_args<wformat_context>;
13252
-
13253
- template<class Out, class charT>
13254
- using format_args_t = basic_format_args<basic_format_context<Out, charT>>;
13255
 
13256
  // [format.error], class format_error
13257
  class format_error;
13258
  }
13259
  ```
@@ -13345,13 +10499,13 @@ manual indexing. — *end note*]
13345
 
13346
  ``` cpp
13347
  string s0 = format("{} to {}", "a", "b"); // OK, automatic indexing
13348
  string s1 = format("{1} to {0}", "a", "b"); // OK, manual indexing
13349
  string s2 = format("{0} to {}", "a", "b"); // not a format string (mixing automatic and manual indexing),
13350
- // throws format_error
13351
  string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing),
13352
- // throws format_error
13353
  ```
13354
 
13355
  — *end example*]
13356
 
13357
  The *format-spec* field contains *format specifications* that define how
@@ -13373,17 +10527,17 @@ by *arg-id*, the string is not a format string for `args`.
13373
 
13374
  — *end example*]
13375
 
13376
  #### Standard format specifiers <a id="format.string.std">[[format.string.std]]</a>
13377
 
13378
- Each `formatter` specializations described in [[format.formatter.spec]]
13379
  for fundamental and string types interprets *format-spec* as a
13380
  *std-format-spec*.
13381
 
13382
  [*Note 1*: The format specification can be used to specify such details
13383
- as field width, alignment, padding, and decimal precision. Some of the
13384
- formatting options are only supported for arithmetic
13385
  types. — *end note*]
13386
 
13387
  The syntax of format specifications is as follows:
13388
 
13389
  ``` bnf
@@ -13423,21 +10577,40 @@ precision
13423
  '.' '{' arg-idₒₚₜ '}'
13424
  ```
13425
 
13426
  ``` bnf
13427
  type one of
13428
- 'a A b B c d e E f F g G o p s x X'
13429
  ```
13430
 
13431
- [*Note 2*: The *fill* character can be any character other than `{` or
13432
- `}`. The presence of a fill character is signaled by the character
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13433
  following it, which must be one of the alignment options. If the second
13434
  character of *std-format-spec* is not a valid alignment option, then it
13435
- is assumed that both the fill character and the alignment option are
13436
  absent. — *end note*]
13437
 
13438
- The *align* specifier applies to all argument types. The meaning of the
13439
  various alignment options is as specified in [[format.align]].
13440
 
13441
  [*Example 1*:
13442
 
13443
  ``` cpp
@@ -13447,34 +10620,49 @@ string s1 = format("{:6}", 'x'); // value of s1 is "x\ \ \ \ \ "
13447
  string s2 = format("{:*<6}", 'x'); // value of s2 is "x*****"
13448
  string s3 = format("{:*>6}", 'x'); // value of s3 is "*****x"
13449
  string s4 = format("{:*^6}", 'x'); // value of s4 is "**x***"
13450
  string s5 = format("{:6d}", c); // value of s5 is "\ \ \ 120"
13451
  string s6 = format("{:6}", true); // value of s6 is "true\ \ "
 
 
 
 
13452
  ```
13453
 
13454
  — *end example*]
13455
 
13456
- [*Note 3*: Unless a minimum field width is defined, the field width is
13457
- determined by the size of the content and the alignment option has no
13458
- effect. *end note*]
 
 
 
 
 
 
13459
 
13460
  **Table: Meaning of align options** <a id="format.align">[format.align]</a>
13461
 
13462
  | Option | Meaning |
13463
- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13464
- | `<` | Forces the field to be aligned to the start of the available space. This is the default for non-arithmetic types, `charT`, and `bool`, unless an integer presentation type is specified. |
13465
- | % `>` | Forces the field to be aligned to the end of the available space. This is the default for arithmetic types other than `charT` and `bool` or when an integer presentation type is specified. |
13466
- | % `^` | Forces the field to be centered within the available space by inserting $\bigl\lfloor \frac{n}{2} \bigr\rfloor$ characters before and $\bigl\lceil \frac{n}{2} \bigr\rceil$ characters after the value, where $n$ is the total number of fill characters to insert. |
13467
 
13468
 
13469
  The *sign* option is only valid for arithmetic types other than `charT`
13470
  and `bool` or when an integer presentation type is specified. The
13471
  meaning of the various options is as specified in [[format.sign]].
13472
 
13473
- [*Note 4*: For negative numbers and negative zero the output of
13474
- `to_chars` will already contain the sign so no additional transformation
13475
- is performed. — *end note*]
 
 
 
 
 
13476
 
13477
  The *sign* option applies to floating-point infinity and NaN.
13478
 
13479
  [*Example 2*:
13480
 
@@ -13500,88 +10688,82 @@ form causes the result of the conversion of finite values to always
13500
  contain a decimal-point character, even if no digits follow it.
13501
  Normally, a decimal-point character appears in the result of these
13502
  conversions only if a digit follows it. In addition, for `g` and `G`
13503
  conversions, trailing zeros are not removed from the result.
13504
 
13505
- If `{ \opt{arg-id} }` is used in a *width* or *precision*, the value of
13506
- the corresponding formatting argument is used in its place. If the
13507
- corresponding formatting argument is not of integral type, or its value
13508
- is negative for *precision* or non-positive for *width*, an exception of
13509
- type `format_error` is thrown.
13510
-
13511
- The *positive-integer* in *width* is a decimal integer defining the
13512
- minimum field width. If *width* is not specified, there is no minimum
13513
- field width, and the field width is determined based on the content of
13514
- the field.
13515
-
13516
- The *width* of a string is defined as the estimated number of column
13517
- positions appropriate for displaying it in a terminal.
13518
-
13519
- [*Note 5*: This is similar to the semantics of the POSIX `wcswidth`
13520
- function. — *end note*]
13521
-
13522
- For the purposes of width computation, a string is assumed to be in a
13523
- locale-independent, implementation-defined encoding. Implementations
13524
- should use a Unicode encoding on platforms capable of displaying Unicode
13525
- text in a terminal.
13526
-
13527
- [*Note 6*: This is the case for Windows-based and many POSIX-based
13528
- operating systems. — *end note*]
13529
-
13530
- For a string in a Unicode encoding, implementations should estimate the
13531
- width of a string as the sum of estimated widths of the first code
13532
- points in its extended grapheme clusters. The extended grapheme clusters
13533
- of a string are defined by UAX \#29. The estimated width of the
13534
- following code points is 2:
13535
-
13536
- - `U+1100-U+115F`
13537
- - `U+2329-U+232A`
13538
- - `U+2E80-U+303E`
13539
- - `U+3040-U+A4CF`
13540
- - `U+AC00-U+D7A3`
13541
- - `U+F900-U+FAFF`
13542
- - `U+FE10-U+FE19`
13543
- - `U+FE30-U+FE6F`
13544
- - `U+FF00-U+FF60`
13545
- - `U+FFE0-U+FFE6`
13546
- - `U+1F300-U+1F64F`
13547
- - `U+1F900-U+1F9FF`
13548
- - `U+20000-U+2FFFD`
13549
- - `U+30000-U+3FFFD`
13550
-
13551
- The estimated width of other code points is 1.
13552
-
13553
- For a string in a non-Unicode encoding, the width of a string is
13554
- unspecified.
13555
-
13556
- A zero (`0`) character preceding the *width* field pads the field with
13557
- leading zeros (following any indication of sign or base) to the field
13558
- width, except when applied to an infinity or NaN. This option is only
13559
- valid for arithmetic types other than `charT` and `bool` or when an
13560
- integer presentation type is specified. If the `0` character and an
13561
- *align* option both appear, the `0` character is ignored.
13562
 
13563
  [*Example 3*:
13564
 
13565
  ``` cpp
13566
  char c = 120;
13567
  string s1 = format("{:+06d}", c); // value of s1 is "+00120"
13568
  string s2 = format("{:#06x}", 0xa); // value of s2 is "0x000a"
13569
- string s3 = format("{:<06}", -42); // value of s3 is "-42\ \ \ " (0 is ignored because of < alignment)
 
13570
  ```
13571
 
13572
  — *end example*]
13573
 
13574
- The *nonnegative-integer* in *precision* is a decimal integer defining
13575
- the precision or maximum field size. It can only be used with
13576
- floating-point and string types. For floating-point types this field
13577
- specifies the formatting precision. For string types, this field
13578
- provides an upper bound for the estimated width of the prefix of the
13579
- input string that is copied into the output. For a string in a Unicode
13580
- encoding, the formatter copies to the output the longest prefix of whole
13581
- extended grapheme clusters whose estimated width is no greater than the
13582
- precision.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13583
 
13584
  When the `L` option is used, the form used for the conversion is called
13585
  the *locale-specific form*. The `L` option is only valid for arithmetic
13586
  types, and its effect depends upon the type.
13587
 
@@ -13602,22 +10784,23 @@ The available string presentation types are specified in
13602
  [[format.type.string]].
13603
 
13604
  **Table: Meaning of type options for strings** <a id="format.type.string">[format.type.string]</a>
13605
 
13606
  | Type | Meaning |
13607
- | --------- | -------------------------------- |
13608
  | none, `s` | Copies the string to the output. |
 
13609
 
13610
 
13611
  The meaning of some non-string presentation types is defined in terms of
13612
  a call to `to_chars`. In such cases, let \[`first`, `last`) be a range
13613
  large enough to hold the `to_chars` output and `value` be the formatting
13614
  argument value. Formatting is done as if by calling `to_chars` as
13615
  specified and copying the output through the output iterator of the
13616
  format context.
13617
 
13618
- [*Note 7*: Additional padding and adjustments are performed prior to
13619
  copying the output through the output iterator as specified by the
13620
  format specifiers. — *end note*]
13621
 
13622
  The available integer presentation types for integral types other than
13623
  `bool` and `charT` are specified in [[format.type.int]].
@@ -13626,49 +10809,61 @@ The available integer presentation types for integral types other than
13626
 
13627
  ``` cpp
13628
  string s0 = format("{}", 42); // value of s0 is "42"
13629
  string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); // value of s1 is "101010 42 52 2a"
13630
  string s2 = format("{0:#x} {0:#X}", 42); // value of s2 is "0x2a 0X2A"
13631
- string s3 = format("{:L}", 1234); // value of s3 might be "1,234"
13632
  // (depending on the locale)
13633
  ```
13634
 
13635
  — *end example*]
13636
 
13637
- [*Note 8*: If the formatting argument type is `charT` or `bool`, the
13638
- default is instead `c` or `s`, respectively. — *end note*]
 
 
 
 
 
 
 
 
 
 
 
13639
 
13640
  The available `charT` presentation types are specified in
13641
  [[format.type.char]].
13642
 
13643
  **Table: Meaning of type options for `charT`** <a id="format.type.char">[format.type.char]</a>
13644
 
13645
  | Type | Meaning |
13646
- | ------------------------------ | ------------------------------------ |
13647
  | none, `c` | Copies the character to the output. |
13648
  | % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]]. |
 
13649
 
13650
 
13651
  The available `bool` presentation types are specified in
13652
  [[format.type.bool]].
13653
 
13654
  **Table: Meaning of type options for `bool`** <a id="format.type.bool">[format.type.bool]</a>
13655
 
13656
  | Type | Meaning |
13657
- | ----------------------------------- | -------------------------------------------------------------------------------------- |
13658
  | none, `s` | Copies textual representation, either `true` or `false`, to the output. |
13659
- | % `b`, `B`, `c`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]] for the value `static_cast<unsigned char>(value)`. |
13660
 
13661
 
13662
  The available floating-point presentation types and their meanings for
13663
  values other than infinity and NaN are specified in
13664
  [[format.type.float]]. For lower-case presentation types, infinity and
13665
  NaN are formatted as `inf` and `nan`, respectively. For upper-case
13666
  presentation types, infinity and NaN are formatted as `INF` and `NAN`,
13667
  respectively.
13668
 
13669
- [*Note 9*: In either case, a sign is included if indicated by the
13670
  *sign* option. — *end note*]
13671
 
13672
  **Table: Meaning of type options for floating-point types** <a id="format.type.float">[format.type.float]</a>
13673
 
13674
  | Type | Meaning |
@@ -13684,77 +10879,107 @@ respectively.
13684
 
13685
 
13686
  The available pointer presentation types and their mapping to `to_chars`
13687
  are specified in [[format.type.ptr]].
13688
 
13689
- [*Note 10*: Pointer presentation types also apply to
13690
  `nullptr_t`. — *end note*]
13691
 
13692
  **Table: Meaning of type options for pointer types** <a id="format.type.ptr">[format.type.ptr]</a>
13693
 
13694
  | Type | Meaning |
13695
- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13696
- | 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` added to the output; otherwise, implementation-defined. |
13697
 
13698
 
13699
  ### Error reporting <a id="format.err.report">[[format.err.report]]</a>
13700
 
13701
  Formatting functions throw `format_error` if an argument `fmt` is passed
13702
  that is not a format string for `args`. They propagate exceptions thrown
13703
  by operations of `formatter` specializations and iterators. Failure to
13704
  allocate storage is reported by throwing an exception as described in 
13705
  [[res.on.exception.handling]].
13706
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13707
  ### Formatting functions <a id="format.functions">[[format.functions]]</a>
13708
 
13709
  In the description of the functions, operator `+` is used for some of
13710
  the iterator categories for which it does not have to be defined. In
13711
  these cases the semantics of `a + n` are the same as in
13712
  [[algorithms.requirements]].
13713
 
13714
  ``` cpp
13715
  template<class... Args>
13716
- string format(string_view fmt, const Args&... args);
13717
  ```
13718
 
13719
  *Effects:* Equivalent to:
13720
 
13721
  ``` cpp
13722
- return vformat(fmt, make_format_args(args...));
13723
  ```
13724
 
13725
  ``` cpp
13726
  template<class... Args>
13727
- wstring format(wstring_view fmt, const Args&... args);
13728
  ```
13729
 
13730
  *Effects:* Equivalent to:
13731
 
13732
  ``` cpp
13733
- return vformat(fmt, make_wformat_args(args...));
13734
  ```
13735
 
13736
  ``` cpp
13737
  template<class... Args>
13738
- string format(const locale& loc, string_view fmt, const Args&... args);
13739
  ```
13740
 
13741
  *Effects:* Equivalent to:
13742
 
13743
  ``` cpp
13744
- return vformat(loc, fmt, make_format_args(args...));
13745
  ```
13746
 
13747
  ``` cpp
13748
  template<class... Args>
13749
- wstring format(const locale& loc, wstring_view fmt, const Args&... args);
13750
  ```
13751
 
13752
  *Effects:* Equivalent to:
13753
 
13754
  ``` cpp
13755
- return vformat(loc, fmt, make_wformat_args(args...));
13756
  ```
13757
 
13758
  ``` cpp
13759
  string vformat(string_view fmt, format_args args);
13760
  wstring vformat(wstring_view fmt, wformat_args args);
@@ -13769,98 +10994,108 @@ locale-specific formatting.
13769
 
13770
  *Throws:* As specified in  [[format.err.report]].
13771
 
13772
  ``` cpp
13773
  template<class Out, class... Args>
13774
- Out format_to(Out out, string_view fmt, const Args&... args);
 
 
 
 
 
 
 
 
 
13775
  template<class Out, class... Args>
13776
- Out format_to(Out out, wstring_view fmt, const Args&... args);
13777
  ```
13778
 
13779
  *Effects:* Equivalent to:
13780
 
13781
  ``` cpp
13782
- using context = basic_format_context<Out, decltype(fmt)::value_type>;
13783
- return vformat_to(out, fmt, make_format_args<context>(args...));
13784
  ```
13785
 
13786
  ``` cpp
13787
  template<class Out, class... Args>
13788
- Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
 
 
 
 
 
 
 
 
 
13789
  template<class Out, class... Args>
13790
- Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
13791
  ```
13792
 
13793
  *Effects:* Equivalent to:
13794
 
13795
  ``` cpp
13796
- using context = basic_format_context<Out, decltype(fmt)::value_type>;
13797
- return vformat_to(out, loc, fmt, make_format_args<context>(args...));
13798
  ```
13799
 
13800
  ``` cpp
13801
  template<class Out>
13802
- Out vformat_to(Out out, string_view fmt,
13803
- format_args_t<type_identity_t<Out>, char> args);
13804
  template<class Out>
13805
- Out vformat_to(Out out, wstring_view fmt,
13806
- format_args_t<type_identity_t<Out>, wchar_t> args);
13807
  template<class Out>
13808
- Out vformat_to(Out out, const locale& loc, string_view fmt,
13809
- format_args_t<type_identity_t<Out>, char> args);
13810
  template<class Out>
13811
- Out vformat_to(Out out, const locale& loc, wstring_view fmt,
13812
- format_args_t<type_identity_t<Out>, wchar_t> args);
13813
  ```
13814
 
13815
  Let `charT` be `decltype(fmt)::value_type`.
13816
 
13817
  *Constraints:* `Out` satisfies `output_iterator<const charT&>`.
13818
 
13819
  *Preconditions:* `Out` models `output_iterator<const charT&>`.
13820
 
13821
  *Effects:* Places the character representation of formatting the
13822
  arguments provided by `args`, formatted according to the specifications
13823
- given in `fmt`, into the range \[`out`, `out + N`), where `N` is
13824
- `formatted_size(fmt, args...)` for the functions without a `loc`
13825
- parameter and `formatted_size(loc, fmt, args...)` for the functions with
13826
- a `loc` parameter. If present, `loc` is used for locale-specific
13827
- formatting.
13828
 
13829
  *Returns:* `out + N`.
13830
 
13831
  *Throws:* As specified in  [[format.err.report]].
13832
 
13833
  ``` cpp
13834
  template<class Out, class... Args>
13835
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13836
- string_view fmt, const Args&... args);
13837
  template<class Out, class... Args>
13838
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13839
- wstring_view fmt, const Args&... args);
13840
  template<class Out, class... Args>
13841
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13842
- const locale& loc, string_view fmt,
13843
- const Args&... args);
13844
  template<class Out, class... Args>
13845
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
13846
- const locale& loc, wstring_view fmt,
13847
- const Args&... args);
13848
  ```
13849
 
13850
  Let
13851
 
13852
- - `charT` be `decltype(fmt)::value_type`,
13853
  - `N` be `formatted_size(fmt, args...)` for the functions without a
13854
  `loc` parameter and `formatted_size(loc, fmt, args...)` for the
13855
  functions with a `loc` parameter, and
13856
  - `M` be `clamp(n, 0, N)`.
13857
 
13858
  *Constraints:* `Out` satisfies `output_iterator<const charT&>`.
13859
 
13860
  *Preconditions:* `Out` models `output_iterator<const charT&>`, and
13861
- `formatter<``Tᵢ``, charT>` meets the
13862
  requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
13863
 
13864
  *Effects:* Places the first `M` characters of the character
13865
  representation of formatting the arguments provided by `args`, formatted
13866
  according to the specifications given in `fmt`, into the range \[`out`,
@@ -13870,22 +11105,22 @@ according to the specifications given in `fmt`, into the range \[`out`,
13870
 
13871
  *Throws:* As specified in  [[format.err.report]].
13872
 
13873
  ``` cpp
13874
  template<class... Args>
13875
- size_t formatted_size(string_view fmt, const Args&... args);
13876
  template<class... Args>
13877
- size_t formatted_size(wstring_view fmt, const Args&... args);
13878
  template<class... Args>
13879
- size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
13880
  template<class... Args>
13881
- size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
13882
  ```
13883
 
13884
- Let `charT` be `decltype(fmt)::value_type`.
13885
 
13886
- *Preconditions:* `formatter<``Tᵢ``, charT>` meets the
13887
  requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
13888
 
13889
  *Returns:* The number of characters in the character representation of
13890
  formatting arguments `args` formatted according to specifications given
13891
  in `fmt`. If present, `loc` is used for locale-specific formatting.
@@ -13894,27 +11129,30 @@ in `fmt`. If present, `loc` is used for locale-specific formatting.
13894
 
13895
  ### Formatter <a id="format.formatter">[[format.formatter]]</a>
13896
 
13897
  #### Formatter requirements <a id="formatter.requirements">[[formatter.requirements]]</a>
13898
 
13899
- A type `F` meets the requirements if:
13900
 
13901
- - it meets the
13902
  - *Cpp17DefaultConstructible* ([[cpp17.defaultconstructible]]),
13903
  - *Cpp17CopyConstructible* ([[cpp17.copyconstructible]]),
13904
- - *Cpp17CopyAssignable* ([[cpp17.copyassignable]]), and
 
13905
  - *Cpp17Destructible* ([[cpp17.destructible]])
13906
 
13907
- requirements,
13908
- - it is swappable [[swappable.requirements]] for lvalues, and
13909
- - the expressions shown in [[formatter]] are valid and have the
13910
- indicated semantics.
 
 
13911
 
13912
  Given character type `charT`, output iterator type `Out`, and formatting
13913
- argument type `T`, in [[formatter]]:
13914
 
13915
- - `f` is a value of type `F`,
 
13916
  - `u` is an lvalue of type `T`,
13917
  - `t` is a value of a type convertible to (possibly const) `T`,
13918
  - `PC` is `basic_format_parse_context<charT>`,
13919
  - `FC` is `basic_format_context<Out, charT>`,
13920
  - `pc` is an lvalue of type `PC`, and
@@ -13926,35 +11164,70 @@ string. If *format-spec* is empty then either `pc.begin() == pc.end()`
13926
  or `*pc.begin() == '}'`.
13927
 
13928
  [*Note 1*: This allows formatters to emit meaningful error
13929
  messages. — *end note*]
13930
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
13931
  #### Formatter specializations <a id="format.formatter.spec">[[format.formatter.spec]]</a>
13932
 
13933
  The functions defined in [[format.functions]] use specializations of the
13934
  class template `formatter` to format individual arguments.
13935
 
13936
  Let `charT` be either `char` or `wchar_t`. Each specialization of
13937
- `formatter` is either enabled or disabled, as described below.
 
 
 
 
 
 
13938
 
13939
- [*Note 1*: Enabled specializations meet the requirements, and disabled
13940
- specializations do not. — *end note*]
13941
-
13942
- Each header that declares the template `formatter` provides the
13943
- following enabled specializations:
13944
-
13945
- - The specializations
13946
  ``` cpp
13947
  template<> struct formatter<char, char>;
13948
  template<> struct formatter<char, wchar_t>;
13949
  template<> struct formatter<wchar_t, wchar_t>;
13950
  ```
13951
- - For each `charT`, the string type specializations
13952
  ``` cpp
13953
  template<> struct formatter<charT*, charT>;
13954
  template<> struct formatter<const charT*, charT>;
13955
- template<size_t N> struct formatter<const charT[N], charT>;
13956
  template<class traits, class Allocator>
13957
  struct formatter<basic_string<charT, traits, Allocator>, charT>;
13958
  template<class traits>
13959
  struct formatter<basic_string_view<charT, traits>, charT>;
13960
  ```
@@ -13973,21 +11246,21 @@ following enabled specializations:
13973
 
13974
  The `parse` member functions of these formatters interpret the format
13975
  specification as a *std-format-spec* as described in
13976
  [[format.string.std]].
13977
 
13978
- [*Note 2*: Specializations such as `formatter<wchar_t, char>` and
13979
  `formatter<const char*, wchar_t>` that would require implicit multibyte
13980
  / wide string or character conversion are disabled. — *end note*]
13981
 
13982
  For any types `T` and `charT` for which neither the library nor the user
13983
  provides an explicit or partial specialization of the class template
13984
  `formatter`, `formatter<T, charT>` is disabled.
13985
 
13986
  If the library provides an explicit or partial specialization of
13987
- `formatter<T, charT>`, that specialization is enabled except as noted
13988
- otherwise.
13989
 
13990
  If `F` is a disabled specialization of `formatter`, these values are
13991
  `false`:
13992
 
13993
  - `is_default_constructible_v<F>`,
@@ -14006,11 +11279,11 @@ An enabled specialization `formatter<T, charT>` meets the requirements
14006
 
14007
  enum color { red, green, blue };
14008
  const char* color_names[] = { "red", "green", "blue" };
14009
 
14010
  template<> struct std::formatter<color> : std::formatter<const char*> {
14011
- auto format(color c, format_context& ctx) {
14012
  return formatter<const char*>::format(color_names[c], ctx);
14013
  }
14014
  };
14015
 
14016
  struct err {};
@@ -14021,10 +11294,95 @@ std::string s2 = std::format("{}", red); // OK, user-provided formatter
14021
  std::string s3 = std::format("{}", err{}); // error: disabled formatter
14022
  ```
14023
 
14024
  — *end example*]
14025
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14026
  #### Class template `basic_format_parse_context` <a id="format.parse.ctx">[[format.parse.ctx]]</a>
14027
 
14028
  ``` cpp
14029
  namespace std {
14030
  template<class charT>
@@ -14093,37 +11451,41 @@ constexpr void advance_to(const_iterator it);
14093
 
14094
  ``` cpp
14095
  constexpr size_t next_arg_id();
14096
  ```
14097
 
14098
- *Effects:* If `indexing_ != manual`, equivalent to:
14099
 
14100
  ``` cpp
14101
  if (indexing_ == unknown)
14102
  indexing_ = automatic;
14103
  return next_arg_id_++;
14104
  ```
14105
 
14106
- *Throws:* `format_error` if `indexing_ == manual` which indicates mixing
14107
- of automatic and manual argument indexing.
 
 
 
 
14108
 
14109
  ``` cpp
14110
  constexpr void check_arg_id(size_t id);
14111
  ```
14112
 
14113
- *Effects:* If `indexing_ != automatic`, equivalent to:
14114
 
14115
  ``` cpp
14116
  if (indexing_ == unknown)
14117
  indexing_ = manual;
14118
  ```
14119
 
14120
- *Throws:* `format_error` if `indexing_ == automatic` which indicates
14121
- mixing of automatic and manual argument indexing.
14122
 
14123
- *Remarks:* Call expressions where `id >= num_args_` are not core
14124
- constant expressions [[expr.const]].
14125
 
14126
  #### Class template `basic_format_context` <a id="format.context">[[format.context]]</a>
14127
 
14128
  ``` cpp
14129
  namespace std {
@@ -14135,11 +11497,11 @@ namespace std {
14135
  public:
14136
  using iterator = Out;
14137
  using char_type = charT;
14138
  template<class T> using formatter_type = formatter<T, charT>;
14139
 
14140
- basic_format_arg<basic_format_context> arg(size_t id) const;
14141
  std::locale locale();
14142
 
14143
  iterator out();
14144
  void advance_to(iterator it);
14145
  };
@@ -14155,19 +11517,18 @@ of the formatting arguments and the output iterator.
14155
  `basic_format_context` with an output iterator that appends to `string`,
14156
  such as `back_insert_iterator<string>`. Similarly, `wformat_context` is
14157
  an alias for a specialization of `basic_format_context` with an output
14158
  iterator that appends to `wstring`.
14159
 
14160
- [*Note 1*: For a given type `charT`, implementations are encouraged to
14161
  provide a single instantiation of `basic_format_context` for appending
14162
  to `basic_string<charT>`, `vector<charT>`, or any other container with
14163
  contiguous storage by wrapping those in temporary objects with a uniform
14164
- interface (such as a `span<charT>`) and polymorphic
14165
- reallocation. — *end note*]
14166
 
14167
  ``` cpp
14168
- basic_format_arg<basic_format_context> arg(size_t id) const;
14169
  ```
14170
 
14171
  *Returns:* `args_.get(id)`.
14172
 
14173
  ``` cpp
@@ -14179,17 +11540,17 @@ takes one, and `std::locale()` otherwise.
14179
 
14180
  ``` cpp
14181
  iterator out();
14182
  ```
14183
 
14184
- *Returns:* `out_`.
14185
 
14186
  ``` cpp
14187
  void advance_to(iterator it);
14188
  ```
14189
 
14190
- *Effects:* Equivalent to: `out_ = it;`
14191
 
14192
  [*Example 1*:
14193
 
14194
  ``` cpp
14195
  struct S { int value; };
@@ -14211,11 +11572,11 @@ template<> struct std::formatter<S> {
14211
  ctx.check_arg_id(width_arg_id);
14212
  return ++iter;
14213
  }
14214
 
14215
  // Formats an S with width given by the argument width_arg_id.
14216
- auto format(S s, format_context& ctx) {
14217
  int width = visit_format_arg([](auto value) -> int {
14218
  if constexpr (!is_integral_v<decltype(value)>)
14219
  throw format_error("width is not integral");
14220
  else if (value < 0 || value > numeric_limits<int>::max())
14221
  throw format_error("invalid width");
@@ -14229,10 +11590,425 @@ template<> struct std::formatter<S> {
14229
  std::string s = std::format("{0:{1}}", S{42}, 10); // value of s is "xxxxxxxx42"
14230
  ```
14231
 
14232
  — *end example*]
14233
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14234
  ### Arguments <a id="format.arguments">[[format.arguments]]</a>
14235
 
14236
  #### Class template `basic_format_arg` <a id="format.arg">[[format.arg]]</a>
14237
 
14238
  ``` cpp
@@ -14249,28 +12025,11 @@ namespace std {
14249
  int, unsigned int, long long int, unsigned long long int,
14250
  float, double, long double,
14251
  const char_type*, basic_string_view<char_type>,
14252
  const void*, handle> value; // exposition only
14253
 
14254
- template<class T> explicit basic_format_arg(const T& v) noexcept; // exposition only
14255
- explicit basic_format_arg(float n) noexcept; // exposition only
14256
- explicit basic_format_arg(double n) noexcept; // exposition only
14257
- explicit basic_format_arg(long double n) noexcept; // exposition only
14258
- explicit basic_format_arg(const char_type* s); // exposition only
14259
-
14260
- template<class traits>
14261
- explicit basic_format_arg(
14262
- basic_string_view<char_type, traits> s) noexcept; // exposition only
14263
-
14264
- template<class traits, class Allocator>
14265
- explicit basic_format_arg(
14266
- const basic_string<char_type, traits, Allocator>& s) noexcept; // exposition only
14267
-
14268
- explicit basic_format_arg(nullptr_t) noexcept; // exposition only
14269
-
14270
- template<class T>
14271
- explicit basic_format_arg(const T* p) noexcept; // exposition only
14272
 
14273
  public:
14274
  basic_format_arg() noexcept;
14275
 
14276
  explicit operator bool() const noexcept;
@@ -14289,95 +12048,47 @@ basic_format_arg() noexcept;
14289
  ```
14290
 
14291
  *Ensures:* `!(*this)`.
14292
 
14293
  ``` cpp
14294
- template<class T> explicit basic_format_arg(const T& v) noexcept;
14295
  ```
14296
 
14297
- *Constraints:* The template specialization
14298
 
14299
- ``` cpp
14300
- typename Context::template formatter_type<T>
14301
- ```
14302
-
14303
- meets the requirements [[formatter.requirements]]. The extent to which
14304
- an implementation determines that the specialization meets the
14305
- requirements is unspecified, except that as a minimum the expression
14306
-
14307
- ``` cpp
14308
- typename Context::template formatter_type<T>()
14309
- .format(declval<const T&>(), declval<Context&>())
14310
- ```
14311
-
14312
- shall be well-formed when treated as an unevaluated operand.
14313
 
14314
- *Effects:*
14315
 
14316
- - if `T` is `bool` or `char_type`, initializes `value` with `v`;
14317
- - otherwise, if `T` is `char` and `char_type` is `wchar_t`, initializes
14318
  `value` with `static_cast<wchar_t>(v)`;
14319
- - otherwise, if `T` is a signed integer type [[basic.fundamental]] and
14320
- `sizeof(T) <= sizeof(int)`, initializes `value` with
14321
  `static_cast<int>(v)`;
14322
- - otherwise, if `T` is an unsigned integer type and
14323
- `sizeof(T) <= sizeof(unsigned int)`, initializes `value` with
14324
  `static_cast<unsigned int>(v)`;
14325
- - otherwise, if `T` is a signed integer type and
14326
- `sizeof(T) <= sizeof(long long int)`, initializes `value` with
14327
  `static_cast<long long int>(v)`;
14328
- - otherwise, if `T` is an unsigned integer type and
14329
- `sizeof(T) <= sizeof(unsigned long long int)`, initializes `value`
14330
  with `static_cast<unsigned long long int>(v)`;
 
 
 
 
 
 
 
 
 
 
14331
  - otherwise, initializes `value` with `handle(v)`.
14332
 
14333
- ``` cpp
14334
- explicit basic_format_arg(float n) noexcept;
14335
- explicit basic_format_arg(double n) noexcept;
14336
- explicit basic_format_arg(long double n) noexcept;
14337
- ```
14338
-
14339
- *Effects:* Initializes `value` with `n`.
14340
-
14341
- ``` cpp
14342
- explicit basic_format_arg(const char_type* s);
14343
- ```
14344
-
14345
- *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
14346
-
14347
- *Effects:* Initializes `value` with `s`.
14348
-
14349
- ``` cpp
14350
- template<class traits>
14351
- explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
14352
- ```
14353
-
14354
- *Effects:* Initializes `value` with `s`.
14355
-
14356
- ``` cpp
14357
- template<class traits, class Allocator>
14358
- explicit basic_format_arg(
14359
- const basic_string<char_type, traits, Allocator>& s) noexcept;
14360
- ```
14361
-
14362
- *Effects:* Initializes `value` with
14363
- `basic_string_view<char_type>(s.data(), s.size())`.
14364
-
14365
- ``` cpp
14366
- explicit basic_format_arg(nullptr_t) noexcept;
14367
- ```
14368
-
14369
- *Effects:* Initializes `value` with `static_cast<const void*>(nullptr)`.
14370
-
14371
- ``` cpp
14372
- template<class T> explicit basic_format_arg(const T* p) noexcept;
14373
- ```
14374
-
14375
- *Constraints:* `is_void_v<T>` is `true`.
14376
-
14377
- *Effects:* Initializes `value` with `p`.
14378
-
14379
  [*Note 1*: Constructing `basic_format_arg` from a pointer to a member
14380
  is ill-formed unless the user provides an enabled specialization of
14381
  `formatter` for that pointer to member type. — *end note*]
14382
 
14383
  ``` cpp
@@ -14394,32 +12105,41 @@ namespace std {
14394
  class basic_format_arg<Context>::handle {
14395
  const void* ptr_; // exposition only
14396
  void (*format_)(basic_format_parse_context<char_type>&,
14397
  Context&, const void*); // exposition only
14398
 
14399
- template<class T> explicit handle(const T& val) noexcept; // exposition only
14400
 
14401
  friend class basic_format_arg<Context>; // exposition only
14402
 
14403
  public:
14404
  void format(basic_format_parse_context<char_type>&, Context& ctx) const;
14405
  };
14406
  }
14407
  ```
14408
 
14409
  ``` cpp
14410
- template<class T> explicit handle(const T& val) noexcept;
14411
  ```
14412
 
 
 
 
 
 
 
 
 
14413
  *Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
14414
 
14415
  ``` cpp
14416
  [](basic_format_parse_context<char_type>& parse_ctx,
14417
  Context& format_ctx, const void* ptr) {
14418
- typename Context::template formatter_type<T> f;
14419
  parse_ctx.advance_to(f.parse(parse_ctx));
14420
- format_ctx.advance_to(f.format(*static_cast<const T*>(ptr), format_ctx));
 
14421
  }
14422
  ```
14423
 
14424
  ``` cpp
14425
  void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
@@ -14427,43 +12147,46 @@ void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ct
14427
 
14428
  *Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
14429
 
14430
  ``` cpp
14431
  template<class Visitor, class Context>
14432
- see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
14433
  ```
14434
 
14435
  *Effects:* Equivalent to:
14436
- `return visit(forward<Visitor>(vis), arg.value);`
14437
 
14438
  #### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
14439
 
14440
  ``` cpp
14441
  namespace std {
14442
  template<class Context, class... Args>
14443
- struct format-arg-store { // exposition only
14444
- array<basic_format_arg<Context>, sizeof...(Args)> args;
14445
  };
14446
  }
14447
  ```
14448
 
14449
  An instance of *`format-arg-store`* stores formatting arguments.
14450
 
14451
  ``` cpp
14452
  template<class Context = format_context, class... Args>
14453
- format-arg-store<Context, Args...> make_format_args(const Args&... args);
14454
  ```
14455
 
14456
  *Preconditions:* The type
14457
- `typename Context::template formatter_type<``Tᵢ``>` meets the
14458
- requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
 
14459
 
14460
- *Returns:* `{basic_format_arg<Context>(args)...}`.
 
 
14461
 
14462
  ``` cpp
14463
  template<class... Args>
14464
- format-arg-store<wformat_context, Args...> make_wformat_args(const Args&... args);
14465
  ```
14466
 
14467
  *Effects:* Equivalent to:
14468
  `return make_format_args<wformat_context>(args...);`
14469
 
@@ -14482,15 +12205,22 @@ namespace std {
14482
  template<class... Args>
14483
  basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
14484
 
14485
  basic_format_arg<Context> get(size_t i) const noexcept;
14486
  };
 
 
 
14487
  }
14488
  ```
14489
 
14490
  An instance of `basic_format_args` provides access to formatting
14491
- arguments.
 
 
 
 
14492
 
14493
  ``` cpp
14494
  basic_format_args() noexcept;
14495
  ```
14496
 
@@ -14508,14 +12238,140 @@ template<class... Args>
14508
  basic_format_arg<Context> get(size_t i) const noexcept;
14509
  ```
14510
 
14511
  *Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
14512
 
14513
- [*Note 1*: Implementations are encouraged to optimize the
14514
- representation of `basic_format_args` for small number of formatting
14515
- arguments by storing indices of type alternatives separately from values
14516
- and packing the former. *end note*]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14517
 
14518
  ### Class `format_error` <a id="format.error">[[format.error]]</a>
14519
 
14520
  ``` cpp
14521
  namespace std {
@@ -14540,128 +12396,423 @@ format_error(const string& what_arg);
14540
  format_error(const char* what_arg);
14541
  ```
14542
 
14543
  *Ensures:* `strcmp(what(), what_arg) == 0`.
14544
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14545
  <!-- Link reference definitions -->
14546
- [alg.sorting]: algorithms.md#alg.sorting
14547
  [algorithms]: algorithms.md#algorithms
14548
  [algorithms.general]: algorithms.md#algorithms.general
14549
  [algorithms.requirements]: algorithms.md#algorithms.requirements
14550
- [allocator.adaptor]: #allocator.adaptor
14551
- [allocator.adaptor.cnstr]: #allocator.adaptor.cnstr
14552
- [allocator.adaptor.members]: #allocator.adaptor.members
14553
- [allocator.adaptor.syn]: #allocator.adaptor.syn
14554
- [allocator.adaptor.types]: #allocator.adaptor.types
14555
- [allocator.globals]: #allocator.globals
14556
- [allocator.members]: #allocator.members
14557
- [allocator.requirements.completeness]: library.md#allocator.requirements.completeness
14558
- [allocator.tag]: #allocator.tag
14559
- [allocator.traits]: #allocator.traits
14560
- [allocator.traits.members]: #allocator.traits.members
14561
- [allocator.traits.types]: #allocator.traits.types
14562
- [allocator.uses]: #allocator.uses
14563
- [allocator.uses.construction]: #allocator.uses.construction
14564
- [allocator.uses.trait]: #allocator.uses.trait
14565
  [any]: #any
14566
  [any.assign]: #any.assign
14567
  [any.bad.any.cast]: #any.bad.any.cast
14568
  [any.class]: #any.class
 
14569
  [any.cons]: #any.cons
 
14570
  [any.modifiers]: #any.modifiers
14571
  [any.nonmembers]: #any.nonmembers
14572
  [any.observers]: #any.observers
14573
  [any.synop]: #any.synop
14574
  [arithmetic.operations]: #arithmetic.operations
14575
  [arithmetic.operations.divides]: #arithmetic.operations.divides
 
14576
  [arithmetic.operations.minus]: #arithmetic.operations.minus
14577
  [arithmetic.operations.modulus]: #arithmetic.operations.modulus
14578
  [arithmetic.operations.multiplies]: #arithmetic.operations.multiplies
14579
  [arithmetic.operations.negate]: #arithmetic.operations.negate
14580
  [arithmetic.operations.plus]: #arithmetic.operations.plus
14581
- [array]: containers.md#array
14582
  [associative]: containers.md#associative
14583
- [basic.align]: basic.md#basic.align
14584
- [basic.compound]: basic.md#basic.compound
14585
- [basic.def.odr]: basic.md#basic.def.odr
14586
  [basic.fundamental]: basic.md#basic.fundamental
14587
- [basic.life]: basic.md#basic.life
14588
- [basic.stc.dynamic.allocation]: basic.md#basic.stc.dynamic.allocation
14589
- [basic.stc.dynamic.safety]: basic.md#basic.stc.dynamic.safety
14590
- [basic.types]: basic.md#basic.types
 
 
 
 
 
 
 
 
14591
  [bitmask.types]: library.md#bitmask.types
14592
  [bitset]: #bitset
14593
  [bitset.cons]: #bitset.cons
14594
  [bitset.hash]: #bitset.hash
14595
  [bitset.members]: #bitset.members
14596
  [bitset.operators]: #bitset.operators
14597
  [bitset.syn]: #bitset.syn
14598
  [bitwise.operations]: #bitwise.operations
14599
  [bitwise.operations.and]: #bitwise.operations.and
 
14600
  [bitwise.operations.not]: #bitwise.operations.not
14601
  [bitwise.operations.or]: #bitwise.operations.or
14602
  [bitwise.operations.xor]: #bitwise.operations.xor
14603
- [c.malloc]: #c.malloc
14604
  [charconv]: #charconv
14605
  [charconv.from.chars]: #charconv.from.chars
14606
  [charconv.syn]: #charconv.syn
14607
  [charconv.to.chars]: #charconv.to.chars
 
14608
  [class.copy.ctor]: class.md#class.copy.ctor
14609
- [class.mem]: class.md#class.mem
14610
  [comparisons]: #comparisons
14611
  [comparisons.equal.to]: #comparisons.equal.to
 
14612
  [comparisons.greater]: #comparisons.greater
14613
  [comparisons.greater.equal]: #comparisons.greater.equal
14614
  [comparisons.less]: #comparisons.less
14615
  [comparisons.less.equal]: #comparisons.less.equal
14616
  [comparisons.not.equal.to]: #comparisons.not.equal.to
14617
  [comparisons.three.way]: #comparisons.three.way
14618
  [concepts.equality]: concepts.md#concepts.equality
14619
- [conv.array]: expr.md#conv.array
14620
- [conv.func]: expr.md#conv.func
14621
- [conv.lval]: expr.md#conv.lval
14622
- [conv.qual]: expr.md#conv.qual
14623
- [conv.rank]: basic.md#conv.rank
14624
- [cpp17.allocator]: #cpp17.allocator
14625
  [cpp17.copyassignable]: #cpp17.copyassignable
14626
  [cpp17.copyconstructible]: #cpp17.copyconstructible
14627
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
14628
  [cpp17.destructible]: #cpp17.destructible
14629
  [cpp17.hash]: #cpp17.hash
14630
  [cpp17.moveassignable]: #cpp17.moveassignable
14631
  [cpp17.moveconstructible]: #cpp17.moveconstructible
14632
- [cpp17.nullablepointer]: #cpp17.nullablepointer
14633
- [dcl.array]: dcl.md#dcl.array
14634
  [dcl.constexpr]: dcl.md#dcl.constexpr
14635
- [dcl.ref]: dcl.md#dcl.ref
14636
  [declval]: #declval
14637
- [default.allocator]: #default.allocator
14638
- [defns.const.subexpr]: library.md#defns.const.subexpr
14639
- [defns.expression-equivalent]: library.md#defns.expression-equivalent
14640
- [defns.ntcts]: library.md#defns.ntcts
14641
  [defns.order.ptr]: #defns.order.ptr
14642
- [defns.referenceable]: library.md#defns.referenceable
 
14643
  [execpol]: #execpol
14644
  [execpol.general]: #execpol.general
14645
  [execpol.objects]: #execpol.objects
14646
  [execpol.par]: #execpol.par
14647
  [execpol.parunseq]: #execpol.parunseq
14648
  [execpol.seq]: #execpol.seq
14649
  [execpol.type]: #execpol.type
14650
  [execpol.unseq]: #execpol.unseq
14651
  [execution.syn]: #execution.syn
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14652
  [expr.add]: expr.md#expr.add
14653
- [expr.alignof]: expr.md#expr.alignof
14654
  [expr.bit.and]: expr.md#expr.bit.and
14655
  [expr.call]: expr.md#expr.call
14656
  [expr.const]: expr.md#expr.const
14657
  [expr.eq]: expr.md#expr.eq
14658
  [expr.log.and]: expr.md#expr.log.and
14659
  [expr.log.or]: expr.md#expr.log.or
14660
  [expr.mul]: expr.md#expr.mul
14661
  [expr.or]: expr.md#expr.or
14662
- [expr.prop]: expr.md#expr.prop
14663
  [expr.rel]: expr.md#expr.rel
14664
  [expr.unary.op]: expr.md#expr.unary.op
14665
  [expr.xor]: expr.md#expr.xor
14666
  [format]: #format
14667
  [format.align]: #format.align
@@ -14670,33 +12821,50 @@ format_error(const char* what_arg);
14670
  [format.args]: #format.args
14671
  [format.arguments]: #format.arguments
14672
  [format.context]: #format.context
14673
  [format.err.report]: #format.err.report
14674
  [format.error]: #format.error
 
 
 
14675
  [format.formatter]: #format.formatter
14676
  [format.formatter.spec]: #format.formatter.spec
14677
  [format.functions]: #format.functions
14678
  [format.parse.ctx]: #format.parse.ctx
 
 
 
 
 
 
 
14679
  [format.sign]: #format.sign
14680
  [format.string]: #format.string
 
14681
  [format.string.general]: #format.string.general
14682
  [format.string.std]: #format.string.std
14683
  [format.syn]: #format.syn
 
14684
  [format.type.bool]: #format.type.bool
14685
  [format.type.char]: #format.type.char
14686
  [format.type.float]: #format.type.float
14687
  [format.type.int]: #format.type.int
14688
  [format.type.ptr]: #format.type.ptr
14689
  [format.type.string]: #format.type.string
14690
  [formatter]: #formatter
 
 
14691
  [formatter.requirements]: #formatter.requirements
 
14692
  [forward]: #forward
 
14693
  [func.bind]: #func.bind
14694
  [func.bind.bind]: #func.bind.bind
14695
- [func.bind.front]: #func.bind.front
14696
  [func.bind.isbind]: #func.bind.isbind
14697
  [func.bind.isplace]: #func.bind.isplace
 
14698
  [func.bind.place]: #func.bind.place
14699
  [func.def]: #func.def
14700
  [func.identity]: #func.identity
14701
  [func.invoke]: #func.invoke
14702
  [func.memfn]: #func.memfn
@@ -14704,79 +12872,46 @@ format_error(const char* what_arg);
14704
  [func.require]: #func.require
14705
  [func.search]: #func.search
14706
  [func.search.bm]: #func.search.bm
14707
  [func.search.bmh]: #func.search.bmh
14708
  [func.search.default]: #func.search.default
 
14709
  [func.wrap]: #func.wrap
14710
  [func.wrap.badcall]: #func.wrap.badcall
14711
  [func.wrap.func]: #func.wrap.func
14712
  [func.wrap.func.alg]: #func.wrap.func.alg
14713
  [func.wrap.func.cap]: #func.wrap.func.cap
14714
  [func.wrap.func.con]: #func.wrap.func.con
 
14715
  [func.wrap.func.inv]: #func.wrap.func.inv
14716
  [func.wrap.func.mod]: #func.wrap.func.mod
14717
  [func.wrap.func.nullptr]: #func.wrap.func.nullptr
14718
  [func.wrap.func.targ]: #func.wrap.func.targ
 
 
 
 
 
 
 
14719
  [function.objects]: #function.objects
 
14720
  [functional.syn]: #functional.syn
14721
  [intro.multithread]: basic.md#intro.multithread
14722
  [intro.object]: basic.md#intro.object
14723
- [intseq]: #intseq
14724
- [intseq.general]: #intseq.general
14725
- [intseq.intseq]: #intseq.intseq
14726
- [intseq.make]: #intseq.make
14727
  [invalid.argument]: diagnostics.md#invalid.argument
14728
- [iostate.flags]: input.md#iostate.flags
14729
  [istream.formatted]: input.md#istream.formatted
 
 
14730
  [logical.operations]: #logical.operations
14731
  [logical.operations.and]: #logical.operations.and
 
14732
  [logical.operations.not]: #logical.operations.not
14733
  [logical.operations.or]: #logical.operations.or
14734
- [mem.poly.allocator.class]: #mem.poly.allocator.class
14735
- [mem.poly.allocator.ctor]: #mem.poly.allocator.ctor
14736
- [mem.poly.allocator.eq]: #mem.poly.allocator.eq
14737
- [mem.poly.allocator.mem]: #mem.poly.allocator.mem
14738
- [mem.res]: #mem.res
14739
- [mem.res.class]: #mem.res.class
14740
- [mem.res.eq]: #mem.res.eq
14741
- [mem.res.global]: #mem.res.global
14742
- [mem.res.monotonic.buffer]: #mem.res.monotonic.buffer
14743
- [mem.res.monotonic.buffer.ctor]: #mem.res.monotonic.buffer.ctor
14744
- [mem.res.monotonic.buffer.mem]: #mem.res.monotonic.buffer.mem
14745
- [mem.res.pool]: #mem.res.pool
14746
- [mem.res.pool.ctor]: #mem.res.pool.ctor
14747
- [mem.res.pool.mem]: #mem.res.pool.mem
14748
- [mem.res.pool.options]: #mem.res.pool.options
14749
- [mem.res.pool.overview]: #mem.res.pool.overview
14750
- [mem.res.private]: #mem.res.private
14751
- [mem.res.public]: #mem.res.public
14752
- [mem.res.syn]: #mem.res.syn
14753
- [memory]: #memory
14754
- [memory.general]: #memory.general
14755
- [memory.syn]: #memory.syn
14756
- [meta]: #meta
14757
- [meta.const.eval]: #meta.const.eval
14758
- [meta.help]: #meta.help
14759
- [meta.logical]: #meta.logical
14760
- [meta.member]: #meta.member
14761
- [meta.rel]: #meta.rel
14762
- [meta.rqmts]: #meta.rqmts
14763
- [meta.trans]: #meta.trans
14764
- [meta.trans.arr]: #meta.trans.arr
14765
- [meta.trans.cv]: #meta.trans.cv
14766
- [meta.trans.other]: #meta.trans.other
14767
- [meta.trans.ptr]: #meta.trans.ptr
14768
- [meta.trans.ref]: #meta.trans.ref
14769
- [meta.trans.sign]: #meta.trans.sign
14770
- [meta.type.synop]: #meta.type.synop
14771
- [meta.unary]: #meta.unary
14772
- [meta.unary.cat]: #meta.unary.cat
14773
- [meta.unary.comp]: #meta.unary.comp
14774
- [meta.unary.prop]: #meta.unary.prop
14775
- [meta.unary.prop.query]: #meta.unary.prop.query
14776
  [namespace.std]: library.md#namespace.std
14777
- [new.delete]: support.md#new.delete
14778
  [optional]: #optional
14779
  [optional.assign]: #optional.assign
14780
  [optional.assign.copy]: #optional.assign.copy
14781
  [optional.assign.copy.templ]: #optional.assign.copy.templ
14782
  [optional.assign.move]: #optional.assign.move
@@ -14786,73 +12921,66 @@ format_error(const char* what_arg);
14786
  [optional.ctor]: #optional.ctor
14787
  [optional.dtor]: #optional.dtor
14788
  [optional.general]: #optional.general
14789
  [optional.hash]: #optional.hash
14790
  [optional.mod]: #optional.mod
 
14791
  [optional.nullops]: #optional.nullops
14792
  [optional.nullopt]: #optional.nullopt
14793
  [optional.observe]: #optional.observe
14794
  [optional.optional]: #optional.optional
 
14795
  [optional.relops]: #optional.relops
14796
  [optional.specalg]: #optional.specalg
14797
  [optional.swap]: #optional.swap
14798
  [optional.syn]: #optional.syn
14799
  [ostream.formatted]: input.md#ostream.formatted
14800
  [out.of.range]: diagnostics.md#out.of.range
14801
  [over.match.call]: over.md#over.match.call
14802
- [over.match.class.deduct]: over.md#over.match.class.deduct
14803
  [overflow.error]: diagnostics.md#overflow.error
14804
  [pair.astuple]: #pair.astuple
14805
  [pair.piecewise]: #pair.piecewise
14806
  [pairs]: #pairs
14807
  [pairs.general]: #pairs.general
14808
  [pairs.pair]: #pairs.pair
14809
  [pairs.spec]: #pairs.spec
14810
- [pointer.conversion]: #pointer.conversion
14811
- [pointer.traits]: #pointer.traits
14812
- [pointer.traits.functions]: #pointer.traits.functions
14813
- [pointer.traits.optmem]: #pointer.traits.optmem
14814
- [pointer.traits.types]: #pointer.traits.types
14815
- [ptr.align]: #ptr.align
14816
  [range.cmp]: #range.cmp
14817
- [ratio]: #ratio
14818
- [ratio.arithmetic]: #ratio.arithmetic
14819
- [ratio.comparison]: #ratio.comparison
14820
- [ratio.general]: #ratio.general
14821
- [ratio.ratio]: #ratio.ratio
14822
- [ratio.si]: #ratio.si
14823
- [ratio.syn]: #ratio.syn
14824
  [refwrap]: #refwrap
14825
  [refwrap.access]: #refwrap.access
14826
  [refwrap.assign]: #refwrap.assign
 
14827
  [refwrap.const]: #refwrap.const
 
14828
  [refwrap.helpers]: #refwrap.helpers
14829
  [refwrap.invoke]: #refwrap.invoke
14830
  [res.on.exception.handling]: library.md#res.on.exception.handling
14831
  [round.style]: support.md#round.style
14832
- [scoped.adaptor.operators]: #scoped.adaptor.operators
14833
- [smartptr]: #smartptr
14834
- [special]: class.md#special
14835
- [specialized.addressof]: #specialized.addressof
14836
- [specialized.algorithms]: algorithms.md#specialized.algorithms
14837
- [stmt.dcl]: stmt.md#stmt.dcl
14838
- [stmt.return]: stmt.md#stmt.return
14839
  [support.signal]: support.md#support.signal
14840
  [swappable.requirements]: library.md#swappable.requirements
14841
- [temp.deduct]: temp.md#temp.deduct
14842
  [temp.param]: temp.md#temp.param
14843
  [temp.type]: temp.md#temp.type
14844
  [template.bitset]: #template.bitset
 
 
 
 
 
 
 
 
14845
  [time.format]: time.md#time.format
14846
  [tuple]: #tuple
14847
  [tuple.apply]: #tuple.apply
14848
  [tuple.assign]: #tuple.assign
14849
  [tuple.cnstr]: #tuple.cnstr
 
14850
  [tuple.creation]: #tuple.creation
14851
  [tuple.elem]: #tuple.elem
14852
  [tuple.general]: #tuple.general
14853
  [tuple.helper]: #tuple.helper
 
14854
  [tuple.rel]: #tuple.rel
14855
  [tuple.special]: #tuple.special
14856
  [tuple.swap]: #tuple.swap
14857
  [tuple.syn]: #tuple.syn
14858
  [tuple.traits]: #tuple.traits
@@ -14860,64 +12988,23 @@ format_error(const char* what_arg);
14860
  [type.index]: #type.index
14861
  [type.index.hash]: #type.index.hash
14862
  [type.index.members]: #type.index.members
14863
  [type.index.overview]: #type.index.overview
14864
  [type.index.synopsis]: #type.index.synopsis
14865
- [unique.ptr]: #unique.ptr
14866
- [unique.ptr.create]: #unique.ptr.create
14867
- [unique.ptr.dltr]: #unique.ptr.dltr
14868
- [unique.ptr.dltr.dflt]: #unique.ptr.dltr.dflt
14869
- [unique.ptr.dltr.dflt1]: #unique.ptr.dltr.dflt1
14870
- [unique.ptr.dltr.general]: #unique.ptr.dltr.general
14871
- [unique.ptr.io]: #unique.ptr.io
14872
- [unique.ptr.runtime]: #unique.ptr.runtime
14873
- [unique.ptr.runtime.asgn]: #unique.ptr.runtime.asgn
14874
- [unique.ptr.runtime.ctor]: #unique.ptr.runtime.ctor
14875
- [unique.ptr.runtime.modifiers]: #unique.ptr.runtime.modifiers
14876
- [unique.ptr.runtime.observers]: #unique.ptr.runtime.observers
14877
- [unique.ptr.single]: #unique.ptr.single
14878
- [unique.ptr.single.asgn]: #unique.ptr.single.asgn
14879
- [unique.ptr.single.ctor]: #unique.ptr.single.ctor
14880
- [unique.ptr.single.dtor]: #unique.ptr.single.dtor
14881
- [unique.ptr.single.modifiers]: #unique.ptr.single.modifiers
14882
- [unique.ptr.single.observers]: #unique.ptr.single.observers
14883
- [unique.ptr.special]: #unique.ptr.special
14884
  [unord]: containers.md#unord
14885
  [unord.hash]: #unord.hash
14886
- [util.dynamic.safety]: #util.dynamic.safety
14887
- [util.smartptr.enab]: #util.smartptr.enab
14888
- [util.smartptr.getdeleter]: #util.smartptr.getdeleter
14889
- [util.smartptr.hash]: #util.smartptr.hash
14890
- [util.smartptr.ownerless]: #util.smartptr.ownerless
14891
- [util.smartptr.shared]: #util.smartptr.shared
14892
- [util.smartptr.shared.assign]: #util.smartptr.shared.assign
14893
- [util.smartptr.shared.cast]: #util.smartptr.shared.cast
14894
- [util.smartptr.shared.cmp]: #util.smartptr.shared.cmp
14895
- [util.smartptr.shared.const]: #util.smartptr.shared.const
14896
- [util.smartptr.shared.create]: #util.smartptr.shared.create
14897
- [util.smartptr.shared.dest]: #util.smartptr.shared.dest
14898
- [util.smartptr.shared.io]: #util.smartptr.shared.io
14899
- [util.smartptr.shared.mod]: #util.smartptr.shared.mod
14900
- [util.smartptr.shared.obs]: #util.smartptr.shared.obs
14901
- [util.smartptr.shared.spec]: #util.smartptr.shared.spec
14902
- [util.smartptr.weak]: #util.smartptr.weak
14903
- [util.smartptr.weak.assign]: #util.smartptr.weak.assign
14904
- [util.smartptr.weak.bad]: #util.smartptr.weak.bad
14905
- [util.smartptr.weak.const]: #util.smartptr.weak.const
14906
- [util.smartptr.weak.dest]: #util.smartptr.weak.dest
14907
- [util.smartptr.weak.mod]: #util.smartptr.weak.mod
14908
- [util.smartptr.weak.obs]: #util.smartptr.weak.obs
14909
- [util.smartptr.weak.spec]: #util.smartptr.weak.spec
14910
  [utilities]: #utilities
14911
  [utilities.general]: #utilities.general
14912
  [utilities.summary]: #utilities.summary
14913
  [utility]: #utility
14914
  [utility.as.const]: #utility.as.const
14915
  [utility.exchange]: #utility.exchange
14916
  [utility.intcmp]: #utility.intcmp
14917
  [utility.swap]: #utility.swap
14918
  [utility.syn]: #utility.syn
 
 
14919
  [variant]: #variant
14920
  [variant.assign]: #variant.assign
14921
  [variant.bad.access]: #variant.bad.access
14922
  [variant.ctor]: #variant.ctor
14923
  [variant.dtor]: #variant.dtor
@@ -14932,14 +13019,16 @@ format_error(const char* what_arg);
14932
  [variant.specalg]: #variant.specalg
14933
  [variant.status]: #variant.status
14934
  [variant.swap]: #variant.swap
14935
  [variant.syn]: #variant.syn
14936
  [variant.variant]: #variant.variant
 
14937
  [variant.visit]: #variant.visit
14938
 
14939
- [^1]: `pointer_safety::preferred` might be returned to indicate that a
14940
- leak detector is running so that the program can avoid spurious leak
14941
- reports.
14942
-
14943
- [^2]: Such a type is a function pointer or a class type which has a
14944
  member `operator()` or a class type which has a conversion to a
14945
  pointer to function.
 
 
 
 
 
 
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
 
32
  ### Header `<utility>` synopsis <a id="utility.syn">[[utility.syn]]</a>
33
 
34
  The header `<utility>` contains some basic function and class templates
35
  that are used throughout the rest of the library.
36
 
37
  ``` cpp
38
+ // all freestanding
39
  #include <compare> // see [compare.syn]
40
  #include <initializer_list> // see [initializer.list.syn]
41
 
42
  namespace std {
43
  // [utility.swap], swap
 
46
  template<class T, size_t N>
47
  constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);
48
 
49
  // [utility.exchange], exchange
50
  template<class T, class U = T>
51
+ constexpr T exchange(T& obj, U&& new_val) noexcept(see below);
52
 
53
  // [forward], forward/move
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&&>
 
90
  constexpr bool cmp_greater_equal(T t, U u) noexcept;
91
 
92
  template<class R, class T>
93
  constexpr bool in_range(T t) noexcept;
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
 
106
  template<class T, T...>
 
118
 
119
  // [pairs], class template pair
120
  template<class T1, class T2>
121
  struct pair;
122
 
123
+ template<class T1, class T2, class U1, class U2,
124
+ template<class> class TQual, template<class> class UQual>
125
+ requires requires { typename pair<common_reference_t<TQual<T1>, UQual<U1>>,
126
+ common_reference_t<TQual<T2>, UQual<U2>>>; }
127
+ struct basic_common_reference<pair<T1, T2>, pair<U1, U2>, TQual, UQual> {
128
+ using type = pair<common_reference_t<TQual<T1>, UQual<U1>>,
129
+ common_reference_t<TQual<T2>, UQual<U2>>>;
130
+ };
131
+
132
+ template<class T1, class T2, class U1, class U2>
133
+ requires requires { typename pair<common_type_t<T1, U1>, common_type_t<T2, U2>>; }
134
+ struct common_type<pair<T1, T2>, pair<U1, U2>> {
135
+ using type = pair<common_type_t<T1, U1>, common_type_t<T2, U2>>;
136
+ };
137
+
138
  // [pairs.spec], pair specialized algorithms
139
+ template<class T1, class T2, class U1, class U2>
140
+ constexpr bool operator==(const pair<T1, T2>&, const pair<U1, U2>&);
141
+ template<class T1, class T2, class U1, class U2>
142
+ constexpr common_comparison_category_t<synth-three-way-result<T1, U1>,
143
+ synth-three-way-result<T2, U2>>
144
+ operator<=>(const pair<T1, T2>&, const pair<U1, U2>&);
145
 
146
  template<class T1, class T2>
147
  constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
148
+ template<class T1, class T2>
149
+ constexpr void swap(const pair<T1, T2>& x, const pair<T1, T2>& y)
150
+ noexcept(noexcept(x.swap(y)));
151
 
152
  template<class T1, class T2>
153
  constexpr see below make_pair(T1&&, T2&&);
154
 
155
  // [pair.astuple], tuple-like access to pair
 
205
 
206
  template<class T>
207
  struct in_place_type_t {
208
  explicit in_place_type_t() = default;
209
  };
210
+ template<class T> constexpr in_place_type_t<T> in_place_type{};
211
 
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
 
 
231
  ([[cpp17.moveconstructible]]) and *Cpp17MoveAssignable*
232
  ([[cpp17.moveassignable]]) requirements.
233
 
234
  *Effects:* Exchanges values stored in two locations.
235
 
236
+ *Remarks:* The exception specification is equivalent to:
 
 
237
 
238
  ``` cpp
239
  is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>
240
  ```
241
 
 
253
 
254
  ### `exchange` <a id="utility.exchange">[[utility.exchange]]</a>
255
 
256
  ``` cpp
257
  template<class T, class U = T>
258
+ constexpr T exchange(T& obj, U&& new_val) noexcept(see below);
259
  ```
260
 
261
  *Effects:* Equivalent to:
262
 
263
  ``` cpp
264
  T old_val = std::move(obj);
265
  obj = std::forward<U>(new_val);
266
  return old_val;
267
  ```
268
 
269
+ *Remarks:* The exception specification is equivalent to:
270
+
271
+ ``` cpp
272
+ is_nothrow_move_constructible_v<T> && is_nothrow_assignable_v<T&, U>
273
+ ```
274
+
275
  ### Forward/move helpers <a id="forward">[[forward]]</a>
276
 
277
  The library provides templated helper functions to simplify applying
278
  move semantics to an lvalue and to simplify the implementation of
279
  forwarding functions. All functions specified in this subclause are
 
314
  constructor as an lvalue. In both cases, `A2` is deduced as `double`, so
315
  1.414 is forwarded to `A`’s constructor as an rvalue.
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,
327
+ otherwise `B`.
328
+ - Let *`OVERRIDE_REF`*`(A, B)` be `remove_reference_t<B>&&` if `A` is an
329
+ rvalue reference type, otherwise `B&`.
330
+ - Let `V` be
331
+ ``` cpp
332
+ OVERRIDE_REF(T&&, COPY_CONST(remove_reference_t<T>, remove_reference_t<U>))
333
+ ```
334
+
335
+ *Returns:* `static_cast<V>(x)`.
336
+
337
+ *Remarks:* The return type is `V`.
338
+
339
+ [*Example 2*:
340
+
341
+ ``` cpp
342
+ struct accessor {
343
+ vector<string>* container;
344
+ decltype(auto) operator[](this auto&& self, size_t i) {
345
+ return std::forward_like<decltype(self)>((*container)[i]);
346
+ }
347
+ };
348
+ void g() {
349
+ vector v{"a"s, "b"s};
350
+ accessor a{&v};
351
+ string& x = a[0]; // OK, binds to lvalue reference
352
+ string&& y = std::move(a)[0]; // OK, is rvalue reference
353
+ string const&& z = std::move(as_const(a))[1]; // OK, is const&&
354
+ string& w = as_const(a)[1]; // error: will not bind to non-const
355
+ }
356
+ ```
357
+
358
+ — *end example*]
359
+
360
  ``` cpp
361
  template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;
362
  ```
363
 
364
  *Returns:* `static_cast<remove_reference_t<T>&&>(t)`.
365
 
366
+ [*Example 3*:
367
 
368
  ``` cpp
369
  template<class T, class A1>
370
  shared_ptr<T> factory(A1&& a1) {
371
  return shared_ptr<T>(new T(std::forward<A1>(a1)));
 
378
  };
379
 
380
  void g() {
381
  A a;
382
  shared_ptr<A> sp1 = factory<A>(a); // ``a'' binds to A(const A&)
383
+ shared_ptr<A> sp2 = factory<A>(std::move(a)); // ``a'' binds to A(A&&)
384
  }
385
  ```
386
 
387
  In the first call to `factory`, `A1` is deduced as `A&`, so `a` is
388
  forwarded as a non-const lvalue. This binds to the constructor
 
411
 
412
  ### Function template `declval` <a id="declval">[[declval]]</a>
413
 
414
  The library provides the function template `declval` to simplify the
415
  definition of expressions which occur as unevaluated operands
416
+ [[term.unevaluated.operand]].
417
 
418
  ``` cpp
419
  template<class T> add_rvalue_reference_t<T> declval() noexcept; // as unevaluated operand
420
  ```
421
 
422
+ *Mandates:* This function is not odr-used [[term.odr.use]].
423
 
424
  *Remarks:* The template parameter `T` of `declval` may be an incomplete
425
  type.
426
 
427
  [*Example 1*:
 
429
  ``` cpp
430
  template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&);
431
  ```
432
 
433
  declares a function template `convert` which only participates in
434
+ overload resolution if the type `From` can be explicitly converted to
435
+ type `To`. For another example see class template `common_type`
436
  [[meta.trans.other]].
437
 
438
  — *end example*]
439
 
440
  ### Integer comparison functions <a id="utility.intcmp">[[utility.intcmp]]</a>
 
526
 
527
  [*Note 1*: These function templates cannot be used to compare `byte`,
528
  `char`, `char8_t`, `char16_t`, `char32_t`, `wchar_t`, and
529
  `bool`. — *end note*]
530
 
531
+ ### Function template `to_underlying` <a id="utility.underlying">[[utility.underlying]]</a>
532
 
533
+ ``` cpp
534
+ 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
 
546
+ *Preconditions:* `false` is `true`.
547
+
548
+ [*Note 1*: This precondition cannot be satisfied, thus the behavior of
549
+ calling `unreachable` is undefined. — *end note*]
550
 
551
+ [*Example 1*:
552
 
553
  ``` cpp
554
+ int f(int x) {
555
+ switch (x) {
556
+ case 0:
557
+ case 1:
558
+ return x;
559
+ default:
560
+ std::unreachable();
561
+ }
562
+ }
563
+ 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
 
 
590
 
591
  pair(const pair&) = default;
592
  pair(pair&&) = default;
593
  constexpr explicit(see below) pair();
594
  constexpr explicit(see below) pair(const T1& x, const T2& y);
595
+ template<class U1 = T1, class U2 = T2>
596
  constexpr explicit(see below) pair(U1&& x, U2&& y);
597
+ template<class U1, class U2>
598
+ constexpr explicit(see below) pair(pair<U1, U2>& p);
599
  template<class U1, class U2>
600
  constexpr explicit(see below) pair(const pair<U1, U2>& p);
601
  template<class U1, class U2>
602
  constexpr explicit(see below) pair(pair<U1, U2>&& p);
603
+ template<class U1, class U2>
604
+ constexpr explicit(see below) pair(const pair<U1, U2>&& p);
605
+ template<pair-like P>
606
+ constexpr explicit(see below) pair(P&& p);
607
  template<class... Args1, class... Args2>
608
  constexpr pair(piecewise_construct_t,
609
  tuple<Args1...> first_args, tuple<Args2...> second_args);
610
 
611
  constexpr pair& operator=(const pair& p);
612
+ constexpr const pair& operator=(const pair& p) const;
613
  template<class U1, class U2>
614
  constexpr pair& operator=(const pair<U1, U2>& p);
615
+ template<class U1, class U2>
616
+ constexpr const pair& operator=(const pair<U1, U2>& p) const;
617
  constexpr pair& operator=(pair&& p) noexcept(see below);
618
+ constexpr const pair& operator=(pair&& p) const;
619
  template<class U1, class U2>
620
  constexpr pair& operator=(pair<U1, U2>&& p);
621
+ template<class U1, class U2>
622
+ constexpr const pair& operator=(pair<U1, U2>&& p) const;
623
+ template<pair-like P>
624
+ constexpr pair& operator=(P&& p);
625
+ template<pair-like P>
626
+ constexpr const pair& operator=(P&& p) const;
627
 
628
  constexpr void swap(pair& p) noexcept(see below);
629
+ constexpr void swap(const pair& p) const noexcept(see below);
630
  };
631
 
632
  template<class T1, class T2>
633
  pair(T1, T2) -> pair<T1, T2>;
634
  }
 
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
 
 
657
  constexpr explicit(see below) pair();
658
  ```
659
 
660
  *Constraints:*
661
 
662
+ - `is_default_constructible_v<T1>` is `true` and
663
+ - `is_default_constructible_v<T2>` is `true`.
664
 
665
  *Effects:* Value-initializes `first` and `second`.
666
 
667
  *Remarks:* The expression inside `explicit` evaluates to `true` if and
668
+ only if either `T1` or `T2` is not implicitly default-constructible.
 
669
 
670
  [*Note 1*: This behavior can be implemented with a trait that checks
671
+ whether a `const T1&` or a `const T2&` can be initialized with
672
+ `{}`. — *end note*]
673
 
674
  ``` cpp
675
  constexpr explicit(see below) pair(const T1& x, const T2& y);
676
  ```
677
 
678
  *Constraints:*
679
 
680
+ - `is_copy_constructible_v<T1>` is `true` and
681
+ - `is_copy_constructible_v<T2>` is `true`.
682
 
683
  *Effects:* Initializes `first` with `x` and `second` with `y`.
684
 
685
  *Remarks:* The expression inside `explicit` is equivalent to:
686
 
687
  ``` cpp
688
+ !is_convertible_v<const T1&, T1> || !is_convertible_v<const T2&, T2>
 
689
  ```
690
 
691
  ``` cpp
692
+ template<class U1 = T1, class U2 = T2> constexpr explicit(see below) pair(U1&& x, U2&& y);
693
  ```
694
 
695
  *Constraints:*
696
 
697
+ - `is_constructible_v<T1, U1>` is `true` and
698
+ - `is_constructible_v<T2, U2>` is `true`.
699
 
700
  *Effects:* Initializes `first` with `std::forward<U1>(x)` and `second`
701
  with `std::forward<U2>(y)`.
702
 
703
  *Remarks:* The expression inside `explicit` is equivalent to:
704
 
705
  ``` cpp
706
+ !is_convertible_v<U1, T1> || !is_convertible_v<U2, T2>
707
  ```
708
 
709
+ This constructor is defined as deleted if
710
+ `reference_constructs_from_temporary_v<first_type, U1&&>` is `true` or
711
+ `reference_constructs_from_temporary_v<second_type, U2&&>` is `true`.
712
+
713
  ``` cpp
714
+ template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>& p);
715
  template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>& p);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
716
  template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>&& p);
717
+ template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>&& p);
718
+ template<pair-like P> constexpr explicit(see below) pair(P&& p);
719
  ```
720
 
721
+ Let *`FWD`*`(u)` be `static_cast<decltype(u)>(u)`.
722
+
723
  *Constraints:*
724
 
725
+ - For the last overload, `remove_cvref_t<P>` is not a specialization of
726
+ `ranges::subrange`,
727
+ - `is_constructible_v<T1, decltype(get<0>(`*`FWD`*`(p)))>` is `true`,
728
+ and
729
+ - `is_constructible_v<T2, decltype(get<1>(`*`FWD`*`(p)))>` is `true`.
730
 
731
+ *Effects:* Initializes `first` with `get<0>(`*`FWD`*`(p))` and `second`
732
+ with `get<1>(`*`FWD`*`(p))`.
733
 
734
+ *Remarks:* The expression inside `explicit` is equivalent to:
735
 
736
  ``` cpp
737
+ !is_convertible_v<decltype(get<0>(FWD(p))), T1> ||
738
+ !is_convertible_v<decltype(get<1>(FWD(p))), T2>
739
  ```
740
 
741
+ The constructor is defined as deleted if
742
+
743
+ ``` cpp
744
+ reference_constructs_from_temporary_v<first_type, decltype(get<0>(FWD(p)))> ||
745
+ reference_constructs_from_temporary_v<second_type, decltype(get<1>(FWD(p)))>
746
+ ```
747
+
748
+ is `true`.
749
+
750
  ``` cpp
751
  template<class... Args1, class... Args2>
752
  constexpr pair(piecewise_construct_t,
753
  tuple<Args1...> first_args, tuple<Args2...> second_args);
754
  ```
755
 
756
  *Mandates:*
757
 
758
+ - `is_constructible_v<T1, Args1...>` is `true` and
759
+ - `is_constructible_v<T2, Args2...>` is `true`.
760
 
761
  *Effects:* Initializes `first` with arguments of types `Args1...`
762
  obtained by forwarding the elements of `first_args` and initializes
763
  `second` with arguments of types `Args2...` obtained by forwarding the
764
  elements of `second_args`. (Here, forwarding an element `x` of type `U`
765
  within a `tuple` object means calling `std::forward<U>(x)`.) This form
766
  of construction, whereby constructor arguments for `first` and `second`
767
  are each provided in a separate `tuple` object, is called *piecewise
768
  construction*.
769
 
770
+ [*Note 2*: If a data member of `pair` is of reference type and its
771
+ initialization binds it to a temporary object, the program is
772
+ ill-formed [[class.base.init]]. — *end note*]
773
+
774
  ``` cpp
775
  constexpr pair& operator=(const pair& p);
776
  ```
777
 
778
  *Effects:* Assigns `p.first` to `first` and `p.second` to `second`.
779
 
780
+ *Returns:* `*this`.
781
+
782
  *Remarks:* This operator is defined as deleted unless
783
+ `is_copy_assignable_v<T1>` is `true` and `is_copy_assignable_v<T2>` is
784
+ `true`.
785
+
786
+ ``` cpp
787
+ constexpr const pair& operator=(const pair& p) const;
788
+ ```
789
+
790
+ *Constraints:*
791
+
792
+ - `is_copy_assignable_v<const T1>` is `true` and
793
+ - `is_copy_assignable_v<const T2>` is `true`.
794
+
795
+ *Effects:* Assigns `p.first` to `first` and `p.second` to `second`.
796
 
797
  *Returns:* `*this`.
798
 
799
  ``` cpp
800
  template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p);
801
  ```
802
 
803
  *Constraints:*
804
 
805
+ - `is_assignable_v<T1&, const U1&>` is `true` and
806
+ - `is_assignable_v<T2&, const U2&>` is `true`.
807
+
808
+ *Effects:* Assigns `p.first` to `first` and `p.second` to `second`.
809
+
810
+ *Returns:* `*this`.
811
+
812
+ ``` cpp
813
+ template<class U1, class U2> constexpr const pair& operator=(const pair<U1, U2>& p) const;
814
+ ```
815
+
816
+ *Constraints:*
817
+
818
+ - `is_assignable_v<const T1&, const U1&>` is `true`, and
819
+ - `is_assignable_v<const T2&, const U2&>` is `true`.
820
 
821
  *Effects:* Assigns `p.first` to `first` and `p.second` to `second`.
822
 
823
  *Returns:* `*this`.
824
 
 
826
  constexpr pair& operator=(pair&& p) noexcept(see below);
827
  ```
828
 
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
 
841
  ``` cpp
842
  is_nothrow_move_assignable_v<T1> && is_nothrow_move_assignable_v<T2>
843
  ```
844
 
845
+ ``` cpp
846
+ constexpr const pair& operator=(pair&& p) const;
847
+ ```
848
+
849
+ *Constraints:*
850
+
851
+ - `is_assignable_v<const T1&, T1>` is `true` and
852
+ - `is_assignable_v<const T2&, T2>` is `true`.
853
+
854
+ *Effects:* Assigns `std::forward<T1>(p.first)` to `first` and
855
+ `std::forward<T2>(p.second)` to `second`.
856
+
857
+ *Returns:* `*this`.
858
+
859
  ``` cpp
860
  template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p);
861
  ```
862
 
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);
876
+ ```
877
+
878
+ *Constraints:*
879
+
880
+ - `different-from<P, pair>` [[range.utility.helpers]] is `true`,
881
+ - `remove_cvref_t<P>` is not a specialization of `ranges::subrange`,
882
+ - `is_assignable_v<T1&, decltype(get<0>(std::forward<P>(p)))>` is
883
+ `true`, and
884
+ - `is_assignable_v<T2&, decltype(get<1>(std::forward<P>(p)))>` is
885
+ `true`.
886
+
887
+ *Effects:* Assigns `get<0>(std::forward<P>(p))` to `first` and
888
+ `get<1>(std::forward<P>(p))` to `second`.
889
+
890
+ *Returns:* `*this`.
891
+
892
+ ``` cpp
893
+ template<pair-like P> constexpr const pair& operator=(P&& p) const;
894
+ ```
895
+
896
+ *Constraints:*
897
+
898
+ - `different-from<P, pair>` [[range.utility.helpers]] is `true`,
899
+ - `remove_cvref_t<P>` is not a specialization of `ranges::subrange`,
900
+ - `is_assignable_v<const T1&, decltype(get<0>(std::forward<P>(p)))>` is
901
+ `true`, and
902
+ - `is_assignable_v<const T2&, decltype(get<1>(std::forward<P>(p)))>` is
903
+ `true`.
904
+
905
+ *Effects:* Assigns `get<0>(std::forward<P>(p))` to `first` and
906
+ `get<1>(std::forward<P>(p))` to `second`.
907
+
908
+ *Returns:* `*this`.
909
+
910
+ ``` cpp
911
+ template<class U1, class U2> constexpr const pair& operator=(pair<U1, U2>&& p) const;
912
+ ```
913
+
914
+ *Constraints:*
915
+
916
+ - `is_assignable_v<const T1&, U1>` is `true`, and
917
+ - `is_assignable_v<const T2&, U2>` is `true`.
918
+
919
+ *Effects:* Assigns `std::forward<U1>(p.first)` to `first` and
920
+ `std::forward<U2>(u.second)` to `second`.
921
+
922
+ *Returns:* `*this`.
923
+
924
  ``` cpp
925
  constexpr void swap(pair& p) noexcept(see below);
926
+ constexpr void swap(const pair& p) const noexcept(see below);
927
  ```
928
 
929
+ *Mandates:*
930
+
931
+ - For the first overload, `is_swappable_v<T1>` is `true` and
932
+ `is_swappable_v<T2>` is `true`.
933
+ - For the second overload, `is_swappable_v<const T1>` is `true` and
934
+ `is_swappable_v<const T2>` is `true`.
935
+
936
  *Preconditions:* `first` is swappable with [[swappable.requirements]]
937
  `p.first` and `second` is swappable with `p.second`.
938
 
939
  *Effects:* Swaps `first` with `p.first` and `second` with `p.second`.
940
 
941
+ *Remarks:* The exception specification is equivalent to:
942
 
943
+ - `is_nothrow_swappable_v<T1> && is_nothrow_swappable_v<T2>` for the
944
+ first overload, and
945
+ - `is_nothrow_swappable_v<const T1> && is_nothrow_swappable_v<const T2>`
946
+ for the second overload.
947
 
948
  ### Specialized algorithms <a id="pairs.spec">[[pairs.spec]]</a>
949
 
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>
962
+ constexpr common_comparison_category_t<synth-three-way-result<T1, U1>,
963
+ synth-three-way-result<T2, U2>>
964
+ operator<=>(const pair<T1, T2>& x, const pair<U1, U2>& y);
965
  ```
966
 
967
  *Effects:* Equivalent to:
968
 
969
  ``` cpp
 
972
  ```
973
 
974
  ``` cpp
975
  template<class T1, class T2>
976
  constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
977
+ template<class T1, class T2>
978
+ constexpr void swap(const pair<T1, T2>& x, const pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
979
  ```
980
 
981
+ *Constraints:*
982
+
983
+ - For the first overload, `is_swappable_v<T1>` is `true` and
984
+ `is_swappable_v<T2>` is `true`.
985
+ - For the second overload, `is_swappable_v<const T1>` is `true` and
986
+ `is_swappable_v<const T2>` is `true`.
987
 
988
  *Effects:* Equivalent to `x.swap(y)`.
989
 
990
  ``` cpp
991
  template<class T1, class T2>
 
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]
1117
 
1118
  namespace std {
1119
  // [tuple.tuple], class template tuple
1120
  template<class... Types>
1121
  class tuple;
1122
 
1123
+ // [tuple.like], concept tuple-like
1124
+ template<class T>
1125
+ concept tuple-like = see belownc; // exposition only
1126
+ template<class T>
1127
+ concept pair-like = // exposition only
1128
+ tuple-like<T> && tuple_size_v<remove_cvref_t<T>> == 2;
1129
+
1130
+ // [tuple.common.ref], common_reference related specializations
1131
+ template<exposition onlyconceptnc{tuple-like} TTuple, exposition onlyconceptnc{tuple-like} UTuple,
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&&...);
 
1144
  constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&...) noexcept;
1145
 
1146
  template<class... TTypes>
1147
  constexpr tuple<TTypes&...> tie(TTypes&...) noexcept;
1148
 
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
1160
  template<class T> struct tuple_size; // not defined
1161
  template<class T> struct tuple_size<const T>;
 
1190
  constexpr const T&& get(const tuple<Types...>&& t) noexcept;
1191
 
1192
  // [tuple.rel], relational operators
1193
  template<class... TTypes, class... UTypes>
1194
  constexpr bool operator==(const tuple<TTypes...>&, const tuple<UTypes...>&);
1195
+ template<class... TTypes, exposition onlyconceptnc{tuple-like} UTuple>
1196
+ constexpr bool operator==(const tuple<TTypes...>&, const UTuple&);
1197
  template<class... TTypes, class... UTypes>
1198
  constexpr common_comparison_category_t<synth-three-way-result<TTypes, UTypes>...>
1199
  operator<=>(const tuple<TTypes...>&, const tuple<UTypes...>&);
1200
+ template<class... TTypes, exposition onlyconceptnc{tuple-like} UTuple>
1201
+ constexpr see belownc operator<=>(const tuple<TTypes...>&, const UTuple&);
1202
 
1203
  // [tuple.traits], allocator-related traits
1204
  template<class... Types, class Alloc>
1205
  struct uses_allocator<tuple<Types...>, Alloc>;
1206
 
1207
  // [tuple.special], specialized algorithms
1208
  template<class... Types>
1209
  constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(see below);
1210
+ template<class... Types>
1211
+ constexpr void swap(const tuple<Types...>& x, const tuple<Types...>& y) noexcept(see below);
1212
 
1213
  // [tuple.helper], tuple helper classes
1214
  template<class T>
1215
+ constexpr size_t tuple_size_v@ = tuple_size<T>::value;
1216
  }
1217
  ```
1218
 
1219
+ ### Concept <a id="tuple.like">[[tuple.like]]</a>
1220
+
1221
+ ``` cpp
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>
 
1241
  constexpr explicit(see below) tuple(UTypes&&...); // only if sizeof...(Types) >= 1
1242
 
1243
  tuple(const tuple&) = default;
1244
  tuple(tuple&&) = default;
1245
 
1246
+ template<class... UTypes>
1247
+ constexpr explicit(see below) tuple(tuple<UTypes...>&);
1248
  template<class... UTypes>
1249
  constexpr explicit(see below) tuple(const tuple<UTypes...>&);
1250
  template<class... UTypes>
1251
  constexpr explicit(see below) tuple(tuple<UTypes...>&&);
1252
+ template<class... UTypes>
1253
+ constexpr explicit(see below) tuple(const tuple<UTypes...>&&);
1254
 
1255
+ template<class U1, class U2>
1256
+ constexpr explicit(see below) tuple(pair<U1, U2>&); // only if sizeof...(Types) == 2
1257
  template<class U1, class U2>
1258
  constexpr explicit(see below) tuple(const pair<U1, U2>&); // only if sizeof...(Types) == 2
1259
  template<class U1, class U2>
1260
  constexpr explicit(see below) tuple(pair<U1, U2>&&); // only if sizeof...(Types) == 2
1261
+ template<class U1, class U2>
1262
+ constexpr explicit(see below) tuple(const pair<U1, U2>&&); // only if sizeof...(Types) == 2
1263
+
1264
+ template<tuple-like UTuple>
1265
+ constexpr explicit(see below) tuple(UTuple&&);
1266
 
1267
  // allocator-extended constructors
1268
  template<class Alloc>
1269
  constexpr explicit(see below)
1270
  tuple(allocator_arg_t, const Alloc& a);
 
1276
  tuple(allocator_arg_t, const Alloc& a, UTypes&&...);
1277
  template<class Alloc>
1278
  constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&);
1279
  template<class Alloc>
1280
  constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&);
1281
+ template<class Alloc, class... UTypes>
1282
+ constexpr explicit(see below)
1283
+ tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&);
1284
  template<class Alloc, class... UTypes>
1285
  constexpr explicit(see below)
1286
  tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
1287
  template<class Alloc, class... UTypes>
1288
  constexpr explicit(see below)
1289
  tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
1290
+ template<class Alloc, class... UTypes>
1291
+ constexpr explicit(see below)
1292
+ tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&&);
1293
+ template<class Alloc, class U1, class U2>
1294
+ constexpr explicit(see below)
1295
+ tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&);
1296
  template<class Alloc, class U1, class U2>
1297
  constexpr explicit(see below)
1298
  tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
1299
  template<class Alloc, class U1, class U2>
1300
  constexpr explicit(see below)
1301
  tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
1302
+ template<class Alloc, class U1, class U2>
1303
+ constexpr explicit(see below)
1304
+ tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&&);
1305
+
1306
+ template<class Alloc, exposition onlyconceptnc{tuple-like} UTuple>
1307
+ constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTuple&&);
1308
 
1309
  // [tuple.assign], tuple assignment
1310
  constexpr tuple& operator=(const tuple&);
1311
+ constexpr const tuple& operator=(const tuple&) const;
1312
  constexpr tuple& operator=(tuple&&) noexcept(see below);
1313
+ constexpr const tuple& operator=(tuple&&) const;
1314
 
1315
  template<class... UTypes>
1316
  constexpr tuple& operator=(const tuple<UTypes...>&);
1317
+ template<class... UTypes>
1318
+ constexpr const tuple& operator=(const tuple<UTypes...>&) const;
1319
  template<class... UTypes>
1320
  constexpr tuple& operator=(tuple<UTypes...>&&);
1321
+ template<class... UTypes>
1322
+ constexpr const tuple& operator=(tuple<UTypes...>&&) const;
1323
 
1324
  template<class U1, class U2>
1325
  constexpr tuple& operator=(const pair<U1, U2>&); // only if sizeof...(Types) == 2
1326
+ template<class U1, class U2>
1327
+ constexpr const tuple& operator=(const pair<U1, U2>&) const;
1328
+ // only if sizeof...(Types) == 2
1329
  template<class U1, class U2>
1330
  constexpr tuple& operator=(pair<U1, U2>&&); // only if sizeof...(Types) == 2
1331
+ template<class U1, class U2>
1332
+ constexpr const tuple& operator=(pair<U1, U2>&&) const; // only if sizeof...(Types) == 2
1333
+
1334
+ template<exposition onlyconceptnc{tuple-like} UTuple>
1335
+ constexpr tuple& operator=(UTuple&&);
1336
+ template<exposition onlyconceptnc{tuple-like}@ UTuple>
1337
+ constexpr const tuple& operator=(UTuple&&) const;
1338
 
1339
  // [tuple.swap], tuple swap
1340
  constexpr void swap(tuple&) noexcept(see below);
1341
+ constexpr void swap(const tuple&) const noexcept(see below);
1342
  };
1343
 
1344
  template<class... UTypes>
1345
  tuple(UTypes...) -> tuple<UTypes...>;
1346
  template<class T1, class T2>
 
1364
  For each `tuple` constructor, an exception is thrown only if the
1365
  construction of one of the types in `Types` throws an exception.
1366
 
1367
  The defaulted move and copy constructor, respectively, of `tuple` is a
1368
  constexpr function if and only if all required element-wise
1369
+ initializations for move and copy, respectively, would be
1370
+ constexpr-suitable [[dcl.constexpr]]. The defaulted move and copy
1371
  constructor of `tuple<>` are constexpr functions.
1372
 
1373
  If `is_trivially_destructible_v<Tᵢ>` is `true` for all `Tᵢ`, then the
1374
  destructor of `tuple` is trivial.
1375
 
1376
+ The default constructor of `tuple<>` is trivial.
1377
+
1378
  ``` cpp
1379
  constexpr explicit(see below) tuple();
1380
  ```
1381
 
1382
  *Constraints:* `is_default_constructible_v<``Tᵢ``>` is `true` for all i.
 
1408
 
1409
  ``` cpp
1410
  template<class... UTypes> constexpr explicit(see below) tuple(UTypes&&... u);
1411
  ```
1412
 
1413
+ Let *disambiguating-constraint* be:
1414
+
1415
+ - `negation<is_same<remove_cvref_t<``U₀``>, tuple>>` if
1416
+ `sizeof...(Types)` is 1;
1417
+ - otherwise,
1418
+ `bool_constant<!is_same_v<remove_cvref_t<``U₀``>, allocator_arg_t> || is_- same_v<remove_cvref_t<``T₀``>, allocator_arg_t>>`
1419
+ if `sizeof...(Types)` is 2 or 3;
1420
+ - otherwise, `true_type`.
1421
+
1422
+ *Constraints:*
1423
+
1424
+ - `sizeof...(Types)` equals `sizeof...(UTypes)`,
1425
+ - `sizeof...(Types)` ≥ 1, and
1426
+ - `conjunction_v<`*`disambiguating-constraint`*`, is_constructible<Types, UTypes>...>`
1427
+ is `true`.
1428
 
1429
  *Effects:* Initializes the elements in the tuple with the corresponding
1430
  value in `std::forward<UTypes>(u)`.
1431
 
1432
  *Remarks:* The expression inside `explicit` is equivalent to:
1433
 
1434
  ``` cpp
1435
  !conjunction_v<is_convertible<UTypes, Types>...>
1436
  ```
1437
 
1438
+ This constructor is defined as deleted if
1439
+
1440
+ ``` cpp
1441
+ (reference_constructs_from_temporary_v<Types, UTypes&&> || ...)
1442
+ ```
1443
+
1444
+ is `true`.
1445
+
1446
  ``` cpp
1447
  tuple(const tuple& u) = default;
1448
  ```
1449
 
1450
  *Mandates:* `is_copy_constructible_v<``Tᵢ``>` is `true` for all i.
 
1460
 
1461
  *Effects:* For all i, initializes the iᵗʰ element of `*this` with
1462
  `std::forward<``Tᵢ``>(get<`i`>(u))`.
1463
 
1464
  ``` cpp
1465
+ template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>& u);
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
1477
+ - `(is_constructible_v<Types, decltype(get<I>(`*`FWD`*`(u)))> && ...)`
1478
+ is `true`, and
1479
  - either `sizeof...(Types)` is not 1, or (when `Types...` expands to `T`
1480
+ and `UTypes...` expands to `U`) `is_convertible_v<decltype(u), T>`,
1481
+ `is_constructible_v<T, decltype(u)>`, and `is_same_v<T, U>` are all
1482
  `false`.
1483
 
1484
+ *Effects:* For all i, initializes the $i^\textrm{th}$ element of `*this`
1485
+ with `get<`i`>(`*`FWD`*`(u))`.
1486
 
1487
  *Remarks:* The expression inside `explicit` is equivalent to:
1488
 
1489
  ``` cpp
1490
+ !(is_convertible_v<decltype(get<I>(FWD(u))), Types> && ...)
1491
  ```
1492
 
1493
+ The constructor is defined as deleted if
1494
+
1495
+ ``` cpp
1496
+ (reference_constructs_from_temporary_v<Types, decltype(get<I>(FWD(u)))> || ...)
1497
+ ```
1498
+
1499
+ is `true`.
1500
+
1501
  ``` cpp
1502
+ template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>& u);
1503
  template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>& u);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1504
  template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&& u);
1505
+ template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>&& u);
1506
  ```
1507
 
1508
+ Let *`FWD`*`(u)` be `static_cast<decltype(u)>(u)`.
1509
+
1510
  *Constraints:*
1511
 
1512
  - `sizeof...(Types)` is 2,
1513
+ - `is_constructible_v<``T₀``, decltype(get<0>(`*`FWD`*`(u)))>` is
1514
+ `true`, and
1515
+ - `is_constructible_v<``T₁``, decltype(get<1>(`*`FWD`*`(u)))>` is
1516
+ `true`.
1517
 
1518
+ *Effects:* Initializes the first element with `get<0>(`*`FWD`*`(u))` and
1519
+ the second element with `get<1>(`*`FWD`*`(u))`.
 
1520
 
1521
+ *Remarks:* The expression inside `explicit` is equivalent to:
1522
 
1523
  ``` cpp
1524
+ !is_convertible_v<decltype(get<0>(FWD(u))), $T_0$> ||
1525
+ !is_convertible_v<decltype(get<1>(FWD(u))), $T_1$>
1526
+ ```
1527
+
1528
+ The constructor is defined as deleted if
1529
+
1530
+ ``` cpp
1531
+ reference_constructs_from_temporary_v<$T_0$, decltype(get<0>(FWD(u)))> ||
1532
+ reference_constructs_from_temporary_v<$T_1$, decltype(get<1>(FWD(u)))>
1533
+ ```
1534
+
1535
+ is `true`.
1536
+
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))`.
1558
+
1559
+ *Remarks:* The expression inside `explicit` is equivalent to:
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)
 
1574
  tuple(allocator_arg_t, const Alloc& a, UTypes&&...);
1575
  template<class Alloc>
1576
  constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&);
1577
  template<class Alloc>
1578
  constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&);
1579
+ template<class Alloc, class... UTypes>
1580
+ constexpr explicit(see below)
1581
+ tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&);
1582
  template<class Alloc, class... UTypes>
1583
  constexpr explicit(see below)
1584
  tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
1585
  template<class Alloc, class... UTypes>
1586
  constexpr explicit(see below)
1587
  tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
1588
+ template<class Alloc, class... UTypes>
1589
+ constexpr explicit(see below)
1590
+ tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&&);
1591
+ template<class Alloc, class U1, class U2>
1592
+ constexpr explicit(see below)
1593
+ tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&);
1594
  template<class Alloc, class U1, class U2>
1595
  constexpr explicit(see below)
1596
  tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
1597
  template<class Alloc, class U1, class U2>
1598
  constexpr explicit(see below)
1599
  tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
1600
+ template<class Alloc, class U1, class U2>
1601
+ constexpr explicit(see below)
1602
+ tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&&);
1603
+ template<class Alloc, tuple-like UTuple>
1604
+ constexpr explicit(see below)
1605
+ tuple(allocator_arg_t, const Alloc& a, UTuple&&);
1606
  ```
1607
 
1608
+ *Preconditions:* `Alloc` meets the *Cpp17Allocator*
1609
+ requirements [[allocator.requirements.general]].
1610
 
1611
  *Effects:* Equivalent to the preceding constructors except that each
1612
  element is constructed with uses-allocator
1613
  construction [[allocator.uses.construction]].
1614
 
 
1626
  ```
1627
 
1628
  *Effects:* Assigns each element of `u` to the corresponding element of
1629
  `*this`.
1630
 
1631
+ *Returns:* `*this`.
1632
+
1633
  *Remarks:* This operator is defined as deleted unless
1634
  `is_copy_assignable_v<``Tᵢ``>` is `true` for all i.
1635
 
1636
+ ``` cpp
1637
+ constexpr const tuple& operator=(const tuple& u) const;
1638
+ ```
1639
+
1640
+ *Constraints:* `(is_copy_assignable_v<const Types> && ...)` is `true`.
1641
+
1642
+ *Effects:* Assigns each element of `u` to the corresponding element of
1643
+ `*this`.
1644
+
1645
  *Returns:* `*this`.
1646
 
1647
  ``` cpp
1648
  constexpr tuple& operator=(tuple&& u) noexcept(see below);
1649
  ```
 
1651
  *Constraints:* `is_move_assignable_v<``Tᵢ``>` is `true` for all i.
1652
 
1653
  *Effects:* For all i, assigns `std::forward<``Tᵢ``>(get<`i`>(u))` to
1654
  `get<`i`>(*this)`.
1655
 
1656
+ *Returns:* `*this`.
1657
+
1658
+ *Remarks:* The exception specification is equivalent to the logical of
1659
+ the following expressions:
1660
 
1661
  ``` cpp
1662
  is_nothrow_move_assignable_v<Tᵢ>
1663
  ```
1664
 
1665
  where Tᵢ is the iᵗʰ type in `Types`.
1666
 
1667
+ ``` cpp
1668
+ constexpr const tuple& operator=(tuple&& u) const;
1669
+ ```
1670
+
1671
+ *Constraints:* `(is_assignable_v<const Types&, Types> && ...)` is
1672
+ `true`.
1673
+
1674
+ *Effects:* For all i, assigns `std::forward<T`ᵢ`>(get<`i`>(u))` to
1675
+ `get<`i`>(*this)`.
1676
+
1677
  *Returns:* `*this`.
1678
 
1679
  ``` cpp
1680
  template<class... UTypes> constexpr tuple& operator=(const tuple<UTypes...>& u);
1681
  ```
 
1688
  *Effects:* Assigns each element of `u` to the corresponding element of
1689
  `*this`.
1690
 
1691
  *Returns:* `*this`.
1692
 
1693
+ ``` cpp
1694
+ template<class... UTypes> constexpr const tuple& operator=(const tuple<UTypes...>& u) const;
1695
+ ```
1696
+
1697
+ *Constraints:*
1698
+
1699
+ - `sizeof...(Types)` equals `sizeof...(UTypes)` and
1700
+ - `(is_assignable_v<const Types&, const UTypes&> && ...)` is `true`.
1701
+
1702
+ *Effects:* Assigns each element of `u` to the corresponding element of
1703
+ `*this`.
1704
+
1705
+ *Returns:* `*this`.
1706
+
1707
  ``` cpp
1708
  template<class... UTypes> constexpr tuple& operator=(tuple<UTypes...>&& u);
1709
  ```
1710
 
1711
  *Constraints:*
 
1716
  *Effects:* For all i, assigns `std::forward<``Uᵢ``>(get<`i`>(u))` to
1717
  `get<`i`>(*this)`.
1718
 
1719
  *Returns:* `*this`.
1720
 
1721
+ ``` cpp
1722
+ template<class... UTypes> constexpr const tuple& operator=(tuple<UTypes...>&& u) const;
1723
+ ```
1724
+
1725
+ *Constraints:*
1726
+
1727
+ - `sizeof...(Types)` equals `sizeof...(UTypes)` and
1728
+ - `(is_assignable_v<const Types&, UTypes> && ...)` is `true`.
1729
+
1730
+ *Effects:* For all i, assigns `std::forward<U`ᵢ`>(get<`i`>(u))` to
1731
+ `get<`i`>(*this)`.
1732
+
1733
+ *Returns:* `*this`.
1734
+
1735
  ``` cpp
1736
  template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>& u);
1737
  ```
1738
 
1739
  *Constraints:*
 
1745
  *Effects:* Assigns `u.first` to the first element of `*this` and
1746
  `u.second` to the second element of `*this`.
1747
 
1748
  *Returns:* `*this`.
1749
 
1750
+ ``` cpp
1751
+ template<class U1, class U2> constexpr const tuple& operator=(const pair<U1, U2>& u) const;
1752
+ ```
1753
+
1754
+ *Constraints:*
1755
+
1756
+ - `sizeof...(Types)` is 2,
1757
+ - `is_assignable_v<const ``T₀``&, const U1&>` is `true`, and
1758
+ - `is_assignable_v<const ``T₁``&, const U2&>` is `true`.
1759
+
1760
+ *Effects:* Assigns `u.first` to the first element and `u.second` to the
1761
+ second element.
1762
+
1763
+ *Returns:* `*this`.
1764
+
1765
  ``` cpp
1766
  template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&& u);
1767
  ```
1768
 
1769
  *Constraints:*
 
1776
  `*this` and
1777
  `std::forward<U2>(u.second)` to the second element of `*this`.
1778
 
1779
  *Returns:* `*this`.
1780
 
1781
+ ``` cpp
1782
+ template<class U1, class U2> constexpr const tuple& operator=(pair<U1, U2>&& u) const;
1783
+ ```
1784
+
1785
+ *Constraints:*
1786
+
1787
+ - `sizeof...(Types)` is 2,
1788
+ - `is_assignable_v<const ``T₀``&, U1>` is `true`, and
1789
+ - `is_assignable_v<const ``T₁``&, U2>` is `true`.
1790
+
1791
+ *Effects:* Assigns `std::forward<U1>(u.first)` to the first element
1792
+ and
1793
+ `std::forward<U2>(u.second)` to the second element.
1794
+
1795
+ *Returns:* `*this`.
1796
+
1797
+ ``` cpp
1798
+ template<tuple-like UTuple>
1799
+ constexpr tuple& operator=(UTuple&& u);
1800
+ ```
1801
+
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)`.
1813
+
1814
+ *Returns:* `*this`.
1815
+
1816
+ ``` cpp
1817
+ template<tuple-like UTuple>
1818
+ constexpr const tuple& operator=(UTuple&& u) const;
1819
+ ```
1820
+
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)`.
1832
+
1833
+ *Returns:* `*this`.
1834
+
1835
  #### `swap` <a id="tuple.swap">[[tuple.swap]]</a>
1836
 
1837
  ``` cpp
1838
  constexpr void swap(tuple& rhs) noexcept(see below);
1839
+ constexpr void swap(const tuple& rhs) const noexcept(see below);
1840
  ```
1841
 
1842
+ Let i be in the range \[`0`, `sizeof...(Types)`) in order.
 
1843
 
1844
+ *Mandates:*
 
1845
 
1846
+ - For the first overload, `(is_swappable_v<Types> && ...)` is `true`.
1847
+ - For the second overload, `(is_swappable_v<const Types> && ...)` is
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
 
1859
+ *Remarks:* The exception specification is equivalent to
1860
+
1861
+ - `(is_nothrow_swappable_v<Types> && ...)` for the first overload and
1862
+ - `(is_nothrow_swappable_v<const Types> && ...)` for the second
1863
+ overload.
1864
+
1865
  ### Tuple creation functions <a id="tuple.creation">[[tuple.creation]]</a>
1866
 
 
 
 
 
1867
  ``` cpp
1868
  template<class... TTypes>
1869
  constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&... t);
1870
  ```
1871
 
 
1874
 
1875
  [*Example 1*:
1876
 
1877
  ``` cpp
1878
  int i; float j;
1879
+ make_tuple(1, ref(i), cref(j));
1880
  ```
1881
 
1882
  creates a tuple of type `tuple<int, int&, const float&>`.
1883
 
1884
  — *end example*]
 
1918
  ```
1919
 
1920
  — *end example*]
1921
 
1922
  ``` cpp
1923
+ template<tuple-like... Tuples>
1924
  constexpr tuple<CTypes...> tuple_cat(Tuples&&... tpls);
1925
  ```
1926
 
1927
+ Let n be `sizeof...(Tuples)`. For every integer 0 i < n:
 
 
1928
 
1929
+ - Let `Tᵢ` be the iᵗʰ type in `Tuples`.
1930
+ - Let `Uᵢ` be `remove_cvref_t<``Tᵢ``>`.
1931
+ - Let `tpᵢ` be the iᵗʰ element in the function parameter pack `tpls`.
1932
+ - Let Sᵢ be `tuple_size_v<``Uᵢ``>`.
1933
+ - Let Eᵢᵏ be `tuple_element_t<`k`, ``Uᵢ``>`.
1934
+ - Let eᵢᵏ be `get<`k`>(std::forward<``Tᵢ``>(``tpᵢ``))`.
1935
+ - Let Elemsᵢ be a pack of the types $E_i^0, \dotsc, E_i^{S_{i-1}}$.
1936
+ - Let elemsᵢ be a pack of the expressions
1937
+ $e_i^0, \dotsc, e_i^{S_{i-1}}$.
1938
 
1939
+ The types in `CTypes` are equal to the ordered sequence of the expanded
1940
+ packs of types Elems₀`...`, Elems₁`...`, …, Elemsₙ₋₁`...`. Let `celems`
1941
+ be the ordered sequence of the expanded packs of expressions
1942
+ elems₀`...`, …, elemsₙ₋₁`...`.
1943
 
1944
+ *Mandates:* `(is_constructible_v<CTypes, decltype(celems)> && ...)` is
1945
+ `true`.
 
 
 
1946
 
1947
+ *Returns:* `tuple<CTypes...>(celems...)`.
 
 
 
 
 
 
 
 
 
 
 
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...>) {
1962
  // exposition only
1963
+ return INVOKE(std::forward<F>(f), get<I>(std::forward<Tuple>(t))...); // see [func.require]
1964
+ }
1965
  }
1966
  ```
1967
 
1968
  Equivalent to:
1969
 
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>()))...>
1998
  constexpr T make-from-tuple-impl(Tuple&& t, index_sequence<I...>) { // exposition only
1999
  return T(get<I>(std::forward<Tuple>(t))...);
2000
  }
2001
+ }
2002
  ```
2003
 
2004
  Equivalent to:
2005
 
2006
  ``` cpp
2007
  return make-from-tuple-impl<T>(
2008
+ std::forward<Tuple>(t),
2009
  make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
2010
  ```
2011
 
2012
  [*Note 1*: The type of `T` must be supplied as an explicit template
2013
  parameter, as it cannot be deduced from the argument
 
2044
  template<class T> struct tuple_size<const T>;
2045
  ```
2046
 
2047
  Let `TS` denote `tuple_size<T>` of the cv-unqualified type `T`. If the
2048
  expression `TS::value` is well-formed when treated as an unevaluated
2049
+ operand [[term.unevaluated.operand]], then each specialization of the
2050
+ template meets the *Cpp17UnaryTypeTrait* requirements [[meta.rqmts]]
2051
+ with a base characteristic of
2052
 
2053
  ``` cpp
2054
  integral_constant<size_t, TS::value>
2055
  ```
2056
 
 
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>
 
2149
  ### Relational operators <a id="tuple.rel">[[tuple.rel]]</a>
2150
 
2151
  ``` cpp
2152
  template<class... TTypes, class... UTypes>
2153
  constexpr bool operator==(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
2154
+ 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
2171
+ `true`. *end note*]
2172
+
2173
+ *Remarks:*
2174
+
2175
+ - The elementary comparisons are performed in order from the zeroth
2176
+ index upwards. No comparisons or element accesses are performed after
2177
+ the first equality comparison that evaluates to `false`.
2178
+ - The second overload is to be found via argument-dependent
2179
+ lookup [[basic.lookup.argdep]] only.
2180
 
2181
  ``` cpp
2182
  template<class... TTypes, class... UTypes>
2183
  constexpr common_comparison_category_t<synth-three-way-result<TTypes, UTypes>...>
2184
  operator<=>(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
2185
+ template<class... TTypes, tuple-like UTuple>
2186
+ constexpr common_comparison_category_t<synth-three-way-result<TTypes, Elems>...>
2187
+ operator<=>(const tuple<TTypes...>& t, const UTuple& u);
2188
  ```
2189
 
2190
+ For the second overload, `Elems` denotes the pack of types
2191
+ `tuple_element_t<0, UTuple>`, `tuple_element_t<1, UTuple>`, …,
2192
+ `tuple_element_t<tuple_size_v<UTuple> - 1, UTuple>`.
2193
+
2194
+ *Effects:* Performs a lexicographical comparison between `t` and `u`. If
2195
+ `sizeof...(TTypes)` equals zero, returns `strong_ordering::equal`.
2196
+ Otherwise, equivalent to:
2197
 
2198
  ``` cpp
2199
  if (auto c = synth-three-way(get<0>(t), get<0>(u)); c != 0) return c;
2200
  return $t_tail$ <=> $u_tail$;
2201
  ```
2202
 
2203
+ where `r_tail` for some `r` is a tuple containing all but the first
2204
+ element of `r`.
2205
+
2206
+ *Remarks:* The second overload is to be found via argument-dependent
2207
+ 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:
2219
+
2220
+ - Let `TTypes` be a pack formed by the sequence of
2221
+ `tuple_element_t<i, TTuple>` for every integer
2222
+ 0 ≤ i < `tuple_size_v<TTuple>`.
2223
+ - Let `UTypes` be a pack formed by the sequence of
2224
+ `tuple_element_t<i, UTuple>` for every integer
2225
+ 0 ≤ i < `tuple_size_v<UTuple>`.
2226
+
2227
+ ``` cpp
2228
+ template<tuple-like TTuple, tuple-like UTuple,
2229
+ template<class> class TQual, template<class> class UQual>
2230
+ struct basic_common_reference<TTuple, UTuple, TQual, UQual> {
2231
+ using type = see below;
2232
+ };
2233
+ ```
2234
+
2235
+ *Constraints:*
2236
+
2237
+ - `TTuple` is a specialization of `tuple` or `UTuple` is a
2238
+ specialization of `tuple`.
2239
+ - `is_same_v<TTuple, decay_t<TTuple>>` is `true`.
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> {
2251
+ using type = see below;
2252
+ };
2253
+ ```
2254
+
2255
+ *Constraints:*
2256
+
2257
+ - `TTuple` is a specialization of `tuple` or `UTuple` is a
2258
+ specialization of `tuple`.
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
2270
  template<class... Types, class Alloc>
2271
  struct uses_allocator<tuple<Types...>, Alloc> : true_type { };
2272
  ```
2273
 
2274
+ *Preconditions:* `Alloc` meets the *Cpp17Allocator*
2275
+ requirements [[allocator.requirements.general]].
2276
 
2277
  [*Note 1*: Specialization of this trait informs other library
2278
  components that `tuple` can be constructed with an allocator, even
2279
  though it does not have a nested `allocator_type`. — *end note*]
2280
 
2281
  ### Tuple specialized algorithms <a id="tuple.special">[[tuple.special]]</a>
2282
 
2283
  ``` cpp
2284
  template<class... Types>
2285
  constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(see below);
2286
+ template<class... Types>
2287
+ constexpr void swap(const tuple<Types...>& x, const tuple<Types...>& y) noexcept(see below);
2288
  ```
2289
 
2290
+ *Constraints:*
 
2291
 
2292
+ - For the first overload, `(is_swappable_v<Types> && ...)` is `true`.
2293
+ - For the second overload, `(is_swappable_v<const Types> && ...)` is
2294
+ `true`.
 
 
2295
 
2296
  *Effects:* As if by `x.swap(y)`.
2297
 
2298
+ *Remarks:* The exception specification is equivalent to:
2299
+
2300
+ ``` cpp
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
 
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
+ };
2330
+
2331
  // [optional.nullopt], no-value state indicator
2332
  struct nullopt_t{see below};
2333
  inline constexpr nullopt_t nullopt(unspecified);
2334
 
2335
  // [optional.bad.access], class bad_optional_access
 
2368
  template<class T, class U> constexpr bool operator>(const T&, const optional<U>&);
2369
  template<class T, class U> constexpr bool operator<=(const optional<T>&, const U&);
2370
  template<class T, class U> constexpr bool operator<=(const T&, const optional<U>&);
2371
  template<class T, class U> constexpr bool operator>=(const optional<T>&, const U&);
2372
  template<class T, class U> constexpr bool operator>=(const T&, const optional<U>&);
2373
+ template<class T, class U>
2374
+ requires (!is-derived-from-optional<U>) && three_way_comparable_with<T, U>
2375
  constexpr compare_three_way_result_t<T, U>
2376
  operator<=>(const optional<T>&, const U&);
2377
 
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);
 
2392
  }
2393
  ```
2394
 
2395
  ### Class template `optional` <a id="optional.optional">[[optional.optional]]</a>
2396
 
2397
+ #### General <a id="optional.optional.general">[[optional.optional.general]]</a>
2398
+
2399
  ``` cpp
2400
  namespace std {
2401
  template<class T>
2402
  class optional {
2403
  public:
 
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>&&);
2421
 
2422
  // [optional.dtor], destructor
2423
+ constexpr ~optional();
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 &;
2458
+ template<class F> constexpr auto and_then(F&& f) const &&;
2459
+ template<class F> constexpr auto transform(F&& f) &;
2460
+ template<class F> constexpr auto transform(F&& f) &&;
2461
+ template<class F> constexpr auto transform(F&& f) const &;
2462
+ template<class F> constexpr auto transform(F&& f) const &&;
2463
+ template<class F> constexpr optional or_else(F&& f) &&;
2464
+ template<class F> constexpr optional or_else(F&& f) const &;
2465
+
2466
  // [optional.mod], modifiers
2467
+ constexpr void reset() noexcept;
2468
 
2469
  private:
2470
  T *val; // exposition only
2471
  };
2472
 
 
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`.
2498
+
2499
+ ``` cpp
2500
+ template<class T, class W>
2501
+ constexpr bool converts-from-any-cvref = // exposition only
2502
+ disjunction_v<is_constructible<T, W&>, is_convertible<W&, T>,
2503
+ is_constructible<T, W>, is_convertible<W, T>,
2504
+ is_constructible<T, const W&>, is_convertible<const W&, T>,
2505
+ is_constructible<T, const W>, is_convertible<const W, T>>;
2506
+ ```
2507
+
2508
  ``` cpp
2509
  constexpr optional() noexcept;
2510
  constexpr optional(nullopt_t) noexcept;
2511
  ```
2512
 
 
2517
 
2518
  ``` cpp
2519
  constexpr optional(const optional& rhs);
2520
  ```
2521
 
2522
+ *Effects:* If `rhs` contains a value, direct-non-list-initializes the
2523
+ contained value with `*rhs`.
 
2524
 
2525
+ *Ensures:* `rhs.has_value() == this->has_value()`.
2526
 
2527
  *Throws:* Any exception thrown by the selected constructor of `T`.
2528
 
2529
  *Remarks:* This constructor is defined as deleted unless
2530
  `is_copy_constructible_v<T>` is `true`. If
 
2535
  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
 
2547
+ *Remarks:* The exception specification is equivalent to
2548
  `is_nothrow_move_constructible_v<T>`. If
2549
  `is_trivially_move_constructible_v<T>` is `true`, this constructor is
2550
  trivial.
2551
 
2552
  ``` cpp
2553
  template<class... Args> constexpr explicit optional(in_place_t, Args&&... args);
2554
  ```
2555
 
2556
  *Constraints:* `is_constructible_v<T, Args...>` is `true`.
2557
 
2558
+ *Effects:* Direct-non-list-initializes the contained value with
 
2559
  `std::forward<Args>(args)...`.
2560
 
2561
  *Ensures:* `*this` contains a value.
2562
 
2563
  *Throws:* Any exception thrown by the selected constructor of `T`.
 
2571
  ```
2572
 
2573
  *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
2574
  `true`.
2575
 
2576
+ *Effects:* Direct-non-list-initializes the contained value with
 
2577
  `il, std::forward<Args>(args)...`.
2578
 
2579
  *Ensures:* `*this` contains a value.
2580
 
2581
  *Throws:* Any exception thrown by the selected constructor of `T`.
 
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`,
2593
+ - `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`,
2594
+ - `is_same_v<remove_cvref_t<U>, optional>` is `false`, and
2595
+ - if `T` is cv `bool`, `remove_cvref_t<U>` is not a specialization of
2596
+ `optional`.
2597
+
2598
+ *Effects:* Direct-non-list-initializes the contained value with
2599
  `std::forward<U>(v)`.
2600
 
2601
  *Ensures:* `*this` contains a value.
2602
 
2603
  *Throws:* Any exception thrown by the selected constructor of `T`.
 
2609
  ``` cpp
2610
  !is_convertible_v<U, T>
2611
  ```
2612
 
2613
  ``` cpp
2614
+ template<class U> constexpr explicit(see below) optional(const optional<U>& rhs);
2615
  ```
2616
 
2617
  *Constraints:*
2618
 
2619
+ - `is_constructible_v<T, const U&>` is `true`, and
2620
+ - if `T` is not cv `bool`, *`converts-from-any-cvref`*`<T, optional<U>>`
2621
+ is `false`.
 
 
 
 
 
 
2622
 
2623
+ *Effects:* If `rhs` contains a value, direct-non-list-initializes the
2624
+ contained value with `*rhs`.
 
2625
 
2626
+ *Ensures:* `rhs.has_value() == this->has_value()`.
2627
 
2628
  *Throws:* Any exception thrown by the selected constructor of `T`.
2629
 
2630
  *Remarks:* The expression inside `explicit` is equivalent to:
2631
 
2632
  ``` cpp
2633
  !is_convertible_v<const U&, T>
2634
  ```
2635
 
2636
  ``` cpp
2637
+ template<class U> constexpr explicit(see below) optional(optional<U>&& rhs);
2638
  ```
2639
 
2640
  *Constraints:*
2641
 
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
 
2653
  *Remarks:* The expression inside `explicit` is equivalent to:
2654
 
 
2657
  ```
2658
 
2659
  #### Destructor <a id="optional.dtor">[[optional.dtor]]</a>
2660
 
2661
  ``` cpp
2662
+ constexpr ~optional();
2663
  ```
2664
 
2665
  *Effects:* If `is_trivially_destructible_v<T> != true` and `*this`
2666
  contains a value, calls
2667
 
 
2673
  destructor is trivial.
2674
 
2675
  #### Assignment <a id="optional.assign">[[optional.assign]]</a>
2676
 
2677
  ``` cpp
2678
+ constexpr optional<T>& operator=(nullopt_t) noexcept;
2679
  ```
2680
 
2681
  *Effects:* If `*this` contains a value, calls `val->T::T̃()` to destroy
2682
  the contained value; otherwise no effect.
2683
 
 
2692
  *Effects:* See [[optional.assign.copy]].
2693
 
2694
  **Table: `optional::operator=(const optional&)` effects** <a id="optional.assign.copy">[optional.assign.copy]</a>
2695
 
2696
  | | `*this` contains a value | `*this` does not contain a value |
2697
+ | ------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------- |
2698
+ | `rhs` contains a value | assigns `*rhs` to the contained value | direct-non-list-initializes the contained value with `*rhs` |
2699
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2700
 
2701
 
2702
+ *Ensures:* `rhs.has_value() == this->has_value()`.
2703
 
2704
  *Returns:* `*this`.
2705
 
2706
  *Remarks:* If any exception is thrown, the result of the expression
2707
+ `this->has_value()` remains unchanged. If an exception is thrown during
2708
+ the call to `T`’s copy constructor, no effect. If an exception is thrown
2709
  during the call to `T`’s copy assignment, the state of its contained
2710
  value is as defined by the exception safety guarantee of `T`’s copy
2711
  assignment. This operator is defined as deleted unless
2712
  `is_copy_constructible_v<T>` is `true` and `is_copy_assignable_v<T>` is
2713
  `true`. If `is_trivially_copy_constructible_v<T> &&`
 
2720
 
2721
  *Constraints:* `is_move_constructible_v<T>` is `true` and
2722
  `is_move_assignable_v<T>` is `true`.
2723
 
2724
  *Effects:* See [[optional.assign.move]]. The result of the expression
2725
+ `rhs.has_value()` remains unchanged.
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
 
2737
  *Returns:* `*this`.
2738
 
2739
+ *Remarks:* The exception specification is equivalent to:
2740
 
2741
  ``` cpp
2742
  is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T>
2743
  ```
2744
 
2745
+ If any exception is thrown, the result of the expression
2746
+ `this->has_value()` remains unchanged. If an exception is thrown during
2747
+ the call to `T`’s move constructor, the state of `*rhs.val` is
2748
+ determined by the exception safety guarantee of `T`’s move constructor.
2749
+ If an exception is thrown during the call to `T`’s move assignment, the
2750
+ state of `*val` and `*rhs.val` is determined by the exception safety
2751
+ 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
 
2769
  *Ensures:* `*this` contains a value.
2770
 
2771
  *Returns:* `*this`.
2772
 
2773
  *Remarks:* If any exception is thrown, the result of the expression
2774
+ `this->has_value()` remains unchanged. If an exception is thrown during
2775
+ the call to `T`’s constructor, the state of `v` is determined by the
2776
  exception safety guarantee of `T`’s constructor. If an exception is
2777
  thrown during the call to `T`’s assignment, the state of `*val` and `v`
2778
  is determined by the exception safety guarantee of `T`’s assignment.
2779
 
2780
  ``` cpp
2781
+ template<class U> constexpr optional<T>& operator=(const optional<U>& rhs);
2782
  ```
2783
 
2784
  *Constraints:*
2785
 
2786
  - `is_constructible_v<T, const U&>` is `true`,
2787
  - `is_assignable_v<T&, const U&>` is `true`,
2788
+ - *`converts-from-any-cvref`*`<T, optional<U>>` is `false`,
 
 
 
 
 
 
 
2789
  - `is_assignable_v<T&, optional<U>&>` is `false`,
2790
  - `is_assignable_v<T&, optional<U>&&>` is `false`,
2791
  - `is_assignable_v<T&, const optional<U>&>` is `false`, and
2792
  - `is_assignable_v<T&, const optional<U>&&>` is `false`.
2793
 
2794
  *Effects:* See [[optional.assign.copy.templ]].
2795
 
2796
  **Table: `optional::operator=(const optional<U>&)` effects** <a id="optional.assign.copy.templ">[optional.assign.copy.templ]</a>
2797
 
2798
  | | `*this` contains a value | `*this` does not contain a value |
2799
+ | ------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------- |
2800
+ | `rhs` contains a value | assigns `*rhs` to the contained value | direct-non-list-initializes the contained value with `*rhs` |
2801
  | `rhs` does not contain a value | destroys the contained value by calling `val->T::~T()` | no effect |
2802
 
2803
 
2804
+ *Ensures:* `rhs.has_value() == this->has_value()`.
2805
 
2806
  *Returns:* `*this`.
2807
 
2808
  *Remarks:* If any exception is thrown, the result of the expression
2809
+ `this->has_value()` remains unchanged. If an exception is thrown during
2810
+ the call to `T`’s constructor, the state of `*rhs.val` is determined by
2811
+ the exception safety guarantee of `T`’s constructor. If an exception is
2812
  thrown during the call to `T`’s assignment, the state of `*val` and
2813
  `*rhs.val` is determined by the exception safety guarantee of `T`’s
2814
  assignment.
2815
 
2816
  ``` cpp
2817
+ template<class U> constexpr optional<T>& operator=(optional<U>&& rhs);
2818
  ```
2819
 
2820
  *Constraints:*
2821
 
2822
  - `is_constructible_v<T, U>` is `true`,
2823
  - `is_assignable_v<T&, U>` is `true`,
2824
+ - *`converts-from-any-cvref`*`<T, optional<U>>` is `false`,
 
 
 
 
 
 
 
2825
  - `is_assignable_v<T&, optional<U>&>` is `false`,
2826
  - `is_assignable_v<T&, optional<U>&&>` is `false`,
2827
  - `is_assignable_v<T&, const optional<U>&>` is `false`, and
2828
  - `is_assignable_v<T&, const optional<U>&&>` is `false`.
2829
 
2830
  *Effects:* See [[optional.assign.move.templ]]. The result of the
2831
+ 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
 
2843
  *Returns:* `*this`.
2844
 
2845
  *Remarks:* If any exception is thrown, the result of the expression
2846
+ `this->has_value()` remains unchanged. If an exception is thrown during
2847
+ the call to `T`’s constructor, the state of `*rhs.val` is determined by
2848
+ the exception safety guarantee of `T`’s constructor. If an exception is
2849
  thrown during the call to `T`’s assignment, the state of `*val` and
2850
  `*rhs.val` is determined by the exception safety guarantee of `T`’s
2851
  assignment.
2852
 
2853
  ``` cpp
2854
+ template<class... Args> constexpr T& emplace(Args&&... args);
2855
  ```
2856
 
2857
  *Mandates:* `is_constructible_v<T, Args...>` is `true`.
2858
 
2859
+ *Effects:* Calls `*this = nullopt`. Then direct-non-list-initializes the
2860
+ contained value with `std::forward<Args>(args)...`.
 
2861
 
2862
  *Ensures:* `*this` contains a value.
2863
 
2864
  *Returns:* A reference to the new contained value.
2865
 
 
2868
  *Remarks:* If an exception is thrown during the call to `T`’s
2869
  constructor, `*this` does not contain a value, and the previous `*val`
2870
  (if any) has been destroyed.
2871
 
2872
  ``` cpp
2873
+ template<class U, class... Args> constexpr T& emplace(initializer_list<U> il, Args&&... args);
2874
  ```
2875
 
2876
  *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
2877
  `true`.
2878
 
2879
+ *Effects:* Calls `*this = nullopt`. Then direct-non-list-initializes the
2880
+ contained value with `il, std::forward<Args>(args)...`.
 
2881
 
2882
  *Ensures:* `*this` contains a value.
2883
 
2884
  *Returns:* A reference to the new contained value.
2885
 
 
2890
  (if any) has been destroyed.
2891
 
2892
  #### Swap <a id="optional.swap">[[optional.swap]]</a>
2893
 
2894
  ``` cpp
2895
+ constexpr void swap(optional& rhs) noexcept(see below);
2896
  ```
2897
 
2898
  *Mandates:* `is_move_constructible_v<T>` is `true`.
2899
 
2900
+ *Preconditions:* `T` meets the *Cpp17Swappable*
2901
+ requirements [[swappable.requirements]].
2902
 
2903
  *Effects:* See [[optional.swap]].
2904
 
2905
  **Table: `optional::swap(optional&)` effects** <a id="optional.swap">[optional.swap]</a>
2906
 
2907
  | | `*this` contains a value | `*this` does not contain a value |
2908
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2909
+ | `rhs` contains a value | calls `swap(*(*this), *rhs)` | direct-non-list-initializes the contained value of `*this` with `std::move(*rhs)`, followed by `rhs.val->T::~T()`; postcondition is that `*this` contains a value and `rhs` does not contain a value |
2910
+ | `rhs` does not contain a value | direct-non-list-initializes the contained value of `rhs` with `std::move(*(*this))`, followed by `val->T::~T()`; postcondition is that `*this` does not contain a value and `rhs` contains a value | no effect |
2911
 
2912
 
2913
  *Throws:* Any exceptions thrown by the operations in the relevant part
2914
  of [[optional.swap]].
2915
 
2916
+ *Remarks:* The exception specification is equivalent to:
2917
 
2918
  ``` cpp
2919
  is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T>
2920
  ```
2921
 
2922
+ If any exception is thrown, the results of the expressions
2923
+ `this->has_value()` and `rhs.has_value()` remain unchanged. If an
2924
+ 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);`
 
2982
  ```
2983
 
2984
  *Effects:* Equivalent to:
2985
 
2986
  ``` cpp
2987
+ return has_value() ? *val : throw bad_optional_access();
2988
  ```
2989
 
2990
  ``` cpp
2991
  constexpr T&& value() &&;
2992
  constexpr const T&& value() const &&;
2993
  ```
2994
 
2995
  *Effects:* Equivalent to:
2996
 
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
  ```
 
3006
  `true`.
3007
 
3008
  *Effects:* Equivalent to:
3009
 
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
  ```
 
3019
  `true`.
3020
 
3021
  *Effects:* Equivalent to:
3022
 
3023
  ``` cpp
3024
+ return has_value() ? std::move(**this) : static_cast<T>(std::forward<U>(v));
3025
+ ```
3026
+
3027
+ #### Monadic operations <a id="optional.monadic">[[optional.monadic]]</a>
3028
+
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
+
3125
+ *Effects:* Equivalent to:
3126
+
3127
+ ``` cpp
3128
+ if (*this) {
3129
+ return *this;
3130
+ } else {
3131
+ return std::forward<F>(f)();
3132
+ }
3133
+ ```
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
+
3145
+ *Effects:* Equivalent to:
3146
+
3147
+ ``` cpp
3148
+ if (*this) {
3149
+ return std::move(*this);
3150
+ } else {
3151
+ return std::forward<F>(f)();
3152
+ }
3153
  ```
3154
 
3155
  #### Modifiers <a id="optional.mod">[[optional.mod]]</a>
3156
 
3157
  ``` cpp
3158
+ constexpr void reset() noexcept;
3159
  ```
3160
 
3161
  *Effects:* If `*this` contains a value, calls `val->T::T̃()` to destroy
3162
  the contained value; otherwise no effect.
3163
 
 
3180
  initializer-list constructor, and shall not be an aggregate.
3181
 
3182
  ### Class `bad_optional_access` <a id="optional.bad.access">[[optional.bad.access]]</a>
3183
 
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.
 
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`.
3217
 
3218
  *Remarks:* Specializations of this function template for which
3219
  `*x == *y` is a core constant expression are constexpr functions.
3220
 
3221
  ``` cpp
 
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
3232
  `*x != *y` is a core constant expression are constexpr functions.
3233
 
3234
  ``` cpp
 
3287
  template<class T, three_way_comparable_with<T> U>
3288
  constexpr compare_three_way_result_t<T, U>
3289
  operator<=>(const optional<T>& x, const optional<U>& y);
3290
  ```
3291
 
3292
+ *Returns:* If `x && y`, `*x <=> *y`; otherwise
3293
+ `x.has_value() <=> y.has_value()`.
3294
 
3295
  *Remarks:* Specializations of this function template for which
3296
  `*x <=> *y` is a core constant expression are constexpr functions.
3297
 
3298
  ### Comparison with `nullopt` <a id="optional.nullops">[[optional.nullops]]</a>
 
3305
 
3306
  ``` cpp
3307
  template<class T> constexpr strong_ordering operator<=>(const optional<T>& x, nullopt_t) noexcept;
3308
  ```
3309
 
3310
+ *Returns:* `x.has_value() <=> false`.
3311
 
3312
  ### Comparison with `T` <a id="optional.comp.with.t">[[optional.comp.with.t]]</a>
3313
 
3314
  ``` cpp
3315
  template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
 
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>
3426
+ requires (!is-derived-from-optional<U>) && three_way_comparable_with<T, U>
3427
  constexpr compare_three_way_result_t<T, U>
3428
  operator<=>(const optional<T>& x, const U& v);
3429
  ```
3430
 
3431
  *Effects:* Equivalent to:
3432
+ `return x.has_value() ? *x <=> v : strong_ordering::less;`
3433
 
3434
  ### Specialized algorithms <a id="optional.specalg">[[optional.specalg]]</a>
3435
 
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
 
 
3471
  template<class T> struct hash<optional<T>>;
3472
  ```
3473
 
3474
  The specialization `hash<optional<T>>` is enabled [[unord.hash]] if and
3475
  only if `hash<remove_const_t<T>>` is enabled. When enabled, for an
3476
+ object `o` of type `optional<T>`, if `o.has_value() == true`, then
3477
  `hash<optional<T>>()(o)` evaluates to the same value as
3478
  `hash<remove_const_t<T>>()(*o)`; otherwise it evaluates to an
3479
  unspecified value. The member functions are not guaranteed to be
3480
  `noexcept`.
3481
 
 
3500
 
3501
  // [variant.helper], variant helper classes
3502
  template<class T> struct variant_size; // not defined
3503
  template<class T> struct variant_size<const T>;
3504
  template<class T>
3505
+ constexpr size_t variant_size_v = variant_size<T>::value;
3506
 
3507
  template<class... Types>
3508
  struct variant_size<variant<Types...>>;
3509
 
3510
  template<size_t I, class T> struct variant_alternative; // not defined
 
3583
  constexpr bool operator==(monostate, monostate) noexcept;
3584
  constexpr strong_ordering operator<=>(monostate, monostate) noexcept;
3585
 
3586
  // [variant.specalg], specialized algorithms
3587
  template<class... Types>
3588
+ constexpr void swap(variant<Types...>&, variant<Types...>&) noexcept(see below);
3589
 
3590
  // [variant.bad.access], class bad_variant_access
3591
  class bad_variant_access;
3592
 
3593
  // [variant.hash], hash support
 
3597
  }
3598
  ```
3599
 
3600
  ### Class template `variant` <a id="variant.variant">[[variant.variant]]</a>
3601
 
3602
+ #### General <a id="variant.variant.general">[[variant.variant.general]]</a>
3603
+
3604
  ``` cpp
3605
  namespace std {
3606
  template<class... Types>
3607
  class variant {
3608
  public:
 
3623
  constexpr explicit variant(in_place_index_t<I>, Args&&...);
3624
  template<size_t I, class U, class... Args>
3625
  constexpr explicit variant(in_place_index_t<I>, initializer_list<U>, Args&&...);
3626
 
3627
  // [variant.dtor], destructor
3628
+ constexpr ~variant();
3629
 
3630
  // [variant.assign], assignment
3631
  constexpr variant& operator=(const variant&);
3632
  constexpr variant& operator=(variant&&) noexcept(see below);
3633
 
3634
+ template<class T> constexpr variant& operator=(T&&) noexcept(see below);
3635
 
3636
  // [variant.mod], modifiers
3637
  template<class T, class... Args>
3638
+ constexpr T& emplace(Args&&...);
3639
  template<class T, class U, class... Args>
3640
+ constexpr T& emplace(initializer_list<U>, Args&&...);
3641
  template<size_t I, class... Args>
3642
+ constexpr variant_alternative_t<I, variant<Types...>>& emplace(Args&&...);
3643
  template<size_t I, class U, class... Args>
3644
+ constexpr variant_alternative_t<I, variant<Types...>>&
3645
+ emplace(initializer_list<U>, Args&&...);
3646
 
3647
  // [variant.status], value status
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
 
3685
  *Ensures:* `valueless_by_exception()` is `false` and `index()` is `0`.
3686
 
3687
  *Throws:* Any exception thrown by the value-initialization of `T₀`.
3688
 
3689
  *Remarks:* This function is `constexpr` if and only if the
3690
+ value-initialization of the alternative type `T₀` would be
3691
+ constexpr-suitable [[dcl.constexpr]]. The exception specification is
3692
+ equivalent to `is_nothrow_default_constructible_v<``T₀``>`.
3693
 
3694
  [*Note 1*: See also class `monostate`. — *end note*]
3695
 
3696
  ``` cpp
3697
  constexpr variant(const variant& w);
 
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
3728
  `is_trivially_move_constructible_v<``Tᵢ``>` is `true` for all i, this
3729
  constructor is trivial.
3730
 
3731
  ``` cpp
3732
  template<class T> constexpr variant(T&& t) noexcept(see below);
 
3754
  is ill-formed, as both alternative types have an equally viable
3755
  constructor for the argument.
3756
  — *end note*]
3757
 
3758
  *Effects:* Initializes `*this` to hold the alternative type `Tⱼ` and
3759
+ direct-non-list-initializes the contained value with
3760
+ `std::forward<T>(t)`.
3761
 
3762
  *Ensures:* `holds_alternative<``Tⱼ``>(*this)` is `true`.
3763
 
3764
  *Throws:* Any exception thrown by the initialization of the selected
3765
  alternative `Tⱼ`.
3766
 
3767
+ *Remarks:* The exception specification is equivalent to
3768
  `is_nothrow_constructible_v<``Tⱼ``, T>`. If `Tⱼ`’s selected constructor
3769
  is a constexpr constructor, this constructor is a constexpr constructor.
3770
 
3771
  ``` cpp
3772
  template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&... args);
 
3775
  *Constraints:*
3776
 
3777
  - There is exactly one occurrence of `T` in `Types...` and
3778
  - `is_constructible_v<T, Args...>` is `true`.
3779
 
3780
+ *Effects:* Direct-non-list-initializes the contained value of type `T`
3781
+ with `std::forward<Args>(args)...`.
 
3782
 
3783
  *Ensures:* `holds_alternative<T>(*this)` is `true`.
3784
 
3785
  *Throws:* Any exception thrown by calling the selected constructor of
3786
  `T`.
 
3796
  *Constraints:*
3797
 
3798
  - There is exactly one occurrence of `T` in `Types...` and
3799
  - `is_constructible_v<T, initializer_list<U>&, Args...>` is `true`.
3800
 
3801
+ *Effects:* Direct-non-list-initializes the contained value of type `T`
3802
+ with `il, std::forward<Args>(args)...`.
 
3803
 
3804
  *Ensures:* `holds_alternative<T>(*this)` is `true`.
3805
 
3806
  *Throws:* Any exception thrown by calling the selected constructor of
3807
  `T`.
 
3816
  *Constraints:*
3817
 
3818
  - `I` is less than `sizeof...(Types)` and
3819
  - `is_constructible_v<``T_I``, Args...>` is `true`.
3820
 
3821
+ *Effects:* Direct-non-list-initializes the contained value of type `T_I`
3822
+ with `std::forward<Args>(args)...`.
 
3823
 
3824
  *Ensures:* `index()` is `I`.
3825
 
3826
  *Throws:* Any exception thrown by calling the selected constructor of
3827
  `T_I`.
 
3838
 
3839
  - `I` is less than `sizeof...(Types)` and
3840
  - `is_constructible_v<``T_I``, initializer_list<U>&, Args...>` is
3841
  `true`.
3842
 
3843
+ *Effects:* Direct-non-list-initializes the contained value of type `T_I`
3844
+ with `il, std::forward<Args>(args)...`.
 
3845
 
3846
  *Ensures:* `index()` is `I`.
3847
 
3848
  *Remarks:* If `T_I`’s selected constructor is a constexpr constructor,
3849
  this constructor is a constexpr constructor.
3850
 
3851
  #### Destructor <a id="variant.dtor">[[variant.dtor]]</a>
3852
 
3853
  ``` cpp
3854
+ constexpr ~variant();
3855
  ```
3856
 
3857
  *Effects:* If `valueless_by_exception()` is `false`, destroys the
3858
  currently contained value.
3859
 
 
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`.
3886
+
3887
  *Remarks:* This operator is defined as deleted unless
3888
  `is_copy_constructible_v<``Tᵢ``> &&` `is_copy_assignable_v<``Tᵢ``>` is
3889
  `true` for all i. If `is_trivially_copy_constructible_v<``Tᵢ``> &&`
3890
  `is_trivially_copy_assignable_v<``Tᵢ``> &&`
3891
  `is_trivially_destructible_v<``Tᵢ``>` is `true` for all i, this
 
3912
  *Returns:* `*this`.
3913
 
3914
  *Remarks:* If `is_trivially_move_constructible_v<``Tᵢ``> &&`
3915
  `is_trivially_move_assignable_v<``Tᵢ``> &&`
3916
  `is_trivially_destructible_v<``Tᵢ``>` is `true` for all i, this
3917
+ assignment operator is trivial. The exception specification is
3918
+ equivalent to
3919
  `is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_move_assignable_v<``Tᵢ``>`
3920
  for all i.
3921
 
3922
  - If an exception is thrown during the call to `Tⱼ`’s move construction
3923
  (with j being `rhs.index()`), the `variant` will hold no value.
3924
  - If an exception is thrown during the call to `Tⱼ`’s move assignment,
3925
  the state of the contained value is as defined by the exception safety
3926
  guarantee of `Tⱼ`’s move assignment; `index()` will be j.
3927
 
3928
  ``` cpp
3929
+ template<class T> constexpr variant& operator=(T&& t) noexcept(see below);
3930
  ```
3931
 
3932
  Let `Tⱼ` be a type that is determined as follows: build an imaginary
3933
  function *FUN*(Tᵢ) for each alternative type `Tᵢ` for which `Tᵢ`` x[] =`
3934
  `{std::forward<T>(t)};` is well-formed for some invented variable `x`.
 
3956
  - If `*this` holds a `Tⱼ`, assigns `std::forward<T>(t)` to the value
3957
  contained in `*this`.
3958
  - Otherwise, if `is_nothrow_constructible_v<``Tⱼ``, T> ||`
3959
  `!is_nothrow_move_constructible_v<``Tⱼ``>` is `true`, equivalent to
3960
  `emplace<`j`>(std::forward<T>(t))`.
3961
+ - Otherwise, equivalent to `emplace<`j`>(``Tⱼ``(std::forward<T>(t)))`.
3962
 
3963
  *Ensures:* `holds_alternative<``Tⱼ``>(*this)` is `true`, with `Tⱼ`
3964
  selected by the imaginary function overload resolution described above.
3965
 
3966
  *Returns:* `*this`.
3967
 
3968
+ *Remarks:* The exception specification is equivalent to:
3969
 
3970
  ``` cpp
3971
  is_nothrow_assignable_v<Tⱼ&, T> && is_nothrow_constructible_v<Tⱼ, T>
3972
  ```
3973
 
 
3975
  `std::forward<T>(t)` to the value contained in `*this`, the state of
3976
  the contained value and `t` are as defined by the exception safety
3977
  guarantee of the assignment expression; `valueless_by_exception()`
3978
  will be `false`.
3979
  - If an exception is thrown during the initialization of the contained
3980
+ value, the `variant` object is permitted to not hold a value.
3981
 
3982
  #### Modifiers <a id="variant.mod">[[variant.mod]]</a>
3983
 
3984
  ``` cpp
3985
+ template<class T, class... Args> constexpr T& emplace(Args&&... args);
3986
  ```
3987
 
3988
  *Constraints:* `is_constructible_v<T, Args...>` is `true`, and `T`
3989
  occurs exactly once in `Types`.
3990
 
 
3995
  ```
3996
 
3997
  where I is the zero-based index of `T` in `Types`.
3998
 
3999
  ``` cpp
4000
+ template<class T, class U, class... Args>
4001
+ constexpr T& emplace(initializer_list<U> il, Args&&... args);
4002
  ```
4003
 
4004
  *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
4005
  `true`, and `T` occurs exactly once in `Types`.
4006
 
 
4012
 
4013
  where I is the zero-based index of `T` in `Types`.
4014
 
4015
  ``` cpp
4016
  template<size_t I, class... Args>
4017
+ constexpr variant_alternative_t<I, variant<Types...>>& emplace(Args&&... args);
4018
  ```
4019
 
4020
  *Mandates:* `I` < `sizeof...(Types)`.
4021
 
4022
  *Constraints:* `is_constructible_v<``T_I``, Args...>` is `true`.
4023
 
4024
  *Effects:* Destroys the currently contained value if
4025
+ `valueless_by_exception()` is `false`. Then direct-non-list-initializes
4026
+ the contained value of type `T_I` with the arguments
4027
+ `std::forward<Args>(args)...`.
4028
 
4029
  *Ensures:* `index()` is `I`.
4030
 
4031
  *Returns:* A reference to the new contained value.
4032
 
4033
  *Throws:* Any exception thrown during the initialization of the
4034
  contained value.
4035
 
4036
  *Remarks:* If an exception is thrown during the initialization of the
4037
+ contained value, the `variant` is permitted to not hold a value.
4038
 
4039
  ``` cpp
4040
  template<size_t I, class U, class... Args>
4041
+ constexpr variant_alternative_t<I, variant<Types...>>&
4042
+ emplace(initializer_list<U> il, Args&&... args);
4043
  ```
4044
 
4045
  *Mandates:* `I` < `sizeof...(Types)`.
4046
 
4047
  *Constraints:*
4048
  `is_constructible_v<``T_I``, initializer_list<U>&, Args...>` is `true`.
4049
 
4050
  *Effects:* Destroys the currently contained value if
4051
+ `valueless_by_exception()` is `false`. Then direct-non-list-initializes
4052
+ the contained value of type `T_I` with
4053
+ `il, std::forward<Args>(args)...`.
4054
 
4055
  *Ensures:* `index()` is `I`.
4056
 
4057
  *Returns:* A reference to the new contained value.
4058
 
4059
  *Throws:* Any exception thrown during the initialization of the
4060
  contained value.
4061
 
4062
  *Remarks:* If an exception is thrown during the initialization of the
4063
+ contained value, the `variant` is permitted to not hold a value.
4064
 
4065
  #### Value status <a id="variant.status">[[variant.status]]</a>
4066
 
4067
  ``` cpp
4068
  constexpr bool valueless_by_exception() const noexcept;
 
4070
 
4071
  *Effects:* Returns `false` if and only if the `variant` holds a value.
4072
 
4073
  [*Note 1*:
4074
 
4075
+ It is possible for a `variant` to hold no value if an exception is
4076
+ thrown during a type-changing assignment or emplacement. The latter
4077
+ means that even a `variant<float, int>` can become
4078
+ `valueless_by_exception()`, for instance by
4079
 
4080
  ``` cpp
4081
  struct S { operator int() { throw 42; }};
4082
  variant<float, int> v{12.f};
4083
  v.emplace<1>(S());
 
4094
  alternative of the contained value.
4095
 
4096
  #### Swap <a id="variant.swap">[[variant.swap]]</a>
4097
 
4098
  ``` cpp
4099
+ constexpr void swap(variant& rhs) noexcept(see below);
4100
  ```
4101
 
4102
  *Mandates:* `is_move_constructible_v<``Tᵢ``>` is `true` for all i.
4103
 
4104
+ *Preconditions:* Each `Tᵢ` meets the *Cpp17Swappable*
4105
+ requirements [[swappable.requirements]].
4106
 
4107
  *Effects:*
4108
 
4109
  - If `valueless_by_exception() && rhs.valueless_by_exception()` no
4110
  effect.
 
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
 
 
4137
  All specializations of `variant_size` meet the *Cpp17UnaryTypeTrait*
4138
  requirements [[meta.rqmts]] with a base characteristic of
4139
  `integral_constant<size_t, N>` for some `N`.
4140
 
4141
  ``` cpp
4142
+ template<class T> struct variant_size<const T>;
4143
  ```
4144
 
4145
  Let `VS` denote `variant_size<T>` of the cv-unqualified type `T`. Then
4146
  each specialization of the template meets the *Cpp17UnaryTypeTrait*
4147
  requirements [[meta.rqmts]] with a base characteristic of
 
4151
  template<class... Types>
4152
  struct variant_size<variant<Types...>> : integral_constant<size_t, sizeof...(Types)> { };
4153
  ```
4154
 
4155
  ``` cpp
4156
+ 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
 
4344
  constexpr see below visit(Visitor&& vis, Variants&&... vars);
4345
  template<class R, class Visitor, class... Variants>
4346
  constexpr R visit(Visitor&& vis, Variants&&... vars);
4347
  ```
4348
 
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ᵢ``)``))`.
4366
+
4367
+ *Constraints:* `Vᵢ` is a valid type for all 0 ≤ i < n.
4368
+
4369
+ Let `V` denote the pack of types `Vᵢ`.
4370
+
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
4388
+ expressions are of the same type and value category.
4389
 
4390
+ *Returns:* e(m), where m is the pack for which mᵢ is
4391
+ *`as-variant`*`(vars`ᵢ`).index()` for all 0 ≤ i < n. The return type is
4392
+ `decltype(`e(m)`)` for the first form.
4393
 
4394
+ *Throws:* `bad_variant_access` if
4395
+ `(`*`as-variant`*`(vars).valueless_by_exception() || ...)` is `true`.
4396
 
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{};
 
4421
 
4422
  ### Specialized algorithms <a id="variant.specalg">[[variant.specalg]]</a>
4423
 
4424
  ``` cpp
4425
  template<class... Types>
4426
+ constexpr void swap(variant<Types...>& v, variant<Types...>& w) noexcept(see below);
4427
  ```
4428
 
4429
  *Constraints:*
4430
  `is_move_constructible_v<``Tᵢ``> && is_swappable_v<``Tᵢ``>` is `true`
4431
  for all i.
4432
 
4433
  *Effects:* Equivalent to `v.swap(w)`.
4434
 
4435
+ *Remarks:* The exception specification is equivalent to
4436
  `noexcept(v.swap(w))`.
4437
 
4438
  ### Class `bad_variant_access` <a id="variant.bad.access">[[variant.bad.access]]</a>
4439
 
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
 
 
4472
 
4473
  The specialization is enabled [[unord.hash]].
4474
 
4475
  ## Storage for any type <a id="any">[[any]]</a>
4476
 
4477
+ ### General <a id="any.general">[[any.general]]</a>
 
4478
 
4479
+ Subclause [[any]] describes components that C++ programs may use to
4480
+ perform operations on objects of a discriminated type.
4481
+
4482
+ [*Note 1*: The discriminated type can contain values of different types
4483
  but does not attempt conversion between them, i.e., `5` is held strictly
4484
  as an `int` and is not implicitly convertible either to `"5"` or to
4485
  `5.0`. This indifference to interpretation but awareness of type
4486
  effectively allows safe, generic containers of single values, with no
4487
  scope for surprises from ambiguous conversions. — *end note*]
 
4519
  ```
4520
 
4521
  ### Class `bad_any_cast` <a id="any.bad.any.cast">[[any.bad.any.cast]]</a>
4522
 
4523
  ``` cpp
4524
+ namespace std {
4525
  class bad_any_cast : public bad_cast {
4526
  public:
4527
  // see [exception] for the specification of the special member functions
4528
  const char* what() const noexcept override;
4529
  };
4530
+ }
4531
  ```
4532
 
4533
  Objects of type `bad_any_cast` are thrown by a failed `any_cast`
4534
  [[any.nonmembers]].
4535
 
 
4539
 
4540
  *Returns:* An *implementation-defined* NTBS.
4541
 
4542
  ### Class `any` <a id="any.class">[[any.class]]</a>
4543
 
4544
+ #### General <a id="any.class.general">[[any.class.general]]</a>
4545
+
4546
  ``` cpp
4547
  namespace std {
4548
  class any {
4549
  public:
4550
  // [any.cons], construction and destruction
 
4661
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
4662
  `is_constructible_v<VT, Args...>` is `true`.
4663
 
4664
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
4665
 
4666
+ *Effects:* Direct-non-list-initializes the contained value of type `VT`
4667
+ with `std::forward<Args>(args)...`.
 
4668
 
4669
  *Ensures:* `*this` contains a value of type `VT`.
4670
 
4671
  *Throws:* Any exception thrown by the selected constructor of `VT`.
4672
 
 
4680
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
4681
  `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`.
4682
 
4683
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
4684
 
4685
+ *Effects:* Direct-non-list-initializes the contained value of type `VT`
4686
+ with `il, std::forward<Args>(args)...`.
 
4687
 
4688
  *Ensures:* `*this` contains a value.
4689
 
4690
  *Throws:* Any exception thrown by the selected constructor of `VT`.
4691
 
 
4713
  any& operator=(any&& rhs) noexcept;
4714
  ```
4715
 
4716
  *Effects:* As if by `any(std::move(rhs)).swap(*this)`.
4717
 
 
 
4718
  *Ensures:* The state of `*this` is equivalent to the original state of
4719
  `rhs`.
4720
 
4721
+ *Returns:* `*this`.
4722
+
4723
  ``` cpp
4724
  template<class T>
4725
  any& operator=(T&& rhs);
4726
  ```
4727
 
 
4752
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
4753
  `is_constructible_v<VT, Args...>` is `true`.
4754
 
4755
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
4756
 
4757
+ *Effects:* Calls `reset()`. Then direct-non-list-initializes the
4758
+ contained value of type `VT` with `std::forward<Args>(args)...`.
 
4759
 
4760
  *Ensures:* `*this` contains a value.
4761
 
4762
  *Returns:* A reference to the new contained value.
4763
 
 
4777
  *Constraints:* `is_copy_constructible_v<VT>` is `true` and
4778
  `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`.
4779
 
4780
  *Preconditions:* `VT` meets the *Cpp17CopyConstructible* requirements.
4781
 
4782
+ *Effects:* Calls `reset()`. Then direct-non-list-initializes the
4783
+ contained value of type `VT` with `il, std::forward<Args>(args)...`.
 
4784
 
4785
  *Ensures:* `*this` contains a value.
4786
 
4787
  *Returns:* A reference to the new contained value.
4788
 
 
4917
  }
4918
  ```
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
4939
+ template<class E> class bad_expected_access;
4940
+
4941
+ // [expected.bad.void], specialization for void
4942
+ template<> class bad_expected_access<void>;
4943
+
4944
+ // in-place construction of unexpected values
4945
+ struct unexpect_t {
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
+
4960
+ #### General <a id="expected.un.general">[[expected.un.general]]</a>
4961
+
4962
+ Subclause [[expected.unexpected]] describes the class template
4963
+ `unexpected` that represents unexpected objects stored in `expected`
4964
+ objects.
4965
+
4966
+ ``` cpp
4967
+ namespace std {
4968
+ template<class E>
4969
+ class unexpected {
4970
+ public:
4971
+ // [expected.un.cons], constructors
4972
+ constexpr unexpected(const unexpected&) = default;
4973
+ constexpr unexpected(unexpected&&) = default;
4974
+ template<class Err = E>
4975
+ constexpr explicit unexpected(Err&&);
4976
+ template<class... Args>
4977
+ constexpr explicit unexpected(in_place_t, Args&&...);
4978
+ template<class U, class... Args>
4979
+ constexpr explicit unexpected(in_place_t, initializer_list<U>, Args&&...);
4980
+
4981
+ constexpr unexpected& operator=(const unexpected&) = default;
4982
+ constexpr unexpected& operator=(unexpected&&) = default;
4983
+
4984
+ constexpr const E& error() const & noexcept;
4985
+ constexpr E& error() & noexcept;
4986
+ constexpr const E&& error() const && noexcept;
4987
+ constexpr E&& error() && noexcept;
4988
+
4989
+ constexpr void swap(unexpected& other) noexcept(see below);
4990
+
4991
+ template<class E2>
4992
+ friend constexpr bool operator==(const unexpected&, const unexpected<E2>&);
4993
+
4994
+ friend constexpr void swap(unexpected& x, unexpected& y) noexcept(noexcept(x.swap(y)));
4995
+
4996
+ private:
4997
+ E unex; // exposition only
4998
+ };
4999
+
5000
+ template<class E> unexpected(E) -> unexpected<E>;
5001
+ }
5002
+ ```
5003
+
5004
+ A program that instantiates the definition of `unexpected` for a
5005
+ non-object type, an array type, a specialization of `unexpected`, or a
5006
+ cv-qualified type is ill-formed.
5007
+
5008
+ #### Constructors <a id="expected.un.cons">[[expected.un.cons]]</a>
5009
+
5010
+ ``` cpp
5011
+ template<class Err = E>
5012
+ constexpr explicit unexpected(Err&& e);
5013
+ ```
5014
+
5015
+ *Constraints:*
5016
+
5017
+ - `is_same_v<remove_cvref_t<Err>, unexpected>` is `false`; and
5018
+ - `is_same_v<remove_cvref_t<Err>, in_place_t>` is `false`; and
5019
+ - `is_constructible_v<E, Err>` is `true`.
5020
+
5021
+ *Effects:* Direct-non-list-initializes *unex* with
5022
+ `std::forward<Err>(e)`.
5023
+
5024
+ *Throws:* Any exception thrown by the initialization of *unex*.
5025
+
5026
+ ``` cpp
5027
+ template<class... Args>
5028
+ constexpr explicit unexpected(in_place_t, Args&&... args);
5029
+ ```
5030
+
5031
+ *Constraints:* `is_constructible_v<E, Args...>` is `true`.
5032
+
5033
+ *Effects:* Direct-non-list-initializes *unex* with
5034
+ `std::forward<Args>(args)...`.
5035
+
5036
+ *Throws:* Any exception thrown by the initialization of *unex*.
5037
+
5038
+ ``` cpp
5039
+ template<class U, class... Args>
5040
+ constexpr explicit unexpected(in_place_t, initializer_list<U> il, Args&&... args);
5041
+ ```
5042
+
5043
+ *Constraints:* `is_constructible_v<E, initializer_list<U>&, Args...>` is
5044
+ `true`.
5045
+
5046
+ *Effects:* Direct-non-list-initializes *unex* with
5047
+ `il, std::forward<Args>(args)...`.
5048
+
5049
+ *Throws:* Any exception thrown by the initialization of *unex*.
5050
+
5051
+ #### Observers <a id="expected.un.obs">[[expected.un.obs]]</a>
5052
+
5053
+ ``` cpp
5054
+ constexpr const E& error() const & noexcept;
5055
+ constexpr E& error() & noexcept;
5056
+ ```
5057
+
5058
+ *Returns:* *unex*.
5059
+
5060
+ ``` cpp
5061
+ constexpr E&& error() && noexcept;
5062
+ constexpr const E&& error() const && noexcept;
5063
+ ```
5064
+
5065
+ *Returns:* `std::move(`*`unex`*`)`.
5066
+
5067
+ #### Swap <a id="expected.un.swap">[[expected.un.swap]]</a>
5068
+
5069
+ ``` cpp
5070
+ constexpr void swap(unexpected& other) noexcept(is_nothrow_swappable_v<E>);
5071
+ ```
5072
+
5073
+ *Mandates:* `is_swappable_v<E>` is `true`.
5074
+
5075
+ *Effects:* Equivalent to:
5076
+ `using std::swap; swap(`*`unex`*`, other.`*`unex`*`);`
5077
+
5078
+ ``` cpp
5079
+ friend constexpr void swap(unexpected& x, unexpected& y) noexcept(noexcept(x.swap(y)));
5080
+ ```
5081
+
5082
+ *Constraints:* `is_swappable_v<E>` is `true`.
5083
+
5084
+ *Effects:* Equivalent to `x.swap(y)`.
5085
+
5086
+ #### Equality operator <a id="expected.un.eq">[[expected.un.eq]]</a>
5087
+
5088
+ ``` cpp
5089
+ template<class E2>
5090
+ friend constexpr bool operator==(const unexpected& x, const unexpected<E2>& y);
5091
+ ```
5092
+
5093
+ *Mandates:* The expression `x.error() == y.error()` is well-formed and
5094
+ its result is convertible to `bool`.
5095
+
5096
+ *Returns:* `x.error() == y.error()`.
5097
+
5098
+ ### Class template `bad_expected_access` <a id="expected.bad">[[expected.bad]]</a>
5099
+
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
+ }
5116
+ ```
5117
+
5118
+ 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
+
5179
+ ``` cpp
5180
+ namespace std {
5181
+ template<class T, class E>
5182
+ class expected {
5183
+ public:
5184
+ using value_type = T;
5185
+ using error_type = E;
5186
+ using unexpected_type = unexpected<E>;
5187
+
5188
+ template<class U>
5189
+ using rebind = expected<U, error_type>;
5190
+
5191
+ // [expected.object.cons], constructors
5192
+ constexpr expected();
5193
+ constexpr expected(const expected&);
5194
+ constexpr expected(expected&&) noexcept(see below);
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>
5206
+ constexpr explicit(see below) expected(unexpected<G>&&);
5207
+
5208
+ template<class... Args>
5209
+ constexpr explicit expected(in_place_t, Args&&...);
5210
+ template<class U, class... Args>
5211
+ constexpr explicit expected(in_place_t, initializer_list<U>, Args&&...);
5212
+ template<class... Args>
5213
+ constexpr explicit expected(unexpect_t, Args&&...);
5214
+ template<class U, class... Args>
5215
+ constexpr explicit expected(unexpect_t, initializer_list<U>, Args&&...);
5216
+
5217
+ // [expected.object.dtor], destructor
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
+
5229
+ template<class... Args>
5230
+ constexpr T& emplace(Args&&...) noexcept;
5231
+ template<class U, class... Args>
5232
+ constexpr T& emplace(initializer_list<U>, Args&&...) noexcept;
5233
+
5234
+ // [expected.object.swap], swap
5235
+ constexpr void swap(expected&) noexcept(see below);
5236
+ friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
5237
+
5238
+ // [expected.object.obs], observers
5239
+ constexpr const T* operator->() const noexcept;
5240
+ constexpr T* operator->() noexcept;
5241
+ constexpr const T& operator*() const & noexcept;
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) &;
5262
+ template<class F> constexpr auto and_then(F&& f) &&;
5263
+ template<class F> constexpr auto and_then(F&& f) const &;
5264
+ template<class F> constexpr auto and_then(F&& f) const &&;
5265
+ template<class F> constexpr auto or_else(F&& f) &;
5266
+ template<class F> constexpr auto or_else(F&& f) &&;
5267
+ template<class F> constexpr auto or_else(F&& f) const &;
5268
+ template<class F> constexpr auto or_else(F&& f) const &&;
5269
+ template<class F> constexpr auto transform(F&& f) &;
5270
+ template<class F> constexpr auto transform(F&& f) &&;
5271
+ template<class F> constexpr auto transform(F&& f) const &;
5272
+ template<class F> constexpr auto transform(F&& f) const &&;
5273
+ template<class F> constexpr auto transform_error(F&& f) &;
5274
+ template<class F> constexpr auto transform_error(F&& f) &&;
5275
+ template<class F> constexpr auto transform_error(F&& f) const &;
5276
+ template<class F> constexpr auto transform_error(F&& f) const &&;
5277
+
5278
+ // [expected.object.eq], equality operators
5279
+ template<class T2, class E2> requires (!is_void_v<T2>)
5280
+ friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
5281
+ template<class T2>
5282
+ friend constexpr bool operator==(const expected&, const T2&);
5283
+ template<class E2>
5284
+ friend constexpr bool operator==(const expected&, const unexpected<E2>&);
5285
+
5286
+ private:
5287
+ bool has_val; // exposition only
5288
+ union {
5289
+ T val; // exposition only
5290
+ E unex; // exposition only
5291
+ };
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
5307
+ is not a valid value type for `expected` is ill-formed. A program that
5308
+ instantiates the definition of the template `expected<T, E>` with a type
5309
+ for the `E` parameter that is not a valid template argument for
5310
+ `unexpected` is ill-formed.
5311
+
5312
+ When `T` is not cv `void`, it shall meet the *Cpp17Destructible*
5313
+ requirements ([[cpp17.destructible]]). `E` shall meet the
5314
+ *Cpp17Destructible* requirements.
5315
+
5316
+ #### Constructors <a id="expected.object.cons">[[expected.object.cons]]</a>
5317
+
5318
+ The exposition-only variable template *`converts-from-any-cvref`*
5319
+ defined in [[optional.ctor]] is used by some constructors for
5320
+ `expected`.
5321
+
5322
+ ``` cpp
5323
+ constexpr expected();
5324
+ ```
5325
+
5326
+ *Constraints:* `is_default_constructible_v<T>` is `true`.
5327
+
5328
+ *Effects:* Value-initializes *val*.
5329
+
5330
+ *Ensures:* `has_value()` is `true`.
5331
+
5332
+ *Throws:* Any exception thrown by the initialization of *val*.
5333
+
5334
+ ``` cpp
5335
+ constexpr expected(const expected& rhs);
5336
+ ```
5337
+
5338
+ *Effects:* If `rhs.has_value()` is `true`, direct-non-list-initializes
5339
+ *val* with `*rhs`. Otherwise, direct-non-list-initializes *unex* with
5340
+ `rhs.error()`.
5341
+
5342
+ *Ensures:* `rhs.has_value() == this->has_value()`.
5343
+
5344
+ *Throws:* Any exception thrown by the initialization of *val* or *unex*.
5345
+
5346
+ *Remarks:* This constructor is defined as deleted unless
5347
+
5348
+ - `is_copy_constructible_v<T>` is `true` and
5349
+ - `is_copy_constructible_v<E>` is `true`.
5350
+
5351
+ This constructor is trivial if
5352
+
5353
+ - `is_trivially_copy_constructible_v<T>` is `true` and
5354
+ - `is_trivially_copy_constructible_v<E>` is `true`.
5355
+
5356
+ ``` cpp
5357
+ constexpr expected(expected&& rhs) noexcept(see below);
5358
+ ```
5359
+
5360
+ *Constraints:*
5361
+
5362
+ - `is_move_constructible_v<T>` is `true` and
5363
+ - `is_move_constructible_v<E>` is `true`.
5364
+
5365
+ *Effects:* If `rhs.has_value()` is `true`, direct-non-list-initializes
5366
+ *val* with `std::move(*rhs)`. Otherwise, direct-non-list-initializes
5367
+ *unex* with `std::move(rhs.error())`.
5368
+
5369
+ *Ensures:* `rhs.has_value()` is unchanged;
5370
+ `rhs.has_value() == this->has_value()` is `true`.
5371
+
5372
+ *Throws:* Any exception thrown by the initialization of *val* or *unex*.
5373
+
5374
+ *Remarks:* The exception specification is equivalent to
5375
+ `is_nothrow_move_constructible_v<T> && is_nothrow_move_constructible_v<E>`.
5376
+
5377
+ This constructor is trivial if
5378
+
5379
+ - `is_trivially_move_constructible_v<T>` is `true` and
5380
+ - `is_trivially_move_constructible_v<E>` is `true`.
5381
+
5382
+ ``` cpp
5383
+ template<class U, class G>
5384
+ constexpr explicit(see below) expected(const expected<U, G>& rhs);
5385
+ template<class U, class G>
5386
+ constexpr explicit(see below) expected(expected<U, G>&& rhs);
5387
+ ```
5388
+
5389
+ Let:
5390
+
5391
+ - `UF` be `const U&` for the first overload and `U` for the second
5392
+ overload.
5393
+ - `GF` be `const G&` for the first overload and `G` for the second
5394
+ overload.
5395
+
5396
+ *Constraints:*
5397
+
5398
+ - `is_constructible_v<T, UF>` is `true`; and
5399
+ - `is_constructible_v<E, GF>` is `true`; and
5400
+ - if `T` is not cv `bool`,
5401
+ *`converts-from-any-cvref`*`<T, expected<U, G>>` is `false`; and
5402
+ - `is_constructible_v<unexpected<E>, expected<U, G>&>` is `false`; and
5403
+ - `is_constructible_v<unexpected<E>, expected<U, G>>` is `false`; and
5404
+ - `is_constructible_v<unexpected<E>, const expected<U, G>&>` is `false`;
5405
+ and
5406
+ - `is_constructible_v<unexpected<E>, const expected<U, G>>` is `false`.
5407
+
5408
+ *Effects:* If `rhs.has_value()`, direct-non-list-initializes *val* with
5409
+ `std::forward<UF>(*rhs)`. Otherwise, direct-non-list-initializes *unex*
5410
+ with `std::forward<GF>(rhs.error())`.
5411
+
5412
+ *Ensures:* `rhs.has_value()` is unchanged;
5413
+ `rhs.has_value() == this->has_value()` is `true`.
5414
+
5415
+ *Throws:* Any exception thrown by the initialization of *val* or *unex*.
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
+
5434
+ *Effects:* Direct-non-list-initializes *val* with `std::forward<U>(v)`.
5435
+
5436
+ *Ensures:* `has_value()` is `true`.
5437
+
5438
+ *Throws:* Any exception thrown by the initialization of *val*.
5439
+
5440
+ ``` cpp
5441
+ template<class G>
5442
+ constexpr explicit(!is_convertible_v<const G&, E>) expected(const unexpected<G>& e);
5443
+ template<class G>
5444
+ constexpr explicit(!is_convertible_v<G, E>) expected(unexpected<G>&& e);
5445
+ ```
5446
+
5447
+ Let `GF` be `const G&` for the first overload and `G` for the second
5448
+ overload.
5449
+
5450
+ *Constraints:* `is_constructible_v<E, GF>` is `true`.
5451
+
5452
+ *Effects:* Direct-non-list-initializes *unex* with
5453
+ `std::forward<GF>(e.error())`.
5454
+
5455
+ *Ensures:* `has_value()` is `false`.
5456
+
5457
+ *Throws:* Any exception thrown by the initialization of *unex*.
5458
+
5459
+ ``` cpp
5460
+ template<class... Args>
5461
+ constexpr explicit expected(in_place_t, Args&&... args);
5462
+ ```
5463
+
5464
+ *Constraints:* `is_constructible_v<T, Args...>` is `true`.
5465
+
5466
+ *Effects:* Direct-non-list-initializes *val* with
5467
+ `std::forward<Args>(args)...`.
5468
+
5469
+ *Ensures:* `has_value()` is `true`.
5470
+
5471
+ *Throws:* Any exception thrown by the initialization of *val*.
5472
+
5473
+ ``` cpp
5474
+ template<class U, class... Args>
5475
+ constexpr explicit expected(in_place_t, initializer_list<U> il, Args&&... args);
5476
+ ```
5477
+
5478
+ *Constraints:* `is_constructible_v<T, initializer_list<U>&, Args...>` is
5479
+ `true`.
5480
+
5481
+ *Effects:* Direct-non-list-initializes *val* with
5482
+ `il, std::forward<Args>(args)...`.
5483
+
5484
+ *Ensures:* `has_value()` is `true`.
5485
+
5486
+ *Throws:* Any exception thrown by the initialization of *val*.
5487
+
5488
+ ``` cpp
5489
+ template<class... Args>
5490
+ constexpr explicit expected(unexpect_t, Args&&... args);
5491
+ ```
5492
+
5493
+ *Constraints:* `is_constructible_v<E, Args...>` is `true`.
5494
+
5495
+ *Effects:* Direct-non-list-initializes *unex* with
5496
+ `std::forward<Args>(args)...`.
5497
+
5498
+ *Ensures:* `has_value()` is `false`.
5499
+
5500
+ *Throws:* Any exception thrown by the initialization of *unex*.
5501
+
5502
+ ``` cpp
5503
+ template<class U, class... Args>
5504
+ constexpr explicit expected(unexpect_t, initializer_list<U> il, Args&&... args);
5505
+ ```
5506
+
5507
+ *Constraints:* `is_constructible_v<E, initializer_list<U>&, Args...>` is
5508
+ `true`.
5509
+
5510
+ *Effects:* Direct-non-list-initializes *unex* with
5511
+ `il, std::forward<Args>(args)...`.
5512
+
5513
+ *Ensures:* `has_value()` is `false`.
5514
+
5515
+ *Throws:* Any exception thrown by the initialization of *unex*.
5516
+
5517
+ #### Destructor <a id="expected.object.dtor">[[expected.object.dtor]]</a>
5518
+
5519
+ ``` cpp
5520
+ constexpr ~expected();
5521
+ ```
5522
+
5523
+ *Effects:* If `has_value()` is `true`, destroys *val*, otherwise
5524
+ destroys *unex*.
5525
+
5526
+ *Remarks:* If `is_trivially_destructible_v<T>` is `true`, and
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...>) {
5538
+ destroy_at(addressof(oldval));
5539
+ construct_at(addressof(newval), std::forward<Args>(args)...);
5540
+ } else if constexpr (is_nothrow_move_constructible_v<T>) {
5541
+ T tmp(std::forward<Args>(args)...);
5542
+ destroy_at(addressof(oldval));
5543
+ construct_at(addressof(newval), std::move(tmp));
5544
+ } else {
5545
+ U tmp(std::move(oldval));
5546
+ destroy_at(addressof(oldval));
5547
+ try {
5548
+ construct_at(addressof(newval), std::forward<Args>(args)...);
5549
+ } catch (...) {
5550
+ construct_at(addressof(oldval), std::move(tmp));
5551
+ throw;
5552
+ }
5553
+ }
5554
+ }
5555
+ ```
5556
+
5557
+ ``` cpp
5558
+ constexpr expected& operator=(const expected& rhs);
5559
+ ```
5560
+
5561
+ *Effects:*
5562
+
5563
+ - If `this->has_value() && rhs.has_value()` is `true`, equivalent to
5564
+ *`val`*` = *rhs`.
5565
+ - Otherwise, if `this->has_value()` is `true`, equivalent to:
5566
+ ``` cpp
5567
+ reinit-expected(unex, val, rhs.error())
5568
+ ```
5569
+ - Otherwise, if `rhs.has_value()` is `true`, equivalent to:
5570
+ ``` cpp
5571
+ reinit-expected(val, unex, *rhs)
5572
+ ```
5573
+ - Otherwise, equivalent to *`unex`*` = rhs.error()`.
5574
+
5575
+ Then, if no exception was thrown, equivalent to:
5576
+ *`has_val`*` = rhs.has_value(); return *this;`
5577
+
5578
+ *Returns:* `*this`.
5579
+
5580
+ *Remarks:* This operator is defined as deleted unless:
5581
+
5582
+ - `is_copy_assignable_v<T>` is `true` and
5583
+ - `is_copy_constructible_v<T>` is `true` and
5584
+ - `is_copy_assignable_v<E>` is `true` and
5585
+ - `is_copy_constructible_v<E>` is `true` and
5586
+ - `is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>`
5587
+ is `true`.
5588
+
5589
+ ``` cpp
5590
+ constexpr expected& operator=(expected&& rhs) noexcept(see below);
5591
+ ```
5592
+
5593
+ *Constraints:*
5594
+
5595
+ - `is_move_constructible_v<T>` is `true` and
5596
+ - `is_move_assignable_v<T>` is `true` and
5597
+ - `is_move_constructible_v<E>` is `true` and
5598
+ - `is_move_assignable_v<E>` is `true` and
5599
+ - `is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>`
5600
+ is `true`.
5601
+
5602
+ *Effects:*
5603
+
5604
+ - If `this->has_value() && rhs.has_value()` is `true`, equivalent to
5605
+ *`val`*` = std::move(*rhs)`.
5606
+ - Otherwise, if `this->has_value()` is `true`, equivalent to:
5607
+ ``` cpp
5608
+ reinit-expected(unex, val, std::move(rhs.error()))
5609
+ ```
5610
+ - Otherwise, if `rhs.has_value()` is `true`, equivalent to:
5611
+ ``` cpp
5612
+ reinit-expected(val, unex, std::move(*rhs))
5613
+ ```
5614
+ - Otherwise, equivalent to *`unex`*` = std::move(rhs.error())`.
5615
+
5616
+ Then, if no exception was thrown, equivalent to:
5617
+ `has_val = rhs.has_value(); return *this;`
5618
+
5619
+ *Returns:* `*this`.
5620
+
5621
+ *Remarks:* The exception specification is equivalent to:
5622
+
5623
+ ``` cpp
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
+
5635
+ - `is_same_v<expected, remove_cvref_t<U>>` is `false`; and
5636
+ - `remove_cvref_t<U>` is not a specialization of `unexpected`; and
5637
+ - `is_constructible_v<T, U>` is `true`; and
5638
+ - `is_assignable_v<T&, U>` is `true`; and
5639
+ - `is_nothrow_constructible_v<T, U> || is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>`
5640
+ is `true`.
5641
+
5642
+ *Effects:*
5643
+
5644
+ - If `has_value()` is `true`, equivalent to:
5645
+ *`val`*` = std::forward<U>(v);`
5646
+ - Otherwise, equivalent to:
5647
+ ``` cpp
5648
+ reinit-expected(val, unex, std::forward<U>(v));
5649
+ has_val = true;
5650
+ ```
5651
+
5652
+ *Returns:* `*this`.
5653
+
5654
+ ``` cpp
5655
+ template<class G>
5656
+ constexpr expected& operator=(const unexpected<G>& e);
5657
+ template<class G>
5658
+ constexpr expected& operator=(unexpected<G>&& e);
5659
+ ```
5660
+
5661
+ Let `GF` be `const G&` for the first overload and `G` for the second
5662
+ overload.
5663
+
5664
+ *Constraints:*
5665
+
5666
+ - `is_constructible_v<E, GF>` is `true`; and
5667
+ - `is_assignable_v<E&, GF>` is `true`; and
5668
+ - `is_nothrow_constructible_v<E, GF> || is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>`
5669
+ is `true`.
5670
+
5671
+ *Effects:*
5672
+
5673
+ - If `has_value()` is `true`, equivalent to:
5674
+ ``` cpp
5675
+ reinit-expected(unex, val, std::forward<GF>(e.error()));
5676
+ has_val = false;
5677
+ ```
5678
+ - Otherwise, equivalent to: *`unex`*` = std::forward<GF>(e.error());`
5679
+
5680
+ *Returns:* `*this`.
5681
+
5682
+ ``` cpp
5683
+ template<class... Args>
5684
+ constexpr T& emplace(Args&&... args) noexcept;
5685
+ ```
5686
+
5687
+ *Constraints:* `is_nothrow_constructible_v<T, Args...>` is `true`.
5688
+
5689
+ *Effects:* Equivalent to:
5690
+
5691
+ ``` cpp
5692
+ if (has_value()) {
5693
+ destroy_at(addressof(val));
5694
+ } else {
5695
+ destroy_at(addressof(unex));
5696
+ has_val = true;
5697
+ }
5698
+ return *construct_at(addressof(val), std::forward<Args>(args)...);
5699
+ ```
5700
+
5701
+ ``` cpp
5702
+ template<class U, class... Args>
5703
+ constexpr T& emplace(initializer_list<U> il, Args&&... args) noexcept;
5704
+ ```
5705
+
5706
+ *Constraints:*
5707
+ `is_nothrow_constructible_v<T, initializer_list<U>&, Args...>` is
5708
+ `true`.
5709
+
5710
+ *Effects:* Equivalent to:
5711
+
5712
+ ``` cpp
5713
+ if (has_value()) {
5714
+ destroy_at(addressof(val));
5715
+ } else {
5716
+ destroy_at(addressof(unex));
5717
+ has_val = true;
5718
+ }
5719
+ return *construct_at(addressof(val), il, std::forward<Args>(args)...);
5720
+ ```
5721
+
5722
+ #### Swap <a id="expected.object.swap">[[expected.object.swap]]</a>
5723
+
5724
+ ``` cpp
5725
+ constexpr void swap(expected& rhs) noexcept(see below);
5726
+ ```
5727
+
5728
+ *Constraints:*
5729
+
5730
+ - `is_swappable_v<T>` is `true` and
5731
+ - `is_swappable_v<E>` is `true` and
5732
+ - `is_move_constructible_v<T> && is_move_constructible_v<E>` is `true`,
5733
+ and
5734
+ - `is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>`
5735
+ is `true`.
5736
+
5737
+ *Effects:* See [[expected.object.swap]].
5738
+
5739
+ **Table: `swap(expected&)` effects** <a id="expected.object.swap">[expected.object.swap]</a>
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));
5752
+ try {
5753
+ construct_at(addressof(rhs.val), std::move(val));
5754
+ destroy_at(addressof(val));
5755
+ construct_at(addressof(unex), std::move(tmp));
5756
+ } catch(...) {
5757
+ construct_at(addressof(rhs.unex), std::move(tmp));
5758
+ throw;
5759
+ }
5760
+ } else {
5761
+ T tmp(std::move(val));
5762
+ destroy_at(addressof(val));
5763
+ try {
5764
+ construct_at(addressof(unex), std::move(rhs.unex));
5765
+ destroy_at(addressof(rhs.unex));
5766
+ construct_at(addressof(rhs.val), std::move(tmp));
5767
+ } catch (...) {
5768
+ construct_at(addressof(val), std::move(tmp));
5769
+ throw;
5770
+ }
5771
+ }
5772
+ has_val = false;
5773
+ rhs.has_val = true;
5774
+ ```
5775
+
5776
+ *Throws:* Any exception thrown by the expressions in the *Effects*.
5777
+
5778
+ *Remarks:* The exception specification is equivalent to:
5779
+
5780
+ ``` cpp
5781
+ is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T> &&
5782
+ is_nothrow_move_constructible_v<E> && is_nothrow_swappable_v<E>
5783
+ ```
5784
+
5785
+ ``` cpp
5786
+ friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
5787
+ ```
5788
+
5789
+ *Effects:* Equivalent to `x.swap(y)`.
5790
+
5791
+ #### Observers <a id="expected.object.obs">[[expected.object.obs]]</a>
5792
+
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;
5822
+ constexpr bool has_value() const noexcept;
5823
+ ```
5824
+
5825
+ *Returns:* *has_val*.
5826
+
5827
+ ``` cpp
5828
+ constexpr const T& value() const &;
5829
+ constexpr T& value() &;
5830
+ ```
5831
+
5832
+ *Mandates:* `is_copy_constructible_v<E>` is `true`.
5833
+
5834
+ *Returns:* *val*, if `has_value()` is `true`.
5835
+
5836
+ *Throws:* `bad_expected_access(as_const(error()))` if `has_value()` is
5837
+ `false`.
5838
+
5839
+ ``` cpp
5840
+ constexpr T&& value() &&;
5841
+ constexpr const T&& value() const &&;
5842
+ ```
5843
+
5844
+ *Mandates:* `is_copy_constructible_v<E>` is `true` and
5845
+ `is_constructible_v<E, decltype(std::move(error()))>` is `true`.
5846
+
5847
+ *Returns:* `std::move(`*`val`*`)`, if `has_value()` is `true`.
5848
+
5849
+ *Throws:* `bad_expected_access(std::move(error()))` if `has_value()` is
5850
+ `false`.
5851
+
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
+
5886
+ *Returns:*
5887
+ `has_value() ? std::move(**this) : static_cast<T>(std::forward<U>(v))`.
5888
+
5889
+ ``` cpp
5890
+ template<class G = E> constexpr E error_or(G&& e) const &;
5891
+ ```
5892
+
5893
+ *Mandates:* `is_copy_constructible_v<E>` is `true` and
5894
+ `is_convertible_v<G, E>` is `true`.
5895
+
5896
+ *Returns:* `std::forward<G>(e)` if `has_value()` is `true`, `error()`
5897
+ otherwise.
5898
+
5899
+ ``` cpp
5900
+ template<class G = E> constexpr E error_or(G&& e) &&;
5901
+ ```
5902
+
5903
+ *Mandates:* `is_move_constructible_v<E>` is `true` and
5904
+ `is_convertible_v<G, E>` is `true`.
5905
+
5906
+ *Returns:* `std::forward<G>(e)` if `has_value()` is `true`,
5907
+ `std::move(error())` otherwise.
5908
+
5909
+ #### Monadic operations <a id="expected.object.monadic">[[expected.object.monadic]]</a>
5910
+
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
5956
+ 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
5977
+ template<class F> constexpr auto or_else(F&& f) &&;
5978
+ 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:*
6018
+
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
6072
+ 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) &&;
6084
+ 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
6097
+ 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>
6109
+
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>
6144
+
6145
+ #### General <a id="expected.void.general">[[expected.void.general]]</a>
6146
+
6147
+ ``` cpp
6148
+ template<class T, class E> requires is_void_v<T>
6149
+ class expected<T, E> {
6150
+ public:
6151
+ using value_type = T;
6152
+ using error_type = E;
6153
+ using unexpected_type = unexpected<E>;
6154
+
6155
+ template<class U>
6156
+ using rebind = expected<U, error_type>;
6157
+
6158
+ // [expected.void.cons], constructors
6159
+ constexpr expected() noexcept;
6160
+ constexpr expected(const expected&);
6161
+ constexpr expected(expected&&) noexcept(see below);
6162
+ template<class U, class G>
6163
+ constexpr explicit(see below) expected(const expected<U, G>&);
6164
+ template<class U, class G>
6165
+ constexpr explicit(see below) expected(expected<U, G>&&);
6166
+
6167
+ template<class G>
6168
+ constexpr explicit(see below) expected(const unexpected<G>&);
6169
+ template<class G>
6170
+ constexpr explicit(see below) expected(unexpected<G>&&);
6171
+
6172
+ constexpr explicit expected(in_place_t) noexcept;
6173
+ template<class... Args>
6174
+ constexpr explicit expected(unexpect_t, Args&&...);
6175
+ template<class U, class... Args>
6176
+ constexpr explicit expected(unexpect_t, initializer_list<U>, Args&&...);
6177
+
6178
+
6179
+ // [expected.void.dtor], destructor
6180
+ constexpr ~expected();
6181
+
6182
+ // [expected.void.assign], assignment
6183
+ constexpr expected& operator=(const expected&);
6184
+ constexpr expected& operator=(expected&&) noexcept(see below);
6185
+ template<class G>
6186
+ constexpr expected& operator=(const unexpected<G>&);
6187
+ template<class G>
6188
+ constexpr expected& operator=(unexpected<G>&&);
6189
+ constexpr void emplace() noexcept;
6190
+
6191
+ // [expected.void.swap], swap
6192
+ constexpr void swap(expected&) noexcept(see below);
6193
+ friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
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 &;
6206
+ template<class G = E> constexpr E error_or(G&&) &&;
6207
+
6208
+ // [expected.void.monadic], monadic operations
6209
+ template<class F> constexpr auto and_then(F&& f) &;
6210
+ template<class F> constexpr auto and_then(F&& f) &&;
6211
+ template<class F> constexpr auto and_then(F&& f) const &;
6212
+ template<class F> constexpr auto and_then(F&& f) const &&;
6213
+ template<class F> constexpr auto or_else(F&& f) &;
6214
+ template<class F> constexpr auto or_else(F&& f) &&;
6215
+ template<class F> constexpr auto or_else(F&& f) const &;
6216
+ template<class F> constexpr auto or_else(F&& f) const &&;
6217
+ template<class F> constexpr auto transform(F&& f) &;
6218
+ template<class F> constexpr auto transform(F&& f) &&;
6219
+ template<class F> constexpr auto transform(F&& f) const &;
6220
+ template<class F> constexpr auto transform(F&& f) const &&;
6221
+ template<class F> constexpr auto transform_error(F&& f) &;
6222
+ template<class F> constexpr auto transform_error(F&& f) &&;
6223
+ template<class F> constexpr auto transform_error(F&& f) const &;
6224
+ template<class F> constexpr auto transform_error(F&& f) const &&;
6225
+
6226
+ // [expected.void.eq], equality operators
6227
+ template<class T2, class E2> requires is_void_v<T2>
6228
+ friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
6229
+ template<class E2>
6230
+ friend constexpr bool operator==(const expected&, const unexpected<E2>&);
6231
+
6232
+ private:
6233
+ bool has_val; // exposition only
6234
+ union {
6235
+ E unex; // exposition only
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
+
6251
+ `E` shall meet the requirements of *Cpp17Destructible* (
6252
+ [[cpp17.destructible]]).
6253
+
6254
+ #### Constructors <a id="expected.void.cons">[[expected.void.cons]]</a>
6255
+
6256
+ ``` cpp
6257
+ constexpr expected() noexcept;
6258
+ ```
6259
+
6260
+ *Ensures:* `has_value()` is `true`.
6261
+
6262
+ ``` cpp
6263
+ constexpr expected(const expected& rhs);
6264
+ ```
6265
+
6266
+ *Effects:* If `rhs.has_value()` is `false`, direct-non-list-initializes
6267
+ *unex* with `rhs.error()`.
6268
+
6269
+ *Ensures:* `rhs.has_value() == this->has_value()`.
6270
+
6271
+ *Throws:* Any exception thrown by the initialization of *unex*.
6272
+
6273
+ *Remarks:* This constructor is defined as deleted unless
6274
+ `is_copy_constructible_v<E>` is `true`.
6275
+
6276
+ This constructor is trivial if `is_trivially_copy_constructible_v<E>` is
6277
+ `true`.
6278
+
6279
+ ``` cpp
6280
+ constexpr expected(expected&& rhs) noexcept(is_nothrow_move_constructible_v<E>);
6281
+ ```
6282
+
6283
+ *Constraints:* `is_move_constructible_v<E>` is `true`.
6284
+
6285
+ *Effects:* If `rhs.has_value()` is `false`, direct-non-list-initializes
6286
+ *unex* with `std::move(rhs.error())`.
6287
+
6288
+ *Ensures:* `rhs.has_value()` is unchanged;
6289
+ `rhs.has_value() == this->has_value()` is `true`.
6290
+
6291
+ *Throws:* Any exception thrown by the initialization of *unex*.
6292
+
6293
+ *Remarks:* This constructor is trivial if
6294
+ `is_trivially_move_constructible_v<E>` is `true`.
6295
+
6296
+ ``` cpp
6297
+ template<class U, class G>
6298
+ constexpr explicit(!is_convertible_v<const G&, E>) expected(const expected<U, G>& rhs);
6299
+ template<class U, class G>
6300
+ constexpr explicit(!is_convertible_v<G, E>) expected(expected<U, G>&& rhs);
6301
+ ```
6302
+
6303
+ Let `GF` be `const G&` for the first overload and `G` for the second
6304
+ overload.
6305
+
6306
+ *Constraints:*
6307
+
6308
+ - `is_void_v<U>` is `true`; and
6309
+ - `is_constructible_v<E, GF>` is `true`; and
6310
+ - `is_constructible_v<unexpected<E>, expected<U, G>&>` is `false`; and
6311
+ - `is_constructible_v<unexpected<E>, expected<U, G>>` is `false`; and
6312
+ - `is_constructible_v<unexpected<E>, const expected<U, G>&>` is `false`;
6313
+ and
6314
+ - `is_constructible_v<unexpected<E>, const expected<U, G>>` is `false`.
6315
+
6316
+ *Effects:* If `rhs.has_value()` is `false`, direct-non-list-initializes
6317
+ *unex* with `std::forward<GF>(rhs.error())`.
6318
+
6319
+ *Ensures:* `rhs.has_value()` is unchanged;
6320
+ `rhs.has_value() == this->has_value()` is `true`.
6321
+
6322
+ *Throws:* Any exception thrown by the initialization of *unex*.
6323
+
6324
+ ``` cpp
6325
+ template<class G>
6326
+ constexpr explicit(!is_convertible_v<const G&, E>) expected(const unexpected<G>& e);
6327
+ template<class G>
6328
+ constexpr explicit(!is_convertible_v<G, E>) expected(unexpected<G>&& e);
6329
+ ```
6330
+
6331
+ Let `GF` be `const G&` for the first overload and `G` for the second
6332
+ overload.
6333
+
6334
+ *Constraints:* `is_constructible_v<E, GF>` is `true`.
6335
+
6336
+ *Effects:* Direct-non-list-initializes *unex* with
6337
+ `std::forward<GF>(e.error())`.
6338
+
6339
+ *Ensures:* `has_value()` is `false`.
6340
+
6341
+ *Throws:* Any exception thrown by the initialization of *unex*.
6342
+
6343
+ ``` cpp
6344
+ constexpr explicit expected(in_place_t) noexcept;
6345
+ ```
6346
+
6347
+ *Ensures:* `has_value()` is `true`.
6348
+
6349
+ ``` cpp
6350
+ template<class... Args>
6351
+ constexpr explicit expected(unexpect_t, Args&&... args);
6352
+ ```
6353
+
6354
+ *Constraints:* `is_constructible_v<E, Args...>` is `true`.
6355
+
6356
+ *Effects:* Direct-non-list-initializes *unex* with
6357
+ `std::forward<Args>(args)...`.
6358
+
6359
+ *Ensures:* `has_value()` is `false`.
6360
+
6361
+ *Throws:* Any exception thrown by the initialization of *unex*.
6362
+
6363
+ ``` cpp
6364
+ template<class U, class... Args>
6365
+ constexpr explicit expected(unexpect_t, initializer_list<U> il, Args&&... args);
6366
+ ```
6367
+
6368
+ *Constraints:* `is_constructible_v<E, initializer_list<U>&, Args...>` is
6369
+ `true`.
6370
+
6371
+ *Effects:* Direct-non-list-initializes *unex* with
6372
+ `il, std::forward<Args>(args)...`.
6373
+
6374
+ *Ensures:* `has_value()` is `false`.
6375
+
6376
+ *Throws:* Any exception thrown by the initialization of *unex*.
6377
+
6378
+ #### Destructor <a id="expected.void.dtor">[[expected.void.dtor]]</a>
6379
+
6380
+ ``` cpp
6381
+ constexpr ~expected();
6382
+ ```
6383
+
6384
+ *Effects:* If `has_value()` is `false`, destroys *unex*.
6385
+
6386
+ *Remarks:* If `is_trivially_destructible_v<E>` is `true`, then this
6387
+ destructor is a trivial destructor.
6388
+
6389
+ #### Assignment <a id="expected.void.assign">[[expected.void.assign]]</a>
6390
+
6391
+ ``` cpp
6392
+ constexpr expected& operator=(const expected& rhs);
6393
+ ```
6394
+
6395
+ *Effects:*
6396
+
6397
+ - If `this->has_value() && rhs.has_value()` is `true`, no effects.
6398
+ - Otherwise, if `this->has_value()` is `true`, equivalent to:
6399
+ `construct_at(addressof(`*`unex`*`), rhs.`*`unex`*`); `*`has_val`*` = false;`
6400
+ - Otherwise, if `rhs.has_value()` is `true`, destroys *unex* and sets
6401
+ *has_val* to `true`.
6402
+ - Otherwise, equivalent to *`unex`*` = rhs.error()`.
6403
+
6404
+ *Returns:* `*this`.
6405
+
6406
+ *Remarks:* This operator is defined as deleted unless
6407
+ `is_copy_assignable_v<E>` is `true` and `is_copy_constructible_v<E>` is
6408
+ `true`.
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
6419
+ construct_at(addressof(unex), std::move(rhs.unex));
6420
+ has_val = false;
6421
+ ```
6422
+ - Otherwise, if `rhs.has_value()` is `true`, destroys *unex* and sets
6423
+ *has_val* to `true`.
6424
+ - Otherwise, equivalent to *`unex`*` = std::move(rhs.error())`.
6425
+
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);
6439
+ ```
6440
+
6441
+ Let `GF` be `const G&` for the first overload and `G` for the second
6442
+ overload.
6443
+
6444
+ *Constraints:* `is_constructible_v<E, GF>` is `true` and
6445
+ `is_assignable_v<E&, GF>` is `true`.
6446
+
6447
+ *Effects:*
6448
+
6449
+ - If `has_value()` is `true`, equivalent to:
6450
+ ``` cpp
6451
+ construct_at(addressof(unex), std::forward<GF>(e.error()));
6452
+ has_val = false;
6453
+ ```
6454
+ - Otherwise, equivalent to: *`unex`*` = std::forward<GF>(e.error());`
6455
+
6456
+ *Returns:* `*this`.
6457
+
6458
+ ``` cpp
6459
+ constexpr void emplace() noexcept;
6460
+ ```
6461
+
6462
+ *Effects:* If `has_value()` is `false`, destroys *unex* and sets
6463
+ *has_val* to `true`.
6464
+
6465
+ #### Swap <a id="expected.void.swap">[[expected.void.swap]]</a>
6466
+
6467
+ ``` cpp
6468
+ constexpr void swap(expected& rhs) noexcept(see below);
6469
+ ```
6470
+
6471
+ *Constraints:* `is_swappable_v<E>` is `true` and
6472
+ `is_move_constructible_v<E>` is `true`.
6473
+
6474
+ *Effects:* See [[expected.void.swap]].
6475
+
6476
+ **Table: `swap(expected&)` effects** <a id="expected.void.swap">[expected.void.swap]</a>
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;
6489
+ rhs.has_val = true;
6490
+ ```
6491
+
6492
+ *Throws:* Any exception thrown by the expressions in the *Effects*.
6493
+
6494
+ *Remarks:* The exception specification is equivalent to
6495
+ `is_nothrow_move_constructible_v<E> && is_nothrow_swappable_v<E>`.
6496
+
6497
+ ``` cpp
6498
+ friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
6499
+ ```
6500
+
6501
+ *Effects:* Equivalent to `x.swap(y)`.
6502
+
6503
+ #### Observers <a id="expected.void.obs">[[expected.void.obs]]</a>
6504
+
6505
+ ``` cpp
6506
+ constexpr explicit operator bool() const noexcept;
6507
+ constexpr bool has_value() const noexcept;
6508
+ ```
6509
+
6510
+ *Returns:* *has_val*.
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 &;
6551
+ ```
6552
+
6553
+ *Mandates:* `is_copy_constructible_v<E>` is `true` and
6554
+ `is_convertible_v<G, E>` is `true`.
6555
+
6556
+ *Returns:* `std::forward<G>(e)` if `has_value()` is `true`, `error()`
6557
+ otherwise.
6558
+
6559
+ ``` cpp
6560
+ template<class G = E> constexpr E error_or(G&& e) &&;
6561
+ ```
6562
+
6563
+ *Mandates:* `is_move_constructible_v<E>` is `true` and
6564
+ `is_convertible_v<G, E>` is `true`.
6565
+
6566
+ *Returns:* `std::forward<G>(e)` if `has_value()` is `true`,
6567
+ `std::move(error())` otherwise.
6568
+
6569
+ #### Monadic operations <a id="expected.void.monadic">[[expected.void.monadic]]</a>
6570
+
6571
+ ``` cpp
6572
+ template<class F> constexpr auto and_then(F&& f) &;
6573
+ template<class F> constexpr auto and_then(F&& f) const &;
6574
+ ```
6575
+
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())
6587
+ return invoke(std::forward<F>(f));
6588
+ else
6589
+ return U(unexpect, error());
6590
+ ```
6591
+
6592
+ ``` cpp
6593
+ template<class F> constexpr auto and_then(F&& f) &&;
6594
+ template<class F> constexpr auto and_then(F&& f) const &&;
6595
+ ```
6596
+
6597
+ 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())
6609
+ return invoke(std::forward<F>(f));
6610
+ else
6611
+ return U(unexpect, std::move(error()));
6612
+ ```
6613
+
6614
+ ``` cpp
6615
+ template<class F> constexpr auto or_else(F&& f) &;
6616
+ 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())
6628
+ return G();
6629
+ else
6630
+ return invoke(std::forward<F>(f), error());
6631
+ ```
6632
+
6633
+ ``` cpp
6634
+ template<class F> constexpr auto or_else(F&& f) &&;
6635
+ template<class F> constexpr auto or_else(F&& f) const &&;
6636
+ ```
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())
6648
+ return G();
6649
+ else
6650
+ return invoke(std::forward<F>(f), std::move(error()));
6651
+ ```
6652
+
6653
+ ``` cpp
6654
+ template<class F> constexpr auto transform(F&& f) &;
6655
+ template<class F> constexpr auto transform(F&& f) const &;
6656
+ ```
6657
+
6658
+ Let `U` be `remove_cv_t<invoke_result_t<F>>`.
6659
+
6660
+ *Constraints:* `is_constructible_v<E, decltype(error())>` is `true`.
6661
+
6662
+ *Mandates:* `U` is a valid value type for `expected`. If `is_void_v<U>`
6663
+ is `false`, the declaration
6664
+
6665
+ ``` cpp
6666
+ U u(invoke(std::forward<F>(f)));
6667
+ ```
6668
+
6669
+ is well-formed.
6670
+
6671
+ *Effects:*
6672
+
6673
+ - If `has_value()` is `false`, returns
6674
+ `expected<U, E>(unexpect, error())`.
6675
+ - Otherwise, if `is_void_v<U>` is `false`, returns an `expected<U, E>`
6676
+ object whose *has_val* member is `true` and *val* member is
6677
+ direct-non-list-initialized with `invoke(std::forward<F>(f))`.
6678
+ - Otherwise, evaluates `invoke(std::forward<F>(f))` and then returns
6679
+ `expected<U, E>()`.
6680
+
6681
+ ``` cpp
6682
+ template<class F> constexpr auto transform(F&& f) &&;
6683
+ template<class F> constexpr auto transform(F&& f) const &&;
6684
+ ```
6685
+
6686
+ Let `U` be `remove_cv_t<invoke_result_t<F>>`.
6687
+
6688
+ *Constraints:* `is_constructible_v<E, decltype(std::move(error()))>` is
6689
+ `true`.
6690
+
6691
+ *Mandates:* `U` is a valid value type for `expected`. If `is_void_v<U>`
6692
+ is `false`, the declaration
6693
+
6694
+ ``` cpp
6695
+ U u(invoke(std::forward<F>(f)));
6696
+ ```
6697
+
6698
+ is well-formed.
6699
+
6700
+ *Effects:*
6701
+
6702
+ - If `has_value()` is `false`, returns
6703
+ `expected<U, E>(unexpect, std::move(error()))`.
6704
+ - Otherwise, if `is_void_v<U>` is `false`, returns an `expected<U, E>`
6705
+ object whose *has_val* member is `true` and *val* member is
6706
+ direct-non-list-initialized with `invoke(std::forward<F>(f))`.
6707
+ - Otherwise, evaluates `invoke(std::forward<F>(f))` and then returns
6708
+ `expected<U, E>()`.
6709
+
6710
+ ``` cpp
6711
+ template<class F> constexpr auto transform_error(F&& f) &;
6712
+ template<class F> constexpr auto transform_error(F&& f) const &;
6713
+ ```
6714
+
6715
+ Let `G` be `remove_cv_t<invoke_result_t<F, decltype(error())>>`.
6716
+
6717
+ *Mandates:* `G` is a valid template argument for `unexpected`
6718
+ [[expected.un.general]] and the declaration
6719
+
6720
+ ``` cpp
6721
+ G g(invoke(std::forward<F>(f), error()));
6722
+ ```
6723
+
6724
+ is well-formed.
6725
+
6726
+ *Returns:* If `has_value()` is `true`, `expected<T, G>()`; otherwise, an
6727
+ `expected<T, G>` object whose *has_val* member is `false` and *unex*
6728
+ member is direct-non-list-initialized with
6729
+ `invoke(std::forward<F>(f), error())`.
6730
+
6731
+ ``` cpp
6732
+ template<class F> constexpr auto transform_error(F&& f) &&;
6733
+ template<class F> constexpr auto transform_error(F&& f) const &&;
6734
+ ```
6735
+
6736
+ Let `G` be
6737
+ `remove_cv_t<invoke_result_t<F, decltype(std::move(error()))>>`.
6738
+
6739
+ *Mandates:* `G` is a valid template argument for `unexpected`
6740
+ [[expected.un.general]] and the declaration
6741
+
6742
+ ``` cpp
6743
+ G g(invoke(std::forward<F>(f), std::move(error())));
6744
+ ```
6745
+
6746
+ is well-formed.
6747
+
6748
+ *Returns:* If `has_value()` is `true`, `expected<T, G>()`; otherwise, an
6749
+ `expected<T, G>` object whose *has_val* member is `false` and *unex*
6750
+ member is direct-non-list-initialized with
6751
+ `invoke(std::forward<F>(f), std::move(error()))`.
6752
+
6753
+ #### Equality operators <a id="expected.void.eq">[[expected.void.eq]]</a>
6754
+
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>
6778
 
6779
  ### Header `<bitset>` synopsis <a id="bitset.syn">[[bitset.syn]]</a>
6780
 
6781
  The header `<bitset>` defines a class template and several related
6782
  functions for representing and manipulating fixed-size sequences of
6783
  bits.
6784
 
6785
  ``` cpp
6786
+ #include <string> // see [string.syn]
6787
  #include <iosfwd> // for istream[istream.syn], ostream[ostream.syn], see [iosfwd.syn]
6788
 
6789
  namespace std {
6790
  template<size_t N> class bitset;
6791
 
6792
  // [bitset.operators], bitset operators
6793
  template<size_t N>
6794
+ constexpr bitset<N> operator&(const bitset<N>&, const bitset<N>&) noexcept;
6795
  template<size_t N>
6796
+ constexpr bitset<N> operator|(const bitset<N>&, const bitset<N>&) noexcept;
6797
  template<size_t N>
6798
+ constexpr bitset<N> operator^(const bitset<N>&, const bitset<N>&) noexcept;
6799
  template<class charT, class traits, size_t N>
6800
  basic_istream<charT, traits>&
6801
  operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
6802
  template<class charT, class traits, size_t N>
6803
  basic_ostream<charT, traits>&
 
6805
  }
6806
  ```
6807
 
6808
  ### Class template `bitset` <a id="template.bitset">[[template.bitset]]</a>
6809
 
6810
+ #### General <a id="template.bitset.general">[[template.bitset.general]]</a>
6811
+
6812
  ``` cpp
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];
6826
+ constexpr bool operator~() const noexcept; // flips the bit
6827
+ constexpr operator bool() const noexcept; // for x = b[i];
6828
+ constexpr reference& flip() noexcept; // for b[i].flip();
6829
  };
6830
 
6831
  // [bitset.cons], constructors
6832
  constexpr bitset() noexcept;
6833
  constexpr bitset(unsigned long long val) noexcept;
6834
  template<class charT, class traits, class Allocator>
6835
+ constexpr explicit bitset(
6836
  const basic_string<charT, traits, Allocator>& str,
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;
6851
+ constexpr bitset& operator|=(const bitset& rhs) noexcept;
6852
+ constexpr bitset& operator^=(const bitset& rhs) noexcept;
6853
+ constexpr bitset& operator<<=(size_t pos) noexcept;
6854
+ constexpr bitset& operator>>=(size_t pos) noexcept;
6855
+ constexpr bitset operator<<(size_t pos) const noexcept;
6856
+ constexpr bitset operator>>(size_t pos) const noexcept;
6857
+ constexpr bitset& set() noexcept;
6858
+ constexpr bitset& set(size_t pos, bool val = true);
6859
+ constexpr bitset& reset() noexcept;
6860
+ constexpr bitset& reset(size_t pos);
6861
+ constexpr bitset operator~() const noexcept;
6862
+ constexpr bitset& flip() noexcept;
6863
+ constexpr bitset& flip(size_t pos);
6864
 
6865
  // element access
6866
+ constexpr bool operator[](size_t pos) const;
6867
+ constexpr reference operator[](size_t pos);
6868
 
6869
+ constexpr unsigned long to_ulong() const;
6870
+ constexpr unsigned long long to_ullong() const;
6871
  template<class charT = char,
6872
  class traits = char_traits<charT>,
6873
  class Allocator = allocator<charT>>
6874
+ constexpr basic_string<charT, traits, Allocator>
6875
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
6876
 
6877
+ // observers
6878
+ constexpr size_t count() const noexcept;
6879
  constexpr size_t size() const noexcept;
6880
+ constexpr bool operator==(const bitset& rhs) const noexcept;
6881
+ constexpr bool test(size_t pos) const;
6882
+ constexpr bool all() const noexcept;
6883
+ constexpr bool any() const noexcept;
6884
+ constexpr bool none() const noexcept;
 
 
6885
  };
6886
 
6887
  // [bitset.hash], hash support
6888
  template<class T> struct hash;
6889
  template<size_t N> struct hash<bitset<N>>;
 
6899
  between an object of class `bitset<N>` and a value of some integral
6900
  type, bit position `pos` corresponds to the *bit value* `1 << pos`. The
6901
  integral value corresponding to two or more bits is the sum of their bit
6902
  values.
6903
 
6904
+ The functions described in [[template.bitset]] can report three kinds of
6905
  errors, each associated with a distinct exception:
6906
 
6907
  - an *invalid-argument* error is associated with exceptions of type
6908
  `invalid_argument` [[invalid.argument]];
6909
  - an *out-of-range* error is associated with exceptions of type
 
6923
  constexpr bitset(unsigned long long val) noexcept;
6924
  ```
6925
 
6926
  *Effects:* Initializes the first `M` bit positions to the corresponding
6927
  bit values in `val`. `M` is the smaller of `N` and the number of bits in
6928
+ the value representation [[term.object.representation]] of
6929
+ `unsigned long long`. If `M < N`, the remaining bit positions are
6930
+ initialized to zero.
6931
 
6932
  ``` cpp
6933
  template<class charT, class traits, class Allocator>
6934
+ constexpr explicit bitset(
6935
  const basic_string<charT, traits, Allocator>& str,
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'),
 
6959
  any of the `rlen` characters in `str` beginning at position `pos` is
6960
  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
  ```
 
6978
  ```
6979
 
6980
  #### Members <a id="bitset.members">[[bitset.members]]</a>
6981
 
6982
  ``` cpp
6983
+ constexpr bitset& operator&=(const bitset& rhs) noexcept;
6984
  ```
6985
 
6986
  *Effects:* Clears each bit in `*this` for which the corresponding bit in
6987
  `rhs` is clear, and leaves all other bits unchanged.
6988
 
6989
  *Returns:* `*this`.
6990
 
6991
  ``` cpp
6992
+ constexpr bitset& operator|=(const bitset& rhs) noexcept;
6993
  ```
6994
 
6995
  *Effects:* Sets each bit in `*this` for which the corresponding bit in
6996
  `rhs` is set, and leaves all other bits unchanged.
6997
 
6998
  *Returns:* `*this`.
6999
 
7000
  ``` cpp
7001
+ constexpr bitset& operator^=(const bitset& rhs) noexcept;
7002
  ```
7003
 
7004
  *Effects:* Toggles each bit in `*this` for which the corresponding bit
7005
  in `rhs` is set, and leaves all other bits unchanged.
7006
 
7007
  *Returns:* `*this`.
7008
 
7009
  ``` cpp
7010
+ constexpr bitset& operator<<=(size_t pos) noexcept;
7011
  ```
7012
 
7013
  *Effects:* Replaces each bit at position `I` in `*this` with a value
7014
  determined as follows:
7015
 
 
7018
  position `I - pos`.
7019
 
7020
  *Returns:* `*this`.
7021
 
7022
  ``` cpp
7023
+ constexpr bitset& operator>>=(size_t pos) noexcept;
7024
  ```
7025
 
7026
  *Effects:* Replaces each bit at position `I` in `*this` with a value
7027
  determined as follows:
7028
 
 
7031
  position `I + pos`.
7032
 
7033
  *Returns:* `*this`.
7034
 
7035
  ``` cpp
7036
+ constexpr bitset operator<<(size_t pos) const noexcept;
7037
+ ```
7038
+
7039
+ *Returns:* `bitset(*this) <<= pos`.
7040
+
7041
+ ``` cpp
7042
+ constexpr bitset operator>>(size_t pos) const noexcept;
7043
+ ```
7044
+
7045
+ *Returns:* `bitset(*this) >>= pos`.
7046
+
7047
+ ``` cpp
7048
+ constexpr bitset& set() noexcept;
7049
  ```
7050
 
7051
  *Effects:* Sets all bits in `*this`.
7052
 
7053
  *Returns:* `*this`.
7054
 
7055
  ``` cpp
7056
+ constexpr bitset& set(size_t pos, bool val = true);
7057
  ```
7058
 
7059
  *Effects:* Stores a new value in the bit at position `pos` in `*this`.
7060
  If `val` is `true`, the stored value is one, otherwise it is zero.
7061
 
 
7063
 
7064
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
7065
  position.
7066
 
7067
  ``` cpp
7068
+ constexpr bitset& reset() noexcept;
7069
  ```
7070
 
7071
  *Effects:* Resets all bits in `*this`.
7072
 
7073
  *Returns:* `*this`.
7074
 
7075
  ``` cpp
7076
+ constexpr bitset& reset(size_t pos);
7077
  ```
7078
 
7079
  *Effects:* Resets the bit at position `pos` in `*this`.
7080
 
7081
  *Returns:* `*this`.
7082
 
7083
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
7084
  position.
7085
 
7086
  ``` cpp
7087
+ constexpr bitset operator~() const noexcept;
7088
  ```
7089
 
7090
+ *Effects:* Constructs an object `x` of class `bitset` and initializes it
7091
+ with `*this`.
7092
 
7093
  *Returns:* `x.flip()`.
7094
 
7095
  ``` cpp
7096
+ constexpr bitset& flip() noexcept;
7097
  ```
7098
 
7099
  *Effects:* Toggles all bits in `*this`.
7100
 
7101
  *Returns:* `*this`.
7102
 
7103
  ``` cpp
7104
+ constexpr bitset& flip(size_t pos);
7105
  ```
7106
 
7107
  *Effects:* Toggles the bit at position `pos` in `*this`.
7108
 
7109
  *Returns:* `*this`.
7110
 
7111
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
7112
  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
+
7135
+ *Throws:* Nothing.
7136
+
7137
+ *Remarks:* For the purpose of determining the presence of a data
7138
+ race [[intro.multithread]], any access or update through the resulting
7139
+ reference potentially accesses or modifies, respectively, the entire
7140
+ underlying bitset.
7141
+
7142
+ ``` cpp
7143
+ constexpr unsigned long to_ulong() const;
7144
  ```
7145
 
7146
  *Returns:* `x`.
7147
 
7148
  *Throws:* `overflow_error` if the integral value `x` corresponding to
7149
  the bits in `*this` cannot be represented as type `unsigned long`.
7150
 
7151
  ``` cpp
7152
+ constexpr unsigned long long to_ullong() const;
7153
  ```
7154
 
7155
  *Returns:* `x`.
7156
 
7157
  *Throws:* `overflow_error` if the integral value `x` corresponding to
 
7159
 
7160
  ``` cpp
7161
  template<class charT = char,
7162
  class traits = char_traits<charT>,
7163
  class Allocator = allocator<charT>>
7164
+ constexpr basic_string<charT, traits, Allocator>
7165
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
7166
  ```
7167
 
7168
  *Effects:* Constructs a string object of the appropriate type and
7169
  initializes it to a string of length `N` characters. Each character is
 
7174
  character `one`.
7175
 
7176
  *Returns:* The created object.
7177
 
7178
  ``` cpp
7179
+ constexpr size_t count() const noexcept;
7180
  ```
7181
 
7182
  *Returns:* A count of the number of bits set in `*this`.
7183
 
7184
  ``` cpp
 
7186
  ```
7187
 
7188
  *Returns:* `N`.
7189
 
7190
  ``` cpp
7191
+ constexpr bool operator==(const bitset& rhs) const noexcept;
7192
  ```
7193
 
7194
  *Returns:* `true` if the value of each bit in `*this` equals the value
7195
  of the corresponding bit in `rhs`.
7196
 
7197
  ``` cpp
7198
+ constexpr bool test(size_t pos) const;
7199
  ```
7200
 
7201
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
7202
  one.
7203
 
7204
  *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
7205
  position.
7206
 
7207
  ``` cpp
7208
+ constexpr bool all() const noexcept;
7209
  ```
7210
 
7211
  *Returns:* `count() == size()`.
7212
 
7213
  ``` cpp
7214
+ constexpr bool any() const noexcept;
7215
  ```
7216
 
7217
  *Returns:* `count() != 0`.
7218
 
7219
  ``` cpp
7220
+ constexpr bool none() const noexcept;
7221
  ```
7222
 
7223
  *Returns:* `count() == 0`.
7224
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7225
  ### `bitset` hash support <a id="bitset.hash">[[bitset.hash]]</a>
7226
 
7227
  ``` cpp
7228
  template<size_t N> struct hash<bitset<N>>;
7229
  ```
 
7231
  The specialization is enabled [[unord.hash]].
7232
 
7233
  ### `bitset` operators <a id="bitset.operators">[[bitset.operators]]</a>
7234
 
7235
  ``` cpp
7236
+ template<size_t N>
7237
+ constexpr bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
7238
  ```
7239
 
7240
  *Returns:* `bitset<N>(lhs) &= rhs`.
7241
 
7242
  ``` cpp
7243
+ template<size_t N>
7244
+ constexpr bitset<N> operator|(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
7245
  ```
7246
 
7247
  *Returns:* `bitset<N>(lhs) |= rhs`.
7248
 
7249
  ``` cpp
7250
+ template<size_t N>
7251
+ constexpr bitset<N> operator^(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
7252
  ```
7253
 
7254
  *Returns:* `bitset<N>(lhs) ^= rhs`.
7255
 
7256
  ``` cpp
 
7270
  - `N` characters have been extracted and stored;
7271
  - end-of-file occurs on the input sequence;
7272
  - the next input character is neither `is.widen(’0’)` nor
7273
  `is.widen(’1’)` (in which case the input character is not extracted).
7274
 
7275
+ If `N > 0` and no characters are stored in `str`, `ios_base::failbit` is
7276
+ set in the input function’s local error state before `setstate` is
7277
+ called.
7278
 
7279
  *Returns:* `is`.
7280
 
7281
  ``` cpp
7282
  template<class charT, class traits, size_t N>
 
7292
  use_facet<ctype<charT>>(os.getloc()).widen('1'))
7293
  ```
7294
 
7295
  (see  [[ostream.formatted]]).
7296
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7297
  ## Function objects <a id="function.objects">[[function.objects]]</a>
7298
 
7299
+ ### General <a id="function.objects.general">[[function.objects.general]]</a>
7300
+
7301
+ A *function object type* is an object type [[term.object.type]] that can
7302
+ be the type of the *postfix-expression* in a function call
7303
+ [[expr.call]], [[over.match.call]].[^1]
7304
+
7305
+ A *function object* is an object of a function object type. In the
7306
+ places where one would expect to pass a pointer to a function to an
7307
+ algorithmic template [[algorithms]], the interface is specified to
7308
+ accept a function object. This not only makes algorithmic templates work
7309
+ with pointers to functions, but also enables them to work with arbitrary
7310
+ function objects.
7311
 
7312
  ### Header `<functional>` synopsis <a id="functional.syn">[[functional.syn]]</a>
7313
 
7314
  ``` cpp
7315
  namespace std {
7316
  // [func.invoke], invoke
7317
  template<class F, class... Args>
7318
+ constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args) // freestanding
7319
  noexcept(is_nothrow_invocable_v<F, Args...>);
7320
 
7321
+ template<class R, class F, class... Args>
7322
+ constexpr R invoke_r(F&& f, Args&&... args) // freestanding
7323
+ noexcept(is_nothrow_invocable_r_v<R, F, Args...>);
7324
+
7325
  // [refwrap], reference_wrapper
7326
+ template<class T> class reference_wrapper; // freestanding
7327
 
7328
+ template<class T> constexpr reference_wrapper<T> ref(T&) noexcept; // freestanding
7329
+ template<class T> constexpr reference_wrapper<const T> cref(const T&) noexcept; // freestanding
7330
+ template<class T> void ref(const T&&) = delete; // freestanding
7331
+ template<class T> void cref(const T&&) = delete; // freestanding
7332
 
7333
+ template<class T>
7334
+ constexpr reference_wrapper<T> ref(reference_wrapper<T>) noexcept; // freestanding
7335
+ template<class T>
7336
+ constexpr reference_wrapper<const T> cref(reference_wrapper<T>) noexcept; // freestanding
7337
+
7338
+ // [refwrap.common.ref], common_reference related specializations
7339
+ template<class R, class T, template<class> class RQual, template<class> class TQual>
7340
+ requires see below
7341
+ struct basic_common_reference<R, T, RQual, TQual>;
7342
+
7343
+ template<class T, class R, template<class> class TQual, template<class> class RQual>
7344
+ requires see below
7345
+ struct basic_common_reference<T, R, TQual, RQual>;
7346
 
7347
  // [arithmetic.operations], arithmetic operations
7348
+ template<class T = void> struct plus; // freestanding
7349
+ template<class T = void> struct minus; // freestanding
7350
+ template<class T = void> struct multiplies; // freestanding
7351
+ template<class T = void> struct divides; // freestanding
7352
+ template<class T = void> struct modulus; // freestanding
7353
+ template<class T = void> struct negate; // freestanding
7354
+ template<> struct plus<void>; // freestanding
7355
+ template<> struct minus<void>; // freestanding
7356
+ template<> struct multiplies<void>; // freestanding
7357
+ template<> struct divides<void>; // freestanding
7358
+ template<> struct modulus<void>; // freestanding
7359
+ template<> struct negate<void>; // freestanding
7360
 
7361
  // [comparisons], comparisons
7362
+ template<class T = void> struct equal_to; // freestanding
7363
+ template<class T = void> struct not_equal_to; // freestanding
7364
+ template<class T = void> struct greater; // freestanding
7365
+ template<class T = void> struct less; // freestanding
7366
+ template<class T = void> struct greater_equal; // freestanding
7367
+ template<class T = void> struct less_equal; // freestanding
7368
+ template<> struct equal_to<void>; // freestanding
7369
+ template<> struct not_equal_to<void>; // freestanding
7370
+ template<> struct greater<void>; // freestanding
7371
+ template<> struct less<void>; // freestanding
7372
+ template<> struct greater_equal<void>; // freestanding
7373
+ template<> struct less_equal<void>; // freestanding
7374
 
7375
  // [comparisons.three.way], class compare_three_way
7376
+ struct compare_three_way; // freestanding
7377
 
7378
  // [logical.operations], logical operations
7379
+ template<class T = void> struct logical_and; // freestanding
7380
+ template<class T = void> struct logical_or; // freestanding
7381
+ template<class T = void> struct logical_not; // freestanding
7382
+ template<> struct logical_and<void>; // freestanding
7383
+ template<> struct logical_or<void>; // freestanding
7384
+ template<> struct logical_not<void>; // freestanding
7385
 
7386
  // [bitwise.operations], bitwise operations
7387
+ template<class T = void> struct bit_and; // freestanding
7388
+ template<class T = void> struct bit_or; // freestanding
7389
+ template<class T = void> struct bit_xor; // freestanding
7390
+ template<class T = void> struct bit_not; // freestanding
7391
+ template<> struct bit_and<void>; // freestanding
7392
+ template<> struct bit_or<void>; // freestanding
7393
+ template<> struct bit_xor<void>; // freestanding
7394
+ template<> struct bit_not<void>; // freestanding
7395
 
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
7412
+ is_bind_expression<T>::value;
7413
+ template<class T> struct is_placeholder; // freestanding
7414
  template<class T>
7415
+ constexpr int is_placeholder_v = // freestanding
7416
+ is_placeholder<T>::value;
7417
 
7418
  template<class F, class... BoundArgs>
7419
+ constexpr unspecified bind(F&&, BoundArgs&&...); // freestanding
7420
  template<class R, class F, class... BoundArgs>
7421
+ constexpr unspecified bind(F&&, BoundArgs&&...); // freestanding
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,
7461
  class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
7462
  class BinaryPredicate = equal_to<>>
7463
  class boyer_moore_searcher;
 
7467
  class BinaryPredicate = equal_to<>>
7468
  class boyer_moore_horspool_searcher;
7469
 
7470
  // [unord.hash], class template hash
7471
  template<class T>
7472
+ struct hash; // freestanding
7473
 
7474
  namespace ranges {
7475
  // [range.cmp], concept-constrained comparisons
7476
+ struct equal_to; // freestanding
7477
+ struct not_equal_to; // freestanding
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*:
 
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
7552
+ `T` and `t₁` does not satisfy the previous two items;
7553
  - `f(t₁, t₂, …, t_N)` in all other cases.
7554
 
7555
  Define `INVOKE<R>(f, t₁, t₂, …, t_N)` as
7556
  `static_cast<void>(INVOKE(f, t₁, t₂, …, t_N))` if `R` is cv `void`,
7557
+ otherwise `INVOKE(f, t₁, t₂, …, t_N)` implicitly converted to `R`. If
7558
+ `reference_converts_from_temporary_v<R, decltype(INVOKE(f, t₁, t₂, …, t_N))>`
7559
+ is `true`, `INVOKE<R>(f, t₁, t₂, …, t_N)` is ill-formed.
7560
 
7561
  Every call wrapper [[func.def]] meets the *Cpp17MoveConstructible* and
7562
  *Cpp17Destructible* requirements. An *argument forwarding call wrapper*
7563
  is a call wrapper that can be called with an arbitrary argument list and
7564
+ delivers the arguments to the target object as references. This
7565
+ forwarding step delivers rvalue arguments as rvalue references and
7566
  lvalue arguments as lvalue references.
7567
 
7568
  [*Note 1*:
7569
 
7570
  In a typical implementation, argument forwarding call wrappers have an
 
7585
  call wrapper and where cv shall be neither `volatile` nor
7586
  `const volatile`.
7587
 
7588
  A *call pattern* defines the semantics of invoking a perfect forwarding
7589
  call wrapper. A postfix call performed on a perfect forwarding call
7590
+ wrapper is expression-equivalent [[defns.expression.equivalent]] to an
7591
  expression `e` determined from its call pattern `cp` by replacing all
7592
  occurrences of the arguments of the call wrapper and its state entities
7593
  with references as described in the corresponding forwarding steps.
7594
 
7595
  A *simple call wrapper* is a perfect forwarding call wrapper that meets
 
7608
 
7609
  Argument forwarding call wrappers returned by a given standard library
7610
  function template have the same type if the types of their corresponding
7611
  state entities are the same.
7612
 
7613
+ ### `invoke` functions <a id="func.invoke">[[func.invoke]]</a>
7614
 
7615
  ``` cpp
7616
  template<class F, class... Args>
7617
  constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args)
7618
  noexcept(is_nothrow_invocable_v<F, Args...>);
7619
  ```
7620
 
7621
+ *Constraints:* `is_invocable_v<F, Args...>` is `true`.
7622
+
7623
  *Returns:* *INVOKE*(std::forward\<F\>(f),
7624
  std::forward\<Args\>(args)...) [[func.require]].
7625
 
7626
+ ``` cpp
7627
+ template<class R, class F, class... Args>
7628
+ constexpr R invoke_r(F&& f, Args&&... args)
7629
+ noexcept(is_nothrow_invocable_r_v<R, F, Args...>);
7630
+ ```
7631
+
7632
+ *Constraints:* `is_invocable_r_v<R, F, Args...>` is `true`.
7633
+
7634
+ *Returns:* *INVOKE*\<R\>(std::forward\<F\>(f),
7635
+ std::forward\<Args\>(args)...) [[func.require]].
7636
+
7637
  ### Class template `reference_wrapper` <a id="refwrap">[[refwrap]]</a>
7638
 
7639
+ #### General <a id="refwrap.general">[[refwrap.general]]</a>
7640
+
7641
  ``` cpp
7642
  namespace std {
7643
  template<class T> class reference_wrapper {
7644
  public:
7645
  // types
7646
  using type = T;
7647
 
7648
+ // [refwrap.const], constructors
7649
  template<class U>
7650
  constexpr reference_wrapper(U&&) noexcept(see below);
7651
  constexpr reference_wrapper(const reference_wrapper& x) noexcept;
7652
 
7653
+ // [refwrap.assign], assignment
7654
  constexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept;
7655
 
7656
+ // [refwrap.access], access
7657
  constexpr operator T& () const noexcept;
7658
  constexpr T& get() const noexcept;
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
  }
7669
  ```
7670
 
7671
  `reference_wrapper<T>` is a *Cpp17CopyConstructible* and
7672
  *Cpp17CopyAssignable* wrapper around a reference to an object or
7673
  function of type `T`.
7674
 
7675
+ `reference_wrapper<T>` is a trivially copyable type
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);
7686
  ```
 
7697
 
7698
  *Effects:* Creates a variable `r` as if by `T& r = std::forward<U>(u)`,
7699
  then constructs a `reference_wrapper` object that stores a reference to
7700
  `r`.
7701
 
7702
+ *Remarks:* The exception specification is equivalent to
7703
  `noexcept(`*`FUN`*`(declval<U>()))`.
7704
 
7705
  ``` cpp
7706
  constexpr reference_wrapper(const reference_wrapper& x) noexcept;
7707
  ```
 
7734
  #### Invocation <a id="refwrap.invoke">[[refwrap.invoke]]</a>
7735
 
7736
  ``` cpp
7737
  template<class... ArgTypes>
7738
  constexpr invoke_result_t<T&, ArgTypes...>
7739
+ operator()(ArgTypes&&... args) const noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);
7740
  ```
7741
 
7742
  *Mandates:* `T` is a complete type.
7743
 
7744
  *Returns:* *INVOKE*(get(),
 
7757
 
7758
  ``` cpp
7759
  template<class T> constexpr reference_wrapper<T> ref(reference_wrapper<T> t) noexcept;
7760
  ```
7761
 
7762
+ *Returns:* `t`.
7763
 
7764
  ``` cpp
7765
  template<class T> constexpr reference_wrapper<const T> cref(const T& t) noexcept;
7766
  ```
7767
 
 
7769
 
7770
  ``` cpp
7771
  template<class T> constexpr reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
7772
  ```
7773
 
7774
+ *Returns:* `t`.
7775
+
7776
+ #### `common_reference` related specializations <a id="refwrap.common.ref">[[refwrap.common.ref]]</a>
7777
+
7778
+ ``` cpp
7779
+ namespace std {
7780
+ template<class T>
7781
+ constexpr bool is-ref-wrapper = false; // exposition only
7782
+
7783
+ template<class T>
7784
+ constexpr bool is-ref-wrapper<reference_wrapper<T>> = true;
7785
+
7786
+ template<class R, class T, class RQ, class TQ>
7787
+ concept ref-wrap-common-reference-exists-with = // exposition only
7788
+ is-ref-wrapper<R> &&
7789
+ requires { typename common_reference_t<typename R::type&, TQ>; } &&
7790
+ convertible_to<RQ, common_reference_t<typename R::type&, TQ>>;
7791
+
7792
+ template<class R, class T, template<class> class RQual, template<class> class TQual>
7793
+ requires (ref-wrap-common-reference-exists-with<R, T, RQual<R>, TQual<T>> &&
7794
+ !ref-wrap-common-reference-exists-with<T, R, TQual<T>, RQual<R>>)
7795
+ struct basic_common_reference<R, T, RQual, TQual> {
7796
+ using type = common_reference_t<typename R::type&, TQual<T>>;
7797
+ };
7798
+
7799
+ template<class T, class R, template<class> class TQual, template<class> class RQual>
7800
+ requires (ref-wrap-common-reference-exists-with<R, T, RQual<R>, TQual<T>> &&
7801
+ !ref-wrap-common-reference-exists-with<T, R, TQual<T>, RQual<R>>)
7802
+ struct basic_common_reference<T, R, TQual, RQual> {
7803
+ using type = common_reference_t<typename R::type&, TQual<T>>;
7804
+ };
7805
+ }
7806
+ ```
7807
 
7808
  ### Arithmetic operations <a id="arithmetic.operations">[[arithmetic.operations]]</a>
7809
 
7810
+ #### General <a id="arithmetic.operations.general">[[arithmetic.operations.general]]</a>
7811
+
7812
  The library provides basic function object classes for all of the
7813
+ arithmetic operators in the language [[expr.mul]], [[expr.add]].
7814
 
7815
  #### Class template `plus` <a id="arithmetic.operations.plus">[[arithmetic.operations.plus]]</a>
7816
 
7817
  ``` cpp
7818
  template<class T = void> struct plus {
 
7992
 
7993
  *Returns:* `-std::forward<T>(t)`.
7994
 
7995
  ### Comparisons <a id="comparisons">[[comparisons]]</a>
7996
 
7997
+ #### General <a id="comparisons.general">[[comparisons.general]]</a>
7998
+
7999
  The library provides basic function object classes for all of the
8000
+ comparison operators in the language [[expr.rel]], [[expr.eq]].
8001
 
8002
  For templates `less`, `greater`, `less_equal`, and `greater_equal`, the
8003
  specializations for any pointer type yield a result consistent with the
8004
  implementation-defined strict total order over pointers
8005
  [[defns.order.ptr]].
 
8194
 
8195
  *Returns:* `std::forward<T>(t) <= std::forward<U>(u)`.
8196
 
8197
  #### Class `compare_three_way` <a id="comparisons.three.way">[[comparisons.three.way]]</a>
8198
 
 
 
 
 
 
 
 
 
 
 
8199
  ``` cpp
8200
+ namespace std {
8201
  struct compare_three_way {
8202
  template<class T, class U>
 
8203
  constexpr auto operator()(T&& t, U&& u) const;
8204
 
8205
  using is_transparent = unspecified;
8206
  };
8207
+ }
8208
  ```
8209
 
8210
  ``` cpp
8211
  template<class T, class U>
 
8212
  constexpr auto operator()(T&& t, U&& u) const;
8213
  ```
8214
 
8215
+ *Constraints:* `T` and `U` satisfy `three_way_comparable_with`.
8216
+
8217
  *Preconditions:* If the expression
8218
  `std::forward<T>(t) <=> std::forward<U>(u)` results in a call to a
8219
  built-in operator `<=>` comparing pointers of type `P`, the conversion
8220
  sequences from both `T` and `U` to `P` are
8221
+ equality-preserving [[concepts.equality]]; otherwise, `T` and `U` model
8222
+ `three_way_comparable_with`.
8223
 
8224
  *Effects:*
8225
 
8226
  - If the expression `std::forward<T>(t) <=> std::forward<U>(u)` results
8227
  in a call to a built-in operator `<=>` comparing pointers of type `P`,
 
8232
  - Otherwise, equivalent to:
8233
  `return std::forward<T>(t) <=> std::forward<U>(u);`
8234
 
8235
  ### Concept-constrained comparisons <a id="range.cmp">[[range.cmp]]</a>
8236
 
 
 
 
 
 
 
8237
  ``` cpp
8238
  struct ranges::equal_to {
8239
  template<class T, class U>
 
8240
  constexpr bool operator()(T&& t, U&& u) const;
8241
 
8242
  using is_transparent = unspecified;
8243
  };
8244
  ```
8245
 
8246
+ ``` cpp
8247
+ template<class T, class U>
8248
+ constexpr bool operator()(T&& t, U&& u) const;
8249
+ ```
8250
+
8251
+ *Constraints:* `T` and `U` satisfy `equality_comparable_with`.
8252
+
8253
  *Preconditions:* If the expression
8254
  `std::forward<T>(t) == std::forward<U>(u)` results in a call to a
8255
  built-in operator `==` comparing pointers of type `P`, the conversion
8256
  sequences from both `T` and `U` to `P` are
8257
+ equality-preserving [[concepts.equality]]; otherwise, `T` and `U` model
8258
+ `equality_comparable_with`.
8259
 
8260
  *Effects:*
8261
 
8262
  - If the expression `std::forward<T>(t) == std::forward<U>(u)` results
8263
  in a call to a built-in operator `==` comparing pointers: returns
 
8268
  `return std::forward<T>(t) == std::forward<U>(u);`
8269
 
8270
  ``` cpp
8271
  struct ranges::not_equal_to {
8272
  template<class T, class U>
 
8273
  constexpr bool operator()(T&& t, U&& u) const;
8274
 
8275
  using is_transparent = unspecified;
8276
  };
8277
  ```
8278
 
8279
+ ``` cpp
8280
+ template<class T, class U>
8281
+ constexpr bool operator()(T&& t, U&& u) const;
8282
+ ```
8283
+
8284
+ *Constraints:* `T` and `U` satisfy `equality_comparable_with`.
8285
+
8286
+ *Effects:* Equivalent to:
8287
 
8288
  ``` cpp
8289
  return !ranges::equal_to{}(std::forward<T>(t), std::forward<U>(u));
8290
  ```
8291
 
8292
  ``` cpp
8293
  struct ranges::greater {
8294
  template<class T, class U>
 
8295
  constexpr bool operator()(T&& t, U&& u) const;
8296
 
8297
  using is_transparent = unspecified;
8298
  };
8299
  ```
8300
 
8301
+ ``` cpp
8302
+ template<class T, class U>
8303
+ constexpr bool operator()(T&& t, U&& u) const;
8304
+ ```
8305
+
8306
+ *Constraints:* `T` and `U` satisfy `totally_ordered_with`.
8307
+
8308
+ *Effects:* Equivalent to:
8309
 
8310
  ``` cpp
8311
  return ranges::less{}(std::forward<U>(u), std::forward<T>(t));
8312
  ```
8313
 
8314
  ``` cpp
8315
  struct ranges::less {
8316
  template<class T, class U>
 
8317
  constexpr bool operator()(T&& t, U&& u) const;
8318
 
8319
  using is_transparent = unspecified;
8320
  };
8321
  ```
8322
 
8323
+ ``` cpp
8324
+ template<class T, class U>
8325
+ constexpr bool operator()(T&& t, U&& u) const;
8326
+ ```
8327
+
8328
+ *Constraints:* `T` and `U` satisfy `totally_ordered_with`.
8329
+
8330
  *Preconditions:* If the expression
8331
  `std::forward<T>(t) < std::forward<U>(u)` results in a call to a
8332
  built-in operator `<` comparing pointers of type `P`, the conversion
8333
  sequences from both `T` and `U` to `P` are
8334
+ equality-preserving [[concepts.equality]]; otherwise, `T` and `U` model
8335
+ `totally_ordered_with`. For any expressions `ET` and `EU` such that
8336
+ `decltype((ET))` is `T` and `decltype((EU))` is `U`, exactly one of
8337
+ `ranges::less{}(ET, EU)`, `ranges::less{}(EU, ET)`, or
8338
  `ranges::equal_to{}(ET, EU)` is `true`.
8339
 
8340
  *Effects:*
8341
 
8342
  - If the expression `std::forward<T>(t) < std::forward<U>(u)` results in
 
8348
  `return std::forward<T>(t) < std::forward<U>(u);`
8349
 
8350
  ``` cpp
8351
  struct ranges::greater_equal {
8352
  template<class T, class U>
 
8353
  constexpr bool operator()(T&& t, U&& u) const;
8354
 
8355
  using is_transparent = unspecified;
8356
  };
8357
  ```
8358
 
8359
+ ``` cpp
8360
+ template<class T, class U>
8361
+ constexpr bool operator()(T&& t, U&& u) const;
8362
+ ```
8363
+
8364
+ *Constraints:* `T` and `U` satisfy `totally_ordered_with`.
8365
+
8366
+ *Effects:* Equivalent to:
8367
 
8368
  ``` cpp
8369
  return !ranges::less{}(std::forward<T>(t), std::forward<U>(u));
8370
  ```
8371
 
8372
  ``` cpp
8373
  struct ranges::less_equal {
8374
  template<class T, class U>
 
8375
  constexpr bool operator()(T&& t, U&& u) const;
8376
 
8377
  using is_transparent = unspecified;
8378
  };
8379
  ```
8380
 
8381
+ ``` cpp
8382
+ template<class T, class U>
8383
+ constexpr bool operator()(T&& t, U&& u) const;
8384
+ ```
8385
+
8386
+ *Constraints:* `T` and `U` satisfy `totally_ordered_with`.
8387
+
8388
+ *Effects:* Equivalent to:
8389
 
8390
  ``` cpp
8391
  return !ranges::less{}(std::forward<U>(u), std::forward<T>(t));
8392
  ```
8393
 
8394
  ### Logical operations <a id="logical.operations">[[logical.operations]]</a>
8395
 
8396
+ #### General <a id="logical.operations.general">[[logical.operations.general]]</a>
8397
+
8398
  The library provides basic function object classes for all of the
8399
+ logical operators in the language
8400
+ [[expr.log.and]], [[expr.log.or]], [[expr.unary.op]].
8401
 
8402
  #### Class template `logical_and` <a id="logical.operations.and">[[logical.operations.and]]</a>
8403
 
8404
  ``` cpp
8405
  template<class T = void> struct logical_and {
 
8489
 
8490
  *Returns:* `!std::forward<T>(t)`.
8491
 
8492
  ### Bitwise operations <a id="bitwise.operations">[[bitwise.operations]]</a>
8493
 
8494
+ #### General <a id="bitwise.operations.general">[[bitwise.operations.general]]</a>
8495
+
8496
  The library provides basic function object classes for all of the
8497
+ bitwise operators in the language
8498
+ [[expr.bit.and]], [[expr.or]], [[expr.xor]], [[expr.unary.op]].
8499
 
8500
  #### Class template `bit_and` <a id="bitwise.operations.and">[[bitwise.operations.and]]</a>
8501
 
8502
  ``` cpp
8503
  template<class T = void> struct bit_and {
 
8609
  using is_transparent = unspecified;
8610
  };
8611
  ```
8612
 
8613
  ``` cpp
8614
+ template<class T> constexpr auto operator()(T&& t) const
8615
  -> decltype(~std::forward<T>(t));
8616
  ```
8617
 
8618
  *Returns:* `~std::forward<T>(t)`.
8619
 
 
8651
  *Mandates:* `is_constructible_v<FD, F> && is_move_constructible_v<FD>`
8652
  is `true`.
8653
 
8654
  *Preconditions:* `FD` meets the *Cpp17MoveConstructible* requirements.
8655
 
8656
+ *Returns:* A perfect forwarding call
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);
8667
+ template<class F, class... Args>
8668
+ constexpr unspecified bind_back(F&& f, Args&&... args);
8669
  ```
8670
 
8671
+ Within this subclause:
8672
 
8673
+ - `g` is a value of the result of a `bind_front` or `bind_back`
8674
+ invocation,
8675
  - `FD` is the type `decay_t<F>`,
8676
  - `fd` is the target object of `g` [[func.def]] of type `FD`,
8677
  direct-non-list-initialized with `std::forward<F>(f)`,
8678
  - `BoundArgs` is a pack that denotes `decay_t<Args>...`,
8679
  - `bound_args` is a pack of bound argument entities of `g` [[func.def]]
 
8695
 
8696
  *Preconditions:* `FD` meets the *Cpp17MoveConstructible* requirements.
8697
  For each `Tᵢ` in `BoundArgs`, if `Tᵢ` is an object type, `Tᵢ` meets the
8698
  *Cpp17MoveConstructible* requirements.
8699
 
8700
+ *Returns:* A perfect forwarding call
8701
+ wrapper [[term.perfect.forwarding.call.wrapper]] `g` with call pattern:
8702
+
8703
+ - `invoke(fd, bound_args..., call_args...)` for a `bind_front`
8704
+ invocation, or
8705
+ - `invoke(fd, call_args..., bound_args...)` for a `bind_back`
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
8716
+ arguments of callable objects.
8717
 
8718
  #### Class template `is_bind_expression` <a id="func.bind.isbind">[[func.bind.isbind]]</a>
8719
 
8720
  ``` cpp
8721
  namespace std {
 
8743
  template<class T> struct is_placeholder; // see below
8744
  }
8745
  ```
8746
 
8747
  The class template `is_placeholder` can be used to detect the standard
8748
+ placeholders `_1`, `_2`, and so on [[func.bind.place]]. The function
8749
+ template `bind` uses `is_placeholder` to detect placeholders.
8750
 
8751
  Specializations of the `is_placeholder` template shall meet the
8752
  *Cpp17UnaryTypeTrait* requirements [[meta.rqmts]]. The implementation
8753
  provides a definition that has the base characteristic of
8754
  `integral_constant<int, J>` if `T` is the type of
 
8792
 
8793
  *Returns:* An argument forwarding call wrapper `g` [[func.require]]. A
8794
  program that attempts to invoke a volatile-qualified `g` is ill-formed.
8795
  When `g` is not volatile-qualified, invocation of
8796
  `g(``u₁``, ``u₂``, `…`, ``u_M``)` is
8797
+ expression-equivalent [[defns.expression.equivalent]] to
8798
 
8799
  ``` cpp
8800
  INVOKE(static_cast<$V_fd$>($v_fd$),
8801
  static_cast<$V_1$>($v_1$), static_cast<$V_2$>($v_2$), …, static_cast<$V_N$>($v_N$))
8802
  ```
 
8841
 
8842
  #### Placeholders <a id="func.bind.place">[[func.bind.place]]</a>
8843
 
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*.
8857
+
8858
  All placeholder types meet the *Cpp17DefaultConstructible* and
8859
  *Cpp17CopyConstructible* requirements, and their default constructors
8860
  and copy/move constructors are constexpr functions that do not throw
8861
  exceptions. It is *implementation-defined* whether placeholder types
8862
  meet the *Cpp17CopyAssignable* requirements, but if so, their copy
 
8873
 
8874
  ``` cpp
8875
  extern unspecified _1;
8876
  ```
8877
 
8878
+ Placeholders are freestanding items [[freestanding.item]].
8879
+
8880
  ### Function template `mem_fn` <a id="func.memfn">[[func.memfn]]</a>
8881
 
8882
  ``` cpp
8883
  template<class R, class T> constexpr unspecified mem_fn(R T::* pm) noexcept;
8884
  ```
8885
 
8886
+ *Returns:* A simple call wrapper [[term.simple.call.wrapper]] `fn` with
8887
+ call pattern `invoke(pmd, call_args...)`, where `pmd` is the target
8888
+ object of `fn` of type `R T::*` direct-non-list-initialized with `pm`,
8889
+ and `call_args` is an argument pack used in a function call
8890
+ expression [[expr.call]] of `fn`.
8891
 
8892
  ### Polymorphic function wrappers <a id="func.wrap">[[func.wrap]]</a>
8893
 
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
 
8918
 
8919
  *Returns:* An *implementation-defined* NTBS.
8920
 
8921
  #### Class template `function` <a id="func.wrap.func">[[func.wrap.func]]</a>
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>
 
8934
  // [func.wrap.func.con], construct/copy/destroy
8935
  function() noexcept;
8936
  function(nullptr_t) noexcept;
8937
  function(const function&);
8938
  function(function&&) noexcept;
8939
+ template<class F> function(F&&);
8940
 
8941
  function& operator=(const function&);
8942
  function& operator=(function&&);
8943
  function& operator=(nullptr_t) noexcept;
8944
  template<class F> function& operator=(F&&);
 
8963
 
8964
  template<class R, class... ArgTypes>
8965
  function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;
8966
 
8967
  template<class F> function(F) -> function<see below>;
 
 
 
 
 
 
 
 
8968
  }
8969
  ```
8970
 
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*]
8987
 
8988
  ##### Constructors and destructor <a id="func.wrap.func.con">[[func.wrap.func.con]]</a>
8989
 
8990
  ``` cpp
8991
  function() noexcept;
 
9001
 
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.
9013
 
9014
+ *Recommended practice:* Implementations should avoid the use of
9015
+ dynamically allocated memory for small callable objects, for example,
9016
+ where `f`’s target is an object holding only a pointer or reference to
9017
+ an object and a member function pointer.
9018
 
9019
  ``` cpp
9020
  function(function&& f) noexcept;
9021
  ```
9022
 
9023
  *Ensures:* If `!f`, `*this` has no target; otherwise, the target of
9024
  `*this` is equivalent to the target of `f` before the construction, and
9025
  `f` is in a valid state with an unspecified value.
9026
 
9027
+ *Recommended practice:* Implementations should avoid the use of
9028
+ dynamically allocated memory for small callable objects, for example,
9029
+ where `f`’s target is an object holding only a pointer or reference to
9030
+ an object and a member function pointer.
9031
 
9032
  ``` cpp
9033
+ template<class F> function(F&& f);
9034
  ```
9035
 
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`.
9048
+
9049
+ *Preconditions:* `FD` meets the *Cpp17CopyConstructible* requirements.
9050
+
9051
+ *Ensures:* `!*this` is `true` if any of the following hold:
9052
 
9053
  - `f` is a null function pointer value.
9054
  - `f` is a null member pointer value.
9055
+ - `remove_cvref_t<F>` is a specialization of the `function` class
9056
+ template, and `!f` is `true`.
9057
 
9058
+ Otherwise, `*this` has a target object of type `FD`
9059
+ direct-non-list-initialized with `std::forward<F>(f)`.
9060
 
9061
+ *Throws:* Nothing if `FD` is a specialization of `reference_wrapper` or
9062
+ a function pointer type. Otherwise, may throw `bad_alloc` or any
9063
+ exception thrown by the initialization of the target object.
 
9064
 
9065
+ *Recommended practice:* Implementations should avoid the use of
9066
+ dynamically allocated memory for small callable objects, for example,
9067
+ where `f` refers to an object holding only a pointer or reference to an
9068
+ object and a member function pointer.
9069
 
9070
  ``` cpp
9071
  template<class F> function(F) -> function<see below>;
9072
  ```
9073
 
9074
  *Constraints:* `&F::operator()` is well-formed when treated as an
9075
+ unevaluated operand and either
9076
+
9077
+ - `F::operator()` is a non-static member function and
9078
+ `decltype(&F::operator())` is either of the form
9079
+ `R(G::*)(A...)` cv \\ₒₚₜ ` `noexceptₒₚₜ or of the form
9080
+ `R(*)(G, A...) `noexceptₒₚₜ for a type `G`, or
9081
+ - `F::operator()` is a static member function and
9082
+ `decltype(&F::operator())` is of the form `R(*)(A...) `noexceptₒₚₜ .
9083
 
9084
  *Remarks:* The deduced type is `function<R(A...)>`.
9085
 
9086
  [*Example 1*:
9087
 
 
9149
 
9150
  ``` cpp
9151
  void swap(function& other) noexcept;
9152
  ```
9153
 
9154
+ *Effects:* Interchanges the target objects of `*this` and `other`.
9155
 
9156
  ##### Capacity <a id="func.wrap.func.cap">[[func.wrap.func.cap]]</a>
9157
 
9158
  ``` cpp
9159
  explicit operator bool() const noexcept;
 
9170
  *Returns:* *INVOKE*\<R\>(f,
9171
  std::forward\<ArgTypes\>(args)...) [[func.require]], where `f` is the
9172
  target object [[func.def]] of `*this`.
9173
 
9174
  *Throws:* `bad_function_call` if `!*this`; otherwise, any exception
9175
+ thrown by the target object.
9176
 
9177
  ##### Target access <a id="func.wrap.func.targ">[[func.wrap.func.targ]]</a>
9178
 
9179
  ``` cpp
9180
  const type_info& target_type() const noexcept;
 
9189
  ```
9190
 
9191
  *Returns:* If `target_type() == typeid(T)` a pointer to the stored
9192
  function target; otherwise a null pointer.
9193
 
9194
+ ##### Null pointer comparison operator functions <a id="func.wrap.func.nullptr">[[func.wrap.func.nullptr]]</a>
9195
 
9196
  ``` cpp
9197
  template<class R, class... ArgTypes>
9198
  bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
9199
  ```
 
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,
9218
+ *ref*, and *noex* where
9219
+
9220
+ - cv is either const or empty,
9221
+ - *ref* is either `&`, `&&`, or empty, and
9222
+ - *noex* is either `true` or `false`.
9223
+
9224
+ For each of the possible combinations of the placeholders mentioned
9225
+ above, there is a placeholder *inv-quals* defined as follows:
9226
+
9227
+ - If *ref* is empty, let *inv-quals* be cv`&`,
9228
+ - otherwise, let *inv-quals* be cv *ref*.
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>
9247
+ explicit move_only_function(in_place_type_t<T>, Args&&...);
9248
+ template<class T, class U, class... Args>
9249
+ explicit move_only_function(in_place_type_t<T>, initializer_list<U>, Args&&...);
9250
+
9251
+ move_only_function& operator=(move_only_function&&);
9252
+ move_only_function& operator=(nullptr_t) noexcept;
9253
+ template<class F> move_only_function& operator=(F&&);
9254
+
9255
+ ~move_only_function();
9256
+
9257
+ // [func.wrap.move.inv], invocation
9258
+ explicit operator bool() const noexcept;
9259
+ R operator()(ArgTypes...) cv ref noexcept(noex);
9260
+
9261
+ // [func.wrap.move.util], utility
9262
+ void swap(move_only_function&) noexcept;
9263
+ friend void swap(move_only_function&, move_only_function&) noexcept;
9264
+ friend bool operator==(const move_only_function&, nullptr_t) noexcept;
9265
+
9266
+ private:
9267
+ template<class VT>
9268
+ static constexpr bool is-callable-from = see below; // exposition only
9269
+ };
9270
+ }
9271
+ ```
9272
+
9273
+ The `move_only_function` class template provides polymorphic wrappers
9274
+ that generalize the notion of a callable object [[func.def]]. These
9275
+ wrappers can store, move, and call arbitrary callable objects, given a
9276
+ call signature.
9277
+
9278
+ *Recommended practice:* Implementations should avoid the use of
9279
+ 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
+ ```
9291
+
9292
+ If *noex* is `true`, *`is-callable-from`*`<VT>` is equal to:
9293
+
9294
+ ``` cpp
9295
+ is_nothrow_invocable_r_v<R, VT cv ref, ArgTypes...> &&
9296
+ is_nothrow_invocable_r_v<R, VT inv-quals, ArgTypes...>
9297
+ ```
9298
+
9299
+ Otherwise, *`is-callable-from`*`<VT>` is equal to:
9300
+
9301
+ ``` cpp
9302
+ is_invocable_r_v<R, VT cv ref, ArgTypes...> &&
9303
+ is_invocable_r_v<R, VT inv-quals, ArgTypes...>
9304
+ ```
9305
+
9306
+ ``` cpp
9307
+ move_only_function() noexcept;
9308
+ move_only_function(nullptr_t) noexcept;
9309
+ ```
9310
+
9311
+ *Ensures:* `*this` has no target object.
9312
+
9313
+ ``` cpp
9314
+ move_only_function(move_only_function&& f) noexcept;
9315
+ ```
9316
+
9317
+ *Ensures:* The target object of `*this` is the target object `f` had
9318
+ before construction, and `f` is in a valid state with an unspecified
9319
+ value.
9320
+
9321
+ ``` cpp
9322
+ template<class F> move_only_function(F&& f);
9323
+ ```
9324
+
9325
+ Let `VT` be `decay_t<F>`.
9326
+
9327
+ *Constraints:*
9328
+
9329
+ - `remove_cvref_t<F>` is not the same type as `move_only_function`, and
9330
+ - `remove_cvref_t<F>` is not a specialization of `in_place_type_t`, and
9331
+ - *`is-callable-from`*`<VT>` is `true`.
9332
+
9333
+ *Mandates:* `is_constructible_v<VT, F>` is `true`.
9334
+
9335
+ *Preconditions:* `VT` meets the *Cpp17Destructible* requirements, and if
9336
+ `is_move_constructible_v<VT>` is `true`, `VT` meets the
9337
+ *Cpp17MoveConstructible* requirements.
9338
+
9339
+ *Ensures:* `*this` has no target object if any of the following hold:
9340
+
9341
+ - `f` is a null function pointer value, or
9342
+ - `f` is a null member pointer value, or
9343
+ - `remove_cvref_t<F>` is a specialization of the `move_only_function`
9344
+ class template, and `f` has no target object.
9345
+
9346
+ Otherwise, `*this` has a target object of type `VT`
9347
+ direct-non-list-initialized with `std::forward<F>(f)`.
9348
+
9349
+ *Throws:* Any exception thrown by the initialization of the target
9350
+ object. May throw `bad_alloc` unless `VT` is a function pointer or a
9351
+ specialization of `reference_wrapper`.
9352
+
9353
+ ``` cpp
9354
+ template<class T, class... Args>
9355
+ explicit move_only_function(in_place_type_t<T>, Args&&... args);
9356
+ ```
9357
+
9358
+ Let `VT` be `decay_t<T>`.
9359
+
9360
+ *Constraints:*
9361
+
9362
+ - `is_constructible_v<VT, Args...>` is `true`, and
9363
+ - *`is-callable-from`*`<VT>` is `true`.
9364
+
9365
+ *Mandates:* `VT` is the same type as `T`.
9366
+
9367
+ *Preconditions:* `VT` meets the *Cpp17Destructible* requirements, and if
9368
+ `is_move_constructible_v<VT>` is `true`, `VT` meets the
9369
+ *Cpp17MoveConstructible* requirements.
9370
+
9371
+ *Ensures:* `*this` has a target object of type `VT`
9372
+ direct-non-list-initialized with `std::forward<Args>(args)...`.
9373
+
9374
+ *Throws:* Any exception thrown by the initialization of the target
9375
+ object. May throw `bad_alloc` unless `VT` is a function pointer or a
9376
+ specialization of `reference_wrapper`.
9377
+
9378
+ ``` cpp
9379
+ template<class T, class U, class... Args>
9380
+ explicit move_only_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
9381
+ ```
9382
+
9383
+ Let `VT` be `decay_t<T>`.
9384
+
9385
+ *Constraints:*
9386
+
9387
+ - `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`, and
9388
+ - *`is-callable-from`*`<VT>` is `true`.
9389
+
9390
+ *Mandates:* `VT` is the same type as `T`.
9391
+
9392
+ *Preconditions:* `VT` meets the *Cpp17Destructible* requirements, and if
9393
+ `is_move_constructible_v<VT>` is `true`, `VT` meets the
9394
+ *Cpp17MoveConstructible* requirements.
9395
+
9396
+ *Ensures:* `*this` has a target object of type `VT`
9397
+ direct-non-list-initialized with `ilist, std::forward<Args>(args)...`.
9398
+
9399
+ *Throws:* Any exception thrown by the initialization of the target
9400
+ object. May throw `bad_alloc` unless `VT` is a function pointer or a
9401
+ specialization of `reference_wrapper`.
9402
+
9403
+ ``` cpp
9404
+ move_only_function& operator=(move_only_function&& f);
9405
+ ```
9406
+
9407
+ *Effects:* Equivalent to:
9408
+ `move_only_function(std::move(f)).swap(*this);`
9409
+
9410
+ *Returns:* `*this`.
9411
+
9412
+ ``` cpp
9413
+ move_only_function& operator=(nullptr_t) noexcept;
9414
+ ```
9415
+
9416
+ *Effects:* Destroys the target object of `*this`, if any.
9417
+
9418
+ *Returns:* `*this`.
9419
+
9420
+ ``` cpp
9421
+ template<class F> move_only_function& operator=(F&& f);
9422
+ ```
9423
+
9424
+ *Effects:* Equivalent to:
9425
+ `move_only_function(std::forward<F>(f)).swap(*this);`
9426
+
9427
+ *Returns:* `*this`.
9428
+
9429
+ ``` cpp
9430
+ ~move_only_function();
9431
+ ```
9432
+
9433
+ *Effects:* Destroys the target object of `*this`, if any.
9434
+
9435
+ ##### Invocation <a id="func.wrap.move.inv">[[func.wrap.move.inv]]</a>
9436
+
9437
+ ``` cpp
9438
+ explicit operator bool() const noexcept;
9439
+ ```
9440
+
9441
+ *Returns:* `true` if `*this` has a target object, otherwise `false`.
9442
+
9443
+ ``` cpp
9444
+ R operator()(ArgTypes... args) cv ref noexcept(noex);
9445
+ ```
9446
+
9447
+ *Preconditions:* `*this` has a target object.
9448
+
9449
+ *Effects:* Equivalent to:
9450
+
9451
+ ``` cpp
9452
+ return INVOKE<R>(static_cast<F inv-quals>(f), std::forward<ArgTypes>(args)...);
9453
+ ```
9454
+
9455
+ where `f` is an lvalue designating the target object of `*this` and `F`
9456
+ is the type of `f`.
9457
+
9458
+ ##### Utility <a id="func.wrap.move.util">[[func.wrap.move.util]]</a>
9459
+
9460
+ ``` cpp
9461
+ void swap(move_only_function& other) noexcept;
9462
+ ```
9463
+
9464
+ *Effects:* Exchanges the target objects of `*this` and `other`.
9465
+
9466
+ ``` cpp
9467
+ friend void swap(move_only_function& f1, move_only_function& f2) noexcept;
9468
+ ```
9469
+
9470
+ *Effects:* Equivalent to `f1.swap(f2)`.
9471
+
9472
+ ``` cpp
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
9483
+ [[function.objects]] for operations that search for a sequence
9484
+ \[`pat``first`, `pat_last`) in another sequence \[`first`, `last`) that
9485
+ is provided to the object’s function call operator. The first sequence
9486
+ (the pattern to be searched for) is provided to the object’s
9487
+ constructor, and the second (the sequence to be searched) is provided to
9488
+ the function call operator.
9489
+
9490
+ Each specialization of a class template specified in [[func.search]]
9491
+ shall meet the *Cpp17CopyConstructible* and *Cpp17CopyAssignable*
9492
+ requirements. Template parameters named
9493
 
9494
  - `ForwardIterator`,
9495
  - `ForwardIterator1`,
9496
  - `ForwardIterator2`,
9497
  - `RandomAccessIterator`,
9498
  - `RandomAccessIterator1`,
9499
  - `RandomAccessIterator2`, and
9500
  - `BinaryPredicate`
9501
 
9502
+ of templates specified in [[func.search]] shall meet the same
9503
+ requirements and semantics as specified in [[algorithms.general]].
9504
  Template parameters named `Hash` shall meet the *Cpp17Hash* requirements
9505
  ([[cpp17.hash]]).
9506
 
9507
  The Boyer-Moore searcher implements the Boyer-Moore search algorithm.
9508
  The Boyer-Moore-Horspool searcher implements the Boyer-Moore-Horspool
 
9510
  memory and give better runtime performance than Boyer-Moore-Horspool.
9511
 
9512
  #### Class template `default_searcher` <a id="func.search.default">[[func.search.default]]</a>
9513
 
9514
  ``` cpp
9515
+ namespace std {
9516
  template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
9517
  class default_searcher {
9518
  public:
9519
  constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
9520
  BinaryPredicate pred = BinaryPredicate());
 
9526
  private:
9527
  ForwardIterator1 pat_first_; // exposition only
9528
  ForwardIterator1 pat_last_; // exposition only
9529
  BinaryPredicate pred_; // exposition only
9530
  };
9531
+ }
9532
  ```
9533
 
9534
  ``` cpp
9535
+ constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
9536
  BinaryPredicate pred = BinaryPredicate());
9537
  ```
9538
 
9539
  *Effects:* Constructs a `default_searcher` object, initializing
9540
  `pat_first_` with `pat_first`, \texttt{pat_last\_} with `pat_last`, and
 
9556
  `j == next(i, distance(pat_first_, pat_last_))`.
9557
 
9558
  #### Class template `boyer_moore_searcher` <a id="func.search.bm">[[func.search.bm]]</a>
9559
 
9560
  ``` cpp
9561
+ namespace std {
9562
  template<class RandomAccessIterator1,
9563
  class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
9564
  class BinaryPredicate = equal_to<>>
9565
  class boyer_moore_searcher {
9566
  public:
 
9577
  RandomAccessIterator1 pat_first_; // exposition only
9578
  RandomAccessIterator1 pat_last_; // exposition only
9579
  Hash hash_; // exposition only
9580
  BinaryPredicate pred_; // exposition only
9581
  };
9582
+ }
9583
  ```
9584
 
9585
  ``` cpp
9586
  boyer_moore_searcher(RandomAccessIterator1 pat_first,
9587
  RandomAccessIterator1 pat_last,
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`.
 
9599
 
9600
  *Effects:* Initializes `pat_first_` with `pat_first`, `pat_last_` with
9601
+ `pat_last`, `hash_` with `hf`, and \texttt{pred\_} with `pred`.
9602
 
9603
  *Throws:* Any exception thrown by the copy constructor of
9604
  `RandomAccessIterator1`, or by the default constructor, copy
9605
  constructor, or the copy assignment operator of the value type of
9606
  `RandomAccessIterator1`, or the copy constructor or `operator()` of
 
9634
  applications of the predicate.
9635
 
9636
  #### Class template `boyer_moore_horspool_searcher` <a id="func.search.bmh">[[func.search.bmh]]</a>
9637
 
9638
  ``` cpp
9639
+ namespace std {
9640
  template<class RandomAccessIterator1,
9641
  class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
9642
  class BinaryPredicate = equal_to<>>
9643
  class boyer_moore_horspool_searcher {
9644
  public:
 
9655
  RandomAccessIterator1 pat_first_; // exposition only
9656
  RandomAccessIterator1 pat_last_; // exposition only
9657
  Hash hash_; // exposition only
9658
  BinaryPredicate pred_; // exposition only
9659
  };
9660
+ }
9661
  ```
9662
 
9663
  ``` cpp
9664
  boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first,
9665
  RandomAccessIterator1 pat_last,
 
9669
 
9670
  *Preconditions:* The value type of `RandomAccessIterator1` meets the
9671
  *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*, and
9672
  *Cpp17CopyAssignable* requirements.
9673
 
9674
+ Let `V` be `iterator_traits<RandomAccessIterator1>::value_type`. For any
9675
+ two values `A` and `B` of type `V`, if `pred(A, B) == true`, then
9676
+ `hf(A) == hf(B)` is `true`.
 
9677
 
9678
  *Effects:* Initializes `pat_first_` with `pat_first`, `pat_last_` with
9679
+ `pat_last`, `hash_` with `hf`, and \texttt{pred\_} with `pred`.
9680
 
9681
  *Throws:* Any exception thrown by the copy constructor of
9682
  `RandomAccessIterator1`, or by the default constructor, copy
9683
  constructor, or the copy assignment operator of the value type of
9684
+ `RandomAccessIterator1`, or the copy constructor or `operator()` of
9685
  `BinaryPredicate` or `Hash`. May throw `bad_alloc` if additional memory
9686
  needed for internal data structures cannot be allocated.
9687
 
9688
  ``` cpp
9689
  template<class RandomAccessIterator2>
 
9696
 
9697
  *Effects:* Finds a subsequence of equal values in a sequence.
9698
 
9699
  *Returns:* A pair of iterators `i` and `j` such that
9700
 
9701
+ - `i` is the first iterator in the range \[`first`,
9702
  `last - (pat_last_ - pat_first_)`) such that for every non-negative
9703
  integer `n` less than `pat_last_ - pat_first_` the following condition
9704
  holds: `pred(*(i + n), *(pat_first_ + n)) != false`, and
9705
  - `j == next(i, distance(pat_first_, pat_last_))`.
9706
 
 
9745
  An enabled specialization `hash<Key>` will:
9746
 
9747
  - meet the *Cpp17Hash* requirements ([[cpp17.hash]]), with `Key` as the
9748
  function call argument type, the *Cpp17DefaultConstructible*
9749
  requirements ([[cpp17.defaultconstructible]]), the
9750
+ *Cpp17CopyAssignable* requirements ([[cpp17.copyassignable]]), the
9751
+ *Cpp17Swappable* requirements [[swappable.requirements]],
9752
  - meet the requirement that if `k1 == k2` is `true`, `h(k1) == h(k2)` is
9753
  also `true`, where `h` is an object of type `hash<Key>` and `k1` and
9754
  `k2` are objects of type `Key`;
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
 
 
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;
 
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 };
 
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 };
 
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 };
 
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 };
 
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
 
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
 
 
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
 
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
 
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
 
 
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`.
 
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
 
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`.
 
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
  ```
 
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
 
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
 
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
 
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
 
 
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
 
 
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]].
 
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 |
 
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);
 
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`,
 
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.
 
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
 
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
  ```
 
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>`,
 
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 {};
 
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>
 
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 {
 
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
  };
 
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
 
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; };
 
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");
 
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
 
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;
 
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
 
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;
 
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
 
 
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
 
 
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 {
 
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
12406
+ both individual bits and bit sequences.
12407
+
12408
+ ### Header `<bit>` synopsis <a id="bit.syn">[[bit.syn]]</a>
12409
+
12410
+ ``` cpp
12411
+ // all freestanding
12412
+ namespace std {
12413
+ // [bit.cast], bit_cast
12414
+ template<class To, class From>
12415
+ constexpr To bit_cast(const From& from) noexcept;
12416
+
12417
+ // [bit.byteswap], byteswap
12418
+ template<class T>
12419
+ constexpr T byteswap(T value) noexcept;
12420
+
12421
+ // [bit.pow.two], integral powers of 2
12422
+ template<class T>
12423
+ constexpr bool has_single_bit(T x) noexcept;
12424
+ template<class T>
12425
+ constexpr T bit_ceil(T x);
12426
+ template<class T>
12427
+ constexpr T bit_floor(T x) noexcept;
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>
12441
+ constexpr int countl_one(T x) noexcept;
12442
+ template<class T>
12443
+ constexpr int countr_zero(T x) noexcept;
12444
+ template<class T>
12445
+ constexpr int countr_one(T x) noexcept;
12446
+ template<class T>
12447
+ constexpr int popcount(T x) noexcept;
12448
+
12449
+ // [bit.endian], endian
12450
+ enum class endian {
12451
+ little = see below,
12452
+ big = see below,
12453
+ native = see below
12454
+ };
12455
+ }
12456
+ ```
12457
+
12458
+ ### Function template `bit_cast` <a id="bit.cast">[[bit.cast]]</a>
12459
+
12460
+ ``` cpp
12461
+ template<class To, class From>
12462
+ constexpr To bit_cast(const From& from) noexcept;
12463
+ ```
12464
+
12465
+ *Constraints:*
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>
12501
+ constexpr T byteswap(T value) noexcept;
12502
+ ```
12503
+
12504
+ *Constraints:* `T` models `integral`.
12505
+
12506
+ *Mandates:* `T` does not have padding bits [[basic.types.general]].
12507
+
12508
+ Let the sequence R comprise the bytes of the object representation of
12509
+ `value` in reverse order.
12510
+
12511
+ *Returns:* An object `v` of type `T` such that each byte in the object
12512
+ representation of `v` is equal to the byte in the corresponding position
12513
+ in R.
12514
+
12515
+ ### Integral powers of 2 <a id="bit.pow.two">[[bit.pow.two]]</a>
12516
+
12517
+ ``` cpp
12518
+ template<class T>
12519
+ constexpr bool has_single_bit(T x) noexcept;
12520
+ ```
12521
+
12522
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12523
+
12524
+ *Returns:* `true` if `x` is an integral power of two; `false` otherwise.
12525
+
12526
+ ``` cpp
12527
+ template<class T>
12528
+ constexpr T bit_ceil(T x);
12529
+ ```
12530
+
12531
+ Let N be the smallest power of 2 greater than or equal to `x`.
12532
+
12533
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12534
+
12535
+ *Preconditions:* N is representable as a value of type `T`.
12536
+
12537
+ *Returns:* N.
12538
+
12539
+ *Throws:* Nothing.
12540
+
12541
+ *Remarks:* A function call expression that violates the precondition in
12542
+ the *Preconditions:* element is not a core constant
12543
+ expression [[expr.const]].
12544
+
12545
+ ``` cpp
12546
+ template<class T>
12547
+ constexpr T bit_floor(T x) noexcept;
12548
+ ```
12549
+
12550
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12551
+
12552
+ *Returns:* If `x == 0`, `0`; otherwise the maximal value `y` such that
12553
+ `has_single_bit(y)` is `true` and `y <= x`.
12554
+
12555
+ ``` cpp
12556
+ template<class T>
12557
+ constexpr int bit_width(T x) noexcept;
12558
+ ```
12559
+
12560
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12561
+
12562
+ *Returns:* If `x == 0`, `0`; otherwise one plus the base-2 logarithm of
12563
+ `x`, with any fractional part discarded.
12564
+
12565
+ ### Rotating <a id="bit.rotate">[[bit.rotate]]</a>
12566
+
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`.
12578
+
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`.
12590
+
12591
+ *Returns:* If `r` is `0`, `x`; if `r` is positive,
12592
+ `(x >> r) | (x << (N - r))`; if `r` is negative, `rotl(x, -r)`.
12593
+
12594
+ ### Counting <a id="bit.count">[[bit.count]]</a>
12595
+
12596
+ In the following descriptions, let `N` denote
12597
+ `numeric_limits<T>::digits`.
12598
+
12599
+ ``` cpp
12600
+ template<class T>
12601
+ constexpr int countl_zero(T x) noexcept;
12602
+ ```
12603
+
12604
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12605
+
12606
+ *Returns:* The number of consecutive `0` bits in the value of `x`,
12607
+ starting from the most significant bit.
12608
+
12609
+ [*Note 1*: Returns `N` if `x == 0`. — *end note*]
12610
+
12611
+ ``` cpp
12612
+ template<class T>
12613
+ constexpr int countl_one(T x) noexcept;
12614
+ ```
12615
+
12616
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12617
+
12618
+ *Returns:* The number of consecutive `1` bits in the value of `x`,
12619
+ starting from the most significant bit.
12620
+
12621
+ [*Note 2*: Returns `N` if
12622
+ `x == numeric_limits<T>::max()`. — *end note*]
12623
+
12624
+ ``` cpp
12625
+ template<class T>
12626
+ constexpr int countr_zero(T x) noexcept;
12627
+ ```
12628
+
12629
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12630
+
12631
+ *Returns:* The number of consecutive `0` bits in the value of `x`,
12632
+ starting from the least significant bit.
12633
+
12634
+ [*Note 3*: Returns `N` if `x == 0`. — *end note*]
12635
+
12636
+ ``` cpp
12637
+ template<class T>
12638
+ constexpr int countr_one(T x) noexcept;
12639
+ ```
12640
+
12641
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12642
+
12643
+ *Returns:* The number of consecutive `1` bits in the value of `x`,
12644
+ starting from the least significant bit.
12645
+
12646
+ [*Note 4*: Returns `N` if
12647
+ `x == numeric_limits<T>::max()`. — *end note*]
12648
+
12649
+ ``` cpp
12650
+ template<class T>
12651
+ constexpr int popcount(T x) noexcept;
12652
+ ```
12653
+
12654
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
12655
+
12656
+ *Returns:* The number of `1` bits in the value of `x`.
12657
+
12658
+ ### Endian <a id="bit.endian">[[bit.endian]]</a>
12659
+
12660
+ Two common methods of byte ordering in multibyte scalar types are
12661
+ big-endian and little-endian in the execution environment. Big-endian is
12662
+ a format for storage of binary data in which the most significant byte
12663
+ is placed first, with the rest in descending order. Little-endian is a
12664
+ format for storage of binary data in which the least significant byte is
12665
+ placed first, with the rest in ascending order. This subclause describes
12666
+ the endianness of the scalar types of the execution environment.
12667
+
12668
+ ``` cpp
12669
+ enum class endian {
12670
+ little = see below,
12671
+ big = see below,
12672
+ native = see below
12673
+ };
12674
+ ```
12675
+
12676
+ If all scalar types have size 1 byte, then all of `endian::little`,
12677
+ `endian::big`, and `endian::native` have the same value. Otherwise,
12678
+ `endian::little` is not equal to `endian::big`. If all scalar types are
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
12693
  [any.class]: #any.class
12694
+ [any.class.general]: #any.class.general
12695
  [any.cons]: #any.cons
12696
+ [any.general]: #any.general
12697
  [any.modifiers]: #any.modifiers
12698
  [any.nonmembers]: #any.nonmembers
12699
  [any.observers]: #any.observers
12700
  [any.synop]: #any.synop
12701
  [arithmetic.operations]: #arithmetic.operations
12702
  [arithmetic.operations.divides]: #arithmetic.operations.divides
12703
+ [arithmetic.operations.general]: #arithmetic.operations.general
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
12715
+ [bit.byteswap]: #bit.byteswap
12716
+ [bit.cast]: #bit.cast
12717
+ [bit.count]: #bit.count
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
12729
  [bitset.syn]: #bitset.syn
12730
  [bitwise.operations]: #bitwise.operations
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
12745
  [comparisons.greater]: #comparisons.greater
12746
  [comparisons.greater.equal]: #comparisons.greater.equal
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
12781
+ [expected.object.assign]: #expected.object.assign
12782
+ [expected.object.cons]: #expected.object.cons
12783
+ [expected.object.dtor]: #expected.object.dtor
12784
+ [expected.object.eq]: #expected.object.eq
12785
+ [expected.object.general]: #expected.object.general
12786
+ [expected.object.monadic]: #expected.object.monadic
12787
+ [expected.object.obs]: #expected.object.obs
12788
+ [expected.object.swap]: #expected.object.swap
12789
+ [expected.syn]: #expected.syn
12790
+ [expected.un.cons]: #expected.un.cons
12791
+ [expected.un.eq]: #expected.un.eq
12792
+ [expected.un.general]: #expected.un.general
12793
+ [expected.un.obs]: #expected.un.obs
12794
+ [expected.un.swap]: #expected.un.swap
12795
+ [expected.unexpected]: #expected.unexpected
12796
+ [expected.void]: #expected.void
12797
+ [expected.void.assign]: #expected.void.assign
12798
+ [expected.void.cons]: #expected.void.cons
12799
+ [expected.void.dtor]: #expected.void.dtor
12800
+ [expected.void.eq]: #expected.void.eq
12801
+ [expected.void.general]: #expected.void.general
12802
+ [expected.void.monadic]: #expected.void.monadic
12803
+ [expected.void.obs]: #expected.void.obs
12804
+ [expected.void.swap]: #expected.void.swap
12805
  [expr.add]: expr.md#expr.add
 
12806
  [expr.bit.and]: expr.md#expr.bit.and
12807
  [expr.call]: expr.md#expr.call
12808
  [expr.const]: expr.md#expr.const
12809
  [expr.eq]: expr.md#expr.eq
12810
  [expr.log.and]: expr.md#expr.log.and
12811
  [expr.log.or]: expr.md#expr.log.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
 
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
12863
  [func.bind.isbind]: #func.bind.isbind
12864
  [func.bind.isplace]: #func.bind.isplace
12865
+ [func.bind.partial]: #func.bind.partial
12866
  [func.bind.place]: #func.bind.place
12867
  [func.def]: #func.def
12868
  [func.identity]: #func.identity
12869
  [func.invoke]: #func.invoke
12870
  [func.memfn]: #func.memfn
 
12872
  [func.require]: #func.require
12873
  [func.search]: #func.search
12874
  [func.search.bm]: #func.search.bm
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
12885
  [func.wrap.func.inv]: #func.wrap.func.inv
12886
  [func.wrap.func.mod]: #func.wrap.func.mod
12887
  [func.wrap.func.nullptr]: #func.wrap.func.nullptr
12888
  [func.wrap.func.targ]: #func.wrap.func.targ
12889
+ [func.wrap.general]: #func.wrap.general
12890
+ [func.wrap.move]: #func.wrap.move
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
 
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
12937
  [out.of.range]: diagnostics.md#out.of.range
12938
  [over.match.call]: over.md#over.match.call
 
12939
  [overflow.error]: diagnostics.md#overflow.error
12940
  [pair.astuple]: #pair.astuple
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
12977
  [tuple.creation]: #tuple.creation
12978
  [tuple.elem]: #tuple.elem
12979
  [tuple.general]: #tuple.general
12980
  [tuple.helper]: #tuple.helper
12981
+ [tuple.like]: #tuple.like
12982
  [tuple.rel]: #tuple.rel
12983
  [tuple.special]: #tuple.special
12984
  [tuple.swap]: #tuple.swap
12985
  [tuple.syn]: #tuple.syn
12986
  [tuple.traits]: #tuple.traits
 
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
12998
  [utility]: #utility
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
 
13019
  [variant.specalg]: #variant.specalg
13020
  [variant.status]: #variant.status
13021
  [variant.swap]: #variant.swap
13022
  [variant.syn]: #variant.syn
13023
  [variant.variant]: #variant.variant
13024
+ [variant.variant.general]: #variant.variant.general
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.