path: root/libs/variant/doc/reference/apply_visitor.xml

<?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">
<!--
    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)
-->
<header name="boost/variant/apply_visitor.hpp">
  <namespace name="boost">
    <class name="apply_visitor_delayed_t">
      <purpose>Adapts a visitor for use as a function object.</purpose>
      <description>
        <simpara>Adapts the function given at construction for use as a
          function object. This is useful, for example, when one needs to
          operate on each element of a sequence of variant objects using a
          standard library algorithm such as
          <code>std::for_each</code>.</simpara>
        <simpara>See the &quot;visitor-only&quot; form of
          <code><functionname>apply_visitor</functionname></code> for a simple
          way to create <code>apply_visitor_delayed_t</code> objects.</simpara>
        <simpara>See <code><classname>apply_visitor_delayed_cpp14_t</classname></code>
            which is used on C++14 compatible compilers when <code>Visitor</code> has no
            <code>result_type</code> typedef.</simpara>
      </description>

      <template>
        <template-type-parameter name="Visitor"/>
      </template>

      <typedef name="result_type">
        <type>typename Visitor::result_type</type>
      </typedef>

      <constructor specifiers="explicit">
        <parameter name="visitor">
          <paramtype>Visitor &amp;</paramtype>
        </parameter>

        <effects>
          <simpara>Constructs the function object with the given
            visitor.</simpara>
        </effects>
      </constructor>

      <method-group name="function object interface">
        <overloaded-method name="operator()">
          <signature>
            <template>
              <template-type-parameter name="... Variant"/>
            </template>

            <type>result_type</type>
            <parameter name="operand">
              <paramtype>Variant&amp;...</paramtype>
            </parameter>
          </signature>


          <signature>
            <template>
              <template-type-parameter name="Variant"/>
            </template>

            <type>result_type</type>
            <parameter name="operand">
              <paramtype>Variant &amp;</paramtype>
            </parameter>
          </signature>

          <signature>
            <template>
              <template-type-parameter name="Variant1"/>
              <template-type-parameter name="Variant2"/>
            </template>

            <type>result_type</type>
            <parameter name="operand1">
              <paramtype>Variant1 &amp;</paramtype>
            </parameter>
            <parameter name="operand2">
              <paramtype>Variant2 &amp;</paramtype>
            </parameter>
          </signature>

          <purpose>Function call operator.</purpose>
          <description>
            <simpara>Invokes
            <code><functionname>apply_visitor</functionname></code> on the
            stored visitor using the given operands.</simpara>
          </description>
          <notes>Version with variadic templates is used by default if
          <macroname>BOOST_VARIANT_DO_NOT_USE_VARIADIC_TEMPLATES</macroname> is not defined.</notes>
        </overloaded-method>
      </method-group>
    </class>

    <class name="apply_visitor_delayed_cpp14_t">
      <purpose>Adapts a visitor for use as a function object.</purpose>
      <description>
        <simpara>Adapts the function given at construction for use as a
          function object. This is useful, for example, when one needs to
          operate on each element of a sequence of variant objects using a
          standard library algorithm such as
          <code>std::for_each</code>.</simpara>
        <simpara>See the &quot;visitor-only&quot; form of
          <code><functionname>apply_visitor</functionname></code> for a simple
          way to create <code>apply_visitor_delayed_t</code> objects.</simpara>
        <simpara>See <code><classname>apply_visitor_delayed_t</classname></code>
            which is used when <code>Visitor</code> has <code>result_type</code>
            typedef.</simpara>
        <simpara>Available only if macro
          <macroname>BOOST_VARIANT_DO_NOT_USE_VARIADIC_TEMPLATES</macroname> is not defined and
          compiler supports <code>decltype(auto)</code> and <code>decltype(some-expression)</code>.</simpara>
      </description>

      <template>
        <template-type-parameter name="Visitor"/>
      </template>

      <constructor specifiers="explicit">
        <parameter name="visitor">
          <paramtype>Visitor &amp;</paramtype>
        </parameter>

        <effects>
          <simpara>Constructs the function object with the given
            visitor.</simpara>
        </effects>
      </constructor>

      <method-group name="function object interface">
        <overloaded-method name="operator()">
          <signature>
            <template>
              <template-type-parameter name="... Variant"/>
            </template>

            <type>decltype(auto)</type>
            <parameter name="operand">
              <paramtype>Variant&amp;...</paramtype>
            </parameter>
          </signature>

          <purpose>Function call operator.</purpose>
          <description>
            <simpara>Invokes
            <code><functionname>apply_visitor</functionname></code> on the
            stored visitor using the given operands.</simpara>
          </description>
        </overloaded-method>
      </method-group>
    </class>

    <overloaded-function name="apply_visitor">
      <signature>
        <template>
          <template-type-parameter name="Visitor"/>
          <template-type-parameter name="Variant"/>
        </template>

        <type>typename Visitor::result_type</type>

        <parameter name="visitor">
          <paramtype>Visitor &amp;</paramtype>
        </parameter>
        <parameter name="operand">
          <paramtype>Variant &amp;</paramtype>
        </parameter>
      </signature>

      <signature>
        <template>
          <template-type-parameter name="Visitor"/>
          <template-type-parameter name="Variant"/>
        </template>

        <type>typename Visitor::result_type</type>

        <parameter name="visitor">
          <paramtype>const Visitor &amp;</paramtype>
        </parameter>
        <parameter name="operand">
          <paramtype>Variant &amp;</paramtype>
        </parameter>
      </signature>

      <signature>
        <template>
          <template-type-parameter name="BinaryVisitor"/>
          <template-type-parameter name="Variant1"/>
          <template-type-parameter name="Variant2"/>
        </template>

        <type>typename BinaryVisitor::result_type OR decltype(auto)</type>

        <parameter name="visitor">
          <paramtype>BinaryVisitor &amp;</paramtype>
        </parameter>
        <parameter name="operand1">
          <paramtype>Variant1 &amp;</paramtype>
        </parameter>
        <parameter name="operand2">
          <paramtype>Variant2 &amp;</paramtype>
        </parameter>
      </signature>

      <signature>
        <template>
          <template-type-parameter name="BinaryVisitor"/>
          <template-type-parameter name="Variant1"/>
          <template-type-parameter name="Variant2"/>
        </template>

        <type>typename BinaryVisitor::result_type OR decltype(auto)</type>

        <parameter name="visitor">
          <paramtype>const BinaryVisitor &amp;</paramtype>
        </parameter>
        <parameter name="operand1">
          <paramtype>Variant1 &amp;</paramtype>
        </parameter>
        <parameter name="operand2">
          <paramtype>Variant2 &amp;</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 OR decltype(auto)</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 OR decltype(auto)</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>

        <type><classname>apply_visitor_delayed_t</classname>&lt;Visitor&gt;</type>

        <parameter name="visitor">
          <paramtype>Visitor &amp;</paramtype>
        </parameter>
      </signature>


      <signature>
        <template>
          <template-type-parameter name="Visitor"/>
        </template>

        <type><classname>apply_visitor_delayed_cpp14_t</classname>&lt;Visitor&gt;</type>

        <parameter name="visitor">
          <paramtype>Visitor &amp;</paramtype>
        </parameter>
      </signature>

      <purpose>
        <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.</simpara>
      </purpose>

      <description>
        <simpara>The behavior of <code>apply_visitor</code> is dependent on
        the number of arguments on which it operates (i.e., other than the
        visitor). The function behaves as follows:

          <itemizedlist>
            <listitem>Overloads accepting one operand invoke the unary function
              call operator of the given visitor on the content of the given
              <code><classname>variant</classname></code> operand.</listitem>

            <listitem>Overloads accepting two operands invoke the binary
              function call operator of the given visitor on the content of
              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 a header <code>boost/variant/multivisitors.hpp</code>
              (See <xref linkend="header.boost.variant.multivisitors_hpp"/>). That header must be manually included
              if multi visitors are meant for use.</listitem>

            <listitem>The overloads accepting only a visitor return a
              <classname alt="boost::apply_visitor_delayed_t">C++03 compatible generic function object</classname>
              or
                <classname alt="boost::apply_visitor_delayed_cpp14_t">C++14 compatible generic function object</classname>
              that accepts either one, two or arbitrary count of arguments and invoke
              <code><functionname>apply_visitor</functionname></code> using
              these arguments and <code>visitor</code>, thus behaving as
              specified above. (This behavior is particularly useful, for
              example, when one needs to operate on each element of a sequence
              of variant objects using a standard library
              algorithm.)</listitem>
          </itemizedlist>

        </simpara>
      </description>

      <returns>
        <simpara>The overloads acccepting operands return the result of
        applying the given visitor to the content of the given operands.
        The overload accepting only a visitor return a function object, thus
        delaying application of the visitor to any operands.</simpara>
      </returns>

      <requires>
        <simpara>The given visitor must fulfill the
        <link linkend="variant.concepts.static-visitor"><emphasis>StaticVisitor</emphasis></link>
        concept requirements with respect to each of the bounded types of the
        given <code>variant</code>.</simpara>
      </requires>

      <throws>
        <simpara>The overloads accepting operands throw only if the given
        visitor throws when applied. The overload accepting only a visitor
        will not throw. (Note, however, that the returned
        <classname alt="boost::apply_visitor_delayed_t">function object</classname>
        may throw when invoked.)</simpara>
      </throws>
    </overloaded-function>
  </namespace>
</header>