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><<emphasis role="bold">typename P</emphasis>> 50 R <emphasis role="bold">operator</emphasis>()(<emphasis>cv-quals</emphasis> P& 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><F></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&</paramtype> 124 </parameter> 125 <returns><simpara><code>true</code> if <code>this-><methodname>target</methodname><Functor>()</code> is non-NULL and <code><functionname>function_equal</functionname>(*(this->target<Functor>()), f)</code></simpara></returns> 126 127 </method> 128 129 <method name="target_type" cv="const"> 130 <type>const std::type_info&</type> 131 <returns><simpara><code>typeid</code> of the target function object, or <code>typeid(void)</code> if <code>this-><methodname>empty</methodname>()</code>. Works even with RTTI off.</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-><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>&</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>&&</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-><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-><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-><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>&</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-><methodname>empty</methodname>()</code>.</simpara></postconditions> 247 </copy-assignment> 248 249 <copy-assignment> 250 <parameter name="f"> 251 <paramtype><classname>functionN</classname>&&</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>&</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-><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-><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-><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&</paramtype> 321 </parameter> 322 <returns><simpara><code>true</code> if <code>this-><methodname>target</methodname><Functor>()</code> is non-NULL and <code><functionname>function_equal</functionname>(*(this->target<Functor>()), f)</code></simpara></returns> 323 324 </method> 325 326 <method name="target_type" cv="const"> 327 <type>const std::type_info&</type> 328 <returns><simpara><code>typeid</code> of the target function object, or <code>typeid(void)</code> if <code>this-><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-><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><T1, T2, ..., TN>&</paramtype></parameter> 357 <parameter name="f2"><paramtype><classname>functionN</classname><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</paramtype></parameter> 398 <parameter name="g"><paramtype><classname>reference_wrapper</classname><Functor></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><Functor></paramtype></parameter> 410 <parameter name="f"><paramtype>const <classname>functionN</classname><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</paramtype></parameter> 425 <parameter name="f2"><paramtype>const <classname>functionN</classname><U1, U2, ..., UN>&</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><Functor></code> 434 and <code>f.target<Functor>() == 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><Functor></code> 439 and 440 <code><functionname>function_equal</functionname>(*(f.target<Functor>()), 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><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</paramtype></parameter> 493 <parameter name="g"><paramtype><classname>reference_wrapper</classname><Functor></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><Functor></paramtype></parameter> 505 <parameter name="f"><paramtype>const <classname>functionN</classname><T1, T2, ..., TN>&</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><T1, T2, ..., TN>&</paramtype></parameter> 520 <parameter name="f2"><paramtype>const <classname>functionN</classname><U1, U2, ..., UN>&</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><Functor></code> 531 and <code>f.target<Functor>() != 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><Functor></code> 536 and <code>!<functionname>function_equal</functionname>(*(f.target<Functor>()), 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><R, T1, T2, ..., TN></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-><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>&</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>&&</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>&</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>&&</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-><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-><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-><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>&</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-><methodname>empty</methodname>()</code>.</simpara></postconditions> 687 </copy-assignment> 688 689 <copy-assignment> 690 <parameter name="f"> 691 <paramtype><classname>functionN</classname>&&</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>&</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-><methodname>empty</methodname>()</code>.</simpara></throws> 704 </copy-assignment> 705 706 <copy-assignment> 707 <parameter name="f"> 708 <paramtype><classname>function</classname>&&</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>&</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-><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-><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-><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&</paramtype> 778 </parameter> 779 <returns><simpara><code>true</code> if <code>this-><methodname>target</methodname><Functor>()</code> is non-NULL and <code><functionname>function_equal</functionname>(*(this->target<Functor>()), f)</code></simpara></returns> 780 781 </method> 782 783 <method name="target_type" cv="const"> 784 <type>const std::type_info&</type> 785 <returns><simpara><code>typeid</code> of the target function object, or <code>typeid(void)</code> if <code>this-><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-><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><Signature>&</paramtype></parameter> 810 <parameter name="f2"><paramtype><classname>function</classname><Signature>&</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><Signature>&</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><Signature>&</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><Signature>&</paramtype></parameter> 842 <parameter name="g"><paramtype><classname>reference_wrapper</classname><Functor></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><Functor></paramtype></parameter> 851 <parameter name="f"><paramtype>const <classname>function</classname><Signature>&</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><Signature1>&</paramtype></parameter> 860 <parameter name="f2"><paramtype>const <classname>function</classname><Signature2>&</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><Functor></code> 869 and <code>f.target<Functor>() == 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><Functor></code> 874 and <code><functionname>function_equals</functionname>(*(f.target<Functor>()), 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><Signature>&</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><Signature>&</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><Signature>&</paramtype></parameter> 917 <parameter name="g"><paramtype><classname>reference_wrapper</classname><Functor></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><Functor></paramtype></parameter> 926 <parameter name="f"><paramtype>const <classname>function</classname><Signature>&</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><Signature1>&</paramtype></parameter> 935 <parameter name="f2"><paramtype>const <classname>function</classname><Signature2>&</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><Functor></code> 946 and <code>f.target<Functor>() != 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><Functor></code> 951 and <code>!<functionname>function_equals</functionname>(*(f.target<Functor>()), 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&</paramtype> 982 </parameter> 983 <parameter name="g"> 984 <paramtype>const G&</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> 993