Subject: [Boost-commit] svn:boost r84104 - in trunk/libs/variant/doc: reference tutorial
From: antoshkka_at_[hidden]
Date: 2013-05-02 04:39:35
Author: apolukhin
Date: 2013-05-02 04:39:34 EDT (Thu, 02 May 2013)
New Revision: 84104
URL: http://svn.boost.org/trac/boost/changeset/84104
Log:
Update docs of Boost.Variant. Add advice about recursive_wrapper performance (refs #7718)
Text files modified:
trunk/libs/variant/doc/reference/concepts.xml | 24 ++++
trunk/libs/variant/doc/reference/variant.xml | 187 +++++++++++++++++++++++++++++++++++++++
trunk/libs/variant/doc/tutorial/advanced.xml | 4
3 files changed, 211 insertions(+), 4 deletions(-)
Modified: trunk/libs/variant/doc/reference/concepts.xml
==============================================================================
--- trunk/libs/variant/doc/reference/concepts.xml (original)
+++ trunk/libs/variant/doc/reference/concepts.xml 2013-05-02 04:39:34 EDT (Thu, 02 May 2013)
@@ -11,7 +11,7 @@
are as follows:</para>
<itemizedlist>
- <listitem><conceptname>CopyConstructible</conceptname> [20.1.3].</listitem>
+ <listitem><conceptname>CopyConstructible</conceptname> or <conceptname>MoveConstructible</conceptname>.</listitem>
<listitem>Destructor upholds the no-throw exception-safety
guarantee.</listitem>
<listitem>Complete at the point of <code>variant</code> template
@@ -34,6 +34,12 @@
concept. (Note that top-level <code>const</code>-qualified types and
reference types do <emphasis>not</emphasis> meet these
requirements.)</listitem>
+ <listitem><conceptname>MoveAssignable</conceptname>:
+ <code>variant</code> is itself <emphasis>MoveAssignable</emphasis> if and
+ only if every one of its bounded types meets the requirements of the
+ concept. (Note that top-level <code>const</code>-qualified types and
+ reference types do <emphasis>not</emphasis> meet these
+ requirements.)</listitem>
<listitem><conceptname>DefaultConstructible</conceptname> [20.1.4]:
<code>variant</code> is itself
<conceptname>DefaultConstructible</conceptname> if and only if its first
@@ -51,6 +57,10 @@
<code>variant</code> is itself <emphasis>OutputStreamable</emphasis>
if and only if every one of its bounded types meets the requirements
of the concept.</listitem>
+ <listitem><link linkend="variant.concepts.hashable"><emphasis>Hashable</emphasis></link>:
+ <code>variant</code> is itself <emphasis>Hashable</emphasis>
+ if and only if every one of its bounded types meets the requirements
+ of the concept.</listitem>
</itemizedlist>
</section>
@@ -129,4 +139,16 @@
</itemizedlist>
</section>
+ <section id="variant.concepts.hashable">
+ <title><emphasis>Hashable</emphasis></title>
+
+ <para>The requirements on an <emphasis role="bold">hashable</emphasis> type <code>T</code> are as follows:</para>
+
+ <itemizedlist>
+ <listitem>For any object <code>t</code> of type <code>T</code>,
+ <code>boost::hash<T>()(t)</code> must be a valid
+ expression.</listitem>
+ </itemizedlist>
+ </section>
+
</section>
\ No newline at end of file
Modified: trunk/libs/variant/doc/reference/variant.xml
==============================================================================
--- trunk/libs/variant/doc/reference/variant.xml (original)
+++ trunk/libs/variant/doc/reference/variant.xml 2013-05-02 04:39:34 EDT (Thu, 02 May 2013)
@@ -110,6 +110,26 @@
copy constructor of <code>other</code>'s contained type.</simpara>
</throws>
</constructor>
+
+ <constructor>
+ <parameter name="other">
+ <paramtype>variant &&</paramtype>
+ </parameter>
+
+ <requires>
+ <simpara>C++11 compatible compiler.</simpara>
+ </requires>
+
+ <postconditions>
+ <simpara>Content of <code>*this</code> is move constructed from the content of
+ <code>other</code>.</simpara>
+ </postconditions>
+
+ <throws>
+ <simpara>May fail with any exceptions arising from the
+ move constructor of <code>other</code>'s contained type.</simpara>
+ </throws>
+ </constructor>
<constructor>
<template>
@@ -152,6 +172,25 @@
construction from temporaries.</simpara>
</notes>
</constructor>
+
+ <constructor>
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+
+ <parameter name="operand">
+ <paramtype>T &&</paramtype>
+ </parameter>
+
+ <requires>
+ <simpara>C++11 compatible compiler.</simpara>
+ </requires>
+
+ <notes>
+ <simpara>Same semantics as previous constructor, but allows
+ move construction if <code>operand</code> is an rvalue.</simpara>
+ </notes>
+ </constructor>
<constructor>
<template>
@@ -208,6 +247,28 @@
construction from temporaries.</simpara>
</notes>
</constructor>
+
+ <constructor>
+ <template>
+ <template-type-parameter name="U1"/>
+ <template-type-parameter name="U2"/>
+ <template-varargs/>
+ <template-type-parameter name="UN"/>
+ </template>
+
+ <requires>
+ <simpara>C++11 compatible compiler.</simpara>
+ </requires>
+
+ <parameter name="operand">
+ <paramtype>variant<U1, U2, ..., UN> &&</paramtype>
+ </parameter>
+
+ <notes>
+ <simpara>Same semantics as previous constructor, but allows
+ move construction.</simpara>
+ </notes>
+ </constructor>
<method-group name="modifiers">
@@ -220,7 +281,7 @@
<requires>
<simpara>Every bounded type must fulfill the requirements of the
- <conceptname>Assignable</conceptname>
+ <conceptname>MoveAssignable</conceptname>
concept.</simpara>
</requires>
@@ -234,7 +295,7 @@
the contained type of <code>*this</code>, then may fail with any
exceptions arising from the <code>swap</code> of the contents of
<code>*this</code> and <code>other</code>. Otherwise, may fail
- with any exceptions arising from either of the copy constructors
+ with any exceptions arising from either of the move or copy constructors
of the contained types. Also, in the event of insufficient
memory, may fail with <code>std::bad_alloc</code>
(<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
@@ -274,6 +335,43 @@
(<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
</throws>
</method>
+
+ <method name="operator=">
+ <type>variant &</type>
+
+ <parameter name="rhs">
+ <paramtype>variant &&</paramtype>
+ </parameter>
+
+ <requires>
+ <itemizedlist>
+ <listitem>C++11 compatible compiler.</listitem>
+ <listitem>Every bounded type must fulfill the requirements of the
+ <conceptname>MoveAssignable</conceptname>
+ concept.</listitem>
+ </itemizedlist>
+ </requires>
+
+ <effects>
+ <simpara>If the contained type of <code>rhs</code> is the same as
+ the contained type of <code>*this</code>, then move assigns the
+ content of <code>rhs</code> into the content of
+ <code>*this</code>. Otherwise, move constructs
+ <code>*this</code> using the content of <code>rhs</code>,
+ destroying the previous content of <code>*this</code>.</simpara>
+ </effects>
+
+ <throws>
+ <simpara>If the contained type of <code>rhs</code> is the same as
+ the contained type of <code>*this</code>, then may fail with any
+ exceptions arising from the move assignment of the content of
+ <code>rhs</code> into the content <code>*this</code>. Otherwise,
+ may fail with any exceptions arising from the move constructor
+ of the contained type of <code>rhs</code>. Also, in the event of
+ insufficient memory, may fail with <code>std::bad_alloc</code>
+ (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
+ </throws>
+ </method>
<method name="operator=">
<type>variant &</type>
@@ -319,6 +417,52 @@
</throws>
</method>
+ <method name="operator=">
+ <type>variant &</type>
+
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+
+ <parameter name="rhs">
+ <paramtype>T &&</paramtype>
+ </parameter>
+
+ <requires>
+ <itemizedlist>
+ <listitem>C++11 compatible compiler.</listitem>
+ <listitem><code>rhs</code> is an rvalue. Otherwise previous operator will be used.</listitem>
+ <listitem><code>T</code> must be unambiguously convertible to
+ one of the bounded types (i.e., <code>T1</code>,
+ <code>T2</code>, etc.).</listitem>
+ <listitem>Every bounded type must fulfill the requirements of the
+ <conceptname>MoveAssignable</conceptname>
+ concept.</listitem>
+ </itemizedlist>
+ </requires>
+
+ <effects>
+ <simpara>If the contained type of <code>*this</code> is
+ <code>T</code>, then move assigns <code>rhs</code> into the content
+ of <code>*this</code>. Otherwise, makes the content of
+ <code>*this</code> the best conversion of <code>rhs</code> to
+ one of the bounded types, as determined by standard overload
+ resolution rules, destroying the previous content of
+ <code>*this</code>(conversion is usually done via move construction).</simpara>
+ </effects>
+
+ <throws>
+ <simpara>If the contained type of <code>*this</code> is
+ <code>T</code>, then may fail with any exceptions arising from
+ the move assignment of <code>rhs</code> into the content
+ <code>*this</code>. Otherwise, may fail with any exceptions
+ arising from the conversion of <code>rhs</code> to one of the
+ bounded types. Also, in the event of insufficient memory, may
+ fail with <code>std::bad_alloc</code>
+ (<link linkend="variant.design.never-empty.problem">why?</link>).</simpara>
+ </throws>
+ </method>
+
</method-group>
<method-group name="queries">
@@ -549,6 +693,43 @@
</function>
+ <function name="hash_value">
+ <purpose>Provides hashing for <code>variant</code> types so
+ that <code>boost::hash</code> may compute hash.</purpose>
+
+ <template>
+ <template-type-parameter name="T1"/>
+ <template-type-parameter name="T2"/>
+ <template-varargs/>
+ <template-type-parameter name="TN"/>
+ </template>
+
+ <type>std::size_t</type>
+
+ <parameter name="rhs">
+ <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype>
+ </parameter>
+
+ <requires>
+ <simpara>Every bounded type of the <code>variant</code> must
+ fulfill the requirements of the
+ <link linkend="variant.concepts.hashable"><emphasis>Hashable</emphasis></link>
+ concept.</simpara>
+ </requires>
+
+ <effects>
+ <simpara>Calls <code>boost::hash<T>()(x)</code>, where <code>x</code> is
+ the content of <code>rhs</code> and <code>T</code> is its type.</simpara>
+ </effects>
+
+ <notes>
+ <simpara>Actually, this function is defined in
+ <code><boost/variant/detail/hash_variant.hpp></code>
+ header.</simpara>
+ </notes>
+
+ </function>
+
<class name="make_variant_over">
<purpose>
<simpara>Exposes a <code>variant</code> whose bounded types are the
@@ -584,4 +765,4 @@
</description>
</class>
</namespace>
-</header>
\ No newline at end of file
+</header>
Modified: trunk/libs/variant/doc/tutorial/advanced.xml
==============================================================================
--- trunk/libs/variant/doc/tutorial/advanced.xml (original)
+++ trunk/libs/variant/doc/tutorial/advanced.xml 2013-05-02 04:39:34 EDT (Thu, 02 May 2013)
@@ -222,6 +222,10 @@
</para>
+ <para><emphasis role="bold">Performance</emphasis>: <classname>boost::recursive_wrapper</classname>
+ has no empty state, which makes its move constructor not very optimal. Consider using <code>std::unique_ptr</code>
+ or some other safe pointer for better performance on C++11 compatible compilers.</para>
+
</section>
<section id="variant.tutorial.recursive.recursive-variant">