Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/function/doc/reference.xml @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 42.7 KB
Line 
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: 2006/11/03 19:41:09 $">
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;T&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-type-parameter name="Allocator">
145        <default><classname>std::allocator</classname>&lt;void&gt;</default>
146      </template-type-parameter>
147    </template>
148
149    <inherit access="public"><classname>function_base</classname></inherit>
150
151    <purpose>A set of generalized function pointers that can be used for callbacks or wrapping function objects.</purpose>
152
153    <description>
154      <para>Class template <classname>functionN</classname> is
155      actually a family of related classes <classname
156      alt="functionN">function0</classname>, <classname
157      alt="functionN">function1</classname>, etc., up to some
158      implementation-defined maximum. In this context, <code>N</code>
159      refers to the number of parameters.</para>
160    </description>
161
162    <typedef name="result_type"><type>R</type></typedef>
163    <typedef name="allocator_type"><type>Allocator</type></typedef>
164    <typedef name="argument_type">
165      <type>T1</type><purpose>If N == 1</purpose>
166    </typedef>
167    <typedef name="first_argument_type">
168      <type>T1</type>
169      <purpose>If N == 2</purpose>
170    </typedef>
171    <typedef name="second_argument_type">
172      <type>T2</type>
173      <purpose>If N == 2</purpose>
174    </typedef>
175    <typedef name="arg1_type"><type>T1</type></typedef>
176    <typedef name="arg2_type"><type>T2</type></typedef>
177    <typedef name="..."><type/></typedef>
178    <typedef name="argN_type"><type>TN</type></typedef>
179
180    <static-constant name="arity">
181      <type>int</type>
182      <default>N</default>
183    </static-constant>
184
185    <struct name="sig">
186      <template>
187        <template-type-parameter name="Args"/>
188      </template>
189
190      <purpose>
191        <simpara><libraryname>Lambda</libraryname> library support</simpara>
192      </purpose>
193
194      <typedef name="type"><type>result_type</type></typedef>
195    </struct>
196
197    <constructor>
198      <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
199      <throws><simpara>Will not throw.</simpara></throws>
200    </constructor>
201
202    <constructor>
203      <parameter name="f">
204        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
205      </parameter>
206      <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>
207      <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
208    </constructor>
209
210    <constructor>
211      <template>
212        <template-type-parameter name="F"/>
213      </template>
214      <parameter name="f"><paramtype>F</paramtype></parameter>
215      <requires><simpara>F is a function object Callable from <code>this</code>.</simpara></requires>
216      <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>
217    </constructor>
218
219    <destructor>
220      <effects><simpara>If <code>!this-&gt;<methodname>empty</methodname>()</code>, destroys the target of this.</simpara></effects>
221
222    </destructor>
223
224    <copy-assignment>
225      <parameter name="f">
226        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
227      </parameter>
228      <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>
229    </copy-assignment>
230
231    <method-group name="modifiers">
232      <method name="swap">
233        <type>void</type>
234        <parameter name="f"><paramtype>const <classname>functionN</classname>&amp;</paramtype></parameter>
235        <effects><simpara>Interchanges the targets of <code>*this</code> and <code>f</code>.</simpara></effects>
236      </method>
237
238      <method name="clear">
239        <type>void</type>
240        <postconditions><simpara>this-&gt;<methodname>empty</methodname>()</simpara></postconditions>
241      </method>
242    </method-group>
243
244    <method-group name="capacity">
245      <method name="empty" cv="const">
246        <type>bool</type>
247        <returns><simpara><code>false</code> if <code>this</code> has a target, and <code>true</code> otherwise.</simpara></returns>
248        <throws><simpara>Will not throw.</simpara></throws>
249      </method>
250
251      <method name="conversion-operator" cv="const">
252        <type>safe_bool</type>
253        <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>
254        <throws><simpara>Will not throw.</simpara></throws>
255      </method>
256
257      <method name="operator!" cv="const">
258        <type>bool</type>
259        <returns><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></returns>
260        <throws><simpara>Will not throw.</simpara></throws>
261      </method>
262    </method-group>
263
264    <method-group name="target access">
265      <overloaded-method name="target">
266        <signature>
267          <template> 
268            <template-type-parameter name="Functor"/>
269          </template>
270          <type>Functor*</type>
271        </signature>
272        <signature cv="const">
273          <template> 
274            <template-type-parameter name="Functor"/>
275          </template>
276          <type>const Functor*</type>
277        </signature>
278
279        <returns><simpara>If <code>this</code> stores a target of type
280        <code>Functor</code>, returns the address of the
281        target. Otherwise, returns the NULL
282        pointer.</simpara></returns>
283
284        <throws><simpara>Will not throw.</simpara></throws>
285      </overloaded-method>
286
287      <method name="contains" cv="const">
288        <template>
289          <template-type-parameter name="Functor"/>
290        </template>
291        <type>bool</type>
292        <parameter name="f">
293          <paramtype>const Functor&amp;</paramtype>
294        </parameter>
295        <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>
296 
297      </method>
298
299      <method name="target_type" cv="const">
300        <type>const std::type_info&amp;</type>
301        <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>
302        <throws><simpara>Will not throw.</simpara></throws>
303      </method>
304
305    </method-group>
306
307    <method-group name="invocation">
308      <method name="operator()" cv="const">
309        <type>result_type</type>
310        <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
311        <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
312        <parameter><paramtype>...</paramtype></parameter>
313        <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
314        <effects><simpara><code>f(a1, a2, ..., aN)</code>, where <code>f</code> is the target of <code>*this</code>.</simpara></effects>
315        <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>
316        <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>
317      </method>
318    </method-group>
319
320    <free-function-group name="specialized algorithms">
321      <function name="swap">
322        <template>
323          <template-type-parameter name="T1"/>
324          <template-type-parameter name="T2"/>
325          <template-varargs/>
326          <template-type-parameter name="TN"/>
327          <template-type-parameter name="Allocator"/>
328        </template>
329        <type>void</type>
330        <parameter name="f1"><paramtype><classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
331        <parameter name="f2"><paramtype><classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
332        <effects><simpara><code>f1.<methodname>swap</methodname>(f2)</code></simpara></effects>
333      </function>
334    </free-function-group>
335
336    <free-function-group name="comparison operators">
337      <overloaded-function name="operator==">
338        <signature>
339          <template>
340            <template-type-parameter name="T1"/>
341            <template-type-parameter name="T2"/>
342            <template-varargs/>
343            <template-type-parameter name="TN"/>
344            <template-type-parameter name="Allocator"/>
345            <template-type-parameter name="Functor"/>
346          </template>
347          <type>bool</type>
348          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
349          <parameter name="g"><paramtype>Functor</paramtype></parameter>
350        </signature>
351        <signature>
352          <template>
353            <template-type-parameter name="T1"/>
354            <template-type-parameter name="T2"/>
355            <template-varargs/>
356            <template-type-parameter name="TN"/>
357            <template-type-parameter name="Allocator"/>
358            <template-type-parameter name="Functor"/>
359          </template>
360          <type>bool</type>
361          <parameter name="g"><paramtype>Functor</paramtype></parameter>
362          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
363        </signature>       
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="Allocator"/>
371            <template-type-parameter name="Functor"/>
372          </template>
373          <type>bool</type>
374          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
375          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
376        </signature>
377        <signature>
378          <template>
379            <template-type-parameter name="T1"/>
380            <template-type-parameter name="T2"/>
381            <template-varargs/>
382            <template-type-parameter name="TN"/>
383            <template-type-parameter name="Allocator"/>
384            <template-type-parameter name="Functor"/>
385          </template>
386          <type>bool</type>
387          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
388          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
389        </signature>       
390        <signature>
391          <template>
392            <template-type-parameter name="T1"/>
393            <template-type-parameter name="T2"/>
394            <template-varargs/>
395            <template-type-parameter name="TN"/>
396            <template-type-parameter name="Allocator1"/>
397            <template-type-parameter name="U1"/>
398            <template-type-parameter name="U2"/>
399            <template-varargs/>
400            <template-type-parameter name="UN"/>
401            <template-type-parameter name="Allocator2"/>
402          </template>
403          <type>void</type>
404          <parameter name="f1"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator1&gt;&amp;</paramtype></parameter>
405          <parameter name="f2"><paramtype>const <classname>functionN</classname>&lt;U1, U2, ..., UN, Allocator2&gt;&amp;</paramtype></parameter>
406        </signature>
407
408        <returns><simpara>True when <code>f</code> stores an object of
409        type <code>Functor</code> and one of the following conditions applies:
410          <itemizedlist>
411
412            <listitem><simpara><code>g</code> is of type
413            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
414            and <code>f.target&lt;Functor&gt;() == g.<methodname
415            alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
416
417            <listitem><simpara><code>g</code> is not of type
418            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
419            and
420            <code><functionname>function_equal</functionname>(*(f.target&lt;Functor&gt;()),
421            g)</code>.</simpara></listitem>
422
423          </itemizedlist>
424          </simpara></returns>
425
426        <notes><simpara><code><classname>functionN</classname></code>
427        objects are not
428        <conceptname>EqualityComparable</conceptname>.</simpara></notes>
429
430        <rationale><simpara>The <code>safe_bool</code> conversion
431        opens a loophole whereby two <code>functionN</code>
432        instances can be compared via <code>==</code>, although this
433        is not feasible to implement. The undefined <code>void
434        operator==</code> closes the loophole and ensures a
435        compile-time or link-time error.</simpara></rationale>
436      </overloaded-function>
437
438      <overloaded-function name="operator!=">
439        <signature>
440          <template>
441            <template-type-parameter name="T1"/>
442            <template-type-parameter name="T2"/>
443            <template-varargs/>
444            <template-type-parameter name="TN"/>
445            <template-type-parameter name="Allocator"/>
446            <template-type-parameter name="Functor"/>
447          </template>
448          <type>bool</type>
449          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
450          <parameter name="g"><paramtype>Functor</paramtype></parameter>
451        </signature>
452        <signature>
453          <template>
454            <template-type-parameter name="T1"/>
455            <template-type-parameter name="T2"/>
456            <template-varargs/>
457            <template-type-parameter name="TN"/>
458            <template-type-parameter name="Allocator"/>
459            <template-type-parameter name="Functor"/>
460          </template>
461          <type>bool</type>
462          <parameter name="g"><paramtype>Functor</paramtype></parameter>
463          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
464        </signature>       
465        <signature>
466          <template>
467            <template-type-parameter name="T1"/>
468            <template-type-parameter name="T2"/>
469            <template-varargs/>
470            <template-type-parameter name="TN"/>
471            <template-type-parameter name="Allocator"/>
472            <template-type-parameter name="Functor"/>
473          </template>
474          <type>bool</type>
475          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
476          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
477        </signature>
478        <signature>
479          <template>
480            <template-type-parameter name="T1"/>
481            <template-type-parameter name="T2"/>
482            <template-varargs/>
483            <template-type-parameter name="TN"/>
484            <template-type-parameter name="Allocator"/>
485            <template-type-parameter name="Functor"/>
486          </template>
487          <type>bool</type>
488          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
489          <parameter name="f"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
490        </signature>       
491        <signature>
492          <template>
493            <template-type-parameter name="T1"/>
494            <template-type-parameter name="T2"/>
495            <template-varargs/>
496            <template-type-parameter name="TN"/>
497            <template-type-parameter name="Allocator1"/>
498            <template-type-parameter name="U1"/>
499            <template-type-parameter name="U2"/>
500            <template-varargs/>
501            <template-type-parameter name="UN"/>
502            <template-type-parameter name="Allocator2"/>
503          </template>
504          <type>void</type>
505          <parameter name="f1"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator1&gt;&amp;</paramtype></parameter>
506          <parameter name="f2"><paramtype>const <classname>functionN</classname>&lt;U1, U2, ..., UN, Allocator2&gt;&amp;</paramtype></parameter>
507        </signature>
508
509        <returns><simpara>True when <code>f</code> does not store an
510        object of type <code>Functor</code> or it stores an object of
511        type <code>Functor</code> and one of the following conditions
512        applies:
513          <itemizedlist>
514
515            <listitem><simpara><code>g</code> is of type
516            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
517            and <code>f.target&lt;Functor&gt;() != g.<methodname
518            alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
519
520            <listitem><simpara><code>g</code> is not of type
521            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
522            and <code>!<functionname>function_equal</functionname>(*(f.target&lt;Functor&gt;()), g)</code>.</simpara></listitem>
523
524          </itemizedlist>
525          </simpara></returns>
526
527        <notes><simpara><code><classname>functionN</classname></code>
528        objects are not
529        <conceptname>EqualityComparable</conceptname>.</simpara></notes>
530
531        <rationale><simpara>The <code>safe_bool</code> conversion
532        opens a loophole whereby two <code>functionN</code>
533        instances can be compared via <code>!=</code>, although this
534        is not feasible to implement. The undefined <code>void
535        operator!=</code> closes the loophole and ensures a
536        compile-time or link-time error.</simpara></rationale>
537      </overloaded-function>
538    </free-function-group>
539  </class>
540
541  <class name="function">
542    <template>
543      <template-type-parameter name="Signature">
544        <purpose>Function type R (T1, T2, ..., TN)</purpose>
545      </template-type-parameter>
546      <template-type-parameter name="Allocator">
547        <default><classname>std::allocator</classname>&lt;void&gt;</default>
548      </template-type-parameter>
549    </template>
550    <inherit access="public"><classname>functionN</classname>&lt;R, T1, T2, ..., TN, Allocator&gt;</inherit>
551
552    <purpose>A generalized function pointer that can be used for
553    callbacks or wrapping function objects.</purpose>
554
555    <description>
556      <para>Class template <classname>function</classname> is a thin
557      wrapper around the numbered class templates <classname
558      alt="functionN">function0</classname>, <classname
559      alt="functionN">function1</classname>, etc. It accepts a
560      function type with N arguments and will will derive from
561      <classname>functionN</classname> instantiated with the arguments
562      it receives.</para>
563
564      <para>The semantics of all operations in class template
565      <classname>function</classname> are equivalent to that of the
566      underlying <classname>functionN</classname> object, although
567      additional member functions are required to allow proper copy
568      construction and copy assignment of function objects.</para>
569    </description>
570
571    <typedef name="result_type"><type>R</type></typedef>
572    <typedef name="allocator_type"><type>Allocator</type></typedef>
573    <typedef name="argument_type">
574      <type>T1</type><purpose>If N == 1</purpose>
575    </typedef>
576    <typedef name="first_argument_type">
577      <type>T1</type>
578      <purpose>If N == 2</purpose>
579    </typedef>
580    <typedef name="second_argument_type">
581      <type>T2</type>
582      <purpose>If N == 2</purpose>
583    </typedef>
584    <typedef name="arg1_type"><type>T1</type></typedef>
585    <typedef name="arg2_type"><type>T2</type></typedef>
586    <typedef name="..."><type/></typedef>
587    <typedef name="argN_type"><type>TN</type></typedef>
588
589    <static-constant name="arity">
590      <type>int</type>
591      <default>N</default>
592    </static-constant>
593
594    <struct name="sig">
595      <template>
596        <template-type-parameter name="Args"/>
597      </template>
598
599      <purpose>
600        <simpara><libraryname>Lambda</libraryname> library support</simpara>
601      </purpose>
602
603      <typedef name="type"><type>result_type</type></typedef>
604    </struct>
605
606    <constructor>
607      <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
608      <throws><simpara>Will not throw.</simpara></throws>
609    </constructor>
610
611    <constructor>
612      <parameter name="f">
613        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
614      </parameter>
615      <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>
616      <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
617    </constructor>
618
619    <constructor>
620      <parameter name="f">
621        <paramtype>const <classname>function</classname>&amp;</paramtype>
622      </parameter>
623      <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>
624      <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
625    </constructor>
626
627    <constructor>
628      <template>
629        <template-type-parameter name="F"/>
630      </template>
631      <parameter name="f"><paramtype>F</paramtype></parameter>
632      <requires><simpara>F is a function object Callable from <code>this</code>.</simpara></requires>
633      <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>
634    </constructor>
635
636    <destructor>
637      <effects><simpara>If <code>!this-&gt;<methodname>empty</methodname>()</code>, destroys the target of <code>this</code>.</simpara></effects>
638
639    </destructor>
640
641    <copy-assignment>
642      <parameter name="f">
643        <paramtype>const <classname>function</classname>&amp;</paramtype>
644      </parameter>
645      <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>
646    </copy-assignment>
647
648    <copy-assignment>
649      <parameter name="f">
650        <paramtype>const <classname>function</classname>&amp;</paramtype>
651      </parameter>
652      <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>
653      <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>
654    </copy-assignment>
655
656    <method-group name="modifiers">
657      <method name="swap">
658        <type>void</type>
659        <parameter name="f"><paramtype>const <classname>function</classname>&amp;</paramtype></parameter>
660        <effects><simpara>Interchanges the targets of <code>*this</code> and <code>f</code>.</simpara></effects>
661      </method>
662
663      <method name="clear">
664        <type>void</type>
665        <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
666        <throws><simpara>Will not throw.</simpara></throws>
667      </method>
668    </method-group>
669
670    <method-group name="capacity">
671      <method name="empty" cv="const">
672        <type>bool</type>
673        <returns><simpara><code>false</code> if <code>this</code> has a target, and <code>true</code> otherwise.</simpara></returns>
674        <throws><simpara>Will not throw.</simpara></throws>
675      </method>
676
677      <method name="conversion-operator" cv="const">
678        <type>safe_bool</type>
679        <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>
680        <throws><simpara>Will not throw.</simpara></throws>
681      </method>
682
683      <method name="operator!" cv="const">
684        <type>bool</type>
685        <returns><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></returns>
686        <throws><simpara>Will not throw.</simpara></throws>
687      </method>
688    </method-group>
689
690    <method-group name="target access">
691      <overloaded-method name="target">
692        <signature>
693          <template> 
694            <template-type-parameter name="Functor"/>
695          </template>
696          <type>Functor*</type>
697        </signature>
698        <signature cv="const">
699          <template> 
700            <template-type-parameter name="Functor"/>
701          </template>
702          <type>const Functor*</type>
703        </signature>
704
705        <returns><simpara>If <code>this</code> stores a target of type
706        <code>Functor</code>, returns the address of the
707        target. Otherwise, returns the NULL
708        pointer.</simpara></returns>
709        <throws><simpara>Will not throw.</simpara></throws>
710      </overloaded-method>
711
712      <method name="contains" cv="const">
713        <template>
714          <template-type-parameter name="Functor"/>
715        </template>
716        <type>bool</type>
717        <parameter name="f">
718          <paramtype>const Functor&amp;</paramtype>
719        </parameter>
720        <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>
721 
722      </method>
723
724      <method name="target_type" cv="const">
725        <type>const std::type_info&amp;</type>
726        <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>
727        <throws><simpara>Will not throw.</simpara></throws>
728      </method>
729    </method-group>
730
731    <method-group name="invocation">
732      <method name="operator()" cv="const">
733        <type>result_type</type>
734        <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
735        <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
736        <parameter><paramtype>...</paramtype></parameter>
737        <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
738        <effects><simpara><code>f(a1, a2, ..., aN)</code>, where <code>f</code> is the target of <code>*this</code>.</simpara></effects>
739        <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>
740        <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>
741      </method>
742    </method-group>
743
744    <free-function-group name="specialized algorithms">
745      <function name="swap">
746        <template>
747          <template-type-parameter name="Signature"/>
748          <template-type-parameter name="Allocator"/>
749        </template>
750        <type>void</type>
751        <parameter name="f1"><paramtype><classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
752        <parameter name="f2"><paramtype><classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
753        <effects><simpara><code>f1.<methodname>swap</methodname>(f2)</code></simpara></effects>
754      </function>
755    </free-function-group>
756
757    <free-function-group name="comparison operators">
758      <overloaded-function name="operator==">
759        <signature>
760          <template>
761            <template-type-parameter name="Signature"/>
762            <template-type-parameter name="Allocator"/>
763            <template-type-parameter name="Functor"/>
764          </template>
765          <type>bool</type>
766          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
767          <parameter name="g"><paramtype>Functor</paramtype></parameter>
768        </signature>
769        <signature>
770          <template>
771            <template-type-parameter name="Signature"/>
772            <template-type-parameter name="Allocator"/>
773            <template-type-parameter name="Functor"/>
774          </template>
775          <type>bool</type>
776          <parameter name="g"><paramtype>Functor</paramtype></parameter>
777          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
778        </signature>       
779        <signature>
780          <template>
781            <template-type-parameter name="Signature"/>
782            <template-type-parameter name="Allocator"/>
783            <template-type-parameter name="Functor"/>
784          </template>
785          <type>bool</type>
786          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
787          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
788        </signature>
789        <signature>
790          <template>
791            <template-type-parameter name="Signature"/>
792            <template-type-parameter name="Allocator"/>
793            <template-type-parameter name="Functor"/>
794          </template>
795          <type>bool</type>
796          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
797          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
798        </signature>       
799        <signature>
800          <template>
801            <template-type-parameter name="Signature1"/>
802            <template-type-parameter name="Allocator1"/>
803            <template-type-parameter name="Signature2"/>
804            <template-type-parameter name="Allocator2"/>
805          </template>
806          <type>void</type>
807          <parameter name="f1"><paramtype>const <classname>function</classname>&lt;Signature1, Allocator1&gt;&amp;</paramtype></parameter>
808          <parameter name="f2"><paramtype>const <classname>function</classname>&lt;Signature2, Allocator2&gt;&amp;</paramtype></parameter>
809        </signature>
810
811        <returns><simpara>True when <code>f</code> stores an object of
812        type <code>Functor</code> and one of the following conditions applies:
813          <itemizedlist>
814
815            <listitem><simpara><code>g</code> is of type
816            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
817            and <code>f.target&lt;Functor&gt;() == g.<methodname
818            alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
819
820            <listitem><simpara><code>g</code> is not of type
821            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
822            and <code><functionname>function_equals</functionname>(*(f.target&lt;Functor&gt;()), g)</code>.</simpara></listitem>
823
824          </itemizedlist>
825          </simpara></returns>
826
827        <notes><simpara><code><classname>function</classname></code>
828        objects are not
829        <conceptname>EqualityComparable</conceptname>.</simpara></notes>
830
831        <rationale><simpara>The <code>safe_bool</code> conversion
832        opens a loophole whereby two <code>function</code>
833        instances can be compared via <code>==</code>, although this
834        is not feasible to implement. The undefined <code>void
835        operator==</code> closes the loophole and ensures a
836        compile-time or link-time error.</simpara></rationale>
837      </overloaded-function>
838
839      <overloaded-function name="operator!=">
840        <signature>
841          <template>
842            <template-type-parameter name="Signature"/>
843            <template-type-parameter name="Allocator"/>
844            <template-type-parameter name="Functor"/>
845          </template>
846          <type>bool</type>
847          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
848          <parameter name="g"><paramtype>Functor</paramtype></parameter>
849        </signature>
850        <signature>
851          <template>
852            <template-type-parameter name="Signature"/>
853            <template-type-parameter name="Allocator"/>
854            <template-type-parameter name="Functor"/>
855          </template>
856          <type>bool</type>
857          <parameter name="g"><paramtype>Functor</paramtype></parameter>
858          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
859        </signature>       
860        <signature>
861          <template>
862            <template-type-parameter name="Signature"/>
863            <template-type-parameter name="Allocator"/>
864            <template-type-parameter name="Functor"/>
865          </template>
866          <type>bool</type>
867          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
868          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
869        </signature>
870        <signature>
871          <template>
872            <template-type-parameter name="Signature"/>
873            <template-type-parameter name="Allocator"/>
874            <template-type-parameter name="Functor"/>
875          </template>
876          <type>bool</type>
877          <parameter name="g"><paramtype><classname>reference_wrapper</classname>&lt;Functor&gt;</paramtype></parameter>
878          <parameter name="f"><paramtype>const <classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
879        </signature>       
880        <signature>
881          <template>
882            <template-type-parameter name="Signature1"/>
883            <template-type-parameter name="Allocator1"/>
884            <template-type-parameter name="Signature2"/>
885            <template-type-parameter name="Allocator2"/>
886          </template>
887          <type>void</type>
888          <parameter name="f1"><paramtype>const <classname>function</classname>&lt;Signature1, Allocator1&gt;&amp;</paramtype></parameter>
889          <parameter name="f2"><paramtype>const <classname>function</classname>&lt;Signature2, Allocator2&gt;&amp;</paramtype></parameter>
890        </signature>
891
892        <returns><simpara>True when <code>f</code> does not store an
893        object of type <code>Functor</code> or it stores an object of
894        type <code>Functor</code> and one of the following conditions
895        applies:
896          <itemizedlist>
897
898            <listitem><simpara><code>g</code> is of type
899            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
900            and <code>f.target&lt;Functor&gt;() != g.<methodname
901            alt="reference_wrapper::get_pointer">get_pointer</methodname>()</code>.</simpara></listitem>
902
903            <listitem><simpara><code>g</code> is not of type
904            <code><classname>reference_wrapper</classname>&lt;Functor&gt;</code>
905            and <code>!<functionname>function_equals</functionname>(*(f.target&lt;Functor&gt;()), g)</code>.</simpara></listitem>
906
907          </itemizedlist>
908          </simpara></returns>
909
910        <notes><simpara><code><classname>function</classname></code>
911        objects are not
912        <conceptname>EqualityComparable</conceptname>.</simpara></notes>
913
914        <rationale><simpara>The <code>safe_bool</code> conversion
915        opens a loophole whereby two <code>function</code>
916        instances can be compared via <code>!=</code>, although this
917        is not feasible to implement. The undefined <code>void
918        operator!=</code> closes the loophole and ensures a
919        compile-time or link-time error.</simpara></rationale>
920      </overloaded-function>
921    </free-function-group>
922  </class>
923</namespace>
924</header>
925
926<header name="boost/function_equal.hpp">
927  <namespace name="boost">
928  <function name="function_equal">
929    <template>
930      <template-type-parameter name="F"/>
931      <template-type-parameter name="G"/>
932    </template>
933    <type>bool</type>
934    <parameter name="f">
935      <paramtype>const F&amp;</paramtype>
936    </parameter>
937    <parameter name="g">
938      <paramtype>const G&amp;</paramtype>
939    </parameter>
940    <purpose><simpara>Compare two function objects for equality.</simpara></purpose>
941    <returns><simpara><code>f == g</code>.</simpara></returns>
942    <throws><simpara>Only if <code>f == g</code> throws.</simpara></throws>
943  </function>
944  </namespace>
945</header>
946</library-reference>
Note: See TracBrowser for help on using the repository browser.