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.69.1"> |
---|
7 | <link rel="start" href="../index.html" title="The Boost C++ Libraries"> |
---|
8 | <link rel="up" href="../function.html" title="Chapter 4. Boost.Function"> |
---|
9 | <link rel="prev" href="history.html" title="History & 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.png (6897 bytes)" 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><h3 class="title"> |
---|
27 | <a name="function.tutorial"></a>Tutorial</h3></div></div></div> |
---|
28 | <div class="toc"><dl> |
---|
29 | <dt><span class="section"><a href="tutorial.html#id2688219">Basic Usage</a></span></dt> |
---|
30 | <dt><span class="section"><a href="tutorial.html#id2688524">Free functions</a></span></dt> |
---|
31 | <dt><span class="section"><a href="tutorial.html#id2688553">Member functions</a></span></dt> |
---|
32 | <dt><span class="section"><a href="tutorial.html#id2688714">References to Function Objects</a></span></dt> |
---|
33 | <dt><span class="section"><a href="tutorial.html#id2688865">Comparing Boost.Function function objects</a></span></dt> |
---|
34 | </dl></div> |
---|
35 | <p> Boost.Function has two syntactical forms: the preferred form |
---|
36 | and the portable form. The preferred form fits more closely with the |
---|
37 | C++ language and reduces the number of separate template parameters |
---|
38 | that need to be considered, often improving readability; however, the |
---|
39 | preferred form is not supported on all platforms due to compiler |
---|
40 | bugs. The compatible form will work on all compilers supported by |
---|
41 | Boost.Function. Consult the table below to determine which syntactic |
---|
42 | form 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"><div class="itemizedlist"><ul type="disc" compact> |
---|
56 | <li>GNU C++ 2.95.x, 3.0.x, 3.1.x</li> |
---|
57 | <li>Comeau C++ 4.2.45.2</li> |
---|
58 | <li>SGI MIPSpro 7.3.0</li> |
---|
59 | <li>Intel C++ 5.0, 6.0</li> |
---|
60 | <li>Compaq's cxx 6.2</li> |
---|
61 | <li>Microsoft Visual C++ 7.1</li> |
---|
62 | </ul></div></td> |
---|
63 | <td align="left"><div class="itemizedlist"><ul type="disc" compact> |
---|
64 | <li><span class="emphasis"><em>Any compiler supporting the preferred syntax</em></span></li> |
---|
65 | <li>Microsoft Visual C++ 6.0, 7.0</li> |
---|
66 | <li>Borland C++ 5.5.1</li> |
---|
67 | <li>Sun WorkShop 6 update 2 C++ 5.3</li> |
---|
68 | <li>Metrowerks CodeWarrior 8.1</li> |
---|
69 | </ul></div></td> |
---|
70 | </tr></tbody> |
---|
71 | </table></div> |
---|
72 | <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> |
---|
73 | <div class="section" lang="en"> |
---|
74 | <div class="titlepage"><div><div><h4 class="title"> |
---|
75 | <a name="id2688219"></a>Basic Usage</h4></div></div></div> |
---|
76 | <p> A function wrapper is defined simply |
---|
77 | by instantiating the <code class="computeroutput">function</code> class |
---|
78 | template with the desired return type and argument types, formulated |
---|
79 | as a C++ function type. Any number of arguments may be supplied, up to |
---|
80 | some implementation-defined limit (10 is the default maximum). The |
---|
81 | following declares a function object wrapper |
---|
82 | <code class="computeroutput">f</code> that takes two |
---|
83 | <code class="computeroutput">int</code> parameters and returns a |
---|
84 | <code class="computeroutput">float</code>: |
---|
85 | |
---|
86 | </p> |
---|
87 | <div class="informaltable"><table class="table"> |
---|
88 | <colgroup> |
---|
89 | <col> |
---|
90 | <col> |
---|
91 | </colgroup> |
---|
92 | <thead><tr> |
---|
93 | <th align="left">Preferred syntax</th> |
---|
94 | <th align="left">Portable syntax</th> |
---|
95 | </tr></thead> |
---|
96 | <tbody><tr> |
---|
97 | <td align="left"><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><float (int x, int y)> f;</pre></td> |
---|
98 | <td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../functionN.html" title="Class template functionN">boost::function2</a></code><float, int, int> f;</pre></td> |
---|
99 | </tr></tbody> |
---|
100 | </table></div> |
---|
101 | <p> By default, function object wrappers are empty, so we can create a |
---|
102 | function object to assign to <code class="computeroutput">f</code>: |
---|
103 | |
---|
104 | </p> |
---|
105 | <pre class="programlisting">struct int_div { |
---|
106 | float operator()(int x, int y) const { return ((float)x)/y; }; |
---|
107 | };</pre> |
---|
108 | <pre class="programlisting">f = int_div();</pre> |
---|
109 | <p> Now we can use <code class="computeroutput">f</code> to execute |
---|
110 | the underlying function object |
---|
111 | <code class="computeroutput">int_div</code>: |
---|
112 | |
---|
113 | </p> |
---|
114 | <pre class="programlisting">std::cout << f(5, 3) << std::endl;</pre> |
---|
115 | <p> We are free to assign any compatible function object to |
---|
116 | <code class="computeroutput">f</code>. If |
---|
117 | <code class="computeroutput">int_div</code> had been declared to take two |
---|
118 | <code class="computeroutput">long</code> operands, the implicit |
---|
119 | conversions would have been applied to the arguments without any user |
---|
120 | interference. The only limit on the types of arguments is that they be |
---|
121 | CopyConstructible, so we can even use references and arrays: |
---|
122 | |
---|
123 | </p> |
---|
124 | <div class="informaltable"><table class="table"> |
---|
125 | <colgroup><col></colgroup> |
---|
126 | <thead><tr><th align="left">Preferred syntax</th></tr></thead> |
---|
127 | <tbody><tr><td align="left"><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><void (int values[], int n, int& sum, float& avg)> sum_avg;</pre></td></tr></tbody> |
---|
128 | </table></div> |
---|
129 | <div class="informaltable"><table class="table"> |
---|
130 | <colgroup><col></colgroup> |
---|
131 | <thead><tr><th align="left">Portable syntax</th></tr></thead> |
---|
132 | <tbody><tr><td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../functionN.html" title="Class template functionN">boost::function4</a></code><void, int*, int, int&, float&> sum_avg;</pre></td></tr></tbody> |
---|
133 | </table></div> |
---|
134 | <pre class="programlisting">void do_sum_avg(int values[], int n, int& sum, float& avg) |
---|
135 | { |
---|
136 | sum = 0; |
---|
137 | for (int i = 0; i < n; i++) |
---|
138 | sum += values[i]; |
---|
139 | avg = (float)sum / n; |
---|
140 | }</pre> |
---|
141 | <pre class="programlisting">sum_avg = &do_sum_avg;</pre> |
---|
142 | <p> Invoking a function object wrapper that does not actually |
---|
143 | contain a function object is a precondition violation, much like |
---|
144 | trying to call through a null function pointer, and will throw a <code class="computeroutput"><a href="../bad_function_call.html" title="Class bad_function_call">bad_function_call</a></code> exception). We can check for an |
---|
145 | empty 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: |
---|
146 | </p> |
---|
147 | <pre class="programlisting">if (f) |
---|
148 | std::cout << f(5, 3) << std::endl; |
---|
149 | else |
---|
150 | std::cout << "f has no target, so it is unsafe to call" << std::endl;</pre> |
---|
151 | <p> Alternatively, |
---|
152 | <code class="computeroutput"><code class="computeroutput"><a href="../boost/function.html#id2396343-bb">empty</a></code>()</code> |
---|
153 | method will return whether or not the wrapper is empty. </p> |
---|
154 | <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#id2434373-bb">clear</a></code>()</code> member function, e.g., |
---|
155 | </p> |
---|
156 | <pre class="programlisting">f = 0;</pre> |
---|
157 | </div> |
---|
158 | <div class="section" lang="en"> |
---|
159 | <div class="titlepage"><div><div><h4 class="title"> |
---|
160 | <a name="id2688524"></a>Free functions</h4></div></div></div> |
---|
161 | <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: |
---|
162 | </p> |
---|
163 | <pre class="programlisting">float mul_ints(int x, int y) { return ((float)x) * y; }</pre> |
---|
164 | <pre class="programlisting">f = &mul_ints;</pre> |
---|
165 | <p> Note that the <code class="computeroutput">&</code> isn't really necessary unless you happen to be using Microsoft Visual C++ version 6. </p> |
---|
166 | </div> |
---|
167 | <div class="section" lang="en"> |
---|
168 | <div class="titlepage"><div><div><h4 class="title"> |
---|
169 | <a name="id2688553"></a>Member functions</h4></div></div></div> |
---|
170 | <p> In many systems, callbacks often call to member functions of a |
---|
171 | particular object. This is often referred to as "argument binding", |
---|
172 | and is beyond the scope of Boost.Function. The use of member functions |
---|
173 | directly, however, is supported, so the following code is valid: |
---|
174 | |
---|
175 | </p> |
---|
176 | <pre class="programlisting">struct X { |
---|
177 | int foo(int); |
---|
178 | };</pre> |
---|
179 | <div class="informaltable"><table class="table"> |
---|
180 | <colgroup> |
---|
181 | <col> |
---|
182 | <col> |
---|
183 | </colgroup> |
---|
184 | <thead><tr> |
---|
185 | <th align="left">Preferred syntax</th> |
---|
186 | <th align="left">Portable syntax</th> |
---|
187 | </tr></thead> |
---|
188 | <tbody><tr> |
---|
189 | <td align="left"><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><int (X*, int)> f; |
---|
190 | |
---|
191 | f = &X::foo; |
---|
192 | |
---|
193 | X x; |
---|
194 | f(&x, 5);</pre></td> |
---|
195 | <td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../functionN.html" title="Class template functionN">boost::function2</a></code><int, X*, int> f; |
---|
196 | |
---|
197 | f = &X::foo; |
---|
198 | |
---|
199 | X x; |
---|
200 | f(&x, 5);</pre></td> |
---|
201 | </tr></tbody> |
---|
202 | </table></div> |
---|
203 | <p> Several libraries exist that support argument binding. Three such libraries are summarized below: |
---|
204 | </p> |
---|
205 | <div class="itemizedlist"><ul type="disc"> |
---|
206 | <li><p><a href="../../../libs/bind/index.html" target="_top">Bind</a>. This library allows binding of |
---|
207 | arguments for any function object. It is lightweight and very |
---|
208 | portable.</p></li> |
---|
209 | <li> |
---|
210 | <p>The C++ Standard library. Using |
---|
211 | <code class="computeroutput">std::bind1st</code> and |
---|
212 | <code class="computeroutput">std::mem_fun</code> together one can bind |
---|
213 | the object of a pointer-to-member function for use with |
---|
214 | Boost.Function: |
---|
215 | |
---|
216 | </p> |
---|
217 | <div class="informaltable"><table class="table"> |
---|
218 | <colgroup> |
---|
219 | <col> |
---|
220 | <col> |
---|
221 | </colgroup> |
---|
222 | <thead><tr> |
---|
223 | <th align="left">Preferred syntax</th> |
---|
224 | <th align="left">Portable syntax</th> |
---|
225 | </tr></thead> |
---|
226 | <tbody><tr> |
---|
227 | <td align="left"><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><int (int)> f; |
---|
228 | X x; |
---|
229 | f = std::bind1st( |
---|
230 | std::mem_fun(&X::foo), &x); |
---|
231 | f(5); // Call x.foo(5)</pre></td> |
---|
232 | <td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../functionN.html" title="Class template functionN">boost::function1</a></code><int, int> f; |
---|
233 | X x; |
---|
234 | f = std::bind1st( |
---|
235 | std::mem_fun(&X::foo), &x); |
---|
236 | f(5); // Call x.foo(5)</pre></td> |
---|
237 | </tr></tbody> |
---|
238 | </table></div> |
---|
239 | </li> |
---|
240 | <li><p>The <a href="../lambda.html" title="Chapter 6. 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> |
---|
241 | </ul></div> |
---|
242 | </div> |
---|
243 | <div class="section" lang="en"> |
---|
244 | <div class="titlepage"><div><div><h4 class="title"> |
---|
245 | <a name="id2688714"></a>References to Function Objects</h4></div></div></div> |
---|
246 | <p> In some cases it is |
---|
247 | expensive (or semantically incorrect) to have Boost.Function clone a |
---|
248 | function object. In such cases, it is possible to request that |
---|
249 | Boost.Function keep only a reference to the actual function |
---|
250 | object. This is done using the <code class="computeroutput">ref</code> |
---|
251 | and <code class="computeroutput">cref</code> functions to wrap a |
---|
252 | reference to a function object: |
---|
253 | |
---|
254 | </p> |
---|
255 | <div class="informaltable"><table class="table"> |
---|
256 | <colgroup> |
---|
257 | <col> |
---|
258 | <col> |
---|
259 | </colgroup> |
---|
260 | <thead><tr> |
---|
261 | <th align="left">Preferred syntax</th> |
---|
262 | <th align="left">Portable syntax</th> |
---|
263 | </tr></thead> |
---|
264 | <tbody><tr> |
---|
265 | <td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">stateful_type a_function_object; |
---|
266 | <code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code><int (int)> f; |
---|
267 | f = <code class="computeroutput"><a href="../reference_wrapper.html#id2366489">boost::ref</a></code>(a_function_object); |
---|
268 | |
---|
269 | <code class="computeroutput"><a href="../boost/function.html" title="Class template function">boost::function</a></code><int (int)> f2(f);</pre></td> |
---|
270 | <td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">stateful_type a_function_object; |
---|
271 | <code class="computeroutput"><a href="../functionN.html" title="Class template functionN">boost::function1</a></code><int, int> f; |
---|
272 | f = <code class="computeroutput"><a href="../reference_wrapper.html#id2366489">boost::ref</a></code>(a_function_object); |
---|
273 | |
---|
274 | <code class="computeroutput"><a href="../functionN.html" title="Class template functionN">boost::function1</a></code><int, int> f2(f);</pre></td> |
---|
275 | </tr></tbody> |
---|
276 | </table></div> |
---|
277 | <p> Here, <code class="computeroutput">f</code> will not make a copy |
---|
278 | of <code class="computeroutput">a_function_object</code>, nor will |
---|
279 | <code class="computeroutput">f2</code> when it is targeted to |
---|
280 | <code class="computeroutput">f</code>'s reference to |
---|
281 | <code class="computeroutput">a_function_object</code>. Additionally, when |
---|
282 | using references to function objects, Boost.Function will not throw |
---|
283 | exceptions during assignment or construction. |
---|
284 | </p> |
---|
285 | </div> |
---|
286 | <div class="section" lang="en"> |
---|
287 | <div class="titlepage"><div><div><h4 class="title"> |
---|
288 | <a name="id2688865"></a>Comparing Boost.Function function objects</h4></div></div></div> |
---|
289 | <p>Function object wrappers can be compared via <code class="computeroutput">==</code> |
---|
290 | or <code class="computeroutput">!=</code> against any function object that can be stored |
---|
291 | within the wrapper. If the function object wrapper contains a |
---|
292 | function object of that type, it will be compared against the given |
---|
293 | function object (which must be either be |
---|
294 | <a href="../EqualityComparable.html" title="Concept EqualityComparable">EqualityComparable</a> or have an overloaded <code class="computeroutput"><a href="../function_equal.html" title="Function template function_equal">boost::function_equal</a></code>). For instance:</p> |
---|
295 | <pre class="programlisting">int compute_with_X(X*, int); |
---|
296 | |
---|
297 | f = &X::foo; |
---|
298 | assert(f == &X::foo); |
---|
299 | assert(&compute_with_X != f);</pre> |
---|
300 | <p>When comparing against an instance of |
---|
301 | <code class="computeroutput"><a href="../reference_wrapper.html" title="Class template reference_wrapper">reference_wrapper</a></code>, the address |
---|
302 | of the object in the |
---|
303 | <code class="computeroutput"><a href="../reference_wrapper.html" title="Class template reference_wrapper">reference_wrapper</a></code> is compared |
---|
304 | against the address of the object stored by the function object |
---|
305 | wrapper:</p> |
---|
306 | <pre class="programlisting">a_stateful_object so1, so2; |
---|
307 | f = <code class="computeroutput"><a href="../reference_wrapper.html#id2366489">boost::ref</a></code>(so1); |
---|
308 | assert(f == <code class="computeroutput"><a href="../reference_wrapper.html#id2366489">boost::ref</a></code>(so1)); |
---|
309 | assert(f == so1); <span class="emphasis"><em>// Only if a_stateful_object is <a href="../EqualityComparable.html" title="Concept EqualityComparable">EqualityComparable</a></em></span> |
---|
310 | assert(f != <code class="computeroutput"><a href="../reference_wrapper.html#id2366489">boost::ref</a></code>(so2));</pre> |
---|
311 | </div> |
---|
312 | </div> |
---|
313 | <table width="100%"><tr> |
---|
314 | <td align="left"><small><p>Last revised: March 18, 2005 at 04:54:32 GMT</p></small></td> |
---|
315 | <td align="right"><small>Copyright © 2001-2004 Douglas Gregor</small></td> |
---|
316 | </tr></table> |
---|
317 | <hr> |
---|
318 | <div class="spirit-nav"> |
---|
319 | <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> |
---|
320 | </div> |
---|
321 | </body> |
---|
322 | </html> |
---|