Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/function/tutorial.html @ 29

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

updated boost from 1_33_1 to 1_34_1
File size: 17.4 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Tutorial</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../function.html" title="Chapter 6. Boost.Function">
9<link rel="prev" href="history.html" title="History &amp; Compatibility Notes">
10<link rel="next" href="reference.html" title="Reference">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="history.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="function.tutorial"></a>Tutorial</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="tutorial.html#id1186501">Basic Usage</a></span></dt>
30<dt><span class="section"><a href="tutorial.html#id1186864">Free functions</a></span></dt>
31<dt><span class="section"><a href="tutorial.html#id1186900">Member functions</a></span></dt>
32<dt><span class="section"><a href="tutorial.html#id1187118">References to Function Objects</a></span></dt>
33<dt><span class="section"><a href="tutorial.html#id1187293">Comparing Boost.Function function objects</a></span></dt>
34</dl></div>
35<p> Boost.Function has two syntactical forms: the preferred form
36and the portable form. The preferred form fits more closely with the
37C++ language and reduces the number of separate template parameters
38that need to be considered, often improving readability; however, the
39preferred form is not supported on all platforms due to compiler
40bugs. The compatible form will work on all compilers supported by
41Boost.Function. Consult the table below to determine which syntactic
42form to use for your compiler.
43
44  </p>
45<div class="informaltable"><table class="table">
46<colgroup>
47<col>
48<col>
49</colgroup>
50<thead><tr>
51<th align="left">Preferred syntax</th>
52<th align="left">Portable syntax</th>
53</tr></thead>
54<tbody><tr>
55<td align="left">
56            <div class="itemizedlist"><ul type="disc" compact>
57<li>GNU C++ 2.95.x, 3.0.x, 3.1.x</li>
58<li>Comeau C++ 4.2.45.2</li>
59<li>SGI MIPSpro 7.3.0</li>
60<li>Intel C++ 5.0, 6.0</li>
61<li>Compaq's cxx 6.2</li>
62<li>Microsoft Visual C++ 7.1</li>
63</ul></div>
64          </td>
65<td align="left">
66            <div class="itemizedlist"><ul type="disc" compact>
67<li><span class="emphasis"><em>Any compiler supporting the preferred syntax</em></span></li>
68<li>Microsoft Visual C++ 6.0, 7.0</li>
69<li>Borland C++ 5.5.1</li>
70<li>Sun WorkShop 6 update 2 C++ 5.3</li>
71<li>Metrowerks CodeWarrior 8.1</li>
72</ul></div>
73          </td>
74</tr></tbody>
75</table></div>
76<p>
77
78</p>
79<p> If your compiler does not appear in this list, please try the preferred syntax and report your results to the Boost list so that we can keep this table up-to-date.</p>
80<div class="section" lang="en">
81<div class="titlepage"><div><div><h3 class="title">
82<a name="id1186501"></a>Basic Usage</h3></div></div></div>
83<p> A function wrapper is defined simply
84by instantiating the <code class="computeroutput">function</code> class
85template with the desired return type and argument types, formulated
86as a C++ function type. Any number of arguments may be supplied, up to
87some implementation-defined limit (10 is the default maximum). The
88following declares a function object wrapper
89<code class="computeroutput">f</code> that takes two
90<code class="computeroutput">int</code> parameters and returns a
91<code class="computeroutput">float</code>:
92
93  </p>
94<div class="informaltable"><table class="table">
95<colgroup>
96<col>
97<col>
98</colgroup>
99<thead><tr>
100<th align="left">Preferred syntax</th>
101<th align="left">Portable syntax</th>
102</tr></thead>
103<tbody><tr>
104<td align="left">
105<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code>&lt;float (int x, int y)&gt; f;</pre>
106</td>
107<td align="left">
108<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../boost/functionN.html" title="Class template functionN">boost::function2</a></code>&lt;float, int, int&gt; f;</pre>
109</td>
110</tr></tbody>
111</table></div>
112<p>
113</p>
114<p> By default, function object wrappers are empty, so we can create a
115function object to assign to <code class="computeroutput">f</code>:
116
117</p>
118<pre class="programlisting">struct int_div {
119  float operator()(int x, int y) const { return ((float)x)/y; };
120};</pre>
121<p>
122</p>
123<pre class="programlisting">f = int_div();</pre>
124<p>
125</p>
126<p> Now we can use <code class="computeroutput">f</code> to execute
127the underlying function object
128<code class="computeroutput">int_div</code>:
129
130</p>
131<pre class="programlisting">std::cout &lt;&lt; f(5, 3) &lt;&lt; std::endl;</pre>
132<p>
133</p>
134<p> We are free to assign any compatible function object to
135<code class="computeroutput">f</code>. If
136<code class="computeroutput">int_div</code> had been declared to take two
137<code class="computeroutput">long</code> operands, the implicit
138conversions would have been applied to the arguments without any user
139interference. The only limit on the types of arguments is that they be
140CopyConstructible, so we can even use references and arrays:
141
142  </p>
143<div class="informaltable"><table class="table">
144<colgroup><col></colgroup>
145<thead><tr><th align="left">Preferred syntax</th></tr></thead>
146<tbody><tr><td align="left">
147<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code>&lt;void (int values[], int n, int&amp; sum, float&amp; avg)&gt; sum_avg;</pre>
148</td></tr></tbody>
149</table></div>
150<p>
151  </p>
152<div class="informaltable"><table class="table">
153<colgroup><col></colgroup>
154<thead><tr><th align="left">Portable syntax</th></tr></thead>
155<tbody><tr><td align="left">
156<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../boost/functionN.html" title="Class template functionN">boost::function4</a></code>&lt;void, int*, int, int&amp;, float&amp;&gt; sum_avg;</pre>
157</td></tr></tbody>
158</table></div>
159<p>
160
161</p>
162<pre class="programlisting">void do_sum_avg(int values[], int n, int&amp; sum, float&amp; avg)
163{
164  sum = 0;
165  for (int i = 0; i &lt; n; i++)
166    sum += values[i];
167  avg = (float)sum / n;
168}</pre>
169<p>
170
171
172</p>
173<pre class="programlisting">sum_avg = &amp;do_sum_avg;</pre>
174<p>
175</p>
176<p> Invoking a function object wrapper that does not actually
177contain a function object is a precondition violation, much like
178trying to call through a null function pointer, and will throw a <code class="computeroutput"><a href="../boost/bad_function_call.html" title="Class bad_function_call">bad_function_call</a></code> exception). We can check for an
179empty function object wrapper by using it in a boolean context (it evaluates <code class="computeroutput">true</code> if the wrapper is not empty) or compare it against <code class="computeroutput">0</code>. For instance:
180</p>
181<pre class="programlisting">if (f)
182  std::cout &lt;&lt; f(5, 3) &lt;&lt; std::endl;
183else
184  std::cout &lt;&lt; "f has no target, so it is unsafe to call" &lt;&lt; std::endl;</pre>
185<p>
186</p>
187<p> Alternatively,
188<code class="computeroutput"><code class="computeroutput"><a href="../boost/function.html#id835072-bb">empty</a></code>()</code>
189method will return whether or not the wrapper is empty.  </p>
190<p> Finally, we can clear out a function target by assigning it to <code class="computeroutput">0</code> or by calling the <code class="computeroutput"><code class="computeroutput"><a href="../boost/function.html#id970240-bb">clear</a></code>()</code> member function, e.g.,
191</p>
192<pre class="programlisting">f = 0;</pre>
193<p>
194</p>
195</div>
196<div class="section" lang="en">
197<div class="titlepage"><div><div><h3 class="title">
198<a name="id1186864"></a>Free functions</h3></div></div></div>
199<p> Free function pointers can be considered singleton function objects with const function call operators, and can therefore be directly used with the function object wrappers:
200</p>
201<pre class="programlisting">float mul_ints(int x, int y) { return ((float)x) * y; }</pre>
202<p>
203</p>
204<pre class="programlisting">f = &amp;mul_ints;</pre>
205<p>
206</p>
207<p> Note that the <code class="computeroutput">&amp;</code> isn't really necessary unless you happen to be using Microsoft Visual C++ version 6. </p>
208</div>
209<div class="section" lang="en">
210<div class="titlepage"><div><div><h3 class="title">
211<a name="id1186900"></a>Member functions</h3></div></div></div>
212<p> In many systems, callbacks often call to member functions of a
213particular object. This is often referred to as "argument binding",
214and is beyond the scope of Boost.Function. The use of member functions
215directly, however, is supported, so the following code is valid:
216
217</p>
218<pre class="programlisting">struct X {
219  int foo(int);
220};</pre>
221<p>
222
223  </p>
224<div class="informaltable"><table class="table">
225<colgroup>
226<col>
227<col>
228</colgroup>
229<thead><tr>
230<th align="left">Preferred syntax</th>
231<th align="left">Portable syntax</th>
232</tr></thead>
233<tbody><tr>
234<td align="left">
235<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code>&lt;int (X*, int)&gt; f;
236
237f = &amp;X::foo;
238 
239X x;
240f(&amp;x, 5);</pre>
241</td>
242<td align="left">
243<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../boost/functionN.html" title="Class template functionN">boost::function2</a></code>&lt;int, X*, int&gt; f;
244
245f = &amp;X::foo;
246 
247X x;
248f(&amp;x, 5);</pre>
249</td>
250</tr></tbody>
251</table></div>
252<p>
253</p>
254<p> Several libraries exist that support argument binding. Three such libraries are summarized below:
255</p>
256<div class="itemizedlist"><ul type="disc">
257<li><p><a href="../../../libs/bind/index.html" target="_top">Bind</a>. This library allows binding of
258  arguments for any function object. It is lightweight and very
259  portable.</p></li>
260<li>
261<p>The C++ Standard library. Using
262  <code class="computeroutput">std::bind1st</code> and
263  <code class="computeroutput">std::mem_fun</code> together one can bind
264  the object of a pointer-to-member function for use with
265  Boost.Function:
266
267  </p>
268<div class="informaltable"><table class="table">
269<colgroup>
270<col>
271<col>
272</colgroup>
273<thead><tr>
274<th align="left">Preferred syntax</th>
275<th align="left">Portable syntax</th>
276</tr></thead>
277<tbody><tr>
278<td align="left">
279<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">  <code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code>&lt;int (int)&gt; f;
280X x;
281f = std::bind1st(
282      std::mem_fun(&amp;X::foo), &amp;x);
283f(5); // Call x.foo(5)</pre>
284</td>
285<td align="left">
286<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">  <code class="computeroutput"><a href="../boost/functionN.html" title="Class template functionN">boost::function1</a></code>&lt;int, int&gt; f;
287X x;
288f = std::bind1st(
289      std::mem_fun(&amp;X::foo), &amp;x);
290f(5); // Call x.foo(5)</pre>
291</td>
292</tr></tbody>
293</table></div>
294<p>
295</p>
296</li>
297<li><p>The <a href="../lambda.html" title="Chapter 8. Boost.Lambda">Lambda</a> library. This library provides a powerful composition mechanism to construct function objects that uses very natural C++ syntax. Lambda requires a compiler that is reasonably conformant to the C++ standard. </p></li>
298</ul></div>
299<p>
300</p>
301</div>
302<div class="section" lang="en">
303<div class="titlepage"><div><div><h3 class="title">
304<a name="id1187118"></a>References to Function Objects</h3></div></div></div>
305<p> In some cases it is
306  expensive (or semantically incorrect) to have Boost.Function clone a
307  function object. In such cases, it is possible to request that
308  Boost.Function keep only a reference to the actual function
309  object. This is done using the <code class="computeroutput">ref</code>
310  and <code class="computeroutput">cref</code> functions to wrap a
311  reference to a function object:
312
313  </p>
314<div class="informaltable"><table class="table">
315<colgroup>
316<col>
317<col>
318</colgroup>
319<thead><tr>
320<th align="left">Preferred syntax</th>
321<th align="left">Portable syntax</th>
322</tr></thead>
323<tbody><tr>
324<td align="left">
325<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">stateful_type a_function_object;
326<code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code>&lt;int (int)&gt; f;
327f = <code class="computeroutput"><a href="../boost/reference_wrapper.html#id1044490-bb">boost::ref</a></code>(a_function_object);
328
329<code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code>&lt;int (int)&gt; f2(f);</pre>
330</td>
331<td align="left">
332<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">stateful_type a_function_object;
333<code class="computeroutput"><a href="../boost/functionN.html" title="Class template functionN">boost::function1</a></code>&lt;int, int&gt; f;
334f = <code class="computeroutput"><a href="../boost/reference_wrapper.html#id1044490-bb">boost::ref</a></code>(a_function_object);
335
336<code class="computeroutput"><a href="../boost/functionN.html" title="Class template functionN">boost::function1</a></code>&lt;int, int&gt; f2(f);</pre>
337</td>
338</tr></tbody>
339</table></div>
340<p>
341</p>
342<p> Here, <code class="computeroutput">f</code> will not make a copy
343of <code class="computeroutput">a_function_object</code>, nor will
344<code class="computeroutput">f2</code> when it is targeted to
345<code class="computeroutput">f</code>'s reference to
346<code class="computeroutput">a_function_object</code>. Additionally, when
347using references to function objects, Boost.Function will not throw
348exceptions during assignment or construction.
349</p>
350</div>
351<div class="section" lang="en">
352<div class="titlepage"><div><div><h3 class="title">
353<a name="id1187293"></a>Comparing Boost.Function function objects</h3></div></div></div>
354<p>Function object wrappers can be compared via <code class="computeroutput">==</code>
355  or <code class="computeroutput">!=</code> against any function object that can be stored
356  within the wrapper. If the function object wrapper contains a
357  function object of that type, it will be compared against the given
358  function object (which must be either be
359  <a href="../EqualityComparable.html" title="Concept EqualityComparable">EqualityComparable</a> or have an overloaded <code class="computeroutput"><a href="../boost/function_equal.html" title="Function template function_equal">boost::function_equal</a></code>). For instance:</p>
360<pre class="programlisting">int compute_with_X(X*, int);
361
362f = &amp;X::foo;
363assert(f == &amp;X::foo);
364assert(&amp;compute_with_X != f);</pre>
365<p>When comparing against an instance of
366   <code class="computeroutput"><a href="../boost/reference_wrapper.html" title="Class template reference_wrapper">reference_wrapper</a></code>, the address
367   of the object in the
368   <code class="computeroutput"><a href="../boost/reference_wrapper.html" title="Class template reference_wrapper">reference_wrapper</a></code> is compared
369   against the address of the object stored by the function object
370   wrapper:</p>
371<pre class="programlisting">a_stateful_object so1, so2;
372f = <code class="computeroutput"><a href="../boost/reference_wrapper.html#id1044490-bb">boost::ref</a></code>(so1);
373assert(f == <code class="computeroutput"><a href="../boost/reference_wrapper.html#id1044490-bb">boost::ref</a></code>(so1));
374assert(f == so1); <span class="emphasis"><em>// Only if a_stateful_object is <a href="../EqualityComparable.html" title="Concept EqualityComparable">EqualityComparable</a></em></span>
375assert(f != <code class="computeroutput"><a href="../boost/reference_wrapper.html#id1044490-bb">boost::ref</a></code>(so2));</pre>
376</div>
377</div>
378<table width="100%"><tr>
379<td align="left"><small><p>Last revised: November 03, 2006 at 19:41:10 GMT</p></small></td>
380<td align="right"><small>Copyright © 2001-2004 Douglas Gregor</small></td>
381</tr></table>
382<hr>
383<div class="spirit-nav">
384<a accesskey="p" href="history.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../images/next.png" alt="Next"></a>
385</div>
386</body>
387</html>
Note: See TracBrowser for help on using the repository browser.