[variant.variant] - C++14 → C++17

Files changed (1) hide show

tmp/tmpxhgikxcc/{from.md → to.md} +572 -0

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

	@@ -0,0 +1,572 @@

+### Class template `variant` <a id="variant.variant">[[variant.variant]]</a>
+``` cpp
+namespace std {
+  template <class... Types>
+    class variant {
+    public:
+      // [variant.ctor], constructors
+      constexpr variant() noexcept(see below);
+      variant(const variant&);
+      variant(variant&&) noexcept(see below);
+      template <class T>
+        constexpr variant(T&&) noexcept(see below);
+      template <class T, class... Args>
+        constexpr explicit variant(in_place_type_t<T>, Args&&...);
+      template <class T, class U, class... Args>
+        constexpr explicit variant(in_place_type_t<T>, initializer_list<U>, Args&&...);
+      template <size_t I, class... Args>
+        constexpr explicit variant(in_place_index_t<I>, Args&&...);
+      template <size_t I, class U, class... Args>
+        constexpr explicit variant(in_place_index_t<I>, initializer_list<U>, Args&&...);
+      // allocator-extended constructors
+      template <class Alloc>
+        variant(allocator_arg_t, const Alloc&);
+      template <class Alloc>
+        variant(allocator_arg_t, const Alloc&, const variant&);
+      template <class Alloc>
+        variant(allocator_arg_t, const Alloc&, variant&&);
+      template <class Alloc, class T>
+        variant(allocator_arg_t, const Alloc&, T&&);
+      template <class Alloc, class T, class... Args>
+        variant(allocator_arg_t, const Alloc&, in_place_type_t<T>, Args&&...);
+      template <class Alloc, class T, class U, class... Args>
+        variant(allocator_arg_t, const Alloc&, in_place_type_t<T>,
+                initializer_list<U>, Args&&...);
+      template <class Alloc, size_t I, class... Args>
+        variant(allocator_arg_t, const Alloc&, in_place_index_t<I>, Args&&...);
+      template <class Alloc, size_t I, class U, class... Args>
+        variant(allocator_arg_t, const Alloc&, in_place_index_t<I>,
+                initializer_list<U>, Args&&...);
+      // [variant.dtor], destructor
+      ~variant();
+      // [variant.assign], assignment
+      variant& operator=(const variant&);
+      variant& operator=(variant&&) noexcept(see below);
+      template <class T> variant& operator=(T&&) noexcept(see below);
+      // [variant.mod], modifiers
+      template <class T, class... Args>
+        T& emplace(Args&&...);
+      template <class T, class U, class... Args>
+        T& emplace(initializer_list<U>, Args&&...);
+      template <size_t I, class... Args>
+        variant_alternative_t<I, variant<Types...>>& emplace(Args&&...);
+      template <size_t I, class U, class... Args>
+        variant_alternative_t<I, variant<Types...>>& emplace(initializer_list<U>, Args&&...);
+      // [variant.status], value status
+      constexpr bool valueless_by_exception() const noexcept;
+      constexpr size_t index() const noexcept;
+      // [variant.swap], swap
+      void swap(variant&) noexcept(see below);
+    };
+}
+```
+Any instance of `variant` at any given time either holds a value of one
+of its alternative types, or it holds no value. When an instance of
+`variant` holds a value of alternative type `T`, it means that a value
+of type `T`, referred to as the `variant` object’s *contained value*, is
+allocated within the storage of the `variant` object. Implementations
+are not permitted to use additional storage, such as dynamic memory, to
+allocate the contained value. The contained value shall be allocated in
+a region of the `variant` storage suitably aligned for all types in
+`Types...`. It is *implementation-defined* whether over-aligned types
+are supported.
+All types in `Types...` shall be (possibly cv-qualified) object types
+that are not arrays.
+A program that instantiates the definition of `variant` with no template
+arguments is ill-formed.
+#### Constructors <a id="variant.ctor">[[variant.ctor]]</a>
+In the descriptions that follow, let i be in the range \[`0`,
+`sizeof...(Types)`), and `Tᵢ` be the iᵗʰ type in `Types...`.
+``` cpp
+constexpr variant() noexcept(see below);
+```
+*Effects:* Constructs a `variant` holding a value-initialized value of
+type `T₀`.
+*Postconditions:* `valueless_by_exception()` is `false` and `index()` is
+`0`.
+*Throws:* Any exception thrown by the value-initialization of `T₀`.
+*Remarks:* This function shall be `constexpr` if and only if the
+value-initialization of the alternative type `T₀` would satisfy the
+requirements for a constexpr function. The expression inside `noexcept`
+is equivalent to `is_nothrow_default_constructible_v<``T₀``>`. This
+function shall not participate in overload resolution unless
+`is_default_constructible_v<``T₀``>` is `true`.
+[*Note 1*: See also class `monostate`. — *end note*]
+``` cpp
+variant(const variant& w);
+```
+*Effects:* If `w` holds a value, initializes the `variant` to hold the
+same alternative as `w` and direct-initializes the contained value with
+`get<j>(w)`, where `j` is `w.index()`. Otherwise, initializes the
+`variant` to not hold a value.
+*Throws:* Any exception thrown by direct-initializing any `Tᵢ` for all
+i.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_copy_constructible_v<``Tᵢ``>` is `true` for all i.
+``` cpp
+variant(variant&& w) noexcept(see below);
+```
+*Effects:* If `w` holds a value, initializes the `variant` to hold the
+same alternative as `w` and direct-initializes the contained value with
+`get<j>(std::move(w))`, where `j` is `w.index()`. Otherwise, initializes
+the `variant` to not hold a value.
+*Throws:* Any exception thrown by move-constructing any `Tᵢ` for all i.
+*Remarks:* The expression inside `noexcept` is equivalent to the logical
+AND of `is_nothrow_move_constructible_v<``Tᵢ``>` for all i. This
+function shall not participate in overload resolution unless
+`is_move_constructible_v<``Tᵢ``>` is `true` for all i.
+``` cpp
+template <class T> constexpr variant(T&& t) noexcept(see below);
+```
+Let `Tⱼ` be a type that is determined as follows: build an imaginary
+function *FUN*(Tᵢ) for each alternative type `Tᵢ`. The overload
+*FUN*(Tⱼ) selected by overload resolution for the expression
+*FUN*(std::forward\<T\>(t)) defines the alternative `Tⱼ` which is the
+type of the contained value after construction.
+*Effects:* Initializes `*this` to hold the alternative type `Tⱼ` and
+direct-initializes the contained value as if
+direct-non-list-initializing it with `std::forward<T>(t)`.
+*Postconditions:* `holds_alternative<``Tⱼ``>(*this)` is `true`.
+*Throws:* Any exception thrown by the initialization of the selected
+alternative `Tⱼ`.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_same_v<decay_t<T>, variant>` is `false`, unless `decay_t<T>`
+is neither a specialization of `in_place_type_t` nor a specialization of
+`in_place_index_t`, unless `is_constructible_v<``Tⱼ``, T>` is `true`,
+and unless the expression *FUN*(`std::forward<T>(t))` (with *FUN* being
+the above-mentioned set of imaginary functions) is well formed.
+[*Note 2*:
+``` cpp
+variant<string, string> v("abc");
+```
+is ill-formed, as both alternative types have an equally viable
+constructor for the argument.
+— *end note*]
+The expression inside `noexcept` is equivalent to
+`is_nothrow_constructible_v<``Tⱼ``, T>`. If `Tⱼ`’s selected constructor
+is a constexpr constructor, this constructor shall be a constexpr
+constructor.
+``` cpp
+template <class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&... args);
+```
+*Effects:* Initializes the contained value as if
+direct-non-list-initializing an object of type `T` with the arguments
+`std::forward<Args>(args)...`.
+*Postconditions:* `holds_alternative<T>(*this)` is `true`.
+*Throws:* Any exception thrown by calling the selected constructor of
+`T`.
+*Remarks:* This function shall not participate in overload resolution
+unless there is exactly one occurrence of `T` in `Types...` and
+`is_constructible_v<T, Args...>` is `true`. If `T`’s selected
+constructor is a constexpr constructor, this constructor shall be a
+constexpr constructor.
+``` cpp
+template <class T, class U, class... Args>
+  constexpr explicit variant(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
+```
+*Effects:* Initializes the contained value as if
+direct-non-list-initializing an object of type `T` with the arguments
+`il, std::forward<Args>(args)...`.
+*Postconditions:* `holds_alternative<T>(*this)` is `true`.
+*Throws:* Any exception thrown by calling the selected constructor of
+`T`.
+*Remarks:* This function shall not participate in overload resolution
+unless there is exactly one occurrence of `T` in `Types...` and
+`is_constructible_v<T, initializer_list<U>&, Args...>` is `true`. If
+`T`’s selected constructor is a constexpr constructor, this constructor
+shall be a constexpr constructor.
+``` cpp
+template <size_t I, class... Args> constexpr explicit variant(in_place_index_t<I>, Args&&... args);
+```
+*Effects:* Initializes the contained value as if
+direct-non-list-initializing an object of type `T_I` with the arguments
+`std::forward<Args>(args)...`.
+*Postconditions:* `index()` is `I`.
+*Throws:* Any exception thrown by calling the selected constructor of
+`T_I`.
+*Remarks:* This function shall not participate in overload resolution
+unless
+- `I` is less than `sizeof...(Types)` and
+- `is_constructible_v<``T_I``, Args...>` is `true`.
+If `T_I`’s selected constructor is a constexpr constructor, this
+constructor shall be a constexpr constructor.
+``` cpp
+template <size_t I, class U, class... Args>
+  constexpr explicit variant(in_place_index_t<I>, initializer_list<U> il, Args&&... args);
+```
+*Effects:* Initializes the contained value as if
+direct-non-list-initializing an object of type `T_I` with the arguments
+`il, std::forward<Args>(args)...`.
+*Postconditions:* `index()` is `I`.
+*Remarks:* This function shall not participate in overload resolution
+unless
+- `I` is less than `sizeof...(Types)` and
+- `is_constructible_v<``T_I``, initializer_list<U>&, Args...>` is
+  `true`.
+If `T_I`’s selected constructor is a constexpr constructor, this
+constructor shall be a constexpr constructor.
+``` cpp
+// allocator-extended constructors
+template <class Alloc>
+  variant(allocator_arg_t, const Alloc& a);
+template <class Alloc>
+  variant(allocator_arg_t, const Alloc& a, const variant& v);
+template <class Alloc>
+  variant(allocator_arg_t, const Alloc& a, variant&& v);
+template <class Alloc, class T>
+  variant(allocator_arg_t, const Alloc& a, T&& t);
+template <class Alloc, class T, class... Args>
+  variant(allocator_arg_t, const Alloc& a, in_place_type_t<T>, Args&&... args);
+template <class Alloc, class T, class U, class... Args>
+  variant(allocator_arg_t, const Alloc& a, in_place_type_t<T>,
+          initializer_list<U> il, Args&&... args);
+template <class Alloc, size_t I, class... Args>
+  variant(allocator_arg_t, const Alloc& a, in_place_index_t<I>, Args&&... args);
+template <class Alloc, size_t I, class U, class... Args>
+  variant(allocator_arg_t, const Alloc& a, in_place_index_t<I>,
+          initializer_list<U> il, Args&&... args);
+```
+*Requires:* `Alloc` shall meet the requirements for an
+Allocator ([[allocator.requirements]]).
+*Effects:* Equivalent to the preceding constructors except that the
+contained value is constructed with uses-allocator
+construction ([[allocator.uses.construction]]).
+#### Destructor <a id="variant.dtor">[[variant.dtor]]</a>
+``` cpp
+~variant();
+```
+*Effects:* If `valueless_by_exception()` is `false`, destroys the
+currently contained value.
+*Remarks:* If `is_trivially_destructible_v<``Tᵢ``> == true` for all `Tᵢ`
+then this destructor shall be a trivial destructor.
+#### Assignment <a id="variant.assign">[[variant.assign]]</a>
+``` cpp
+variant& operator=(const variant& rhs);
+```
+Let j be `rhs.index()`.
+*Effects:*
+- If neither `*this` nor `rhs` holds a value, there is no effect.
+  Otherwise,
+- if `*this` holds a value but `rhs` does not, destroys the value
+  contained in `*this` and sets `*this` to not hold a value. Otherwise,
+- if `index() == `j, assigns the value contained in `rhs` to the value
+  contained in `*this`. Otherwise,
+- if either `is_nothrow_copy_constructible_v<``Tⱼ``>` or
+  `!is_nothrow_move_constructible_v<``Tⱼ``>` is `true`, equivalent to
+  `emplace<`j`>(get<`j`>(rhs))`. Otherwise,
+- equivalent to `operator=(variant(rhs))`.
+*Returns:* `*this`.
+*Postconditions:* `index() == rhs.index()`.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_copy_constructible_v<``Tᵢ``> &&`
+`is_copy_assignable_v<``Tᵢ``>` is `true` for all i.
+``` cpp
+variant& operator=(variant&& rhs) noexcept(see below);
+```
+Let j be `rhs.index()`.
+*Effects:*
+- If neither `*this` nor `rhs` holds a value, there is no effect.
+  Otherwise,
+- if `*this` holds a value but `rhs` does not, destroys the value
+  contained in `*this` and sets `*this` to not hold a value. Otherwise,
+- if `index() == `j, assigns `get<`j`>(std::move(rhs))` to the value
+  contained in `*this`. Otherwise,
+- equivalent to `emplace<`j`>(get<`j`>(std::move(rhs)))`.
+*Returns:* `*this`.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_move_constructible_v<``Tᵢ``> && is_move_assignable_v<``Tᵢ``>`
+is `true` for all i. The expression inside `noexcept` is equivalent to:
+`is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_move_assignable_v<``Tᵢ``>`
+for all i.
+- If an exception is thrown during the call to `Tⱼ`’s move construction
+  (with j being `rhs.index())`, the `variant` will hold no value.
+- If an exception is thrown during the call to `Tⱼ`’s move assignment,
+  the state of the contained value is as defined by the exception safety
+  guarantee of `Tⱼ`’s move assignment; `index()` will be j.
+``` cpp
+template <class T> variant& operator=(T&& t) noexcept(see below);
+```
+Let `Tⱼ` be a type that is determined as follows: build an imaginary
+function *FUN*(Tᵢ) for each alternative type `Tᵢ`. The overload
+*FUN*(Tⱼ) selected by overload resolution for the expression
+*FUN*(std::forward\<T\>(t)) defines the alternative `Tⱼ` which is the
+type of the contained value after assignment.
+*Effects:*
+- If `*this` holds a `Tⱼ`, assigns `std::forward<T>(t)` to the value
+  contained in `*this`. Otherwise,
+- if `is_nothrow_constructible_v<``Tⱼ``, T> ||`
+  `!is_nothrow_move_constructible_v<``Tⱼ``>` is `true`, equivalent to
+  `emplace<`j`>(std::forward<T>(t))`. Otherwise,
+- equivalent to `operator=(variant(std::forward<T>(t)))`.
+*Postconditions:* `holds_alternative<``Tⱼ``>(*this)` is `true`, with
+`Tⱼ` selected by the imaginary function overload resolution described
+above.
+*Returns:* `*this`.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_same_v<decay_t<T>, variant>` is `false`, unless
+`is_assignable_v<``Tⱼ``&, T> && is_constructible_v<``Tⱼ``, T>` is
+`true`, and unless the expression *FUN*(std::forward\<T\>(t)) (with
+*FUN* being the above-mentioned set of imaginary functions) is well
+formed.
+[*Note 1*:
+``` cpp
+variant<string, string> v;
+v = "abc";
+```
+is ill-formed, as both alternative types have an equally viable
+constructor for the argument.
+— *end note*]
+The expression inside `noexcept` is equivalent to:
+``` cpp
+is_nothrow_assignable_v<Tⱼ&, T> && is_nothrow_constructible_v<Tⱼ, T>
+```
+- If an exception is thrown during the assignment of
+  `std::forward<T>(t)` to the value contained in `*this`, the state of
+  the contained value and `t` are as defined by the exception safety
+  guarantee of the assignment expression; `valueless_by_exception()`
+  will be `false`.
+- If an exception is thrown during the initialization of the contained
+  value, the `variant` object might not hold a value.
+#### Modifiers <a id="variant.mod">[[variant.mod]]</a>
+``` cpp
+template <class T, class... Args> T& emplace(Args&&... args);
+```
+Let I be the zero-based index of `T` in `Types...`.
+*Effects:* Equivalent to:
+`return emplace<`I`>(std::forward<Args>(args)...);`
+*Remarks:* This function shall not participate in overload resolution
+unless `is_constructible_v<T, Args...>` is `true`, and `T` occurs
+exactly once in `Types...`.
+``` cpp
+template <class T, class U, class... Args> T& emplace(initializer_list<U> il, Args&&... args);
+```
+Let I be the zero-based index of `T` in `Types...`.
+*Effects:* Equivalent to:
+`return emplace<`I`>(il, std::forward<Args>(args)...);`
+*Remarks:* This function shall not participate in overload resolution
+unless `is_constructible_v<T, initializer_list<U>&, Args...>` is `true`,
+and `T` occurs exactly once in `Types...`.
+``` cpp
+template <size_t I, class... Args>
+  variant_alternative_t<I, variant<Types...>>& emplace(Args&&... args);
+```
+*Requires:* `I < sizeof...(Types)`.
+*Effects:* Destroys the currently contained value if
+`valueless_by_exception()` is `false`. Then initializes the contained
+value as if direct-non-list-initializing a value of type `T_I` with the
+arguments `std::forward<Args>(args)...`.
+*Postconditions:* `index()` is `I`.
+*Returns:* A reference to the new contained value.
+*Throws:* Any exception thrown during the initialization of the
+contained value.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_constructible_v<``T_I``, Args...>` is `true`. If an exception
+is thrown during the initialization of the contained value, the
+`variant` might not hold a value.
+``` cpp
+template <size_t I, class U, class... Args>
+  variant_alternative_t<I, variant<Types...>>& emplace(initializer_list<U> il, Args&&... args);
+```
+*Requires:* `I < sizeof...(Types)`.
+*Effects:* Destroys the currently contained value if
+`valueless_by_exception()` is `false`. Then initializes the contained
+value as if direct-non-list-initializing a value of type `T_I` with the
+arguments `il, std::forward<Args>(args)...`.
+*Postconditions:* `index()` is `I`.
+*Returns:* A reference to the new contained value.
+*Throws:* Any exception thrown during the initialization of the
+contained value.
+*Remarks:* This function shall not participate in overload resolution
+unless `is_constructible_v<``T_I``, initializer_list<U>&, Args...>` is
+`true`. If an exception is thrown during the initialization of the
+contained value, the `variant` might not hold a value.
+#### Value status <a id="variant.status">[[variant.status]]</a>
+``` cpp
+constexpr bool valueless_by_exception() const noexcept;
+```
+*Effects:* Returns `false` if and only if the `variant` holds a value.
+[*Note 1*:
+A `variant` might not hold a value if an exception is thrown during a
+type-changing assignment or emplacement. The latter means that even a
+`variant<float, int>` can become `valueless_by_exception()`, for
+instance by
+``` cpp
+struct S { operator int() { throw 42; }};
+variant<float, int> v{12.f};
+v.emplace<1>(S());
+```
+— *end note*]
+``` cpp
+constexpr size_t index() const noexcept;
+```
+*Effects:* If `valueless_by_exception()` is `true`, returns
+`variant_npos`. Otherwise, returns the zero-based index of the
+alternative of the contained value.
+#### Swap <a id="variant.swap">[[variant.swap]]</a>
+``` cpp
+void swap(variant& rhs) noexcept(see below);
+```
+*Requires:* Lvalues of type `Tᵢ` shall be
+swappable ([[swappable.requirements]]) and
+`is_move_constructible_v<``Tᵢ``>` shall be `true` for all i.
+*Effects:*
+- if `valueless_by_exception() && rhs.valueless_by_exception()` no
+  effect. Otherwise,
+- if `index() == rhs.index()`, calls
+  `swap(get<`i`>(*this), get<`i`>(rhs))` where i is `index()`.
+  Otherwise,
+- exchanges values of `rhs` and `*this`.
+*Throws:* If `index() == rhs.index()`, any exception thrown by
+`swap(get<`i`>(*this), get<`i`>(rhs))` with i being `index()`.
+Otherwise, any exception thrown by the move constructor of `Tᵢ` or `Tⱼ`
+with i being `index()` and j being `rhs.index()`.
+*Remarks:* If an exception is thrown during the call to function
+`swap(get<`i`>(*this), get<`i`>(rhs))`, the states of the contained
+values of `*this` and of `rhs` are determined by the exception safety
+guarantee of `swap` for lvalues of `Tᵢ` with i being `index()`. If an
+exception is thrown during the exchange of the values of `*this` and
+`rhs`, the states of the values of `*this` and of `rhs` are determined
+by the exception safety guarantee of `variant`’s move constructor. The
+expression inside `noexcept` is equivalent to the logical AND of
+`is_nothrow_move_constructible_v<``Tᵢ``> && is_nothrow_swappable_v<``Tᵢ``>`
+for all i.

Diff to HTML by rtfpessoa