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

Update documentation

Browse Source
This commit is contained in:
Peter Dimov
2019-05-12 18:43:56 +03:00
parent 64ea067c79
commit cacd99d69d
4 changed files with 188 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
doc/html/variant2.html
View File

@ -455,6 +455,30 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
<li><a href="#overview_default_construction">Default Construction</a></li>
</ul>
</li>
<li><a href="#changelog">Revision History</a>
<ul class="sectlevel2">
<li><a href="#changelog_changes_in_1_71_0">Changes in 1.71.0</a></li>
</ul>
</li>
<li><a href="#design">Design</a>
<ul class="sectlevel2">
<li><a href="#design_features">Features</a></li>
<li><a href="#design_rationale">Rationale</a>
<ul class="sectlevel3">
<li><a href="#design_never_valueless">Never Valueless</a></li>
<li><a href="#design_strong_exception_safety">Strong Exception Safety</a></li>
</ul>
</li>
<li><a href="#design_differences_with_stdvariant">Differences with std::variant</a></li>
<li><a href="#design_differences_with_boost_variant">Differences with Boost.Variant</a></li>
</ul>
</li>
<li><a href="#implementation">Implementation</a>
<ul class="sectlevel2">
<li><a href="#implementation_dependencies">Dependencies</a></li>
<li><a href="#implementation_supported_compilers">Supported Compilers</a></li>
</ul>
</li>
<li><a href="#reference">Reference</a>
<ul class="sectlevel2">
<li><a href="#ref_boostvariant2variant_hpp">&lt;boost/variant2/variant.hpp&gt;</a>
@ -862,6 +886,149 @@ which is basically a no-op, as <code>monostate</code> is effectively an empty <c
</div>
</div>
<div class="sect1">
<h2 id="changelog">Revision History</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="changelog_changes_in_1_71_0">Changes in 1.71.0</h3>
<div class="paragraph">
<p>After the Boost formal review, the implementation has been
changed to provide the strong exception safety guarantee,
instead of basic. <code>expected</code> has been removed.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="design">Design</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="design_features">Features</h3>
<div class="paragraph">
<p>This <code>variant</code> implementation has two distinguishing features:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It&#8217;s never "valueless", that is, <code>variant&lt;T1, T2, &#8230;&#8203;, Tn&gt;</code> has an
invariant that it always contains a valid value of one of the types
<code>T1</code>, <code>T2</code>, &#8230;&#8203;, <code>Tn</code>.</p>
</li>
<li>
<p>It provides the strong exception safety guarantee on assignment and
<code>emplace</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This is achieved with the use of double storage, unless all of the
contained types have a non-throwing move constructor.</p>
</div>
</div>
<div class="sect2">
<h3 id="design_rationale">Rationale</h3>
<div class="sect3">
<h4 id="design_never_valueless">Never Valueless</h4>
<div class="paragraph">
<p>&#8230;&#8203;</p>
</div>
</div>
<div class="sect3">
<h4 id="design_strong_exception_safety">Strong Exception Safety</h4>
<div class="paragraph">
<p>&#8230;&#8203;</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="design_differences_with_stdvariant">Differences with std::variant</h3>
<div class="paragraph">
<p>The main differences between this implementation and <code>std::variant</code> are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>No valueless-by-exception state: <code>valueless_by_exception()</code> always
returns <code>false</code>.</p>
</li>
<li>
<p>Strong exception safety guarantee on assignment and <code>emplace</code>.</p>
</li>
<li>
<p><code>emplace</code> first constructs the new value and then destroys the old one;
in the single storage case, this translates to constructing a temporary
and then moving it into place.</p>
</li>
<li>
<p>A converting constructor from, e.g. <code>variant&lt;int, float&gt;</code> to
<code>variant&lt;float, double, int&gt;</code> is provided as an extension.</p>
</li>
<li>
<p>The reverse operation, going from <code>variant&lt;float, double, int&gt;</code> to
<code>variant&lt;int, float&gt;</code> is provided as the member function <code>subset&lt;U&#8230;&#8203;&gt;</code>.
(This operation can throw if the current state of the variant cannot be
represented.)</p>
</li>
<li>
<p><code>variant&lt;T&#8230;&#8203;&gt;</code> is not (yet) trivial when all contained types are trivial,
as mandated by C&#43;&#43;17.</p>
</li>
<li>
<p>The C&#43;&#43;20 additions and changes to <code>std::variant</code> have not yet been
implemented.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="design_differences_with_boost_variant">Differences with Boost.Variant</h3>
<div class="paragraph">
<p>This library is API compatible with <code>std::variant</code>. As such, its interface
is different from Boost.Variant&#8217;s. For example, visitation is performed via
<code>visit</code> instead of <code>apply_visitor</code>.</p>
</div>
<div class="paragraph">
<p>Recursive variants are not supported.</p>
</div>
<div class="paragraph">
<p>Double storage is used instead of temporary heap backup. This <code>variant</code> is
always "stack-based", it never allocates, and never throws <code>bad_alloc</code> on
its own.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="implementation">Implementation</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="implementation_dependencies">Dependencies</h3>
<div class="paragraph">
<p>This implementation only depends on Boost.Config and Boost.Mp11.</p>
</div>
</div>
<div class="sect2">
<h3 id="implementation_supported_compilers">Supported Compilers</h3>
<div class="ulist">
<ul>
<li>
<p>GCC 4.8 or later with <code>-std=c++11</code> or above</p>
</li>
<li>
<p>Clang 3.5 or later with <code>-std=c++11</code> or above</p>
</li>
<li>
<p>Visual Studio 2015, 2017, 2019</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Tested on <a href="https://travis-ci.org/pdimov/variant2/">Travis</a> and
<a href="https://ci.appveyor.com/project/pdimov/variant2/">Appveyor</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="reference">Reference</h2>
<div class="sectionbody">
<div class="sect2">
@ -2466,7 +2633,7 @@ the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Versi
</div>
<div id="footer">
<div id="footer-text">
Last updated 2019-05-12 00:15:41 +0300
Last updated 2019-05-12 02:21:08 +0300
</div>
</div>
<style>

2
doc/variant2/changelog.adoc
View File

@ -15,4 +15,4 @@ http://www.boost.org/LICENSE_1_0.txt
After the Boost formal review, the implementation has been
changed to provide the strong exception safety guarantee,
instead of basic. `expected` has been removed, for now.
instead of basic. `expected` has been removed.

20
doc/variant2/design.adoc
View File

@ -26,6 +26,12 @@ contained types have a non-throwing move constructor.
## Rationale
### Never Valueless
...
### Strong Exception Safety
...
## Differences with std::variant
@ -34,12 +40,12 @@ The main differences between this implementation and `std::variant` are:
* No valueless-by-exception state: `valueless_by_exception()` always
returns `false`.
* Strong exception safety guarantee.
* Strong exception safety guarantee on assignment and `emplace`.
* `emplace` first constructs the new value and then destroys the old one;
in the single storage case, this translates to constructing a temporary
and then moving it into place.
* A converting constructor from, e.g. `variant<int, float>` to
`variant<float, double, int>` is provided as an extension
`variant<float, double, int>` is provided as an extension.
* The reverse operation, going from `variant<float, double, int>` to
`variant<int, float>` is provided as the member function `subset<U...>`.
(This operation can throw if the current state of the variant cannot be
@ -51,4 +57,12 @@ The main differences between this implementation and `std::variant` are:
## Differences with Boost.Variant
...
This library is API compatible with `std::variant`. As such, its interface
is different from Boost.Variant's. For example, visitation is performed via
`visit` instead of `apply_visitor`.
Recursive variants are not supported.
Double storage is used instead of temporary heap backup. This `variant` is
always "stack-based", it never allocates, and never throws `bad_alloc` on
its own.

4
doc/variant2/implementation.adoc
View File

@ -13,13 +13,13 @@ http://www.boost.org/LICENSE_1_0.txt
## Dependencies
This implementation depends on Boost.Config and Boost.Mp11.
This implementation only depends on Boost.Config and Boost.Mp11.
## Supported Compilers
* GCC 4.8 or later with `-std=c++11` or above
* Clang 3.5 or later with `-std=c++11` or above
* Visual Studio 2015, 2017
* Visual Studio 2015, 2017, 2019
Tested on https://travis-ci.org/pdimov/variant2/[Travis] and
https://ci.appveyor.com/project/pdimov/variant2/[Appveyor].