Gitiles
Code Review Sign In
gerrit.named-data.net / ndn-cxx / a28eed8ca42271ce9b4cbab94abd2bbe84f022f1 / . / libs / function / doc / reference.xml
blob: c7c914c07c6f1da6f72a22409e8a3dc775c33bab [file] [log] [blame]
Jeff Thompsona28eed82013-08-22 16:21:10 -0700[diff] [blame^]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: 2013-06-15 00:06:26 -0700 (Sat, 15 Jun 2013) $">
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>