1 <?xml version=
"1.0" encoding=
"utf-8"?>
2 <!DOCTYPE header PUBLIC
"-//Boost//DTD BoostBook XML V1.0//EN"
3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
5 Copyright 2003, Eric Friedman, Itay Maman.
6 Copyright 2013-2014 Antony Polukhin.
8 Distributed under the Boost Software License, Version 1.0. (See accompanying
9 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
11 <header name=
"boost/variant/apply_visitor.hpp">
12 <namespace name=
"boost">
13 <class name=
"apply_visitor_delayed_t">
14 <purpose>Adapts a visitor for use as a function object.
</purpose>
16 <simpara>Adapts the function given at construction for use as a
17 function object. This is useful, for example, when one needs to
18 operate on each element of a sequence of variant objects using a
19 standard library algorithm such as
20 <code>std::for_each
</code>.
</simpara>
21 <simpara>See the
"visitor-only
" form of
22 <code><functionname>apply_visitor
</functionname></code> for a simple
23 way to create
<code>apply_visitor_delayed_t
</code> objects.
</simpara>
24 <simpara>See
<code><classname>apply_visitor_delayed_cpp14_t
</classname></code>
25 which is used on C++
14 compatible compilers when
<code>Visitor
</code> has no
26 <code>result_type
</code> typedef.
</simpara>
30 <template-type-parameter name=
"Visitor"/>
33 <typedef name=
"result_type">
34 <type>typename Visitor::result_type
</type>
37 <constructor specifiers=
"explicit">
38 <parameter name=
"visitor">
39 <paramtype>Visitor
&</paramtype>
43 <simpara>Constructs the function object with the given
48 <method-group name=
"function object interface">
49 <overloaded-method name=
"operator()">
52 <template-type-parameter name=
"... Variant"/>
55 <type>result_type
</type>
56 <parameter name=
"operand">
57 <paramtype>Variant
&...
</paramtype>
64 <template-type-parameter name=
"Variant"/>
67 <type>result_type
</type>
68 <parameter name=
"operand">
69 <paramtype>Variant
&</paramtype>
75 <template-type-parameter name=
"Variant1"/>
76 <template-type-parameter name=
"Variant2"/>
79 <type>result_type
</type>
80 <parameter name=
"operand1">
81 <paramtype>Variant1
&</paramtype>
83 <parameter name=
"operand2">
84 <paramtype>Variant2
&</paramtype>
88 <purpose>Function call operator.
</purpose>
91 <code><functionname>apply_visitor
</functionname></code> on the
92 stored visitor using the given operands.
</simpara>
94 <notes>Version with variadic templates is used by default if
95 <macroname>BOOST_VARIANT_DO_NOT_USE_VARIADIC_TEMPLATES
</macroname> is not defined.
</notes>
100 <class name=
"apply_visitor_delayed_cpp14_t">
101 <purpose>Adapts a visitor for use as a function object.
</purpose>
103 <simpara>Adapts the function given at construction for use as a
104 function object. This is useful, for example, when one needs to
105 operate on each element of a sequence of variant objects using a
106 standard library algorithm such as
107 <code>std::for_each
</code>.
</simpara>
108 <simpara>See the
"visitor-only
" form of
109 <code><functionname>apply_visitor
</functionname></code> for a simple
110 way to create
<code>apply_visitor_delayed_t
</code> objects.
</simpara>
111 <simpara>See
<code><classname>apply_visitor_delayed_t
</classname></code>
112 which is used when
<code>Visitor
</code> has
<code>result_type
</code>
114 <simpara>Available only if macro
115 <macroname>BOOST_VARIANT_DO_NOT_USE_VARIADIC_TEMPLATES
</macroname> is not defined and
116 compiler supports
<code>decltype(auto)
</code> and
<code>decltype(some-expression)
</code>.
</simpara>
120 <template-type-parameter name=
"Visitor"/>
123 <constructor specifiers=
"explicit">
124 <parameter name=
"visitor">
125 <paramtype>Visitor
&</paramtype>
129 <simpara>Constructs the function object with the given
134 <method-group name=
"function object interface">
135 <overloaded-method name=
"operator()">
138 <template-type-parameter name=
"... Variant"/>
141 <type>decltype(auto)
</type>
142 <parameter name=
"operand">
143 <paramtype>Variant
&...
</paramtype>
147 <purpose>Function call operator.
</purpose>
150 <code><functionname>apply_visitor
</functionname></code> on the
151 stored visitor using the given operands.
</simpara>
157 <overloaded-function name=
"apply_visitor">
160 <template-type-parameter name=
"Visitor"/>
161 <template-type-parameter name=
"Variant"/>
164 <type>typename Visitor::result_type
</type>
166 <parameter name=
"visitor">
167 <paramtype>Visitor
&</paramtype>
169 <parameter name=
"operand">
170 <paramtype>Variant
&</paramtype>
176 <template-type-parameter name=
"Visitor"/>
177 <template-type-parameter name=
"Variant"/>
180 <type>typename Visitor::result_type
</type>
182 <parameter name=
"visitor">
183 <paramtype>const Visitor
&</paramtype>
185 <parameter name=
"operand">
186 <paramtype>Variant
&</paramtype>
192 <template-type-parameter name=
"BinaryVisitor"/>
193 <template-type-parameter name=
"Variant1"/>
194 <template-type-parameter name=
"Variant2"/>
197 <type>typename BinaryVisitor::result_type OR decltype(auto)
</type>
199 <parameter name=
"visitor">
200 <paramtype>BinaryVisitor
&</paramtype>
202 <parameter name=
"operand1">
203 <paramtype>Variant1
&</paramtype>
205 <parameter name=
"operand2">
206 <paramtype>Variant2
&</paramtype>
212 <template-type-parameter name=
"BinaryVisitor"/>
213 <template-type-parameter name=
"Variant1"/>
214 <template-type-parameter name=
"Variant2"/>
217 <type>typename BinaryVisitor::result_type OR decltype(auto)
</type>
219 <parameter name=
"visitor">
220 <paramtype>const BinaryVisitor
&</paramtype>
222 <parameter name=
"operand1">
223 <paramtype>Variant1
&</paramtype>
225 <parameter name=
"operand2">
226 <paramtype>Variant2
&</paramtype>
232 <template-type-parameter name=
"MultiVisitor"/>
233 <template-type-parameter name=
"Variant1"/>
234 <template-type-parameter name=
"Variant2"/>
235 <template-type-parameter name=
"Variant3"/>
238 <type>typename MultiVisitor::result_type OR decltype(auto)
</type>
240 <parameter name=
"visitor">
241 <paramtype>MultiVisitor
&</paramtype>
243 <parameter name=
"operand1">
244 <paramtype>Variant1
&</paramtype>
246 <parameter name=
"operand2">
247 <paramtype>Variant2
&</paramtype>
249 <parameter name=
"operand3">
250 <paramtype>Variant3
&</paramtype>
252 <parameter name=
"other_operands">
253 <paramtype>...
</paramtype>
259 <template-type-parameter name=
"MultiVisitor"/>
260 <template-type-parameter name=
"Variant1"/>
261 <template-type-parameter name=
"Variant2"/>
262 <template-type-parameter name=
"Variant3"/>
265 <type>typename MultiVisitor::result_type OR decltype(auto)
</type>
267 <parameter name=
"visitor">
268 <paramtype>const MultiVisitor
&</paramtype>
270 <parameter name=
"operand1">
271 <paramtype>Variant1
&</paramtype>
273 <parameter name=
"operand2">
274 <paramtype>Variant2
&</paramtype>
276 <parameter name=
"operand3">
277 <paramtype>Variant3
&</paramtype>
279 <parameter name=
"other_operands">
280 <paramtype>...
</paramtype>
286 <template-type-parameter name=
"Visitor"/>
289 <type><classname>apply_visitor_delayed_t
</classname><Visitor
></type>
291 <parameter name=
"visitor">
292 <paramtype>Visitor
&</paramtype>
299 <template-type-parameter name=
"Visitor"/>
302 <type><classname>apply_visitor_delayed_cpp14_t
</classname><Visitor
></type>
304 <parameter name=
"visitor">
305 <paramtype>Visitor
&</paramtype>
310 <simpara>Allows compile-time checked type-safe application of the
311 given visitor to the content of the given variant, ensuring that all
312 types are handled by the visitor.
</simpara>
316 <simpara>The behavior of
<code>apply_visitor
</code> is dependent on
317 the number of arguments on which it operates (i.e., other than the
318 visitor). The function behaves as follows:
321 <listitem>Overloads accepting one operand invoke the unary function
322 call operator of the given visitor on the content of the given
323 <code><classname>variant
</classname></code> operand.
</listitem>
325 <listitem>Overloads accepting two operands invoke the binary
326 function call operator of the given visitor on the content of
327 the given
<code><classname>variant
</classname></code>
330 <listitem>Overloads accepting three or more operands invoke the
331 function call operator of the given visitor on the content of
332 the given
<code><classname>variant
</classname></code>
333 operands. Maximum amount of parameters controlled by
334 <code><emphasis role=
"bold"><macroname>BOOST_VARAINT_MAX_MULTIVIZITOR_PARAMS
</macroname></emphasis></code>
335 macro. Those functions are actually defined in a header
<code>boost/variant/multivisitors.hpp
</code>
336 (See
<xref linkend=
"header.boost.variant.multivisitors_hpp"/>). That header must be manually included
337 if multi visitors are meant for use.
</listitem>
339 <listitem>The overloads accepting only a visitor return a
340 <classname alt=
"boost::apply_visitor_delayed_t">C++
03 compatible generic function object
</classname>
342 <classname alt=
"boost::apply_visitor_delayed_cpp14_t">C++
14 compatible generic function object
</classname>
343 that accepts either one, two or arbitrary count of arguments and invoke
344 <code><functionname>apply_visitor
</functionname></code> using
345 these arguments and
<code>visitor
</code>, thus behaving as
346 specified above. (This behavior is particularly useful, for
347 example, when one needs to operate on each element of a sequence
348 of variant objects using a standard library
349 algorithm.)
</listitem>
356 <simpara>The overloads acccepting operands return the result of
357 applying the given visitor to the content of the given operands.
358 The overload accepting only a visitor return a function object, thus
359 delaying application of the visitor to any operands.
</simpara>
363 <simpara>The given visitor must fulfill the
364 <link linkend=
"variant.concepts.static-visitor"><emphasis>StaticVisitor
</emphasis></link>
365 concept requirements with respect to each of the bounded types of the
366 given
<code>variant
</code>.
</simpara>
370 <simpara>The overloads accepting operands throw only if the given
371 visitor throws when applied. The overload accepting only a visitor
372 will not throw. (Note, however, that the returned
373 <classname alt=
"boost::apply_visitor_delayed_t">function object
</classname>
374 may throw when invoked.)
</simpara>
376 </overloaded-function>