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 &</paramtype>
+ </parameter>
+ <parameter name="operand1">
+ <paramtype>Variant1 &</paramtype>
+ </parameter>
+ <parameter name="operand2">
+ <paramtype>Variant2 &</paramtype>
+ </parameter>
+ <parameter name="operand3">
+ <paramtype>Variant3 &</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 &</paramtype>
+ </parameter>
+ <parameter name="operand1">
+ <paramtype>Variant1 &</paramtype>
+ </parameter>
+ <parameter name="operand2">
+ <paramtype>Variant2 &</paramtype>
+ </parameter>
+ <parameter name="operand3">
+ <paramtype>Variant3 &</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 <boost/variant/multivisitors.hpp> 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 &</paramtype>
+ </parameter>
+ <parameter name="operand1">
+ <paramtype>Variant1 &</paramtype>
+ </parameter>
+ <parameter name="operand2">
+ <paramtype>Variant2 &</paramtype>
+ </parameter>
+ <parameter name="operand3">
+ <paramtype>Variant3 &</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 &</paramtype>
+ </parameter>
+ <parameter name="operand1">
+ <paramtype>Variant1 &</paramtype>
+ </parameter>
+ <parameter name="operand2">
+ <paramtype>Variant2 &</paramtype>
+ </parameter>
+ <parameter name="operand3">
+ <paramtype>Variant3 &</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 <boost/multivisiors.hpp>.</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 <boost/variant/multivisitors.hpp>
+
+typedef <classname>boost::variant</classname><int, double, bool> bool_like_t;
+typedef <classname>boost::variant</classname><int, double> arithmetics_t;
+
+struct if_visitor: public <classname>boost::static_visitor</classname><arithmetics_t> {
+ template <class T1, class T2>
+ 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
+ "delayed" 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;
}