[Boost-commit] svn:boost r84104 - in trunk/libs/variant/doc: reference tutorial

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">