1 <?xml version=
"1.0" encoding=
"utf-8"?>
3 Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
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)
9 <!DOCTYPE library PUBLIC
"-//Boost//DTD BoostBook XML V1.0//EN"
10 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
12 <library-reference id=
"function.reference" last-revision=
"$Date$">
14 <section id=
"function.definitions">
15 <title>Definitions
</title>
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:
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>)
30 <emphasis role=
"bold">return
</emphasis> f(arg1, arg2, ..., arg
<emphasis>N
</emphasis>);
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>)
36 f(arg1, arg2, ..., arg
<emphasis>N
</emphasis>);
38 </programlisting></para>
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
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>
52 <emphasis role=
"bold">return
</emphasis> (*x).*mf(arg1, arg2, ..., arg
<emphasis>N
</emphasis>);
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.
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>
77 <effects><simpara>Constructs a
<code><classname>bad_function_call
</classname></code> exception object.
</simpara></effects>
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
86 <method-group name=
"capacity">
87 <method name=
"empty" cv=
"const">
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>
94 <method-group name=
"target access">
95 <overloaded-method name=
"target">
98 <template-type-parameter name=
"Functor"/>
100 <type>Functor*
</type>
102 <signature cv=
"const">
104 <template-type-parameter name=
"Functor"/>
106 <type>const Functor*
</type>
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>
114 <throws><simpara>Will not throw.
</simpara></throws>
117 <method name=
"contains" cv=
"const">
119 <template-type-parameter name=
"Functor"/>
123 <paramtype>const Functor
&</paramtype>
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>
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>
137 <class name=
"functionN">
139 <template-type-parameter name=
"R"/>
140 <template-type-parameter name=
"T1"/>
141 <template-type-parameter name=
"T2"/>
143 <template-type-parameter name=
"TN"/>
146 <inherit access=
"public"><classname>function_base
</classname></inherit>
148 <purpose>A set of generalized function pointers that can be used for callbacks or wrapping function objects.
</purpose>
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>
159 <typedef name=
"result_type"><type>R
</type></typedef>
160 <typedef name=
"argument_type">
161 <type>T1
</type><purpose>If N ==
1</purpose>
163 <typedef name=
"first_argument_type">
165 <purpose>If N ==
2</purpose>
167 <typedef name=
"second_argument_type">
169 <purpose>If N ==
2</purpose>
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>
176 <static-constant name=
"arity">
183 <template-type-parameter name=
"Args"/>
187 <simpara><libraryname>Lambda
</libraryname> library support
</simpara>
190 <typedef name=
"type"><type>result_type
</type></typedef>
194 <postconditions><simpara><code>this-
><methodname>empty
</methodname>()
</code></simpara></postconditions>
195 <throws><simpara>Will not throw.
</simpara></throws>
200 <paramtype>const
<classname>functionN
</classname>&</paramtype>
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>
208 <paramtype><classname>functionN
</classname>&&</paramtype>
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>
217 <template-type-parameter name=
"F"/>
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>
226 <template-type-parameter name=
"F"/>
227 <template-type-parameter name=
"Allocator"/>
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>
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>
238 <effects><simpara>If
<code>!this-
><methodname>empty
</methodname>()
</code>, destroys the target of this.
</simpara></effects>
244 <paramtype>const
<classname>functionN
</classname>&</paramtype>
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>
251 <paramtype><classname>functionN
</classname>&&</paramtype>
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>
258 <method-group name=
"modifiers">
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>
265 <method name=
"clear">
267 <postconditions><simpara>this-
><methodname>empty
</methodname>()
</simpara></postconditions>
271 <method-group name=
"capacity">
272 <method name=
"empty" cv=
"const">
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>
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>
284 <method name=
"operator!" cv=
"const">
286 <returns><simpara><code>this-
><methodname>empty
</methodname>()
</code></simpara></returns>
287 <throws><simpara>Will not throw.
</simpara></throws>
291 <method-group name=
"target access">
292 <overloaded-method name=
"target">
295 <template-type-parameter name=
"Functor"/>
297 <type>Functor*
</type>
299 <signature cv=
"const">
301 <template-type-parameter name=
"Functor"/>
303 <type>const Functor*
</type>
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>
311 <throws><simpara>Will not throw.
</simpara></throws>
314 <method name=
"contains" cv=
"const">
316 <template-type-parameter name=
"Functor"/>
320 <paramtype>const Functor
&</paramtype>
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>
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>
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>
347 <free-function-group name=
"specialized algorithms">
348 <function name=
"swap">
350 <template-type-parameter name=
"T1"/>
351 <template-type-parameter name=
"T2"/>
353 <template-type-parameter name=
"TN"/>
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>
360 </free-function-group>
362 <free-function-group name=
"comparison operators">
363 <overloaded-function name=
"operator==">
366 <template-type-parameter name=
"T1"/>
367 <template-type-parameter name=
"T2"/>
369 <template-type-parameter name=
"TN"/>
370 <template-type-parameter name=
"Functor"/>
373 <parameter name=
"f"><paramtype>const
<classname>functionN
</classname><T1, T2, ..., TN
>&</paramtype></parameter>
374 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
378 <template-type-parameter name=
"T1"/>
379 <template-type-parameter name=
"T2"/>
381 <template-type-parameter name=
"TN"/>
382 <template-type-parameter name=
"Functor"/>
385 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
386 <parameter name=
"f"><paramtype>const
<classname>functionN
</classname><T1, T2, ..., TN
>&</paramtype></parameter>
390 <template-type-parameter name=
"T1"/>
391 <template-type-parameter name=
"T2"/>
393 <template-type-parameter name=
"TN"/>
394 <template-type-parameter name=
"Functor"/>
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>
402 <template-type-parameter name=
"T1"/>
403 <template-type-parameter name=
"T2"/>
405 <template-type-parameter name=
"TN"/>
406 <template-type-parameter name=
"Functor"/>
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>
414 <template-type-parameter name=
"T1"/>
415 <template-type-parameter name=
"T2"/>
417 <template-type-parameter name=
"TN"/>
418 <template-type-parameter name=
"U1"/>
419 <template-type-parameter name=
"U2"/>
421 <template-type-parameter name=
"UN"/>
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>
428 <returns><simpara>True when
<code>f
</code> stores an object of
429 type
<code>Functor
</code> and one of the following conditions applies:
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>
437 <listitem><simpara><code>g
</code> is not of type
438 <code><classname>reference_wrapper
</classname><Functor
></code>
440 <code><functionname>function_equal
</functionname>(*(f.target
<Functor
>()),
441 g)
</code>.
</simpara></listitem>
446 <notes><simpara><code><classname>functionN
</classname></code>
448 <conceptname>EqualityComparable
</conceptname>.
</simpara></notes>
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>
458 <overloaded-function name=
"operator!=">
461 <template-type-parameter name=
"T1"/>
462 <template-type-parameter name=
"T2"/>
464 <template-type-parameter name=
"TN"/>
465 <template-type-parameter name=
"Functor"/>
468 <parameter name=
"f"><paramtype>const
<classname>functionN
</classname><T1, T2, ..., TN
>&</paramtype></parameter>
469 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
473 <template-type-parameter name=
"T1"/>
474 <template-type-parameter name=
"T2"/>
476 <template-type-parameter name=
"TN"/>
477 <template-type-parameter name=
"Functor"/>
480 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
481 <parameter name=
"f"><paramtype>const
<classname>functionN
</classname><T1, T2, ..., TN
>&</paramtype></parameter>
485 <template-type-parameter name=
"T1"/>
486 <template-type-parameter name=
"T2"/>
488 <template-type-parameter name=
"TN"/>
489 <template-type-parameter name=
"Functor"/>
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>
497 <template-type-parameter name=
"T1"/>
498 <template-type-parameter name=
"T2"/>
500 <template-type-parameter name=
"TN"/>
501 <template-type-parameter name=
"Functor"/>
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>
509 <template-type-parameter name=
"T1"/>
510 <template-type-parameter name=
"T2"/>
512 <template-type-parameter name=
"TN"/>
513 <template-type-parameter name=
"U1"/>
514 <template-type-parameter name=
"U2"/>
516 <template-type-parameter name=
"UN"/>
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>
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
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>
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>
541 <notes><simpara><code><classname>functionN
</classname></code>
543 <conceptname>EqualityComparable
</conceptname>.
</simpara></notes>
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>
555 <class name=
"function">
557 <template-type-parameter name=
"Signature">
558 <purpose>Function type R (T1, T2, ..., TN)
</purpose>
559 </template-type-parameter>
561 <inherit access=
"public"><classname>functionN
</classname><R, T1, T2, ..., TN
></inherit>
563 <purpose>A generalized function pointer that can be used for
564 callbacks or wrapping function objects.
</purpose>
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
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>
582 <typedef name=
"result_type"><type>R
</type></typedef>
583 <typedef name=
"argument_type">
584 <type>T1
</type><purpose>If N ==
1</purpose>
586 <typedef name=
"first_argument_type">
588 <purpose>If N ==
2</purpose>
590 <typedef name=
"second_argument_type">
592 <purpose>If N ==
2</purpose>
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>
599 <static-constant name=
"arity">
606 <template-type-parameter name=
"Args"/>
610 <simpara><libraryname>Lambda
</libraryname> library support
</simpara>
613 <typedef name=
"type"><type>result_type
</type></typedef>
617 <postconditions><simpara><code>this-
><methodname>empty
</methodname>()
</code></simpara></postconditions>
618 <throws><simpara>Will not throw.
</simpara></throws>
623 <paramtype>const
<classname>functionN
</classname>&</paramtype>
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>
631 <paramtype><classname>functionN
</classname>&&</paramtype>
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>
640 <paramtype>const
<classname>function
</classname>&</paramtype>
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>
648 <paramtype><classname>function
</classname>&&</paramtype>
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>
657 <template-type-parameter name=
"F"/>
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>
666 <template-type-parameter name=
"F"/>
667 <template-type-parameter name=
"Allocator"/>
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>
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>
678 <effects><simpara>If
<code>!this-
><methodname>empty
</methodname>()
</code>, destroys the target of
<code>this
</code>.
</simpara></effects>
684 <paramtype>const
<classname>functionN
</classname>&</paramtype>
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>
691 <paramtype><classname>functionN
</classname>&&</paramtype>
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>
700 <paramtype>const
<classname>function
</classname>&</paramtype>
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>
708 <paramtype><classname>function
</classname>&&</paramtype>
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>
715 <method-group name=
"modifiers">
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>
722 <method name=
"clear">
724 <postconditions><simpara><code>this-
><methodname>empty
</methodname>()
</code></simpara></postconditions>
725 <throws><simpara>Will not throw.
</simpara></throws>
729 <method-group name=
"capacity">
730 <method name=
"empty" cv=
"const">
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>
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>
742 <method name=
"operator!" cv=
"const">
744 <returns><simpara><code>this-
><methodname>empty
</methodname>()
</code></simpara></returns>
745 <throws><simpara>Will not throw.
</simpara></throws>
749 <method-group name=
"target access">
750 <overloaded-method name=
"target">
753 <template-type-parameter name=
"Functor"/>
755 <type>Functor*
</type>
757 <signature cv=
"const">
759 <template-type-parameter name=
"Functor"/>
761 <type>const Functor*
</type>
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>
771 <method name=
"contains" cv=
"const">
773 <template-type-parameter name=
"Functor"/>
777 <paramtype>const Functor
&</paramtype>
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>
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>
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>
803 <free-function-group name=
"specialized algorithms">
804 <function name=
"swap">
806 <template-type-parameter name=
"Signature"/>
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>
813 </free-function-group>
815 <free-function-group name=
"comparison operators">
816 <overloaded-function name=
"operator==">
819 <template-type-parameter name=
"Signature"/>
820 <template-type-parameter name=
"Functor"/>
823 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
824 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
828 <template-type-parameter name=
"Signature"/>
829 <template-type-parameter name=
"Functor"/>
832 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
833 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
837 <template-type-parameter name=
"Signature"/>
838 <template-type-parameter name=
"Functor"/>
841 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
842 <parameter name=
"g"><paramtype><classname>reference_wrapper
</classname><Functor
></paramtype></parameter>
846 <template-type-parameter name=
"Signature"/>
847 <template-type-parameter name=
"Functor"/>
850 <parameter name=
"g"><paramtype><classname>reference_wrapper
</classname><Functor
></paramtype></parameter>
851 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
855 <template-type-parameter name=
"Signature1"/>
856 <template-type-parameter name=
"Signature2"/>
859 <parameter name=
"f1"><paramtype>const
<classname>function
</classname><Signature1
>&</paramtype></parameter>
860 <parameter name=
"f2"><paramtype>const
<classname>function
</classname><Signature2
>&</paramtype></parameter>
863 <returns><simpara>True when
<code>f
</code> stores an object of
864 type
<code>Functor
</code> and one of the following conditions applies:
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>
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>
879 <notes><simpara><code><classname>function
</classname></code>
881 <conceptname>EqualityComparable
</conceptname>.
</simpara></notes>
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>
891 <overloaded-function name=
"operator!=">
894 <template-type-parameter name=
"Signature"/>
895 <template-type-parameter name=
"Functor"/>
898 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
899 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
903 <template-type-parameter name=
"Signature"/>
904 <template-type-parameter name=
"Functor"/>
907 <parameter name=
"g"><paramtype>Functor
</paramtype></parameter>
908 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
912 <template-type-parameter name=
"Signature"/>
913 <template-type-parameter name=
"Functor"/>
916 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
917 <parameter name=
"g"><paramtype><classname>reference_wrapper
</classname><Functor
></paramtype></parameter>
921 <template-type-parameter name=
"Signature"/>
922 <template-type-parameter name=
"Functor"/>
925 <parameter name=
"g"><paramtype><classname>reference_wrapper
</classname><Functor
></paramtype></parameter>
926 <parameter name=
"f"><paramtype>const
<classname>function
</classname><Signature
>&</paramtype></parameter>
930 <template-type-parameter name=
"Signature1"/>
931 <template-type-parameter name=
"Signature2"/>
934 <parameter name=
"f1"><paramtype>const
<classname>function
</classname><Signature1
>&</paramtype></parameter>
935 <parameter name=
"f2"><paramtype>const
<classname>function
</classname><Signature2
>&</paramtype></parameter>
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
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>
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>
956 <notes><simpara><code><classname>function
</classname></code>
958 <conceptname>EqualityComparable
</conceptname>.
</simpara></notes>
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>
972 <header name=
"boost/function_equal.hpp">
973 <namespace name=
"boost">
974 <function name=
"function_equal">
976 <template-type-parameter name=
"F"/>
977 <template-type-parameter name=
"G"/>
981 <paramtype>const F
&</paramtype>
984 <paramtype>const G
&</paramtype>
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>