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