Boost logo

Boost-Commit :

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&lt;T&gt;()(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 &amp;&amp;</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 &amp;&amp;</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&lt;U1, U2, ..., UN&gt; &amp;&amp;</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 &amp;</type>
+
+ <parameter name="rhs">
+ <paramtype>variant &amp;&amp;</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 &amp;</type>
@@ -319,6 +417,52 @@
           </throws>
         </method>
 
+ <method name="operator=">
+ <type>variant &amp;</type>
+
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+
+ <parameter name="rhs">
+ <paramtype>T &amp;&amp;</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>&lt;T1, T2, ..., TN&gt; &amp;</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&lt;T&gt;()(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>&lt;boost/variant/detail/hash_variant.hpp&gt;</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">


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk