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-2021 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). If your compiler does not support the rvalue references or reference qualifiers then all the 319 forwarding references from above degrade to non const lvalue reference. The function behaves as follows: 320 321 <itemizedlist> 322 <listitem>Overloads accepting one operand invoke the unary function 323 call operator of the given visitor on the content of the given 324 <code><classname>variant</classname></code> operand.</listitem> 325 326 <listitem>Overloads accepting two operands invoke the binary 327 function call operator of the given visitor on the content of 328 the given <code><classname>variant</classname></code> 329 operands.</listitem> 330 331 <listitem>Overloads accepting three or more operands invoke the 332 function call operator of the given visitor on the content of 333 the given <code><classname>variant</classname></code> 334 operands. Maximum amount of parameters controlled by 335 <code><emphasis role="bold"><macroname>BOOST_VARAINT_MAX_MULTIVIZITOR_PARAMS</macroname></emphasis></code> 336 macro. Those functions are actually defined in a header <code>boost/variant/multivisitors.hpp</code> 337 (See <xref linkend="header.boost.variant.multivisitors_hpp"/>). That header must be manually included 338 if multi visitors are meant for use.</listitem> 339 340 <listitem>The overloads accepting only a visitor return a 341 <classname alt="boost::apply_visitor_delayed_t">C++03 compatible generic function object</classname> 342 or 343 <classname alt="boost::apply_visitor_delayed_cpp14_t">C++14 compatible generic function object</classname> 344 that accepts either one, two or arbitrary count of arguments and invoke 345 <code><functionname>apply_visitor</functionname></code> using 346 these arguments and <code>visitor</code>, thus behaving as 347 specified above. (This behavior is particularly useful, for 348 example, when one needs to operate on each element of a sequence 349 of variant objects using a standard library 350 algorithm.)</listitem> 351 </itemizedlist> 352 353 </simpara> 354 </description> 355 356 <returns> 357 <simpara>The overloads acccepting operands return the result of 358 applying the given visitor to the content of the given operands. 359 The overload accepting only a visitor return a function object, thus 360 delaying application of the visitor to any operands.</simpara> 361 </returns> 362 363 <requires> 364 <simpara>The given visitor must fulfill the 365 <link linkend="variant.concepts.static-visitor"><emphasis>StaticVisitor</emphasis></link> 366 concept requirements with respect to each of the bounded types of the 367 given <code>variant</code>.</simpara> 368 </requires> 369 370 <throws> 371 <simpara>The overloads accepting operands throw only if the given 372 visitor throws when applied. The overload accepting only a visitor 373 will not throw. (Note, however, that the returned 374 <classname alt="boost::apply_visitor_delayed_t">function object</classname> 375 may throw when invoked.)</simpara> 376 </throws> 377 </overloaded-function> 378 </namespace> 379</header> 380