feedc0de/boost_variant2
1
0
Fork 0
forked from boostorg/variant2
Code Pull Requests Activity

Add to documentation

Browse Source
This commit is contained in:
Peter Dimov
2019-02-18 19:51:23 +02:00
parent 3fb89b9f5a
commit 16027c5447
2 changed files with 141 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/variant/copyright.adoc
View File

@ -1,5 +1,5 @@
//// ////
Copyright 2018 Peter Dimov Copyright 2018, 2019 Peter Dimov
Distributed under the Boost Software License, Version 1.0. Distributed under the Boost Software License, Version 1.0.
@ -11,5 +11,5 @@ http://www.boost.org/LICENSE_1_0.txt
# Copyright and License # Copyright and License
:idprefix: :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]. the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].

162
doc/variant/reference.adoc
View File

@ -1,5 +1,5 @@
//// ////
Copyright 2018 Peter Dimov Copyright 2018, 2019 Peter Dimov
Distributed under the Boost Software License, Version 1.0. Distributed under the Boost Software License, Version 1.0.
@ -177,13 +177,13 @@ public:
template<class U, class... A> template<class U, class... A>
constexpr explicit variant(in_place_type_t<U>, A&&...); constexpr explicit variant(in_place_type_t<U>, A&&...);
template<class U, class V, class... A> template<class U, class V, class... A>
constexpr explicit variant(in_place_type_t<U>, initializer_list<V>, constexpr explicit variant(in_place_type_t<U>, std::initializer_list<V>,
A&&...); A&&...);
template<size_t I, class... A> template<size_t I, class... A>
constexpr explicit variant(in_place_index_t<I>, A&&...); constexpr explicit variant(in_place_index_t<I>, A&&...);
template<size_t I, class V, class... A> template<size_t I, class V, class... A>
constexpr explicit variant(in_place_index_t<I>, initializer_list<V>, constexpr explicit variant(in_place_index_t<I>, std::initializer_list<V>,
A&&...); A&&...);
// destructor // destructor
@ -202,14 +202,14 @@ public:
template<class U, class... A> template<class U, class... A>
constexpr U& emplace(A&&...); constexpr U& emplace(A&&...);
template<class U, class V, class... A> template<class U, class V, class... A>
constexpr T& emplace(initializer_list<U>, A&&...); constexpr U& emplace(std::initializer_list<V>, A&&...);
template<size_t I, class... A> template<size_t I, class... A>
constexpr variant_alternative_t<I, variant<T...>>& constexpr variant_alternative_t<I, variant<T...>>&
emplace(A&&...); emplace(A&&...);
template<size_t I, class V, class... A> template<size_t I, class V, class... A>
constexpr variant_alternative_t<I, variant<T...>>& constexpr variant_alternative_t<I, variant<T...>>&
emplace(initializer_list<V>, A&&...); emplace(std::initializer_list<V>, A&&...);
// value status // value status
@ -243,7 +243,7 @@ public:
#### Constructors #### Constructors
``` ```
constexpr variant() noexcept(is_nothrow_default_constructible_v<T0>); constexpr variant() noexcept(std::is_nothrow_default_constructible_v<T0>);
``` ```
[none] [none]
* {blank} * {blank}
@ -253,11 +253,11 @@ Effects: :: Constructs a `variant` holding a value-initialized value of
Ensures: :: `index() == 0`. Ensures: :: `index() == 0`.
Throws: :: Any exception thrown by the value-initialization of `T0`. Throws: :: Any exception thrown by the value-initialization of `T0`.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
`is_default_constructible_v<T0>` is `true`. `std::is_default_constructible_v<T0>` is `true`.
``` ```
constexpr variant(variant const & w) constexpr variant(variant const & w)
noexcept( mp_all<is_nothrow_copy_constructible<T>...>::value ); noexcept( mp_all<std::is_nothrow_copy_constructible<T>...>::value );
``` ```
[none] [none]
* {blank} * {blank}
@ -266,11 +266,11 @@ Effects: :: Initializes the variant to hold the same alternative and value as
`w`. `w`.
Throws: :: Any exception thrown by the initialization of the contained value. Throws: :: Any exception thrown by the initialization of the contained value.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
`is_copy_constructible_v<Ti>` is `true` for all `i`. `std::is_copy_constructible_v<Ti>` is `true` for all `i`.
``` ```
constexpr variant(variant&& w) constexpr variant(variant&& w)
noexcept( mp_all<is_nothrow_move_constructible<T>...>::value ); noexcept( mp_all<std::is_nothrow_move_constructible<T>...>::value );
``` ```
[none] [none]
* {blank} * {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 Throws: :: Any exception thrown by the move-initialization of the contained
value. value.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
`is_move_constructible_v<Ti>` is `true` for all `i`. `std::is_move_constructible_v<Ti>` is `true` for all `i`.
``` ```
template<class U> constexpr variant(U&& u) noexcept(/*see below*/); template<class U> constexpr variant(U&& u) noexcept(/*see below*/);
@ -298,13 +298,13 @@ Effects: :: Initializes `*this` to hold the alternative type `Tj` and
Ensures: :: `holds_alternative<Tj>(*this)`. Ensures: :: `holds_alternative<Tj>(*this)`.
Throws: :: Any exception thrown by the initialization of the contained value. Throws: :: Any exception thrown by the initialization of the contained value.
Remarks: :: The expression inside `noexcept` is equivalent to Remarks: :: The expression inside `noexcept` is equivalent to
`is_nothrow_constructible_v<Tj, U>`. This function does not participate in `std::is_nothrow_constructible_v<Tj, U>`. This function does not participate in
overload resolution unless overload resolution unless
- `sizeof...(T)` is nonzero, - `sizeof...(T)` is nonzero,
- `is_same_v<remove_cvref_t<U>, variant>` is `false`, - `std::is_same_v<std::remove_cvref_t<U>, variant>` is `false`,
- `remove_cvref_t<U>` is neither a specialization of `in_place_type_t` nor a - `std::remove_cvref_t<U>` is neither a specialization of `in_place_type_t` nor a
specialization of `in_place_index_t`, specialization of `in_place_index_t`,
- `is_constructible_v<Tj, U>` is `true`, and - `std::is_constructible_v<Tj, U>` is `true`, and
- the expression `FUN(std::forward<U>(u))` is well-formed. - the expression `FUN(std::forward<U>(u))` is well-formed.
``` ```
@ -320,11 +320,11 @@ Ensures: :: `holds_alternative<U>(*this)`.
Throws: :: Any exception thrown by the initialization of the contained value. Throws: :: Any exception thrown by the initialization of the contained value.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
there is exactly one occurrence of `U` in `T...` and there is exactly one occurrence of `U` in `T...` and
`is_constructible_v<U, A...>` is true. `std::is_constructible_v<U, A...>` is true.
``` ```
template<class U, class V, class... A> template<class U, class V, class... A>
constexpr explicit variant(in_place_type_t<U>, initializer_list<V> il, constexpr explicit variant(in_place_type_t<U>, std::initializer_list<V> il,
A&&... a); A&&... a);
``` ```
[none] [none]
@ -336,7 +336,7 @@ Ensures: :: `holds_alternative<U>(*this)`.
Throws: :: Any exception thrown by the initialization of the contained value. Throws: :: Any exception thrown by the initialization of the contained value.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
there is exactly one occurrence of `U` in `T...` and there is exactly one occurrence of `U` in `T...` and
`is_constructible_v<U, initializer_list<V>&, A...>` is `true`. `std::is_constructible_v<U, initializer_list<V>&, A...>` is `true`.
``` ```
template<size_t I, class... A> template<size_t I, class... A>
@ -350,11 +350,11 @@ Effects: :: Initializes the contained value of type `TI` with the arguments
Ensures: :: `index() == I`. Ensures: :: `index() == I`.
Throws: :: Any exception thrown by the initialization of the contained value. Throws: :: Any exception thrown by the initialization of the contained value.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
`I < sizeof...(T)` and `is_constructible_v<TI, A...>` is `true`. `I < sizeof...(T)` and `std::is_constructible_v<TI, A...>` is `true`.
``` ```
template<size_t I, class V, class... A> template<size_t I, class V, class... A>
constexpr explicit variant(in_place_index_t<I>, initializer_list<V> il, constexpr explicit variant(in_place_index_t<I>, std::initializer_list<V> il,
A&&... a); A&&... a);
``` ```
[none] [none]
@ -366,7 +366,7 @@ Ensures: :: `index() == I`.
Throws: :: Any exception thrown by the initialization of the contained value. Throws: :: Any exception thrown by the initialization of the contained value.
Remarks: :: This function does not participate in overload resolution unless Remarks: :: This function does not participate in overload resolution unless
`I < sizeof...(Types)` and `I < sizeof...(Types)` and
`is_constructible_v<TI, initializer_list<V>&, A...>` is `true`. `std::is_constructible_v<TI, initializer_list<V>&, A...>` is `true`.
#### Destructor #### Destructor
@ -397,6 +397,122 @@ Effects: ::
Returns: :: `*this`. Returns: :: `*this`.
Ensures: :: `index() == rhs.index()`. Ensures: :: `index() == rhs.index()`.
Remarks: :: This operator does not participate in overload resolution unless Remarks: :: This operator does not participate in overload resolution unless
`is_copy_constructible_v<Ti> && is_copy_assignable_v<Ti>` is `true` for all `std::is_copy_constructible_v<Ti> && std::is_copy_assignable_v<Ti>` is
`i`. `true` for all `i`.
```
constexpr variant& operator=(variant&& rhs)
noexcept( mp_all<std::is_nothrow_move_constructible<T>...,
std::is_nothrow_move_assignable<T>...>::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<j>(get<j>(std::move(rhs)))`.
Returns: :: `*this`.
Ensures: :: `index() == rhs.index()`.
Remarks: :: This operator does not participate in overload resolution unless
`std::is_move_constructible_v<Ti> && std::is_move_assignable_v<Ti>` is
`true` for all `i`.
```
template<class U> 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>(u))` defines the
alternative `Tj` which is the type of the contained value after construction.
Effects: ::
- If `index() == j`, assigns `std::forward<U>(u)` to the value contained in
`*this`.
- Otherwise, equivalent to `emplace<j>(std::forward<U>(u))`.
Returns: :: `*this`.
Ensures: :: `index() == j`.
Remarks: ::
The expression inside `noexcept` is `std::is_nothrow_constructible_v<Tj, U>
&& std::is_nothrow_assignable_v<Tj&, U>`.
This operator does not participate in overload resolution unless
- `std::is_same_v<std::remove_cvref_t<T>, variant>` is `false`,
- `std::is_constructible_v<Tj, U> && std::is_assignable_v<Tj&, U>` is
`true`, and
- the expression `FUN(std::forward<U>(u))` (with `FUN` being the
above-mentioned set of imaginary functions) is well-formed.
#### Modifiers
```
template<class U, class... A>
constexpr U& emplace(A&&... a);
```
[none]
* {blank}
+
Let `I` be the zero-based index of `U` in `T...`.
Effects: :: Equivalent to: `return emplace<I>(std::forward<A>(a)...);`
Remarks: ::
This function shall not participate in overload resolution unless
`std::is_constructible_v<U, A...>` is `true` and `U` occurs exactly once
in `T...`.
```
template<class U, class V, class... A>
constexpr U& emplace(std::initializer_list<V> il, A&&... a);
```
[none]
* {blank}
+
Let `I` be the zero-based index of `U` in `T...`.
Effects: :: Equivalent to: `return emplace<I>(il, std::forward<A>(a)...);`
Remarks: ::
This function shall not participate in overload resolution unless
`std::is_constructible_v<U, std::initializer_list<V>&, A...>` is `true`
and `U` occurs exactly once in `T...`.
```
template<size_t I, class... A>
constexpr variant_alternative_t<I, variant<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>(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<Ti, A...>` is `true`.
```
template<size_t I, class V, class... A>
constexpr variant_alternative_t<I, variant<T...>>&
emplace(std::initializer_list<V> 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>(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<Ti, std::initializer_list<V>&, A...>` is `true`.