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

Subject: [Boost-commit] svn:boost r84227 - in trunk/libs/variant: doc/reference doc/tutorial test
From: antoshkka_at_[hidden]
Date: 2013-05-10 12:30:13

Author: apolukhin
Date: 2013-05-10 12:30:12 EDT (Fri, 10 May 2013)
New Revision: 84227
URL: http://svn.boost.org/trac/boost/changeset/84227

Log:
Update Boost.Variant documentation, add info about multivisitors (refs #8459)
Added:
   trunk/libs/variant/doc/reference/multivisitor.xml   (contents, props changed)
Text files modified: 
   trunk/libs/variant/doc/reference/apply_visitor.xml  |    63 +++++++++++++++++++++++++++++++++++++++ 
   trunk/libs/variant/doc/reference/reference.xml      |     5 +-                                      
   trunk/libs/variant/doc/tutorial/advanced.xml        |    53 +++++++++++++++++++++++++++++++++       
   trunk/libs/variant/test/variant_multivisit_test.cpp |     8 +++++                                   
   4 files changed, 126 insertions(+), 3 deletions(-)

Modified: trunk/libs/variant/doc/reference/apply_visitor.xml
==============================================================================
--- trunk/libs/variant/doc/reference/apply_visitor.xml	(original)
+++ trunk/libs/variant/doc/reference/apply_visitor.xml	2013-05-10 12:30:12 EDT (Fri, 10 May 2013)
@@ -148,6 +148,60 @@
 
       <signature>
         <template>
+          <template-type-parameter name="MultiVisitor"/>
+          <template-type-parameter name="Variant1"/>
+          <template-type-parameter name="Variant2"/>
+          <template-type-parameter name="Variant3"/>
+        </template>
+
+        <type>typename MultiVisitor::result_type</type>
+
+        <parameter name="visitor">
+          <paramtype>MultiVisitor &amp;</paramtype>
+        </parameter>
+        <parameter name="operand1">
+          <paramtype>Variant1 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand2">
+          <paramtype>Variant2 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand3">
+          <paramtype>Variant3 &amp;</paramtype>
+        </parameter>
+        <parameter name="other_operands">
+          <paramtype>...</paramtype>
+        </parameter>
+      </signature>
+
+      <signature>
+        <template>
+          <template-type-parameter name="MultiVisitor"/>
+          <template-type-parameter name="Variant1"/>
+          <template-type-parameter name="Variant2"/>
+          <template-type-parameter name="Variant3"/>
+        </template>
+
+        <type>typename MultiVisitor::result_type</type>
+
+        <parameter name="visitor">
+          <paramtype>const MultiVisitor &amp;</paramtype>
+        </parameter>
+        <parameter name="operand1">
+          <paramtype>Variant1 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand2">
+          <paramtype>Variant2 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand3">
+          <paramtype>Variant3 &amp;</paramtype>
+        </parameter>
+        <parameter name="other_operands">
+          <paramtype>...</paramtype>
+        </parameter>
+      </signature>
+
+      <signature>
+        <template>
           <template-type-parameter name="Visitor"/>
         </template>
 
@@ -179,6 +233,13 @@
               the given <code><classname>variant</classname></code>
               operands.</listitem>
 
+            <listitem>Overloads accepting three or more operands invoke the
+              function call operator of the given visitor on the content of
+              the given <code><classname>variant</classname></code>
+              operands. Maximum amount of parameters controlled by 
+              <code><emphasis role="bold"><macroname>BOOST_VARAINT_MAX_MULTIVIZITOR_PARAMS</macroname></emphasis></code>
+              macro. Those functions are actually defined in <xref linkend="header.boost.variant.multivisitors_hpp"/>.</listitem>
+
             <listitem>The overload accepting only a visitor returns a
               <classname alt="boost::apply_visitor_delayed_t">generic function object</classname>
               that accepts either one or two arguments and invokes
@@ -216,4 +277,4 @@
       </throws>
     </overloaded-function>
   </namespace>
-</header>
\ No newline at end of file
+</header>

Added: trunk/libs/variant/doc/reference/multivisitor.xml
==============================================================================
--- (empty file)
+++ trunk/libs/variant/doc/reference/multivisitor.xml	2013-05-10 12:30:12 EDT (Fri, 10 May 2013)
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<header name="boost/variant/multivisitors.hpp">
+  <using-namespace name="boost"/>
+
+  <para>Provides declarations of <functionname>apply_visitor</functionname> for three or more
+    <code><classname>variant</classname></code> parameters.</para>
+
+    <macro name="BOOST_VARAINT_MAX_MULTIVIZITOR_PARAMS">
+      <purpose>
+        <simpara>Controls maximum amount of <code><classname>variant</classname></code>
+          parameters for multi visistors. </simpara>
+      </purpose>
+
+      <description>
+        <para><emphasis role="bold">Note</emphasis>: Default amount is 4. Define it 
+          to bigger value before including &lt;boost/variant/multivisitors.hpp&gt; to
+          increase maximum amount of <code><classname>variant</classname></code>
+          parameters for <functionname>apply_visitor</functionname>.</para>
+      </description>
+    </macro>
+
+  <namespace name="boost">
+    <overloaded-function name="apply_visitor /*three or more variant parameters*/">
+      <description>
+        <simpara>Allows compile-time checked type-safe application of the
+        given visitor to the content of the given variant, ensuring that all
+        types are handled by the visitor. See <functionname>apply_visitor</functionname>
+        for more information.</simpara>
+      </description>
+
+      <signature>
+        <template>
+          <template-type-parameter name="MultiVisitor"/>
+          <template-type-parameter name="Variant1"/>
+          <template-type-parameter name="Variant2"/>
+          <template-type-parameter name="Variant3"/>
+        </template>
+
+        <type>typename MultiVisitor::result_type</type>
+
+        <parameter name="visitor">
+          <paramtype>MultiVisitor &amp;</paramtype>
+        </parameter>
+        <parameter name="operand1">
+          <paramtype>Variant1 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand2">
+          <paramtype>Variant2 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand3">
+          <paramtype>Variant3 &amp;</paramtype>
+        </parameter>
+        <parameter name="other_operands">
+          <paramtype>...</paramtype>
+        </parameter>
+      </signature>
+
+      <signature>
+        <template>
+          <template-type-parameter name="MultiVisitor"/>
+          <template-type-parameter name="Variant1"/>
+          <template-type-parameter name="Variant2"/>
+          <template-type-parameter name="Variant3"/>
+        </template>
+
+        <type>typename MultiVisitor::result_type</type>
+
+        <parameter name="visitor">
+          <paramtype>const MultiVisitor &amp;</paramtype>
+        </parameter>
+        <parameter name="operand1">
+          <paramtype>Variant1 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand2">
+          <paramtype>Variant2 &amp;</paramtype>
+        </parameter>
+        <parameter name="operand3">
+          <paramtype>Variant3 &amp;</paramtype>
+        </parameter>
+        <parameter name="other_operands">
+          <paramtype>...</paramtype>
+        </parameter>
+      </signature>
+    </overloaded-function>
+  </namespace>
+</header>

Modified: trunk/libs/variant/doc/reference/reference.xml
==============================================================================
--- trunk/libs/variant/doc/reference/reference.xml	(original)
+++ trunk/libs/variant/doc/reference/reference.xml	2013-05-10 12:30:12 EDT (Fri, 10 May 2013)
@@ -8,7 +8,7 @@
   <header name="boost/variant.hpp">
     <section id="variant.header.include-all">
       <para>This header exists simply as a convenience to the user, including
-      all of the headers in the <code>boost/variant</code> directory.</para>
+      all of the headers in the <code>boost/variant</code> directory except &lt;boost/multivisiors.hpp&gt;.</para>
     </section>
   </header>
 
@@ -17,8 +17,9 @@
   <xi:include href="recursive_variant.xml"/>
   <xi:include href="recursive_wrapper.xml"/>
   <xi:include href="apply_visitor.xml"/>
+  <xi:include href="multivisitor.xml"/>
   <xi:include href="get.xml"/>
   <xi:include href="bad_visit.xml"/>
   <xi:include href="static_visitor.xml"/>
   <xi:include href="visitor_ptr.xml"/>
-</library-reference>
\ No newline at end of file
+</library-reference>

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-10 12:30:12 EDT (Fri, 10 May 2013)
@@ -355,4 +355,57 @@
 
 </section>
 
+<section id="variant.tutorial.multi-visitation">
+  <title>Multi visitation</title>
+
+  <para>Multi visitation extends the power and flexibility of visitation by allowing simultaneous
+    visitation of the content of three and more different <code>variant</code>
+    objects. Note that header for multi visitors shall be included separately.</para>
+
+  <para>Notably this feature requires that multi visitors are incompatible
+    with the visitor objects discussed in the tutorial above, as they must
+    operate on same amout of arguments that was passed to <code>apply_visitor</code>. 
+    The following demonstrates the implementation of a multi visitor for three parameters:
+
+<programlisting>
+#include &lt;boost/variant/multivisitors.hpp&gt;
+
+typedef <classname>boost::variant</classname>&lt;int, double, bool&gt; bool_like_t;
+typedef <classname>boost::variant</classname>&lt;int, double&gt; arithmetics_t;
+
+struct if_visitor: public <classname>boost::static_visitor</classname>&lt;arithmetics_t&gt; {
+    template &lt;class T1, class T2&gt;
+    arithmetics_t operator()(bool b, T1 v1, T2 v2) const {
+        if (b) {
+            return v1;
+        } else {
+            return v2;
+        }
+    }
+};
+</programlisting>
+  </para>
+
+  <para>As expected, the visitor is applied to three <code>variant</code>
+    arguments by means of <code>apply_visitor</code>:
+
+<programlisting>
+bool_like_t v0(1), v1(true), v2(1.0);
+
+assert(
+    <functionname>boost::apply_visitor</functionname>(if_visitor(), v0, v1, v2)
+    ==
+    arithmetics_t(true)
+);
+</programlisting>
+  </para>
+
+  <para>Finally, we must note that multi visitation does not support 
+    &quot;delayed&quot; form of
+    <code><functionname>apply_visitor</functionname></code>.
+  </para>
+
+</section>
+
+
 </section>

Modified: trunk/libs/variant/test/variant_multivisit_test.cpp
==============================================================================
--- trunk/libs/variant/test/variant_multivisit_test.cpp	(original)
+++ trunk/libs/variant/test/variant_multivisit_test.cpp	2013-05-10 12:30:12 EDT (Fri, 10 May 2013)
@@ -112,5 +112,13 @@
         arithmetics_t(true)
     );
 
+    /* Delayed multi visitation is not implemented
+    if_visitor if_vis;
+    BOOST_CHECK(
+        boost::apply_visitor(if_vis)(v0, v1, v2)
+        ==
+        arithmetics_t(true)
+    );
+    */
     return boost::exit_success;
 }