[DEV] add v1.66.0

libs/variant/doc/tutorial/advanced.xml

@@ -0,0 +1,419 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<!--
+    Copyright 2003, Eric Friedman, Itay Maman.
+    Copyright 2013-2014, Antony Polukhin.
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section id="variant.tutorial.advanced">
+  <title>Advanced Topics</title>
+
+<using-namespace name="boost"/>
+<using-class name="boost::variant"/>
+
+<para>This section discusses several features of the library often required
+  for advanced uses of <code>variant</code>. Unlike in the above section, each
+  feature presented below is largely independent of the others. Accordingly,
+  this section is not necessarily intended to be read linearly or in its
+  entirety.</para>
+
+<section id="variant.tutorial.preprocessor">
+  <title>Preprocessor macros</title>
+
+  <para>While the <code>variant</code> class template's variadic parameter
+    list greatly simplifies use for specific instantiations of the template,
+    it significantly complicates use for generic instantiations. For instance,
+    while it is immediately clear how one might write a function accepting a
+    specific <code>variant</code> instantiation, say
+    <code>variant&lt;int, std::string&gt;</code>, it is less clear how one
+    might write a function accepting any given <code>variant</code>.</para>
+
+  <para>Due to the lack of support for true variadic template parameter lists
+    in the C++98 standard, the preprocessor is needed. While the
+    <libraryname>Preprocessor</libraryname> library provides a general and
+    powerful solution, the need to repeat
+    <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>
+    unnecessarily clutters otherwise simple code. Therefore, for common
+    use-cases, this library provides its own macro
+    <code><emphasis role="bold"><macroname>BOOST_VARIANT_ENUM_PARAMS</macroname></emphasis></code>.</para>
+
+  <para>This macro simplifies for the user the process of declaring 
+    <code>variant</code> types in function templates or explicit partial
+    specializations of class templates, as shown in the following:
+
+<programlisting>// general cases
+template &lt;typename T&gt; void some_func(const T &amp;);
+template &lt;typename T&gt; class some_class;
+
+// function template overload
+template &lt;<macroname>BOOST_VARIANT_ENUM_PARAMS</macroname>(typename T)&gt;
+void some_func(const <classname>boost::variant</classname>&lt;<macroname>BOOST_VARIANT_ENUM_PARAMS</macroname>(T)&gt; &amp;);
+
+// explicit partial specialization
+template &lt;<macroname>BOOST_VARIANT_ENUM_PARAMS</macroname>(typename T)&gt;
+class some_class&lt; <classname>boost::variant</classname>&lt;<macroname>BOOST_VARIANT_ENUM_PARAMS</macroname>(T)&gt; &gt;;</programlisting>
+
+  </para>
+
+</section>
+
+<section id="variant.tutorial.over-sequence">
+  <title>Using a type sequence to specify bounded types</title>
+
+  <para>While convenient for typical uses, the <code>variant</code> class
+    template's variadic template parameter list is limiting in two significant
+    dimensions. First, due to the lack of support for true variadic template 
+    parameter lists in C++, the number of parameters must be limited to some
+    implementation-defined maximum (namely,
+    <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>).
+    Second, the nature of parameter lists in general makes compile-time
+    manipulation of the lists excessively difficult.</para>
+
+  <para>To solve these problems,
+    <code>make_variant_over&lt; <emphasis>Sequence</emphasis> &gt;</code>
+    exposes a <code>variant</code> whose bounded types are the elements of
+    <code>Sequence</code> (where <code>Sequence</code> is any type fulfilling
+    the requirements of <libraryname>MPL</libraryname>'s
+    <emphasis>Sequence</emphasis> concept). For instance,
+
+<programlisting>typedef <classname>mpl::vector</classname>&lt; std::string &gt; types_initial;
+typedef <classname>mpl::push_front</classname>&lt; types_initial, int &gt;::type types;
+
+<classname>boost::make_variant_over</classname>&lt; types &gt;::type v1;</programlisting>
+
+    behaves equivalently to
+
+<programlisting><classname>boost::variant</classname>&lt; int, std::string &gt; v2;</programlisting>
+
+  </para>
+
+  <para><emphasis role="bold">Portability</emphasis>: Unfortunately, due to
+    standard conformance issues in several compilers,
+    <code>make_variant_over</code> is not universally available. On these
+    compilers the library indicates its lack of support for the syntax via the
+    definition of the preprocessor symbol
+    <code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>.</para>
+
+</section>
+
+<section id="variant.tutorial.recursive">
+  <title>Recursive <code>variant</code> types</title>
+
+  <para>Recursive types facilitate the construction of complex semantics from
+    simple syntax. For instance, nearly every programmer is familiar with the
+    canonical definition of a linked list implementation, whose simple
+    definition allows sequences of unlimited length:
+
+<programlisting>template &lt;typename T&gt;
+struct list_node
+{
+    T data;
+    list_node * next;
+};</programlisting>
+
+  </para>
+
+  <para>The nature of <code>variant</code> as a generic class template
+    unfortunately precludes the straightforward construction of recursive
+    <code>variant</code> types. Consider the following attempt to construct
+    a structure for simple mathematical expressions:
+
+    <programlisting>struct add;
+struct sub;
+template &lt;typename OpTag&gt; struct binary_op;
+
+typedef <classname>boost::variant</classname>&lt;
+      int
+    , binary_op&lt;add&gt;
+    , binary_op&lt;sub&gt;
+    > expression;
+
+template &lt;typename OpTag&gt;
+struct binary_op
+{
+    expression left;  // <emphasis>variant instantiated here...</emphasis>
+    expression right;
+
+    binary_op( const expression &amp; lhs, const expression &amp; rhs )
+        : left(lhs), right(rhs)
+    {
+    }
+
+}; // <emphasis>...but binary_op not complete until here!</emphasis></programlisting>
+
+  </para>
+
+  <para>While well-intentioned, the above approach will not compile because
+    <code>binary_op</code> is still incomplete when the <code>variant</code>
+    type <code>expression</code> is instantiated. Further, the approach suffers
+    from a more significant logical flaw: even if C++ syntax were different
+    such that the above example could be made to &quot;work,&quot;
+    <code>expression</code> would need to be of infinite size, which is
+    clearly impossible.</para>
+
+  <para>To overcome these difficulties, <code>variant</code> includes special
+    support for the
+    <code><classname>boost::recursive_wrapper</classname></code> class
+    template, which breaks the circular dependency at the heart of these
+    problems. Further,
+    <code><classname>boost::make_recursive_variant</classname></code> provides
+    a more convenient syntax for declaring recursive <code>variant</code>
+    types. Tutorials for use of these facilities is described in
+    <xref linkend="variant.tutorial.recursive.recursive-wrapper"/> and
+    <xref linkend="variant.tutorial.recursive.recursive-variant"/>.</para>
+
+<section id="variant.tutorial.recursive.recursive-wrapper">
+  <title>Recursive types with <code>recursive_wrapper</code></title>
+
+  <para>The following example demonstrates how <code>recursive_wrapper</code>
+    could be used to solve the problem presented in
+    <xref linkend="variant.tutorial.recursive"/>:
+
+    <programlisting>typedef <classname>boost::variant</classname>&lt;
+      int
+    , <classname>boost::recursive_wrapper</classname>&lt; binary_op&lt;add&gt; &gt;
+    , <classname>boost::recursive_wrapper</classname>&lt; binary_op&lt;sub&gt; &gt;
+    &gt; expression;</programlisting>
+
+  </para>
+
+  <para>Because <code>variant</code> provides special support for
+    <code>recursive_wrapper</code>, clients may treat the resultant
+    <code>variant</code> as though the wrapper were not present. This is seen
+    in the implementation of the following visitor, which calculates the value
+    of an <code>expression</code> without any reference to
+    <code>recursive_wrapper</code>:
+
+    <programlisting>class calculator : public <classname>boost::static_visitor&lt;int&gt;</classname>
+{
+public:
+
+    int operator()(int value) const
+    {
+        return value;
+    }
+
+    int operator()(const binary_op&lt;add&gt; &amp; binary) const
+    {
+        return <functionname>boost::apply_visitor</functionname>( calculator(), binary.left )
+             + <functionname>boost::apply_visitor</functionname>( calculator(), binary.right );
+    }
+
+    int operator()(const binary_op&lt;sub&gt; &amp; binary) const
+    {
+        return <functionname>boost::apply_visitor</functionname>( calculator(), binary.left )
+             - <functionname>boost::apply_visitor</functionname>( calculator(), binary.right );
+    }
+
+};</programlisting>
+
+  </para>
+  
+  <para>Finally, we can demonstrate <code>expression</code> in action:
+  
+    <programlisting>void f()
+{
+    // result = ((7-3)+8) = 12
+    expression result(
+        binary_op&lt;add&gt;(
+            binary_op&lt;sub&gt;(7,3)
+          , 8
+          )
+      );
+
+    assert( <functionname>boost::apply_visitor</functionname>(calculator(),result) == 12 );
+}</programlisting>
+
+  </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">
+  <title>Recursive types with <code>make_recursive_variant</code></title>
+
+  <para>For some applications of recursive <code>variant</code> types, a user
+    may be able to sacrifice the full flexibility of using
+    <code>recursive_wrapper</code> with <code>variant</code> for the following
+    convenient syntax:
+
+<programlisting>typedef <classname>boost::make_recursive_variant</classname>&lt;
+      int
+    , std::vector&lt; boost::recursive_variant_ &gt;
+    &gt;::type int_tree_t;</programlisting>
+
+  </para>
+
+  <para>Use of the resultant <code>variant</code> type is as expected:
+
+<programlisting>std::vector&lt; int_tree_t &gt; subresult;
+subresult.push_back(3);
+subresult.push_back(5);
+
+std::vector&lt; int_tree_t &gt; result;
+result.push_back(1);
+result.push_back(subresult);
+result.push_back(7);
+
+int_tree_t var(result);</programlisting>
+
+  </para>
+
+  <para>To be clear, one might represent the resultant content of
+    <code>var</code> as <code>( 1 ( 3 5 ) 7 )</code>.</para>
+
+  <para>Finally, note that a type sequence can be used to specify the bounded
+    types of a recursive <code>variant</code> via the use of
+    <code><classname>boost::make_recursive_variant_over</classname></code>,
+    whose semantics are the same as <code>make_variant_over</code> (which is
+    described in <xref linkend="variant.tutorial.over-sequence"/>).</para>
+
+  <para><emphasis role="bold">Portability</emphasis>: Unfortunately, due to
+    standard conformance issues in several compilers,
+    <code>make_recursive_variant</code> is not universally supported. On these
+    compilers the library indicates its lack of support via the definition
+    of the preprocessor symbol
+    <code><macroname>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</macroname></code>.
+    Thus, unless working with highly-conformant compilers, maximum portability
+    will be achieved by instead using <code>recursive_wrapper</code>, as
+    described in
+    <xref linkend="variant.tutorial.recursive.recursive-wrapper"/>.</para>
+
+</section>
+
+</section> <!--/tutorial.recursive-->
+
+<section id="variant.tutorial.binary-visitation">
+  <title>Binary visitation</title>
+
+  <para>As the tutorial above demonstrates, visitation is a powerful mechanism
+    for manipulating <code>variant</code> content. Binary visitation further
+    extends the power and flexibility of visitation by allowing simultaneous
+    visitation of the content of two different <code>variant</code>
+    objects.</para>
+
+  <para>Notably this feature requires that binary visitors are incompatible
+    with the visitor objects discussed in the tutorial above, as they must
+    operate on two arguments. The following demonstrates the implementation of
+    a binary visitor:
+
+<programlisting>class are_strict_equals
+    : public <classname>boost::static_visitor</classname>&lt;bool&gt;
+{
+public:
+
+    template &lt;typename T, typename U&gt;
+    bool operator()( const T &amp;, const U &amp; ) const
+    {
+        return false; // cannot compare different types
+    }
+
+    template &lt;typename T&gt;
+    bool operator()( const T &amp; lhs, const T &amp; rhs ) const
+    {
+        return lhs == rhs;
+    }
+
+};</programlisting>
+
+  </para>
+
+  <para>As expected, the visitor is applied to two <code>variant</code>
+    arguments by means of <code>apply_visitor</code>:
+
+<programlisting><classname>boost::variant</classname>&lt; int, std::string &gt; v1( "hello" );
+
+<classname>boost::variant</classname>&lt; double, std::string &gt; v2( "hello" );
+assert( <functionname>boost::apply_visitor</functionname>(are_strict_equals(), v1, v2) );
+
+<classname>boost::variant</classname>&lt; int, const char * &gt; v3( "hello" );
+assert( !<functionname>boost::apply_visitor</functionname>(are_strict_equals(), v1, v3) );</programlisting>
+
+  </para>
+
+  <para>Finally, we must note that the function object returned from the
+    &quot;delayed&quot; form of
+    <code><functionname>apply_visitor</functionname></code> also supports
+    binary visitation, as the following demonstrates:
+
+<programlisting>typedef <classname>boost::variant</classname>&lt;double, std::string&gt; my_variant;
+
+std::vector&lt; my_variant &gt; seq1;
+seq1.push_back("pi is close to ");
+seq1.push_back(3.14);
+
+std::list&lt; my_variant &gt; seq2;
+seq2.push_back("pi is close to ");
+seq2.push_back(3.14);
+
+are_strict_equals visitor;
+assert( std::equal(
+      seq1.begin(), seq1.end(), seq2.begin()
+    , <functionname>boost::apply_visitor</functionname>( visitor )
+    ) );</programlisting>
+
+  </para>
+
+</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(true), v1(1), v2(2.0);
+
+assert(
+    <functionname>boost::apply_visitor</functionname>(if_visitor(), v0, v1, v2)
+    ==
+    arithmetics_t(1)
+);
+</programlisting>
+  </para>
+
+  <para>Finally, we must note that multi visitation does not support 
+    &quot;delayed&quot; form of
+    <code><functionname>apply_visitor</functionname> if
+    <macroname>BOOST_VARIANT_DO_NOT_USE_VARIADIC_TEMPLATES</macroname> is defined</code>.
+  </para>
+
+</section>
+
+
+</section>

libs/variant/doc/tutorial/basic.xml

@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<!--
+    Copyright 2003, Eric Friedman, Itay Maman.
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section id="variant.tutorial.basic">
+  <title>Basic Usage</title>
+
+<using-namespace name="boost"/>
+<using-class name="boost::variant"/>
+
+<para>A discriminated union container on some set of types is defined by
+  instantiating the <code><classname>boost::variant</classname></code> class
+  template with the desired types. These types are called
+  <emphasis role="bold">bounded types</emphasis> and are subject to the
+  requirements of the
+  <link linkend="variant.concepts.bounded-type"><emphasis>BoundedType</emphasis></link>
+  concept. Any number of bounded types may be specified, up to some
+  implementation-defined limit (see 
+  <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>).</para>
+
+<para>For example, the following declares a discriminated union container on
+  <code>int</code> and <code>std::string</code>:
+
+<programlisting><classname>boost::variant</classname>&lt; int, std::string &gt; v;</programlisting>
+
+</para>
+
+<para>By default, a <code>variant</code> default-constructs its first
+  bounded type, so <code>v</code> initially contains <code>int(0)</code>. If
+  this is not desired, or if the first bounded type is not
+  default-constructible, a <code>variant</code> can be constructed
+  directly from any value convertible to one of its bounded types. Similarly,
+  a <code>variant</code> can be assigned any value convertible to one of its
+  bounded types, as demonstrated in the following:
+
+<programlisting>v = "hello";</programlisting>
+
+</para>
+
+<para>Now <code>v</code> contains a <code>std::string</code> equal to
+  <code>"hello"</code>. We can demonstrate this by
+  <emphasis role="bold">streaming</emphasis>&nbsp;<code>v</code> to standard
+  output:
+
+<programlisting>std::cout &lt;&lt; v &lt;&lt; std::endl;</programlisting>
+
+</para>
+
+<para>Usually though, we would like to do more with the content of a
+  <code>variant</code> than streaming. Thus, we need some way to access the
+  contained value. There are two ways to accomplish this:
+  <code><functionname>apply_visitor</functionname></code>, which is safest
+  and very powerful, and
+  <code><functionname>get</functionname>&lt;T&gt;</code>, which is
+  sometimes more convenient to use.</para>
+
+<para>For instance, suppose we wanted to concatenate to the string contained
+  in <code>v</code>. With <emphasis role="bold">value retrieval</emphasis>
+  by <code><functionname>get</functionname></code>, this may be accomplished
+  quite simply, as seen in the following:
+
+<programlisting>std::string&amp; str = <functionname>boost::get</functionname>&lt;std::string&gt;(v);
+str += " world! ";</programlisting>
+
+</para>
+
+<para>As desired, the <code>std::string</code> contained by <code>v</code> now
+  is equal to <code>"hello world! "</code>. Again, we can demonstrate this by
+  streaming <code>v</code> to standard output:
+
+<programlisting>std::cout &lt;&lt; v &lt;&lt; std::endl;</programlisting>
+
+</para>
+
+<para>While use of <code>get</code> is perfectly acceptable in this trivial
+  example, <code>get</code> generally suffers from several significant
+  shortcomings. For instance, if we were to write a function accepting a
+  <code>variant&lt;int, std::string&gt;</code>, we would not know whether
+  the passed <code>variant</code> contained an <code>int</code> or a
+  <code>std::string</code>. If we insisted upon continued use of
+  <code>get</code>, we would need to query the <code>variant</code> for its
+  contained type. The following function, which &quot;doubles&quot; the
+  content of the given <code>variant</code>, demonstrates this approach:
+
+<programlisting>void times_two( boost::variant&lt; int, std::string &gt; &amp; operand )
+{
+    if ( int* pi = <functionname>boost::get</functionname>&lt;int&gt;( &amp;operand ) )
+        *pi *= 2;
+    else if ( std::string* pstr = <functionname>boost::get</functionname>&lt;std::string&gt;( &amp;operand ) )
+        *pstr += *pstr;
+}</programlisting>
+
+</para>
+
+<para>However, such code is quite brittle, and without careful attention will
+  likely lead to the introduction of subtle logical errors detectable only at
+  runtime. For instance, consider if we wished to extend
+  <code>times_two</code> to operate on a <code>variant</code> with additional
+  bounded types. Specifically, let's add
+  <code>std::complex&lt;double&gt;</code> to the set. Clearly, we would need
+  to at least change the function declaration:
+
+<programlisting>void times_two( boost::variant&lt; int, std::string, std::complex&lt;double&gt; &gt; &amp; operand )
+{
+    // as above...?
+}</programlisting>
+
+</para>
+
+<para>Of course, additional changes are required, for currently if the passed
+  <code>variant</code> in fact contained a <code>std::complex</code> value,
+  <code>times_two</code> would silently return -- without any of the desired
+  side-effects and without any error. In this case, the fix is obvious. But in
+  more complicated programs, it could take considerable time to identify and
+  locate the error in the first place.</para>
+
+<para>Thus, real-world use of <code>variant</code> typically demands an access
+  mechanism more robust than <code>get</code>. For this reason,
+  <code>variant</code> supports compile-time checked
+  <emphasis role="bold">visitation</emphasis> via
+  <code><functionname>apply_visitor</functionname></code>. Visitation requires
+  that the programmer explicitly handle (or ignore) each bounded type. Failure
+  to do so results in a compile-time error.</para>
+
+<para>Visitation of a <code>variant</code> requires a visitor object. The
+  following demonstrates one such implementation of a visitor implementating
+  behavior identical to <code>times_two</code>:
+
+<programlisting>class times_two_visitor
+    : public <classname>boost::static_visitor</classname>&lt;&gt;
+{
+public:
+
+    void operator()(int &amp; i) const
+    {
+        i *= 2;
+    }
+
+    void operator()(std::string &amp; str) const
+    {
+        str += str;
+    }
+
+};</programlisting>
+
+</para>
+
+<para>With the implementation of the above visitor, we can then apply it to
+  <code>v</code>, as seen in the following:
+
+<programlisting><functionname>boost::apply_visitor</functionname>( times_two_visitor(), v );</programlisting>
+
+</para>
+
+<para>As expected, the content of <code>v</code> is now a
+  <code>std::string</code> equal to <code>"hello world! hello world! "</code>.
+  (We'll skip the verification this time.)</para>
+
+<para>In addition to enhanced robustness, visitation provides another
+  important advantage over <code>get</code>: the ability to write generic
+  visitors. For instance, the following visitor will &quot;double&quot; the
+  content of <emphasis>any</emphasis>&nbsp;<code>variant</code> (provided its
+  bounded types each support operator+=):
+
+<programlisting>class times_two_generic
+    : public <classname>boost::static_visitor</classname>&lt;&gt;
+{
+public:
+
+    template &lt;typename T&gt;
+    void operator()( T &amp; operand ) const
+    {
+        operand += operand;
+    }
+
+};</programlisting>
+
+</para>
+
+<para>Again, <code>apply_visitor</code> sets the wheels in motion:
+
+<programlisting><functionname>boost::apply_visitor</functionname>( times_two_generic(), v );</programlisting>
+
+</para>
+
+<para>While the initial setup costs of visitation may exceed that required for
+  <code>get</code>, the benefits quickly become significant. Before concluding
+  this section, we should explore one last benefit of visitation with
+  <code>apply_visitor</code>:
+  <emphasis role="bold">delayed visitation</emphasis>. Namely, a special form
+  of <code>apply_visitor</code> is available that does not immediately apply
+  the given visitor to any <code>variant</code> but rather returns a function
+  object that operates on any <code>variant</code> given to it. This behavior
+  is particularly useful when operating on sequences of <code>variant</code>
+  type, as the following demonstrates:
+
+<programlisting>std::vector&lt; <classname>boost::variant</classname>&lt;int, std::string&gt; &gt; vec;
+vec.push_back( 21 );
+vec.push_back( "hello " );
+
+times_two_generic visitor;
+std::for_each(
+      vec.begin(), vec.end()
+   , <functionname>boost::apply_visitor</functionname>(visitor)
+   );</programlisting>
+
+</para>
+
+</section>

libs/variant/doc/tutorial/tutorial.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<!--
+    Copyright 2003, Eric Friedman, Itay Maman.
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section xmlns:xi="http://www.w3.org/2001/XInclude" id="variant.tutorial">
+
+<title>Tutorial</title>
+  <xi:include href="basic.xml"/>
+  <xi:include href="advanced.xml"/>
+
+</section>