ceph/src/boost/libs/variant/doc/reference/apply_visitor.xml

   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 &quot;visitor-only&quot; 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 &amp;</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&amp;...</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 &amp;</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 &amp;</paramtype>
  82             </parameter>
  83             <parameter name="operand2">
  84               <paramtype>Variant2 &amp;</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 &quot;visitor-only&quot; 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 &amp;</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&amp;...</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 &amp;</paramtype>
 168         </parameter>
 169         <parameter name="operand">
 170           <paramtype>Variant &amp;</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 &amp;</paramtype>
 184         </parameter>
 185         <parameter name="operand">
 186           <paramtype>Variant &amp;</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 &amp;</paramtype>
 201         </parameter>
 202         <parameter name="operand1">
 203           <paramtype>Variant1 &amp;</paramtype>
 204         </parameter>
 205         <parameter name="operand2">
 206           <paramtype>Variant2 &amp;</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 &amp;</paramtype>
 221         </parameter>
 222         <parameter name="operand1">
 223           <paramtype>Variant1 &amp;</paramtype>
 224         </parameter>
 225         <parameter name="operand2">
 226           <paramtype>Variant2 &amp;</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 &amp;</paramtype>
 242         </parameter>
 243         <parameter name="operand1">
 244           <paramtype>Variant1 &amp;</paramtype>
 245         </parameter>
 246         <parameter name="operand2">
 247           <paramtype>Variant2 &amp;</paramtype>
 248         </parameter>
 249         <parameter name="operand3">
 250           <paramtype>Variant3 &amp;</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 &amp;</paramtype>
 269         </parameter>
 270         <parameter name="operand1">
 271           <paramtype>Variant1 &amp;</paramtype>
 272         </parameter>
 273         <parameter name="operand2">
 274           <paramtype>Variant2 &amp;</paramtype>
 275         </parameter>
 276         <parameter name="operand3">
 277           <paramtype>Variant3 &amp;</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>&lt;Visitor&gt;</type>
 290
 291         <parameter name="visitor">
 292           <paramtype>Visitor &amp;</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>&lt;Visitor&gt;</type>
 303
 304         <parameter name="visitor">
 305           <paramtype>Visitor &amp;</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>