From 16027c544784a7e19ce4dff93d2ae831361aaf0c Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Mon, 18 Feb 2019 19:51:23 +0200 Subject: [PATCH] Add to documentation --- doc/variant/copyright.adoc | 4 +- doc/variant/reference.adoc | 162 +++++++++++++++++++++++++++++++------ 2 files changed, 141 insertions(+), 25 deletions(-) diff --git a/doc/variant/copyright.adoc b/doc/variant/copyright.adoc index fd38de1..b048134 100644 --- a/doc/variant/copyright.adoc +++ b/doc/variant/copyright.adoc @@ -1,5 +1,5 @@ //// -Copyright 2018 Peter Dimov +Copyright 2018, 2019 Peter Dimov Distributed under the Boost Software License, Version 1.0. @@ -11,5 +11,5 @@ http://www.boost.org/LICENSE_1_0.txt # Copyright and License :idprefix: -This documentation is copyright 2018 Peter Dimov and is distributed under +This documentation is copyright 2018, 2019 Peter Dimov and is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0]. diff --git a/doc/variant/reference.adoc b/doc/variant/reference.adoc index 39617cd..8040a7b 100644 --- a/doc/variant/reference.adoc +++ b/doc/variant/reference.adoc @@ -1,5 +1,5 @@ //// -Copyright 2018 Peter Dimov +Copyright 2018, 2019 Peter Dimov Distributed under the Boost Software License, Version 1.0. @@ -177,13 +177,13 @@ public: template constexpr explicit variant(in_place_type_t, A&&...); template - constexpr explicit variant(in_place_type_t, initializer_list, + constexpr explicit variant(in_place_type_t, std::initializer_list, A&&...); template constexpr explicit variant(in_place_index_t, A&&...); template - constexpr explicit variant(in_place_index_t, initializer_list, + constexpr explicit variant(in_place_index_t, std::initializer_list, A&&...); // destructor @@ -202,14 +202,14 @@ public: template constexpr U& emplace(A&&...); template - constexpr T& emplace(initializer_list, A&&...); + constexpr U& emplace(std::initializer_list, A&&...); template constexpr variant_alternative_t>& emplace(A&&...); template constexpr variant_alternative_t>& - emplace(initializer_list, A&&...); + emplace(std::initializer_list, A&&...); // value status @@ -243,7 +243,7 @@ public: #### Constructors ``` -constexpr variant() noexcept(is_nothrow_default_constructible_v); +constexpr variant() noexcept(std::is_nothrow_default_constructible_v); ``` [none] * {blank} @@ -253,11 +253,11 @@ Effects: :: Constructs a `variant` holding a value-initialized value of Ensures: :: `index() == 0`. Throws: :: Any exception thrown by the value-initialization of `T0`. Remarks: :: This function does not participate in overload resolution unless - `is_default_constructible_v` is `true`. + `std::is_default_constructible_v` is `true`. ``` constexpr variant(variant const & w) - noexcept( mp_all...>::value ); + noexcept( mp_all...>::value ); ``` [none] * {blank} @@ -266,11 +266,11 @@ Effects: :: Initializes the variant to hold the same alternative and value as `w`. Throws: :: Any exception thrown by the initialization of the contained value. Remarks: :: This function does not participate in overload resolution unless - `is_copy_constructible_v` is `true` for all `i`. + `std::is_copy_constructible_v` is `true` for all `i`. ``` constexpr variant(variant&& w) - noexcept( mp_all...>::value ); + noexcept( mp_all...>::value ); ``` [none] * {blank} @@ -280,7 +280,7 @@ Effects: :: Initializes the variant to hold the same alternative and value as Throws: :: Any exception thrown by the move-initialization of the contained value. Remarks: :: This function does not participate in overload resolution unless - `is_move_constructible_v` is `true` for all `i`. + `std::is_move_constructible_v` is `true` for all `i`. ``` template constexpr variant(U&& u) noexcept(/*see below*/); @@ -298,13 +298,13 @@ Effects: :: Initializes `*this` to hold the alternative type `Tj` and Ensures: :: `holds_alternative(*this)`. Throws: :: Any exception thrown by the initialization of the contained value. Remarks: :: The expression inside `noexcept` is equivalent to -`is_nothrow_constructible_v`. This function does not participate in +`std::is_nothrow_constructible_v`. This function does not participate in overload resolution unless - `sizeof...(T)` is nonzero, -- `is_same_v, variant>` is `false`, -- `remove_cvref_t` is neither a specialization of `in_place_type_t` nor a +- `std::is_same_v, variant>` is `false`, +- `std::remove_cvref_t` is neither a specialization of `in_place_type_t` nor a specialization of `in_place_index_t`, -- `is_constructible_v` is `true`, and +- `std::is_constructible_v` is `true`, and - the expression `FUN(std::forward(u))` is well-formed. ``` @@ -320,11 +320,11 @@ Ensures: :: `holds_alternative(*this)`. Throws: :: Any exception thrown by the initialization of the contained value. Remarks: :: This function does not participate in overload resolution unless there is exactly one occurrence of `U` in `T...` and - `is_constructible_v` is true. + `std::is_constructible_v` is true. ``` template - constexpr explicit variant(in_place_type_t, initializer_list il, + constexpr explicit variant(in_place_type_t, std::initializer_list il, A&&... a); ``` [none] @@ -336,7 +336,7 @@ Ensures: :: `holds_alternative(*this)`. Throws: :: Any exception thrown by the initialization of the contained value. Remarks: :: This function does not participate in overload resolution unless there is exactly one occurrence of `U` in `T...` and - `is_constructible_v&, A...>` is `true`. + `std::is_constructible_v&, A...>` is `true`. ``` template @@ -350,11 +350,11 @@ Effects: :: Initializes the contained value of type `TI` with the arguments Ensures: :: `index() == I`. Throws: :: Any exception thrown by the initialization of the contained value. Remarks: :: This function does not participate in overload resolution unless - `I < sizeof...(T)` and `is_constructible_v` is `true`. + `I < sizeof...(T)` and `std::is_constructible_v` is `true`. ``` template - constexpr explicit variant(in_place_index_t, initializer_list il, + constexpr explicit variant(in_place_index_t, std::initializer_list il, A&&... a); ``` [none] @@ -366,7 +366,7 @@ Ensures: :: `index() == I`. Throws: :: Any exception thrown by the initialization of the contained value. Remarks: :: This function does not participate in overload resolution unless `I < sizeof...(Types)` and - `is_constructible_v&, A...>` is `true`. + `std::is_constructible_v&, A...>` is `true`. #### Destructor @@ -397,6 +397,122 @@ Effects: :: Returns: :: `*this`. Ensures: :: `index() == rhs.index()`. Remarks: :: This operator does not participate in overload resolution unless - `is_copy_constructible_v && is_copy_assignable_v` is `true` for all - `i`. + `std::is_copy_constructible_v && std::is_copy_assignable_v` is + `true` for all `i`. +``` +constexpr variant& operator=(variant&& rhs) + noexcept( mp_all..., + std::is_nothrow_move_assignable...>::value ); +``` +[none] +* {blank} ++ +Let `j` be `rhs.index()`. + +Effects: :: +- If `index() == j`, assigns the value contained in `std::move(rhs)` to the + value contained in `*this`. +- Otherwise, equivalent to `emplace(get(std::move(rhs)))`. +Returns: :: `*this`. +Ensures: :: `index() == rhs.index()`. +Remarks: :: This operator does not participate in overload resolution unless + `std::is_move_constructible_v && std::is_move_assignable_v` is + `true` for all `i`. + +``` +template constexpr variant& operator=(U&& u) + noexcept( /*see below*/ ); +``` +[none] +* {blank} ++ +Let `Tj` be a type that is determined as follows: build an imaginary function +`FUN(Ti)` for each alternative type `Ti`. The overload `FUN(Tj)` selected by +overload resolution for the expression `FUN(std::forward(u))` defines the +alternative `Tj` which is the type of the contained value after construction. + +Effects: :: +- If `index() == j`, assigns `std::forward(u)` to the value contained in + `*this`. +- Otherwise, equivalent to `emplace(std::forward(u))`. +Returns: :: `*this`. +Ensures: :: `index() == j`. +Remarks: :: + The expression inside `noexcept` is `std::is_nothrow_constructible_v + && std::is_nothrow_assignable_v`. + This operator does not participate in overload resolution unless + - `std::is_same_v, variant>` is `false`, + - `std::is_constructible_v && std::is_assignable_v` is + `true`, and + - the expression `FUN(std::forward(u))` (with `FUN` being the + above-mentioned set of imaginary functions) is well-formed. + +#### Modifiers + +``` +template + constexpr U& emplace(A&&... a); +``` +[none] +* {blank} ++ +Let `I` be the zero-based index of `U` in `T...`. + +Effects: :: Equivalent to: `return emplace(std::forward(a)...);` +Remarks: :: + This function shall not participate in overload resolution unless + `std::is_constructible_v` is `true` and `U` occurs exactly once + in `T...`. + +``` +template + constexpr U& emplace(std::initializer_list il, A&&... a); +``` +[none] +* {blank} ++ +Let `I` be the zero-based index of `U` in `T...`. + +Effects: :: Equivalent to: `return emplace(il, std::forward(a)...);` +Remarks: :: + This function shall not participate in overload resolution unless + `std::is_constructible_v&, A...>` is `true` + and `U` occurs exactly once in `T...`. + + +``` +template + constexpr variant_alternative_t>& + emplace(A&&... a); +``` +[none] +* {blank} ++ +Requires: :: `I < sizeof(T...)`. +Effects: :: + Destroys the currently contained value, then initializes a new contained + value as if using the expression `Ti(std::forward(a)...)`. +Ensures: :: `index() == I`. +Returns: :: A reference to the new contained value. +Remarks: :: + This function shall not participate in overload resolution unless + `std::is_constructible_v` is `true`. + +``` +template + constexpr variant_alternative_t>& + emplace(std::initializer_list il, A&&... a); +``` +[none] +* {blank} ++ +Requires: :: `I < sizeof(T...)`. +Effects: :: + Destroys the currently contained value, then initializes a new contained + value as if using the expression `Ti(il, std::forward(a)...)`. +Ensures: :: `index() == I`. +Returns: :: A reference to the new contained value. +Remarks: :: + This function shall not participate in overload resolution unless + `std::is_constructible_v&, A...>` is `true`.