]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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"> | |
4 | <!-- | |
5 | Copyright 2003, Eric Friedman, Itay Maman. | |
6 | Copyright 2013-2014 Antony Polukhin. | |
7 | ||
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) | |
10 | --> | |
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> | |
15 | <description> | |
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> | |
27 | </description> | |
28 | ||
29 | <template> | |
30 | <template-type-parameter name="Visitor"/> | |
31 | </template> | |
32 | ||
33 | <typedef name="result_type"> | |
34 | <type>typename Visitor::result_type</type> | |
35 | </typedef> | |
36 | ||
37 | <constructor specifiers="explicit"> | |
38 | <parameter name="visitor"> | |
39 | <paramtype>Visitor &</paramtype> | |
40 | </parameter> | |
41 | ||
42 | <effects> | |
43 | <simpara>Constructs the function object with the given | |
44 | visitor.</simpara> | |
45 | </effects> | |
46 | </constructor> | |
47 | ||
48 | <method-group name="function object interface"> | |
49 | <overloaded-method name="operator()"> | |
50 | <signature> | |
51 | <template> | |
52 | <template-type-parameter name="... Variant"/> | |
53 | </template> | |
54 | ||
55 | <type>result_type</type> | |
56 | <parameter name="operand"> | |
57 | <paramtype>Variant&...</paramtype> | |
58 | </parameter> | |
59 | </signature> | |
60 | ||
61 | ||
62 | <signature> | |
63 | <template> | |
64 | <template-type-parameter name="Variant"/> | |
65 | </template> | |
66 | ||
67 | <type>result_type</type> | |
68 | <parameter name="operand"> | |
69 | <paramtype>Variant &</paramtype> | |
70 | </parameter> | |
71 | </signature> | |
72 | ||
73 | <signature> | |
74 | <template> | |
75 | <template-type-parameter name="Variant1"/> | |
76 | <template-type-parameter name="Variant2"/> | |
77 | </template> | |
78 | ||
79 | <type>result_type</type> | |
80 | <parameter name="operand1"> | |
81 | <paramtype>Variant1 &</paramtype> | |
82 | </parameter> | |
83 | <parameter name="operand2"> | |
84 | <paramtype>Variant2 &</paramtype> | |
85 | </parameter> | |
86 | </signature> | |
87 | ||
88 | <purpose>Function call operator.</purpose> | |
89 | <description> | |
90 | <simpara>Invokes | |
91 | <code><functionname>apply_visitor</functionname></code> on the | |
92 | stored visitor using the given operands.</simpara> | |
93 | </description> | |
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> | |
96 | </overloaded-method> | |
97 | </method-group> | |
98 | </class> | |
99 | ||
100 | <class name="apply_visitor_delayed_cpp14_t"> | |
101 | <purpose>Adapts a visitor for use as a function object.</purpose> | |
102 | <description> | |
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> | |
113 | typedef.</simpara> | |
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> | |
117 | </description> | |
118 | ||
119 | <template> | |
120 | <template-type-parameter name="Visitor"/> | |
121 | </template> | |
122 | ||
123 | <constructor specifiers="explicit"> | |
124 | <parameter name="visitor"> | |
125 | <paramtype>Visitor &</paramtype> | |
126 | </parameter> | |
127 | ||
128 | <effects> | |
129 | <simpara>Constructs the function object with the given | |
130 | visitor.</simpara> | |
131 | </effects> | |
132 | </constructor> | |
133 | ||
134 | <method-group name="function object interface"> | |
135 | <overloaded-method name="operator()"> | |
136 | <signature> | |
137 | <template> | |
138 | <template-type-parameter name="... Variant"/> | |
139 | </template> | |
140 | ||
141 | <type>decltype(auto)</type> | |
142 | <parameter name="operand"> | |
143 | <paramtype>Variant&...</paramtype> | |
144 | </parameter> | |
145 | </signature> | |
146 | ||
147 | <purpose>Function call operator.</purpose> | |
148 | <description> | |
149 | <simpara>Invokes | |
150 | <code><functionname>apply_visitor</functionname></code> on the | |
151 | stored visitor using the given operands.</simpara> | |
152 | </description> | |
153 | </overloaded-method> | |
154 | </method-group> | |
155 | </class> | |
156 | ||
157 | <overloaded-function name="apply_visitor"> | |
158 | <signature> | |
159 | <template> | |
160 | <template-type-parameter name="Visitor"/> | |
161 | <template-type-parameter name="Variant"/> | |
162 | </template> | |
163 | ||
164 | <type>typename Visitor::result_type</type> | |
165 | ||
166 | <parameter name="visitor"> | |
167 | <paramtype>Visitor &</paramtype> | |
168 | </parameter> | |
169 | <parameter name="operand"> | |
170 | <paramtype>Variant &</paramtype> | |
171 | </parameter> | |
172 | </signature> | |
173 | ||
174 | <signature> | |
175 | <template> | |
176 | <template-type-parameter name="Visitor"/> | |
177 | <template-type-parameter name="Variant"/> | |
178 | </template> | |
179 | ||
180 | <type>typename Visitor::result_type</type> | |
181 | ||
182 | <parameter name="visitor"> | |
183 | <paramtype>const Visitor &</paramtype> | |
184 | </parameter> | |
185 | <parameter name="operand"> | |
186 | <paramtype>Variant &</paramtype> | |
187 | </parameter> | |
188 | </signature> | |
189 | ||
190 | <signature> | |
191 | <template> | |
192 | <template-type-parameter name="BinaryVisitor"/> | |
193 | <template-type-parameter name="Variant1"/> | |
194 | <template-type-parameter name="Variant2"/> | |
195 | </template> | |
196 | ||
197 | <type>typename BinaryVisitor::result_type OR decltype(auto)</type> | |
198 | ||
199 | <parameter name="visitor"> | |
200 | <paramtype>BinaryVisitor &</paramtype> | |
201 | </parameter> | |
202 | <parameter name="operand1"> | |
203 | <paramtype>Variant1 &</paramtype> | |
204 | </parameter> | |
205 | <parameter name="operand2"> | |
206 | <paramtype>Variant2 &</paramtype> | |
207 | </parameter> | |
208 | </signature> | |
209 | ||
210 | <signature> | |
211 | <template> | |
212 | <template-type-parameter name="BinaryVisitor"/> | |
213 | <template-type-parameter name="Variant1"/> | |
214 | <template-type-parameter name="Variant2"/> | |
215 | </template> | |
216 | ||
217 | <type>typename BinaryVisitor::result_type OR decltype(auto)</type> | |
218 | ||
219 | <parameter name="visitor"> | |
220 | <paramtype>const BinaryVisitor &</paramtype> | |
221 | </parameter> | |
222 | <parameter name="operand1"> | |
223 | <paramtype>Variant1 &</paramtype> | |
224 | </parameter> | |
225 | <parameter name="operand2"> | |
226 | <paramtype>Variant2 &</paramtype> | |
227 | </parameter> | |
228 | </signature> | |
229 | ||
230 | <signature> | |
231 | <template> | |
232 | <template-type-parameter name="MultiVisitor"/> | |
233 | <template-type-parameter name="Variant1"/> | |
234 | <template-type-parameter name="Variant2"/> | |
235 | <template-type-parameter name="Variant3"/> | |
236 | </template> | |
237 | ||
238 | <type>typename MultiVisitor::result_type OR decltype(auto)</type> | |
239 | ||
240 | <parameter name="visitor"> | |
241 | <paramtype>MultiVisitor &</paramtype> | |
242 | </parameter> | |
243 | <parameter name="operand1"> | |
244 | <paramtype>Variant1 &</paramtype> | |
245 | </parameter> | |
246 | <parameter name="operand2"> | |
247 | <paramtype>Variant2 &</paramtype> | |
248 | </parameter> | |
249 | <parameter name="operand3"> | |
250 | <paramtype>Variant3 &</paramtype> | |
251 | </parameter> | |
252 | <parameter name="other_operands"> | |
253 | <paramtype>...</paramtype> | |
254 | </parameter> | |
255 | </signature> | |
256 | ||
257 | <signature> | |
258 | <template> | |
259 | <template-type-parameter name="MultiVisitor"/> | |
260 | <template-type-parameter name="Variant1"/> | |
261 | <template-type-parameter name="Variant2"/> | |
262 | <template-type-parameter name="Variant3"/> | |
263 | </template> | |
264 | ||
265 | <type>typename MultiVisitor::result_type OR decltype(auto)</type> | |
266 | ||
267 | <parameter name="visitor"> | |
268 | <paramtype>const MultiVisitor &</paramtype> | |
269 | </parameter> | |
270 | <parameter name="operand1"> | |
271 | <paramtype>Variant1 &</paramtype> | |
272 | </parameter> | |
273 | <parameter name="operand2"> | |
274 | <paramtype>Variant2 &</paramtype> | |
275 | </parameter> | |
276 | <parameter name="operand3"> | |
277 | <paramtype>Variant3 &</paramtype> | |
278 | </parameter> | |
279 | <parameter name="other_operands"> | |
280 | <paramtype>...</paramtype> | |
281 | </parameter> | |
282 | </signature> | |
283 | ||
284 | <signature> | |
285 | <template> | |
286 | <template-type-parameter name="Visitor"/> | |
287 | </template> | |
288 | ||
289 | <type><classname>apply_visitor_delayed_t</classname><Visitor></type> | |
290 | ||
291 | <parameter name="visitor"> | |
292 | <paramtype>Visitor &</paramtype> | |
293 | </parameter> | |
294 | </signature> | |
295 | ||
296 | ||
297 | <signature> | |
298 | <template> | |
299 | <template-type-parameter name="Visitor"/> | |
300 | </template> | |
301 | ||
302 | <type><classname>apply_visitor_delayed_cpp14_t</classname><Visitor></type> | |
303 | ||
304 | <parameter name="visitor"> | |
305 | <paramtype>Visitor &</paramtype> | |
306 | </parameter> | |
307 | </signature> | |
308 | ||
309 | <purpose> | |
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> | |
313 | </purpose> | |
314 | ||
315 | <description> | |
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: | |
319 | ||
320 | <itemizedlist> | |
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> | |
324 | ||
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> | |
328 | operands.</listitem> | |
329 | ||
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> | |
338 | ||
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> | |
341 | or | |
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> | |
350 | </itemizedlist> | |
351 | ||
352 | </simpara> | |
353 | </description> | |
354 | ||
355 | <returns> | |
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> | |
360 | </returns> | |
361 | ||
362 | <requires> | |
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> | |
367 | </requires> | |
368 | ||
369 | <throws> | |
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> | |
375 | </throws> | |
376 | </overloaded-function> | |
377 | </namespace> | |
378 | </header> |