libs/function/doc/reference.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3    Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
   4
   5    Distributed under the Boost Software License, Version 1.0.
   6    (See accompanying file LICENSE_1_0.txt or copy at
   7    http://www.boost.org/LICENSE_1_0.txt)
   8   -->
   9 <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  10   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
  11
  12 <library-reference id="function.reference" last-revision="$Date$">
  13
  14 <section id="function.definitions">
  15   <title>Definitions</title>
  16 <para>
  17   <itemizedlist>
  18     <listitem>
  19       <para>A function object <computeroutput>f</computeroutput> is
  20       <emphasis>compatible</emphasis> if for the given set of argument
  21       types <computeroutput>Arg1</computeroutput>,
  22       <computeroutput>Arg2</computeroutput>, ...,
  23       <computeroutput>ArgN</computeroutput> and a
  24       return type <computeroutput>ResultType</computeroutput>, the
  25       appropriate following function is well-formed:
  26 <programlisting>
  27   <emphasis>// if ResultType is not <emphasis role="bold">void</emphasis></emphasis>
  28   ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<emphasis>N</emphasis> arg<emphasis>N</emphasis>)
  29   {
  30     <emphasis role="bold">return</emphasis> f(arg1, arg2, ..., arg<emphasis>N</emphasis>);
  31   }
  32
  33   <emphasis>// if ResultType is <emphasis role="bold">void</emphasis></emphasis>
  34   ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<emphasis>N</emphasis> arg<emphasis>N</emphasis>)
  35   {
  36     f(arg1, arg2, ..., arg<emphasis>N</emphasis>);
  37   }
  38 </programlisting></para>
  39
  40       <para> A special provision is made for pointers to member
  41       functions. Though they are not function objects, Boost.Function
  42       will adapt them internally to function objects. This requires
  43       that a pointer to member function of the form <code>R
  44       (X::*mf)(Arg1, Arg2, ..., ArgN)
  45       cv-quals</code> be adapted to a
  46       function object with the following function call operator
  47       overloads:
  48 <programlisting>
  49   <emphasis role="bold">template</emphasis>&lt;<emphasis role="bold">typename P</emphasis>&gt;
  50   R <emphasis role="bold">operator</emphasis>()(<emphasis>cv-quals</emphasis> P&amp; x, Arg1 arg1, Arg2 arg2, ..., Arg<emphasis>N</emphasis> arg<emphasis>N</emphasis>) <emphasis role="bold">const</emphasis>
  51   {
  52     <emphasis role="bold">return</emphasis> (*x).*mf(arg1, arg2, ..., arg<emphasis>N</emphasis>);
  53   }
  54 </programlisting>
  55 </para>
  56     </listitem>
  57     <listitem>
  58       <para>A function object <code>f</code> of
  59       type <code>F</code> is
  60       <emphasis>stateless</emphasis> if it is a function pointer or if
  61       <code><classname>boost::is_stateless</classname>&lt;F&gt;</code>
  62       is true. The construction of or copy to a Boost.Function object
  63       from a stateless function object will not cause exceptions to be
  64       thrown and will not allocate any storage.
  65       </para>
  66     </listitem>
  67   </itemizedlist>
  68 </para>
  69 </section>
  70
  71 <header name="boost/function.hpp">
  72 <namespace name="boost">
  73   <class name="bad_function_call">
  74     <inherit access="public"><classname>std::runtime_error</classname></inherit>
  75     <purpose>An exception type thrown when an instance of a <code>function</code> object is empty when invoked.</purpose>
  76     <constructor>
  77       <effects><simpara>Constructs a <code><classname>bad_function_call</classname></code> exception object.</simpara></effects>
  78     </constructor>
  79   </class>
  80
  81   <class name="function_base">
  82     <purpose>The common base class for all Boost.Function
  83     objects. Objects of type function_base may not be created
  84     directly.</purpose>
  85
  86     <method-group name="capacity">
  87       <method name="empty" cv="const">
  88         <type>bool</type>
  89         <returns><simpara><code>false</code> if <code>this</code> has a target, and <code>true</code> otherwise.</simpara></returns>
  90         <throws><simpara>Will not throw.</simpara></throws>
  91       </method>
  92     </method-group>
  93
  94     <method-group name="target access">
  95       <overloaded-method name="target">
  96         <signature>
  97           <template>
  98             <template-type-parameter name="Functor"/>
  99           </template>
 100           <type>Functor*</type>
 101         </signature>
 102         <signature cv="const">
 103           <template>
 104             <template-type-parameter name="Functor"/>
 105           </template>
 106           <type>const Functor*</type>
 107         </signature>
 108
 109         <returns><simpara>If <code>this</code> stores a target of type
 110         <code>Functor</code>, returns the address of the
 111         target. Otherwise, returns the NULL
 112         pointer.</simpara></returns>
 113
 114         <throws><simpara>Will not throw.</simpara></throws>
 115       </overloaded-method>
 116
 117       <method name="contains" cv="const">
 118         <template>
 119           <template-type-parameter name="Functor"/>
 120         </template>
 121         <type>bool</type>
 122         <parameter name="f">
 123           <paramtype>const Functor&amp;</paramtype>
 124         </parameter>
 125         <returns><simpara><code>true</code> if <code>this-&gt;<methodname>target</methodname>&lt;Functor&gt;()</code> is non-NULL and <code><functionname>function_equal</functionname>(*(this-&gt;target&lt;Functor&gt;()), f)</code></simpara></returns>
 126
 127       </method>
 128
 129       <method name="target_type" cv="const">
 130         <type>const std::type_info&amp;</type>
 131         <returns><simpara><code>typeid</code> of the target function object, or <code>typeid(void)</code> if <code>this-&gt;<methodname>empty</methodname>()</code>.</simpara></returns>
 132         <throws><simpara>Will not throw.</simpara></throws>
 133       </method>
 134     </method-group>
 135   </class>
 136
 137   <class name="functionN">
 138     <template>
 139       <template-type-parameter name="R"/>
 140       <template-type-parameter name="T1"/>
 141       <template-type-parameter name="T2"/>
 142       <template-varargs/>
 143       <template-type-parameter name="TN"/>
 144     </template>
 145
 146     <inherit access="public"><classname>function_base</classname></inherit>
 147
 148     <purpose>A set of generalized function pointers that can be used for callbacks or wrapping function objects.</purpose>
 149
 150     <description>
 151       <para>Class template <classname>functionN</classname> is
 152       actually a family of related classes <classname
 153       alt="functionN">function0</classname>, <classname
 154       alt="functionN">function1</classname>, etc., up to some
 155       implementation-defined maximum. In this context, <code>N</code>
 156       refers to the number of parameters.</para>
 157     </description>
 158
 159     <typedef name="result_type"><type>R</type></typedef>
 160     <typedef name="argument_type">
 161       <type>T1</type><purpose>If N == 1</purpose>
 162     </typedef>
 163     <typedef name="first_argument_type">
 164       <type>T1</type>
 165       <purpose>If N == 2</purpose>
 166     </typedef>
 167     <typedef name="second_argument_type">
 168       <type>T2</type>
 169       <purpose>If N == 2</purpose>
 170     </typedef>
 171     <typedef name="arg1_type"><type>T1</type></typedef>
 172     <typedef name="arg2_type"><type>T2</type></typedef>
 173     <typedef name="..."><type/></typedef>
 174     <typedef name="argN_type"><type>TN</type></typedef>
 175
 176     <static-constant name="arity">
 177       <type>int</type>
 178       <default>N</default>
 179     </static-constant>
 180
 181     <struct name="sig">
 182       <template>
 183         <template-type-parameter name="Args"/>
 184       </template>
 185
 186       <purpose>
 187         <simpara><libraryname>Lambda</libraryname> library support</simpara>
 188       </purpose>
 189
 190       <typedef name="type"><type>result_type</type></typedef>
 191     </struct>
 192
 193     <constructor>
 194       <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
 195       <throws><simpara>Will not throw.</simpara></throws>
 196     </constructor>
 197
 198     <constructor>
 199       <parameter name="f">
 200         <paramtype>const <classname>functionN</classname>&amp;</paramtype>
 201       </parameter>
 202       <postconditions><simpara>Contains a copy of the <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
 203       <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
 204     </constructor>
 205
 206     <constructor>
 207       <parameter name="f">
 208         <paramtype><classname>functionN</classname>&amp;&amp;</paramtype>
 209       </parameter>
 210       <requires><simpara>C++11 compatible compiler.</simpara></requires>
 211       <postconditions><simpara>Moves the value from <code>f</code> to <code>*this</code>. If the argument has its function object allocated on the heap, its buffer will be assigned to <code>*this</code> leaving argument empty.</simpara></postconditions>
 212       <throws><simpara>Will not throw unless argument has its function object allocated not on the heap and copying the target of <code>f</code> throws.</simpara></throws>
 213     </constructor>
 214
 215     <constructor>
 216       <template>
 217         <template-type-parameter name="F"/>
 218       </template>
 219       <parameter name="f"><paramtype>F</paramtype></parameter>
 220       <requires><simpara>F is a function object Callable from <code>this</code>.</simpara></requires>
 221       <postconditions><simpara><code>*this</code> targets a copy of <code>f</code> if <code>f</code> is nonempty, or <code>this-&gt;<methodname>empty</methodname>()</code> if <code>f</code> is empty.</simpara></postconditions>
 222     </constructor>
 223
 224     <constructor>
 225       <template>
 226         <template-type-parameter name="F"/>
 227         <template-type-parameter name="Allocator"/>
 228       </template>
 229       <parameter name="f"><paramtype>F</paramtype></parameter>
 230       <parameter name="alloc"><paramtype>Allocator</paramtype></parameter>
 231       <requires><simpara>F is a function object Callable from <code>this</code>, Allocator is an allocator. The copy constructor and destructor of Allocator shall not throw.</simpara></requires>
 232       <postconditions><simpara><code>*this</code> targets a copy of <code>f</code> if <code>f</code> is nonempty, or <code>this-&gt;<methodname>empty</methodname>()</code> if <code>f</code> is empty.</simpara></postconditions>
 233
 234       <effects><simpara>If memory allocation is required, the given allocator (or a copy of it) will be used to allocate that memory.</simpara></effects>
 235     </constructor>
 236
 237     <destructor>
 238       <effects><simpara>If <code>!this-&gt;<methodname>empty</methodname>()</code>, destroys the target of this.</simpara></effects>
 239
 240     </destructor>
 241
 242     <copy-assignment>
 243       <parameter name="f">
 244         <paramtype>const <classname>functionN</classname>&amp;</paramtype>
 245       </parameter>
 246       <postconditions><simpara>If copy construction does not throw, <code>*this</code> targets a copy of <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>. If copy construction does throw, <code>this-&gt;<methodname>empty</methodname>()</code>.</simpara></postconditions>
 247     </copy-assignment>
 248
 249     <copy-assignment>
 250       <parameter name="f">
 251         <paramtype><classname>functionN</classname>&amp;&amp;</paramtype>
 252       </parameter>
 253       <requires><simpara>C++11 compatible compiler.</simpara></requires>
 254       <postconditions><simpara>Moves the value from <code>f</code> to <code>*this</code>. If the argument has its function object allocated on the heap, its buffer will be assigned to <code>*this</code> leaving argument empty.</simpara></postconditions>
 255       <throws><simpara>Will not throw unless argument has its function object allocated not on the heap and copying the target of <code>f</code> throws.</simpara></throws>
 256     </copy-assignment>
 257
 258     <method-group name="modifiers">
 259       <method name="swap">
 260         <type>void</type>
 261         <parameter name="f"><paramtype>const <classname>functionN</classname>&amp;</paramtype></parameter>
 262         <effects><simpara>Interchanges the targets of <code>*this</code> and <code>f</code>.</simpara></effects>
 263       </method>
 264
 265       <method name="clear">
 266         <type>void</type>
 267         <postconditions><simpara>this-&gt;<methodname>empty</methodname>()</simpara></postconditions>
 268       </method>
 269     </method-group>
 270
 271     <method-group name="capacity">
 272       <method name="empty" cv="const">
 273         <type>bool</type>
 274         <returns><simpara><code>false</code> if <code>this</code> has a target, and <code>true</code> otherwise.</simpara></returns>
 275         <throws><simpara>Will not throw.</simpara></throws>
 276       </method>
 277
 278       <method name="conversion-operator" cv="const">
 279         <type>safe_bool</type>
 280         <returns><simpara>A <code>safe_bool</code> that evaluates <code>false</code> in a boolean context when <code>this-&gt;<methodname>empty</methodname>()</code>, and <code>true</code> otherwise.</simpara></returns>
 281         <throws><simpara>Will not throw.</simpara></throws>
 282       </method>
 283
 284       <method name="operator!" cv="const">
 285         <type>bool</type>
 286         <returns><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></returns>
 287         <throws><simpara>Will not throw.</simpara></throws>
 288       </method>
 289     </method-group>
 290
 291     <method-group name="target access">
 292       <overloaded-method name="target">
 293         <signature>
 294           <template>
 295             <template-type-parameter name="Functor"/>
 296           </template>
 297           <type>Functor*</type>
 298         </signature>
 299         <signature cv="const">
 300           <template>
 301             <template-type-parameter name="Functor"/>
 302           </template>
 303           <type>const Functor*</type>
 304         </signature>
 305
 306         <returns><simpara>If <code>this</code> stores a target of type
 307         <code>Functor</code>, returns the address of the
 308         target. Otherwise, returns the NULL
 309         pointer.</simpara></returns>
 310
 311         <throws><simpara>Will not throw.</simpara></throws>
 312       </overloaded-method>
 313
 314       <method name="contains" cv="const">
 315         <template>
 316           <template-type-parameter name="Functor"/>
 317         </template>
 318         <type>bool</type>
 319         <parameter name="f">
 320           <paramtype>const Functor&amp;</paramtype>
 321         </parameter>
 322         <returns><simpara><code>true</code> if <code>this-&gt;<methodname>target</methodname>&lt;Functor&gt;()</code> is non-NULL and <code><functionname>function_equal</functionname>(*(this-&gt;target&lt;Functor&gt;()), f)</code></simpara></returns>
 323
 324       </method>
 325
 326       <method name="target_type" cv="const">
 327         <type>const std::type_info&amp;</type>
 328         <returns><simpara><code>typeid</code> of the target function object, or <code>typeid(void)</code> if <code>this-&gt;<methodname>empty</methodname>()</code>.</simpara></returns>
 329         <throws><simpara>Will not throw.</simpara></throws>
 330       </method>
 331
 332     </method-group>
 333
 334     <method-group name="invocation">
 335       <method name="operator()" cv="const">
 336         <type>result_type</type>
 337         <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
 338         <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
 339         <parameter><paramtype>...</paramtype></parameter>
 340         <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
 341         <effects><simpara><code>f(a1, a2, ..., aN)</code>, where <code>f</code> is the target of <code>*this</code>.</simpara></effects>
 342         <returns><simpara>if <code>R</code> is <code>void</code>, nothing is returned; otherwise, the return value of the call to <code>f</code> is returned.</simpara></returns>
 343         <throws><simpara><code><classname>bad_function_call</classname></code> if <code>this-&gt;<methodname>empty</methodname>()</code>. Otherwise, may through any exception thrown by the target function <code>f</code>.</simpara></throws>
 344       </method>
 345     </method-group>
 346
 347     <free-function-group name="specialized algorithms">
 348       <function name="swap">
 349         <template>
 350           <template-type-parameter name="T1"/>
 351           <template-type-parameter name="T2"/>
 352           <template-varargs/>
 353           <template-type-parameter name="TN"/>
 354         </template>
 355         <type>void</type>
 356         <parameter name="f1"><paramtype><classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 357         <parameter name="f2"><paramtype><classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 358         <effects><simpara><code>f1.<methodname>swap</methodname>(f2)</code></simpara></effects>
 359       </function>
 360     </free-function-group>
 361
 362     <free-function-group name="comparison operators">
 363       <overloaded-function name="operator==">
 364         <signature>
 365           <template>
 366             <template-type-parameter name="T1"/>
 367             <template-type-parameter name="T2"/>
 368             <template-varargs/>
 369             <template-type-parameter name="TN"/>
 370             <template-type-parameter name="Functor"/>
 371           </template>
 372           <type>bool</type>
 373           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 374           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 375         </signature>
 376         <signature>
 377           <template>
 378             <template-type-parameter name="T1"/>
 379             <template-type-parameter name="T2"/>
 380             <template-varargs/>
 381             <template-type-parameter name="TN"/>
 382             <template-type-parameter name="Functor"/>
 383           </template>
 384           <type>bool</type>
 385           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 386           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 387         </signature>
 388         <signature>
 389           <template>
 390             <template-type-parameter name="T1"/>
 391             <template-type-parameter name="T2"/>
 392             <template-varargs/>
 393             <template-type-parameter name="TN"/>
 394             <template-type-parameter name="Functor"/>
 395           </template>
 396           <type>bool</type>
 397           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 398           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 399         </signature>
 400         <signature>
 401           <template>
 402             <template-type-parameter name="T1"/>
 403             <template-type-parameter name="T2"/>
 404             <template-varargs/>
 405             <template-type-parameter name="TN"/>
 406             <template-type-parameter name="Functor"/>
 407           </template>
 408           <type>bool</type>
 409           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 410           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 411         </signature>
 412         <signature>
 413           <template>
 414             <template-type-parameter name="T1"/>
 415             <template-type-parameter name="T2"/>
 416             <template-varargs/>
 417             <template-type-parameter name="TN"/>
 418             <template-type-parameter name="U1"/>
 419             <template-type-parameter name="U2"/>
 420             <template-varargs/>
 421             <template-type-parameter name="UN"/>
 422           </template>
 423           <type>void</type>
 424           <parameter name="f1"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 425           <parameter name="f2"><paramtype>const <classname>functionN</classname>&lt;U1, U2, ..., UN&gt;&amp;</paramtype></parameter>
 426         </signature>
 427
 428         <returns><simpara>True when <code>f</code> stores an object of
 429         type <code>Functor</code> and one of the following conditions applies:
 430           <itemizedlist>
 431
 432             <listitem><simpara><code>g</code> is of type
 433             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 434             and <code>f.target&lt;Functor&gt;() == g.<methodname
 435             alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
 436
 437             <listitem><simpara><code>g</code> is not of type
 438             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 439             and
 440             <code><functionname>function_equal</functionname>(*(f.target&lt;Functor&gt;()),
 441             g)</code>.</simpara></listitem>
 442
 443           </itemizedlist>
 444           </simpara></returns>
 445
 446         <notes><simpara><code><classname>functionN</classname></code>
 447         objects are not
 448         <conceptname>EqualityComparable</conceptname>.</simpara></notes>
 449
 450         <rationale><simpara>The <code>safe_bool</code> conversion
 451         opens a loophole whereby two <code>functionN</code>
 452         instances can be compared via <code>==</code>, although this
 453         is not feasible to implement. The undefined <code>void
 454         operator==</code> closes the loophole and ensures a
 455         compile-time or link-time error.</simpara></rationale>
 456       </overloaded-function>
 457
 458       <overloaded-function name="operator!=">
 459         <signature>
 460           <template>
 461             <template-type-parameter name="T1"/>
 462             <template-type-parameter name="T2"/>
 463             <template-varargs/>
 464             <template-type-parameter name="TN"/>
 465             <template-type-parameter name="Functor"/>
 466           </template>
 467           <type>bool</type>
 468           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 469           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 470         </signature>
 471         <signature>
 472           <template>
 473             <template-type-parameter name="T1"/>
 474             <template-type-parameter name="T2"/>
 475             <template-varargs/>
 476             <template-type-parameter name="TN"/>
 477             <template-type-parameter name="Functor"/>
 478           </template>
 479           <type>bool</type>
 480           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 481           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 482         </signature>
 483         <signature>
 484           <template>
 485             <template-type-parameter name="T1"/>
 486             <template-type-parameter name="T2"/>
 487             <template-varargs/>
 488             <template-type-parameter name="TN"/>
 489             <template-type-parameter name="Functor"/>
 490           </template>
 491           <type>bool</type>
 492           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 493           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 494         </signature>
 495         <signature>
 496           <template>
 497             <template-type-parameter name="T1"/>
 498             <template-type-parameter name="T2"/>
 499             <template-varargs/>
 500             <template-type-parameter name="TN"/>
 501             <template-type-parameter name="Functor"/>
 502           </template>
 503           <type>bool</type>
 504           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 505           <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 506         </signature>
 507         <signature>
 508           <template>
 509             <template-type-parameter name="T1"/>
 510             <template-type-parameter name="T2"/>
 511             <template-varargs/>
 512             <template-type-parameter name="TN"/>
 513             <template-type-parameter name="U1"/>
 514             <template-type-parameter name="U2"/>
 515             <template-varargs/>
 516             <template-type-parameter name="UN"/>
 517           </template>
 518           <type>void</type>
 519           <parameter name="f1"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN&gt;&amp;</paramtype></parameter>
 520           <parameter name="f2"><paramtype>const <classname>functionN</classname>&lt;U1, U2, ..., UN&gt;&amp;</paramtype></parameter>
 521         </signature>
 522
 523         <returns><simpara>True when <code>f</code> does not store an
 524         object of type <code>Functor</code> or it stores an object of
 525         type <code>Functor</code> and one of the following conditions
 526         applies:
 527           <itemizedlist>
 528
 529             <listitem><simpara><code>g</code> is of type
 530             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 531             and <code>f.target&lt;Functor&gt;() != g.<methodname
 532             alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
 533
 534             <listitem><simpara><code>g</code> is not of type
 535             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 536             and <code>!<functionname>function_equal</functionname>(*(f.target&lt;Functor&gt;()), g)</code>.</simpara></listitem>
 537
 538           </itemizedlist>
 539           </simpara></returns>
 540
 541         <notes><simpara><code><classname>functionN</classname></code>
 542         objects are not
 543         <conceptname>EqualityComparable</conceptname>.</simpara></notes>
 544
 545         <rationale><simpara>The <code>safe_bool</code> conversion
 546         opens a loophole whereby two <code>functionN</code>
 547         instances can be compared via <code>!=</code>, although this
 548         is not feasible to implement. The undefined <code>void
 549         operator!=</code> closes the loophole and ensures a
 550         compile-time or link-time error.</simpara></rationale>
 551       </overloaded-function>
 552     </free-function-group>
 553   </class>
 554
 555   <class name="function">
 556     <template>
 557       <template-type-parameter name="Signature">
 558         <purpose>Function type R (T1, T2, ..., TN)</purpose>
 559       </template-type-parameter>
 560     </template>
 561     <inherit access="public"><classname>functionN</classname>&lt;R, T1, T2, ..., TN&gt;</inherit>
 562
 563     <purpose>A generalized function pointer that can be used for
 564     callbacks or wrapping function objects.</purpose>
 565
 566     <description>
 567       <para>Class template <classname>function</classname> is a thin
 568       wrapper around the numbered class templates <classname
 569       alt="functionN">function0</classname>, <classname
 570       alt="functionN">function1</classname>, etc. It accepts a
 571       function type with N arguments and will will derive from
 572       <classname>functionN</classname> instantiated with the arguments
 573       it receives.</para>
 574
 575       <para>The semantics of all operations in class template
 576       <classname>function</classname> are equivalent to that of the
 577       underlying <classname>functionN</classname> object, although
 578       additional member functions are required to allow proper copy
 579       construction and copy assignment of function objects.</para>
 580     </description>
 581
 582     <typedef name="result_type"><type>R</type></typedef>
 583     <typedef name="argument_type">
 584       <type>T1</type><purpose>If N == 1</purpose>
 585     </typedef>
 586     <typedef name="first_argument_type">
 587       <type>T1</type>
 588       <purpose>If N == 2</purpose>
 589     </typedef>
 590     <typedef name="second_argument_type">
 591       <type>T2</type>
 592       <purpose>If N == 2</purpose>
 593     </typedef>
 594     <typedef name="arg1_type"><type>T1</type></typedef>
 595     <typedef name="arg2_type"><type>T2</type></typedef>
 596     <typedef name="..."><type/></typedef>
 597     <typedef name="argN_type"><type>TN</type></typedef>
 598
 599     <static-constant name="arity">
 600       <type>int</type>
 601       <default>N</default>
 602     </static-constant>
 603
 604     <struct name="sig">
 605       <template>
 606         <template-type-parameter name="Args"/>
 607       </template>
 608
 609       <purpose>
 610         <simpara><libraryname>Lambda</libraryname> library support</simpara>
 611       </purpose>
 612
 613       <typedef name="type"><type>result_type</type></typedef>
 614     </struct>
 615
 616     <constructor>
 617       <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
 618       <throws><simpara>Will not throw.</simpara></throws>
 619     </constructor>
 620
 621     <constructor>
 622       <parameter name="f">
 623         <paramtype>const <classname>functionN</classname>&amp;</paramtype>
 624       </parameter>
 625       <postconditions><simpara>Contains a copy of the <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
 626       <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
 627     </constructor>
 628
 629     <constructor>
 630       <parameter name="f">
 631         <paramtype><classname>functionN</classname>&amp;&amp;</paramtype>
 632       </parameter>
 633       <requires><simpara>C++11 compatible compiler.</simpara></requires>
 634       <postconditions><simpara>Moves the value from <code>f</code> to <code>*this</code>. If the argument has its function object allocated on the heap, its buffer will be assigned to <code>*this</code> leaving argument empty.</simpara></postconditions>
 635       <throws><simpara>Will not throw unless argument has its function object allocated not on the heap and copying the target of <code>f</code> throws.</simpara></throws>
 636     </constructor>
 637
 638     <constructor>
 639       <parameter name="f">
 640         <paramtype>const <classname>function</classname>&amp;</paramtype>
 641       </parameter>
 642       <postconditions><simpara>Contains a copy of the <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
 643       <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
 644     </constructor>
 645
 646     <constructor>
 647       <parameter name="f">
 648         <paramtype><classname>function</classname>&amp;&amp;</paramtype>
 649       </parameter>
 650       <requires><simpara>C++11 compatible compiler.</simpara></requires>
 651       <postconditions><simpara>Moves the value from <code>f</code> to <code>*this</code>. If the argument has its function object allocated on the heap, its buffer will be assigned to <code>*this</code> leaving argument empty.</simpara></postconditions>
 652       <throws><simpara>Will not throw unless argument has its function object allocated not on the heap and copying the target of <code>f</code> throws.</simpara></throws>
 653     </constructor>
 654
 655     <constructor>
 656       <template>
 657         <template-type-parameter name="F"/>
 658       </template>
 659       <parameter name="f"><paramtype>F</paramtype></parameter>
 660       <requires><simpara>F is a function object Callable from <code>this</code>.</simpara></requires>
 661       <postconditions><simpara><code>*this</code> targets a copy of <code>f</code> if <code>f</code> is nonempty, or <code>this-&gt;<methodname>empty</methodname>()</code> if <code>f</code> is empty.</simpara></postconditions>
 662     </constructor>
 663
 664     <constructor>
 665       <template>
 666         <template-type-parameter name="F"/>
 667         <template-type-parameter name="Allocator"/>
 668       </template>
 669       <parameter name="f"><paramtype>F</paramtype></parameter>
 670       <parameter name="alloc"><paramtype>Allocator</paramtype></parameter>
 671       <requires><simpara>F is a function object Callable from <code>this</code>, Allocator is an allocator. The copy constructor and destructor of Allocator shall not throw.</simpara></requires>
 672       <postconditions><simpara><code>*this</code> targets a copy of <code>f</code> if <code>f</code> is nonempty, or <code>this-&gt;<methodname>empty</methodname>()</code> if <code>f</code> is empty.</simpara></postconditions>
 673
 674       <effects><simpara>If memory allocation is required, the given allocator (or a copy of it) will be used to allocate that memory.</simpara></effects>
 675     </constructor>
 676
 677     <destructor>
 678       <effects><simpara>If <code>!this-&gt;<methodname>empty</methodname>()</code>, destroys the target of <code>this</code>.</simpara></effects>
 679
 680     </destructor>
 681
 682     <copy-assignment>
 683       <parameter name="f">
 684         <paramtype>const <classname>functionN</classname>&amp;</paramtype>
 685       </parameter>
 686       <postconditions><simpara>If copy construction does not throw, <code>*this</code> targets a copy of <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>. If copy construction does throw, <code>this-&gt;<methodname>empty</methodname>()</code>.</simpara></postconditions>
 687     </copy-assignment>
 688
 689     <copy-assignment>
 690       <parameter name="f">
 691         <paramtype><classname>functionN</classname>&amp;&amp;</paramtype>
 692       </parameter>
 693       <requires><simpara>C++11 compatible compiler.</simpara></requires>
 694       <postconditions><simpara>Moves the value from <code>f</code> to <code>*this</code>. If the argument has its function object allocated on the heap, its buffer will be assigned to <code>*this</code> leaving argument empty.</simpara></postconditions>
 695       <throws><simpara>Will not throw unless argument has its function object allocated not on the heap and copying the target of <code>f</code> throws.</simpara></throws>
 696     </copy-assignment>
 697
 698     <copy-assignment>
 699       <parameter name="f">
 700         <paramtype>const <classname>function</classname>&amp;</paramtype>
 701       </parameter>
 702       <postconditions><simpara>If copy construction of the target of <code>f</code> does not throw, <code>*this</code> targets a copy of <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>. </simpara></postconditions>
 703       <throws><simpara>Will not throw when the target of <code>f</code> is a stateless function object or a reference to the function object. If copy construction does throw, <code>this-&gt;<methodname>empty</methodname>()</code>.</simpara></throws>
 704     </copy-assignment>
 705
 706     <copy-assignment>
 707       <parameter name="f">
 708         <paramtype><classname>function</classname>&amp;&amp;</paramtype>
 709       </parameter>
 710       <requires><simpara>C++11 compatible compiler.</simpara></requires>
 711       <postconditions><simpara>Moves the value from <code>f</code> to <code>*this</code>. If the argument has its function object allocated on the heap, its buffer will be assigned to <code>*this</code> leaving argument empty.</simpara></postconditions>
 712       <throws><simpara>Will not throw unless argument has its function object allocated not on the heap and copying the target of <code>f</code> throws.</simpara></throws>
 713     </copy-assignment>
 714
 715     <method-group name="modifiers">
 716       <method name="swap">
 717         <type>void</type>
 718         <parameter name="f"><paramtype>const <classname>function</classname>&amp;</paramtype></parameter>
 719         <effects><simpara>Interchanges the targets of <code>*this</code> and <code>f</code>.</simpara></effects>
 720       </method>
 721
 722       <method name="clear">
 723         <type>void</type>
 724         <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
 725         <throws><simpara>Will not throw.</simpara></throws>
 726       </method>
 727     </method-group>
 728
 729     <method-group name="capacity">
 730       <method name="empty" cv="const">
 731         <type>bool</type>
 732         <returns><simpara><code>false</code> if <code>this</code> has a target, and <code>true</code> otherwise.</simpara></returns>
 733         <throws><simpara>Will not throw.</simpara></throws>
 734       </method>
 735
 736       <method name="conversion-operator" cv="const">
 737         <type>safe_bool</type>
 738         <returns><simpara>A <code>safe_bool</code> that evaluates <code>false</code> in a boolean context when <code>this-&gt;<methodname>empty</methodname>()</code>, and <code>true</code> otherwise.</simpara></returns>
 739         <throws><simpara>Will not throw.</simpara></throws>
 740       </method>
 741
 742       <method name="operator!" cv="const">
 743         <type>bool</type>
 744         <returns><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></returns>
 745         <throws><simpara>Will not throw.</simpara></throws>
 746       </method>
 747     </method-group>
 748
 749     <method-group name="target access">
 750       <overloaded-method name="target">
 751         <signature>
 752           <template>
 753             <template-type-parameter name="Functor"/>
 754           </template>
 755           <type>Functor*</type>
 756         </signature>
 757         <signature cv="const">
 758           <template>
 759             <template-type-parameter name="Functor"/>
 760           </template>
 761           <type>const Functor*</type>
 762         </signature>
 763
 764         <returns><simpara>If <code>this</code> stores a target of type
 765         <code>Functor</code>, returns the address of the
 766         target. Otherwise, returns the NULL
 767         pointer.</simpara></returns>
 768         <throws><simpara>Will not throw.</simpara></throws>
 769       </overloaded-method>
 770
 771       <method name="contains" cv="const">
 772         <template>
 773           <template-type-parameter name="Functor"/>
 774         </template>
 775         <type>bool</type>
 776         <parameter name="f">
 777           <paramtype>const Functor&amp;</paramtype>
 778         </parameter>
 779         <returns><simpara><code>true</code> if <code>this-&gt;<methodname>target</methodname>&lt;Functor&gt;()</code> is non-NULL and <code><functionname>function_equal</functionname>(*(this-&gt;target&lt;Functor&gt;()), f)</code></simpara></returns>
 780
 781       </method>
 782
 783       <method name="target_type" cv="const">
 784         <type>const std::type_info&amp;</type>
 785         <returns><simpara><code>typeid</code> of the target function object, or <code>typeid(void)</code> if <code>this-&gt;<methodname>empty</methodname>()</code>.</simpara></returns>
 786         <throws><simpara>Will not throw.</simpara></throws>
 787       </method>
 788     </method-group>
 789
 790     <method-group name="invocation">
 791       <method name="operator()" cv="const">
 792         <type>result_type</type>
 793         <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
 794         <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
 795         <parameter><paramtype>...</paramtype></parameter>
 796         <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
 797         <effects><simpara><code>f(a1, a2, ..., aN)</code>, where <code>f</code> is the target of <code>*this</code>.</simpara></effects>
 798         <returns><simpara>if <code>R</code> is <code>void</code>, nothing is returned; otherwise, the return value of the call to <code>f</code> is returned.</simpara></returns>
 799         <throws><simpara><code><classname>bad_function_call</classname></code> if <code>this-&gt;<methodname>empty</methodname>()</code>. Otherwise, may through any exception thrown by the target function <code>f</code>.</simpara></throws>
 800       </method>
 801     </method-group>
 802
 803     <free-function-group name="specialized algorithms">
 804       <function name="swap">
 805         <template>
 806           <template-type-parameter name="Signature"/>
 807         </template>
 808         <type>void</type>
 809         <parameter name="f1"><paramtype><classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 810         <parameter name="f2"><paramtype><classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 811         <effects><simpara><code>f1.<methodname>swap</methodname>(f2)</code></simpara></effects>
 812       </function>
 813     </free-function-group>
 814
 815     <free-function-group name="comparison operators">
 816       <overloaded-function name="operator==">
 817         <signature>
 818           <template>
 819             <template-type-parameter name="Signature"/>
 820             <template-type-parameter name="Functor"/>
 821           </template>
 822           <type>bool</type>
 823           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 824           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 825         </signature>
 826         <signature>
 827           <template>
 828             <template-type-parameter name="Signature"/>
 829             <template-type-parameter name="Functor"/>
 830           </template>
 831           <type>bool</type>
 832           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 833           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 834         </signature>
 835         <signature>
 836           <template>
 837             <template-type-parameter name="Signature"/>
 838             <template-type-parameter name="Functor"/>
 839           </template>
 840           <type>bool</type>
 841           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 842           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 843         </signature>
 844         <signature>
 845           <template>
 846             <template-type-parameter name="Signature"/>
 847             <template-type-parameter name="Functor"/>
 848           </template>
 849           <type>bool</type>
 850           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 851           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 852         </signature>
 853         <signature>
 854           <template>
 855             <template-type-parameter name="Signature1"/>
 856             <template-type-parameter name="Signature2"/>
 857           </template>
 858           <type>void</type>
 859           <parameter name="f1"><paramtype>const <classname>function</classname>&lt;Signature1&gt;&amp;</paramtype></parameter>
 860           <parameter name="f2"><paramtype>const <classname>function</classname>&lt;Signature2&gt;&amp;</paramtype></parameter>
 861         </signature>
 862
 863         <returns><simpara>True when <code>f</code> stores an object of
 864         type <code>Functor</code> and one of the following conditions applies:
 865           <itemizedlist>
 866
 867             <listitem><simpara><code>g</code> is of type
 868             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 869             and <code>f.target&lt;Functor&gt;() == g.<methodname
 870             alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
 871
 872             <listitem><simpara><code>g</code> is not of type
 873             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 874             and <code><functionname>function_equals</functionname>(*(f.target&lt;Functor&gt;()), g)</code>.</simpara></listitem>
 875
 876           </itemizedlist>
 877           </simpara></returns>
 878
 879         <notes><simpara><code><classname>function</classname></code>
 880         objects are not
 881         <conceptname>EqualityComparable</conceptname>.</simpara></notes>
 882
 883         <rationale><simpara>The <code>safe_bool</code> conversion
 884         opens a loophole whereby two <code>function</code>
 885         instances can be compared via <code>==</code>, although this
 886         is not feasible to implement. The undefined <code>void
 887         operator==</code> closes the loophole and ensures a
 888         compile-time or link-time error.</simpara></rationale>
 889       </overloaded-function>
 890
 891       <overloaded-function name="operator!=">
 892         <signature>
 893           <template>
 894             <template-type-parameter name="Signature"/>
 895             <template-type-parameter name="Functor"/>
 896           </template>
 897           <type>bool</type>
 898           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 899           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 900         </signature>
 901         <signature>
 902           <template>
 903             <template-type-parameter name="Signature"/>
 904             <template-type-parameter name="Functor"/>
 905           </template>
 906           <type>bool</type>
 907           <parameter name="g"><paramtype>Functor</paramtype></parameter>
 908           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 909         </signature>
 910         <signature>
 911           <template>
 912             <template-type-parameter name="Signature"/>
 913             <template-type-parameter name="Functor"/>
 914           </template>
 915           <type>bool</type>
 916           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 917           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 918         </signature>
 919         <signature>
 920           <template>
 921             <template-type-parameter name="Signature"/>
 922             <template-type-parameter name="Functor"/>
 923           </template>
 924           <type>bool</type>
 925           <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
 926           <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature&gt;&amp;</paramtype></parameter>
 927         </signature>
 928         <signature>
 929           <template>
 930             <template-type-parameter name="Signature1"/>
 931             <template-type-parameter name="Signature2"/>
 932           </template>
 933           <type>void</type>
 934           <parameter name="f1"><paramtype>const <classname>function</classname>&lt;Signature1&gt;&amp;</paramtype></parameter>
 935           <parameter name="f2"><paramtype>const <classname>function</classname>&lt;Signature2&gt;&amp;</paramtype></parameter>
 936         </signature>
 937
 938         <returns><simpara>True when <code>f</code> does not store an
 939         object of type <code>Functor</code> or it stores an object of
 940         type <code>Functor</code> and one of the following conditions
 941         applies:
 942           <itemizedlist>
 943
 944             <listitem><simpara><code>g</code> is of type
 945             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 946             and <code>f.target&lt;Functor&gt;() != g.<methodname
 947             alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
 948
 949             <listitem><simpara><code>g</code> is not of type
 950             <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
 951             and <code>!<functionname>function_equals</functionname>(*(f.target&lt;Functor&gt;()), g)</code>.</simpara></listitem>
 952
 953           </itemizedlist>
 954           </simpara></returns>
 955
 956         <notes><simpara><code><classname>function</classname></code>
 957         objects are not
 958         <conceptname>EqualityComparable</conceptname>.</simpara></notes>
 959
 960         <rationale><simpara>The <code>safe_bool</code> conversion
 961         opens a loophole whereby two <code>function</code>
 962         instances can be compared via <code>!=</code>, although this
 963         is not feasible to implement. The undefined <code>void
 964         operator!=</code> closes the loophole and ensures a
 965         compile-time or link-time error.</simpara></rationale>
 966       </overloaded-function>
 967     </free-function-group>
 968   </class>
 969 </namespace>
 970 </header>
 971
 972 <header name="boost/function_equal.hpp">
 973   <namespace name="boost">
 974   <function name="function_equal">
 975     <template>
 976       <template-type-parameter name="F"/>
 977       <template-type-parameter name="G"/>
 978     </template>
 979     <type>bool</type>
 980     <parameter name="f">
 981       <paramtype>const F&amp;</paramtype>
 982     </parameter>
 983     <parameter name="g">
 984       <paramtype>const G&amp;</paramtype>
 985     </parameter>
 986     <purpose><simpara>Compare two function objects for equality.</simpara></purpose>
 987     <returns><simpara><code>f == g</code>.</simpara></returns>
 988     <throws><simpara>Only if <code>f == g</code> throws.</simpara></throws>
 989   </function>
 990   </namespace>
 991 </header>
 992 </library-reference>