Gitiles
Code Review Sign In
gerrit.named-data.net / ndn-cxx / 7aec02511f549132613b80473a4d38906bf8b74b / . / libs / functional / forward / doc / html / index.html
blob: 49d52b0172367e0a6c73eb08fcb9f4a38226259c [file] [log] [blame]
Jeff Thompsona28eed82013-08-22 16:21:10 -0700[diff] [blame]1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4<title>Chapter&#160;1.&#160;Boost.Functional/Forward 1.0</title>
5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7<link rel="home" href="index.html" title="Chapter&#160;1.&#160;Boost.Functional/Forward 1.0">
8</head>
9<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
10<table cellpadding="2" width="100%"><tr>
11<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
12<td align="center"><a href="../../../../../index.html">Home</a></td>
13<td align="center"><a href="../../../../libraries.htm">Libraries</a></td>
14<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
15<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
16<td align="center"><a href="../../../../../more/index.htm">More</a></td>
17</tr></table>
18<hr>
19<div class="spirit-nav"></div>
20<div class="chapter">
21<div class="titlepage"><div>
22<div><h2 class="title">
23<a name="boost_functional_forward"></a>Chapter&#160;1.&#160;Boost.Functional/Forward 1.0</h2></div>
24<div><div class="author"><h3 class="author">
25<span class="firstname">Tobias</span> <span class="surname">Schwinger</span>
26</h3></div></div>
27<div><p class="copyright">Copyright &#169; 2007, 2008 Tobias Schwinger</p></div>
28<div><div class="legalnotice">
29<a name="boost_functional_forward.legal"></a><p>
30 Distributed under the Boost Software License, Version 1.0. (See accompanying
31 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
32 </p>
33</div></div>
34</div></div>
35<div class="toc">
36<p><b>Table of Contents</b></p>
37<dl class="toc">
38<dt><span class="section"><a href="index.html#boost_functional_forward.brief_description">Brief Description</a></span></dt>
39<dt><span class="section"><a href="index.html#boost_functional_forward.background">Background</a></span></dt>
40<dt><span class="section"><a href="index.html#boost_functional_forward.reference">Reference</a></span></dt>
41<dt><span class="section"><a href="index.html#boost_functional_forward.acknowledgements">Acknowledgements</a></span></dt>
42<dt><span class="section"><a href="index.html#boost_functional_forward.references">References</a></span></dt>
43</dl>
44</div>
45<div class="section">
46<div class="titlepage"><div><div><h2 class="title" style="clear: both">
47<a name="boost_functional_forward.brief_description"></a><a class="link" href="index.html#boost_functional_forward.brief_description" title="Brief Description">Brief Description</a>
48</h2></div></div></div>
49<p>
50 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">forward_adapter</span></code> provides a reusable adapter
51 template for function objects. It forwards RValues as references to const,
52 while leaving LValues as-is.
53 </p>
54<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">g</span> <span class="comment">// function object that only accept LValues</span>
55<span class="special">{</span>
56 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T0</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T2</span> <span class="special">&gt;</span>
57 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T0</span> <span class="special">&amp;</span> <span class="identifier">t0</span><span class="special">,</span> <span class="identifier">T1</span> <span class="special">&amp;</span> <span class="identifier">t1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="special">&amp;</span> <span class="identifier">t2</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
58
59 <span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">result_type</span><span class="special">;</span>
60<span class="special">};</span>
61
62<span class="comment">// Adapted version also accepts RValues and forwards</span>
63<span class="comment">// them as references to const, LValues as-is</span>
64<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">forward_adapter</span><span class="special">&lt;</span><span class="identifier">g</span><span class="special">&gt;</span> <span class="identifier">f</span><span class="special">;</span>
65</pre>
66<p>
67 Another adapter, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lighweight_forward_adapter</span></code> allows forwarding
68 with some help from the user accepting and unwrapping reference wrappers (see
69 <a href="http://www.boost.org/doc/html/ref.html" target="_top">Boost.Ref</a>) for
70 reference arguments, const qualifying all other arguments.
71 </p>
72<p>
73 The target functions must be compatible with <a href="http://www.boost.org/libs/utility/utility.htm#result_of" target="_top">Boost.ResultOf</a>,
74 and so are the adapters.
75 </p>
76</div>
77<div class="section">
78<div class="titlepage"><div><div><h2 class="title" style="clear: both">
79<a name="boost_functional_forward.background"></a><a class="link" href="index.html#boost_functional_forward.background" title="Background">Background</a>
80</h2></div></div></div>
81<p>
82 Let's suppose we have some function <code class="computeroutput"><span class="identifier">f</span></code>
83 that we can call like this:
84 </p>
85<pre class="programlisting"><span class="identifier">f</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="identifier">a_variable</span><span class="special">);</span>
86</pre>
87<p>
88 Now we want to write another, generic function <code class="computeroutput"><span class="identifier">g</span></code>
89 that can be called the same way and returns some object that calls <code class="computeroutput"><span class="identifier">f</span></code> with the same arguments.
90 </p>
91<pre class="programlisting"><span class="identifier">f</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="identifier">a_variable</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span><span class="number">123</span><span class="special">,</span><span class="identifier">a_variable</span><span class="special">).</span><span class="identifier">call_f</span><span class="special">()</span>
92</pre>
93<h4>
94<a name="boost_functional_forward.background.h0"></a>
95 <span class="phrase"><a name="boost_functional_forward.background.why_would_we_want_to_do_it__anyway_"></a></span><a class="link" href="index.html#boost_functional_forward.background.why_would_we_want_to_do_it__anyway_">Why
96 would we want to do it, anyway?</a>
97 </h4>
98<p>
99 Maybe we want to run <code class="computeroutput"><span class="identifier">f</span></code> several
100 times. Or maybe we want to run it within another thread. Maybe we just want
101 to encapsulate the call expression for now, and then use it with other code
102 that allows to compose more complex expressions in order to decompose it with
103 C++ templates and have the compiler generate some machinery that eventually
104 calls <code class="computeroutput"><span class="identifier">f</span></code> at runtime (in other
105 words; apply a technique that is commonly referred to as Expression Templates).
106 </p>
107<h4>
108<a name="boost_functional_forward.background.h1"></a>
109 <span class="phrase"><a name="boost_functional_forward.background.now__how_do_we_do_it_"></a></span><a class="link" href="index.html#boost_functional_forward.background.now__how_do_we_do_it_">Now, how
110 do we do it?</a>
111 </h4>
112<p>
113 The bad news is: It's impossible.
114 </p>
115<p>
116 That is so because there is a slight difference between a variable and an expression
117 that evaluates to its value: Given
118 </p>
119<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">y</span><span class="special">;</span>
120<span class="keyword">int</span> <span class="keyword">const</span> <span class="identifier">z</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
121</pre>
122<p>
123 and
124 </p>
125<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</span> <span class="keyword">void</span> <span class="identifier">func1</span><span class="special">(</span><span class="identifier">T</span> <span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
126</pre>
127<p>
128 we can call
129 </p>
130<pre class="programlisting"><span class="identifier">func1</span><span class="special">(</span><span class="identifier">y</span><span class="special">);</span> <span class="comment">// x is a reference to a non-const object</span>
131<span class="identifier">func1</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span> <span class="comment">// x is a reference to a const object</span>
132</pre>
133<p>
134 where
135 </p>
136<pre class="programlisting"><span class="identifier">func1</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> <span class="comment">// fails to compile.</span>
137</pre>
138<p>
139 This way we can safely have <code class="computeroutput"><span class="identifier">func1</span></code>
140 store its reference argument and the compiler keeps us from storing a reference
141 to an object with temporary lifetime.
142 </p>
143<p>
144 It is important to realize that non-constness and whether an object binds to
145 a non-const reference parameter are two different properties. The latter is
146 the distinction between LValues and RValues. The names stem from the left hand
147 side and the right hand side of assignment expressions, thus LValues are typically
148 the ones you can assign to, and RValues the temporary results from the right
149 hand side expression.
150 </p>
151<pre class="programlisting"><span class="identifier">y</span> <span class="special">=</span> <span class="number">1</span><span class="special">+</span><span class="number">2</span><span class="special">;</span> <span class="comment">// a is LValue, 1+2 is the expression producing the RValue,</span>
152<span class="comment">// 1+2 = a; // usually makes no sense. </span>
153
154<span class="identifier">func1</span><span class="special">(</span><span class="identifier">y</span><span class="special">);</span> <span class="comment">// works, because y is an LValue</span>
155<span class="comment">// func1(1+2); // fails to compile, because we only got an RValue.</span>
156</pre>
157<p>
158 If we add const qualification on the parameter, our function also accepts RValues:
159 </p>
160<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</span> <span class="keyword">void</span> <span class="identifier">func2</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
161
162<span class="comment">// [...] function scope:</span>
163<span class="identifier">func2</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> <span class="comment">// x is a reference to a const temporary, object,</span>
164<span class="identifier">func2</span><span class="special">(</span><span class="identifier">y</span><span class="special">);</span> <span class="comment">// x is a reference to a const object, while y is not const, and</span>
165<span class="identifier">func2</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span> <span class="comment">// x is a reference to a const object, just like z.</span>
166</pre>
167<p>
168 In all cases, the argument <code class="computeroutput"><span class="identifier">x</span></code>
169 in <code class="computeroutput"><span class="identifier">func2</span></code> is a const-qualified
170 LValue. We can use function overloading to identify non-const LValues:
171 </p>
172<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</span> <span class="keyword">void</span> <span class="identifier">func3</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span> <span class="comment">// #1</span>
173<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</span> <span class="keyword">void</span> <span class="identifier">func3</span><span class="special">(</span><span class="identifier">T</span> <span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span> <span class="comment">// #2</span>
174
175<span class="comment">// [...] function scope:</span>
176<span class="identifier">func3</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> <span class="comment">// x is a reference to a const, temporary object in #1,</span>
177<span class="identifier">func3</span><span class="special">(</span><span class="identifier">y</span><span class="special">);</span> <span class="comment">// x is a reference to a non-const object in #2, and</span>
178<span class="identifier">func3</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span> <span class="comment">// x is a reference to a const object in #1.</span>
179</pre>
180<p>
181 Note that all arguments <code class="computeroutput"><span class="identifier">x</span></code> in
182 the overloaded function <code class="computeroutput"><span class="identifier">func3</span></code>
183 are LValues. In fact, there is no way to transport RValues into a function
184 as-is in C++98. Also note that we can't distinguish between what used to be
185 a const qualified LValue and an RValue.
186 </p>
187<p>
188 That's as close as we can get to a generic forwarding function <code class="computeroutput"><span class="identifier">g</span></code> as described above by the means of C++
189 98. See <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_top">The
190 Forwarding Problem</a> for a very detailed discussion including solutions
191 that require language changes.
192 </p>
193<p>
194 Now, for actually implementing it, we need 2^N overloads for N parameters (each
195 with and without const qualifier) for each number of arguments (that is 2^(Nmax+1)
196 - 2^Nmin). Right, that means the compile-time complexity is O(2^N), however
197 the factor is low so it works quite well for a reasonable number (&lt; 10)
198 of arguments.
199 </p>
200</div>
201<div class="section">
202<div class="titlepage"><div><div><h2 class="title" style="clear: both">
203<a name="boost_functional_forward.reference"></a><a class="link" href="index.html#boost_functional_forward.reference" title="Reference">Reference</a>
204</h2></div></div></div>
205<div class="toc"><dl class="toc">
206<dt><span class="section"><a href="index.html#boost_functional_forward.reference.forward_adapter">forward_adapter</a></span></dt>
207<dt><span class="section"><a href="index.html#boost_functional_forward.reference.lightweight_forward_adapter">lightweight_forward_adapter</a></span></dt>
208</dl></div>
209<div class="section">
210<div class="titlepage"><div><div><h3 class="title">
211<a name="boost_functional_forward.reference.forward_adapter"></a><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter" title="forward_adapter">forward_adapter</a>
212</h3></div></div></div>
213<h5>
214<a name="boost_functional_forward.reference.forward_adapter.h0"></a>
215 <span class="phrase"><a name="boost_functional_forward.reference.forward_adapter.description"></a></span><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter.description">Description</a>
216 </h5>
217<p>
218 Function object adapter template whose instances are callable with LValue
219 and RValue arguments. RValue arguments are forwarded as reference-to-const
220 typed LValues.
221 </p>
222<p>
223 An arity can be given as second, numeric non-type template argument to restrict
224 forwarding to a specific arity. If a third, numeric non-type template argument
225 is present, the second and third template argument are treated as minimum
226 and maximum arity, respectively. Specifying an arity can be helpful to improve
227 the readability of diagnostic messages and compile time performance.
228 </p>
229<p>
230 <a href="http://www.boost.org/libs/utility/utility.htm#result_of" target="_top">Boost.ResultOf</a>
231 can be used to determine the result types of specific call expressions.
232 </p>
233<h5>
234<a name="boost_functional_forward.reference.forward_adapter.h1"></a>
235 <span class="phrase"><a name="boost_functional_forward.reference.forward_adapter.header"></a></span><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter.header">Header</a>
236 </h5>
237<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">functional</span><span class="special">/</span><span class="identifier">forward_adapter</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
238</pre>
239<h5>
240<a name="boost_functional_forward.reference.forward_adapter.h2"></a>
241 <span class="phrase"><a name="boost_functional_forward.reference.forward_adapter.synopsis"></a></span><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter.synopsis">Synopsis</a>
242 </h5>
243<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span>
244<span class="special">{</span>
245 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">Function</span><span class="special">,</span>
246 <span class="keyword">int</span> <span class="identifier">Arity_Or_MinArity</span> <span class="special">=</span> <span class="emphasis"><em>unspecified</em></span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">MaxArity</span> <span class="special">=</span> <span class="emphasis"><em>unspecified</em></span> <span class="special">&gt;</span>
247 <span class="keyword">class</span> <span class="identifier">forward_adapter</span><span class="special">;</span>
248<span class="special">}</span>
249</pre>
250<div class="variablelist">
251<p class="title"><b>Notation</b></p>
252<dl class="variablelist">
253<dt><span class="term"><code class="computeroutput"><span class="identifier">F</span></code></span></dt>
254<dd><p>
255 a possibly const qualified function object type or reference type thereof
256 </p></dd>
257<dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code></span></dt>
258<dd><p>
259 an object convertible to <code class="computeroutput"><span class="identifier">F</span></code>
260 </p></dd>
261<dt><span class="term"><code class="computeroutput"><span class="identifier">FA</span></code></span></dt>
262<dd><p>
263 the type <code class="computeroutput"><span class="identifier">forward_adapter</span><span class="special">&lt;</span><span class="identifier">F</span><span class="special">&gt;</span></code>
264 </p></dd>
265<dt><span class="term"><code class="computeroutput"><span class="identifier">fa</span></code></span></dt>
266<dd><p>
267 an instance object of <code class="computeroutput"><span class="identifier">FA</span></code>,
268 initialized with <code class="computeroutput"><span class="identifier">f</span></code>
269 </p></dd>
270<dt><span class="term"><code class="computeroutput"><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span></code></span></dt>
271<dd><p>
272 arguments to <code class="computeroutput"><span class="identifier">fa</span></code>
273 </p></dd>
274</dl>
275</div>
276<p>
277 The result type of a target function invocation must be
278 </p>
279<pre class="programlisting"><a href="http://www.boost.org/libs/utility/utility.htm#result_of" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">result_of</span></code></a><span class="special">&lt;</span><span class="identifier">F</span><span class="special">*(</span><span class="identifier">TA0</span> <span class="special">[</span><span class="keyword">const</span><span class="special">]&amp;...</span><span class="identifier">TAN</span> <span class="special">[</span><span class="keyword">const</span><span class="special">]&amp;])&gt;::</span><span class="identifier">type</span>
280</pre>
281<p>
282 where <code class="computeroutput"><span class="identifier">TA0</span></code>...<code class="computeroutput"><span class="identifier">TAN</span></code> denote the argument types of <code class="computeroutput"><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span></code>.
283 </p>
284<h5>
285<a name="boost_functional_forward.reference.forward_adapter.h3"></a>
286 <span class="phrase"><a name="boost_functional_forward.reference.forward_adapter.expression_semantics"></a></span><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter.expression_semantics">Expression
287 Semantics</a>
288 </h5>
289<div class="informaltable"><table class="table">
290<colgroup>
291<col>
292<col>
293</colgroup>
294<thead><tr>
295<th>
296 <p>
297 Expression
298 </p>
299 </th>
300<th>
301 <p>
302 Semantics
303 </p>
304 </th>
305</tr></thead>
306<tbody>
307<tr>
308<td>
309 <p>
310 <code class="computeroutput"><span class="identifier">FA</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></code>
311 </p>
312 </td>
313<td>
314 <p>
315 creates an adapter, initializes the target function with <code class="computeroutput"><span class="identifier">f</span></code>.
316 </p>
317 </td>
318</tr>
319<tr>
320<td>
321 <p>
322 <code class="computeroutput"><span class="identifier">FA</span><span class="special">()</span></code>
323 </p>
324 </td>
325<td>
326 <p>
327 creates an adapter, attempts to use <code class="computeroutput"><span class="identifier">F</span></code>'s
328 default constructor.
329 </p>
330 </td>
331</tr>
332<tr>
333<td>
334 <p>
335 <code class="computeroutput"><span class="identifier">fa</span><span class="special">(</span><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span><span class="special">)</span></code>
336 </p>
337 </td>
338<td>
339 <p>
340 calls <code class="computeroutput"><span class="identifier">f</span></code> with with
341 arguments <code class="computeroutput"><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span></code>.
342 </p>
343 </td>
344</tr>
345</tbody>
346</table></div>
347<h5>
348<a name="boost_functional_forward.reference.forward_adapter.h4"></a>
349 <span class="phrase"><a name="boost_functional_forward.reference.forward_adapter.limits"></a></span><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter.limits">Limits</a>
350 </h5>
351<p>
352 The macro BOOST_FUNCTIONAL_FORWARD_ADAPTER_MAX_ARITY can be defined to set
353 the maximum call arity. It defaults to 6.
354 </p>
355<h5>
356<a name="boost_functional_forward.reference.forward_adapter.h5"></a>
357 <span class="phrase"><a name="boost_functional_forward.reference.forward_adapter.complexity"></a></span><a class="link" href="index.html#boost_functional_forward.reference.forward_adapter.complexity">Complexity</a>
358 </h5>
359<p>
360 Preprocessing time: O(2^N), where N is the arity limit. Compile time: O(2^N),
361 where N depends on the arity range. Run time: O(0) if the compiler inlines,
362 O(1) otherwise.
363 </p>
364</div>
365<div class="section">
366<div class="titlepage"><div><div><h3 class="title">
367<a name="boost_functional_forward.reference.lightweight_forward_adapter"></a><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter" title="lightweight_forward_adapter">lightweight_forward_adapter</a>
368</h3></div></div></div>
369<h5>
370<a name="boost_functional_forward.reference.lightweight_forward_adapter.h0"></a>
371 <span class="phrase"><a name="boost_functional_forward.reference.lightweight_forward_adapter.description"></a></span><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter.description">Description</a>
372 </h5>
373<p>
374 Function object adapter template whose instances are callable with LValue
375 and RValue arguments. All arguments are forwarded as reference-to-const typed
376 LValues, except for reference wrappers which are unwrapped and may yield
377 non-const LValues.
378 </p>
379<p>
380 An arity can be given as second, numeric non-type template argument to restrict
381 forwarding to a specific arity. If a third, numeric non-type template argument
382 is present, the second and third template argument are treated as minimum
383 and maximum arity, respectively. Specifying an arity can be helpful to improve
384 the readability of diagnostic messages and compile time performance.
385 </p>
386<p>
387 <a href="http://www.boost.org/libs/utility/utility.htm#result_of" target="_top">Boost.ResultOf</a>
388 can be used to determine the result types of specific call expressions.
389 </p>
390<h5>
391<a name="boost_functional_forward.reference.lightweight_forward_adapter.h1"></a>
392 <span class="phrase"><a name="boost_functional_forward.reference.lightweight_forward_adapter.header"></a></span><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter.header">Header</a>
393 </h5>
394<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">functional</span><span class="special">/</span><span class="identifier">lightweight_forward_adapter</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
395</pre>
396<h5>
397<a name="boost_functional_forward.reference.lightweight_forward_adapter.h2"></a>
398 <span class="phrase"><a name="boost_functional_forward.reference.lightweight_forward_adapter.synopsis"></a></span><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter.synopsis">Synopsis</a>
399 </h5>
400<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span>
401<span class="special">{</span>
402 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">Function</span><span class="special">,</span>
403 <span class="keyword">int</span> <span class="identifier">Arity_Or_MinArity</span> <span class="special">=</span> <span class="emphasis"><em>unspecified</em></span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">MaxArity</span> <span class="special">=</span> <span class="emphasis"><em>unspecified</em></span> <span class="special">&gt;</span>
404 <span class="keyword">struct</span> <span class="identifier">lightweight_forward_adapter</span><span class="special">;</span>
405<span class="special">}</span>
406</pre>
407<div class="variablelist">
408<p class="title"><b>Notation</b></p>
409<dl class="variablelist">
410<dt><span class="term"><code class="computeroutput"><span class="identifier">F</span></code></span></dt>
411<dd><p>
412 a possibly const qualified function object type or reference type thereof
413 </p></dd>
414<dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code></span></dt>
415<dd><p>
416 an object convertible to <code class="computeroutput"><span class="identifier">F</span></code>
417 </p></dd>
418<dt><span class="term"><code class="computeroutput"><span class="identifier">FA</span></code></span></dt>
419<dd><p>
420 the type <code class="computeroutput"><span class="identifier">lightweight_forward_adapter</span><span class="special">&lt;</span><span class="identifier">F</span><span class="special">&gt;</span></code>
421 </p></dd>
422<dt><span class="term"><code class="computeroutput"><span class="identifier">fa</span></code></span></dt>
423<dd><p>
424 an instance of <code class="computeroutput"><span class="identifier">FA</span></code>,
425 initialized with <code class="computeroutput"><span class="identifier">f</span></code>
426 </p></dd>
427<dt><span class="term"><code class="computeroutput"><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span></code></span></dt>
428<dd><p>
429 arguments to <code class="computeroutput"><span class="identifier">fa</span></code>
430 </p></dd>
431</dl>
432</div>
433<p>
434 The result type of a target function invocation must be
435 </p>
436<pre class="programlisting"><a href="http://www.boost.org/libs/utility/utility.htm#result_of" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">result_of</span></code></a><span class="special">&lt;</span><span class="identifier">F</span><span class="special">*(</span><span class="identifier">TA0</span> <span class="special">[</span><span class="keyword">const</span><span class="special">]&amp;...</span><span class="identifier">TAN</span> <span class="special">[</span><span class="keyword">const</span><span class="special">]&amp;])&gt;::</span><span class="identifier">type</span>
437</pre>
438<p>
439 where <code class="computeroutput"><span class="identifier">TA0</span></code>...<code class="computeroutput"><span class="identifier">TAN</span></code> denote the argument types of <code class="computeroutput"><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span></code>.
440 </p>
441<h5>
442<a name="boost_functional_forward.reference.lightweight_forward_adapter.h3"></a>
443 <span class="phrase"><a name="boost_functional_forward.reference.lightweight_forward_adapter.expression_semantics"></a></span><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter.expression_semantics">Expression
444 Semantics</a>
445 </h5>
446<div class="informaltable"><table class="table">
447<colgroup>
448<col>
449<col>
450</colgroup>
451<thead><tr>
452<th>
453 <p>
454 Expression
455 </p>
456 </th>
457<th>
458 <p>
459 Semantics
460 </p>
461 </th>
462</tr></thead>
463<tbody>
464<tr>
465<td>
466 <p>
467 <code class="computeroutput"><span class="identifier">FA</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></code>
468 </p>
469 </td>
470<td>
471 <p>
472 creates an adapter, initializes the target function with <code class="computeroutput"><span class="identifier">f</span></code>.
473 </p>
474 </td>
475</tr>
476<tr>
477<td>
478 <p>
479 <code class="computeroutput"><span class="identifier">FA</span><span class="special">()</span></code>
480 </p>
481 </td>
482<td>
483 <p>
484 creates an adapter, attempts to use <code class="computeroutput"><span class="identifier">F</span></code>'s
485 default constructor.
486 </p>
487 </td>
488</tr>
489<tr>
490<td>
491 <p>
492 <code class="computeroutput"><span class="identifier">fa</span><span class="special">(</span><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span><span class="special">)</span></code>
493 </p>
494 </td>
495<td>
496 <p>
497 calls <code class="computeroutput"><span class="identifier">f</span></code> with with
498 const arguments <code class="computeroutput"><span class="identifier">a0</span></code>...<code class="computeroutput"><span class="identifier">aN</span></code>. If <code class="computeroutput"><span class="identifier">aI</span></code>
499 is a reference wrapper it is unwrapped.
500 </p>
501 </td>
502</tr>
503</tbody>
504</table></div>
505<h5>
506<a name="boost_functional_forward.reference.lightweight_forward_adapter.h4"></a>
507 <span class="phrase"><a name="boost_functional_forward.reference.lightweight_forward_adapter.limits"></a></span><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter.limits">Limits</a>
508 </h5>
509<p>
510 The macro BOOST_FUNCTIONAL_LIGHTWEIGHT_FORWARD_ADAPTER_MAX_ARITY can be defined
511 to set the maximum call arity. It defaults to 10.
512 </p>
513<h5>
514<a name="boost_functional_forward.reference.lightweight_forward_adapter.h5"></a>
515 <span class="phrase"><a name="boost_functional_forward.reference.lightweight_forward_adapter.complexity"></a></span><a class="link" href="index.html#boost_functional_forward.reference.lightweight_forward_adapter.complexity">Complexity</a>
516 </h5>
517<p>
518 Preprocessing time: O(N), where N is the arity limit. Compile time: O(N),
519 where N is the effective arity of a call. Run time: O(0) if the compiler
520 inlines, O(1) otherwise.
521 </p>
522</div>
523</div>
524<div class="section">
525<div class="titlepage"><div><div><h2 class="title" style="clear: both">
526<a name="boost_functional_forward.acknowledgements"></a><a class="link" href="index.html#boost_functional_forward.acknowledgements" title="Acknowledgements">Acknowledgements</a>
527</h2></div></div></div>
528<p>
529 As these utilities are factored out of the <a href="http://www.boost.org/libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
530 functional module, I want to thank Dan Marsden and Joel de Guzman for letting
531 me participate in the development of that great library in the first place.
532 </p>
533<p>
534 Further, I want to credit the authors of the references below, for their in-depth
535 investigation of the problem and the solution implemented here.
536 </p>
537<p>
538 Last but not least I want to thank Vesa Karnoven and Paul Mensonides for the
539 Boost Preprocessor library. Without it, I would have ended up with an external
540 code generator for this one.
541 </p>
542</div>
543<div class="section">
544<div class="titlepage"><div><div><h2 class="title" style="clear: both">
545<a name="boost_functional_forward.references"></a><a class="link" href="index.html#boost_functional_forward.references" title="References">References</a>
546</h2></div></div></div>
547<div class="orderedlist"><ol class="orderedlist" type="1">
548<li class="listitem">
549 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_top">The
550 Forwarding Problem</a>, Peter Dimov, Howard E. Hinnant, David Abrahams,
551 2002
552 </li>
553<li class="listitem">
554 <a href="http://www.boost.org/libs/utility/utility.htm#result_of" target="_top">Boost.ResultOf</a>,
555 Douglas Gregor, 2004
556 </li>
557<li class="listitem">
558 <a href="http://www.boost.org/doc/html/ref.html" target="_top">Boost.Ref</a>,
559 Jaakko Jarvi, Peter Dimov, Douglas Gregor, David Abrahams, 1999-2002
560 </li>
561</ol></div>
562</div>
563</div>
564<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
565<td align="left"><p><small>Last revised: November 01, 2008 at 19:58:50 GMT</small></p></td>
566<td align="right"><div class="copyright-footer"></div></td>
567</tr></table>
568<hr>
569<div class="spirit-nav"></div>
570</body>
571</html>