123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379 |
- <?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-2019 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 "visitor-only" 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 &</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&...</paramtype>
- </parameter>
- </signature>
- <signature>
- <template>
- <template-type-parameter name="Variant"/>
- </template>
- <type>result_type</type>
- <parameter name="operand">
- <paramtype>Variant &</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 &</paramtype>
- </parameter>
- <parameter name="operand2">
- <paramtype>Variant2 &</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 "visitor-only" 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 &</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&...</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 &</paramtype>
- </parameter>
- <parameter name="operand">
- <paramtype>Variant&&</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 &</paramtype>
- </parameter>
- <parameter name="operand">
- <paramtype>Variant&&</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 &</paramtype>
- </parameter>
- <parameter name="operand1">
- <paramtype>Variant1&&</paramtype>
- </parameter>
- <parameter name="operand2">
- <paramtype>Variant2&&</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 &</paramtype>
- </parameter>
- <parameter name="operand1">
- <paramtype>Variant1&&</paramtype>
- </parameter>
- <parameter name="operand2">
- <paramtype>Variant2&&</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 &</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 OR decltype(auto)</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>
- <type><classname>apply_visitor_delayed_t</classname><Visitor></type>
- <parameter name="visitor">
- <paramtype>Visitor &</paramtype>
- </parameter>
- </signature>
- <signature>
- <template>
- <template-type-parameter name="Visitor"/>
- </template>
- <type><classname>apply_visitor_delayed_cpp14_t</classname><Visitor></type>
- <parameter name="visitor">
- <paramtype>Visitor &</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). If your compiler does not support the rvalue references or reference qualifiers then all the
- forwarding references from above degrade to non const lvalue reference. 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>
|