Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/spirit/phoenix/doc/binders.html @ 29

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

updated boost from 1_33_1 to 1_34_1
File size: 16.9 KB
Line 
1<html>
2<head>
3<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
4<title>Binders</title>
5<link rel="stylesheet" href="theme/style.css" type="text/css">
6<link rel="prev" href="statements.html">
7<link rel="next" href="adaptable_closures.html">
8</head>
9<body>
10<table width="100%" height="48" border="0" background="theme/bkd2.gif" cellspacing="2">
11  <tr>
12    <td width="10">
13    </td>
14    <td width="85%">
15      <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Binders</b></font>
16    </td>
17    <td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" align="right" border="0"></a></td>
18  </tr>
19</table>
20<br>
21<table border="0">
22  <tr>
23    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
24    <td width="30"><a href="statements.html"><img src="theme/l_arr.gif" border="0"></a></td>
25    <td width="20"><a href="adaptable_closures.html"><img src="theme/r_arr.gif" border="0"></a></td>
26   </tr>
27</table>
28<p>
29There are times when it is desireable to bind a simple functor, function, member function or member variable for deferred evaluation. This can be done through the binding facilities provided below. There are template classes:</p>
30<ol><li>function_ptr ( function pointer binder )</li><li>functor ( functor pointer binder )</li><li>member_function_ptr ( member function pointer binder )</li><li>member_var_ptr ( member variable pointer binder )</li></ol><p>
31These template classes are specialized lazy function classes for functors, function pointers, member function pointers and member variable pointers, respectively. These are subclasses of the lazy- function class (see functions). Each of these has a corresponding overloaded bind(x) function. Each bind(x) function generates a suitable binder object.</p>
32<p>
33Example, given a function foo:</p>
34<code><pre>
35    <span class=keyword>void </span><span class=identifier>foo_</span><span class=special>(</span><span class=keyword>int </span><span class=identifier>n</span><span class=special>) { </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>cout </span><span class=special>&lt;&lt; </span><span class=identifier>n </span><span class=special>&lt;&lt; </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>endl</span><span class=special>; }
36</span></pre></code>
37<p>
38Here's how the function foo is bound:</p>
39<code><pre>
40    <span class=identifier>bind</span><span class=special>(&amp;</span><span class=identifier>foo_</span><span class=special>)
41</span></pre></code>
42<p>
43This bind expression results to a lazy-function (see functions) that is lazily evaluated. This bind expression is also equivalent to:</p>
44<code><pre>
45    <span class=identifier>function_ptr</span><span class=special>&lt;</span><span class=keyword>void</span><span class=special>, </span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>foo </span><span class=special>= &amp;</span><span class=identifier>foo_</span><span class=special>;
46</span></pre></code>
47<p>
48The template parameter of the function_ptr is the return and argument types of actual signature of the function to be bound read from left to right. Examples:</p>
49<code><pre>
50    <span class=keyword>void </span><span class=identifier>foo_</span><span class=special>(</span><span class=keyword>int</span><span class=special>);         ---&gt; </span><span class=identifier>function_ptr</span><span class=special>&lt;</span><span class=keyword>void</span><span class=special>, </span><span class=keyword>int</span><span class=special>&gt;
51    </span><span class=keyword>int </span><span class=identifier>bar_</span><span class=special>(</span><span class=keyword>double</span><span class=special>, </span><span class=keyword>int</span><span class=special>);  ---&gt; </span><span class=identifier>function_ptr</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=keyword>double</span><span class=special>, </span><span class=keyword>int</span><span class=special>&gt;
52</span></pre></code>
53<p>
54Either bind(&amp;foo_) and its equivalent foo can now be used in the same way a lazy function (see functions) is used:</p>
55<code><pre>
56    <span class=identifier>bind</span><span class=special>(&amp;</span><span class=identifier>foo_</span><span class=special>)(</span><span class=identifier>arg1</span><span class=special>)
57</span></pre></code>
58<p>
59or</p>
60<code><pre>
61    <span class=identifier>foo</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>)
62</span></pre></code>
63<p>
64The latter, of course, follows C/C++ function call syntax and is much easier to understand. This is now a full-fledged lazy function that can finally be evaluated by another function call invocation. A second function call will invoke the actual foo function:</p>
65<code><pre>
66    <span class=keyword>int </span><span class=identifier>i </span><span class=special>= </span><span class=number>4</span><span class=special>;
67    </span><span class=identifier>foo</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>)(</span><span class=identifier>i</span><span class=special>);
68</span></pre></code>
69<p>
70will print out &quot;4&quot;.</p>
71<p>
72Binding functors and member functions can be done similarly. Here's how to bind a functor (e.g. std::plus&lt;int&gt;):</p>
73<code><pre>
74    <span class=identifier>bind</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>plus</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;())
75</span></pre></code>
76<p>
77or</p>
78<code><pre>
79    <span class=identifier>functor</span><span class=special>&lt;</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>plus</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt; &gt; </span><span class=identifier>plus</span><span class=special>;
80</span></pre></code>
81<p>
82Again, these are full-fledged lazy functions. In this case, unlike the first example, expect 2 arguments (std::plus&lt;int&gt; needs two arguments lhs and rhs). Either or both of which can be lazily bound:</p>
83<code><pre>
84    <span class=identifier>plus</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>, </span><span class=identifier>arg2</span><span class=special>)        // </span><span class=identifier>arg1 </span><span class=special>+ </span><span class=identifier>arg2
85    </span><span class=identifier>plus</span><span class=special>(</span><span class=number>100</span><span class=special>, </span><span class=identifier>arg1</span><span class=special>)         // </span><span class=number>100 </span><span class=special>+ </span><span class=identifier>arg1
86    </span><span class=identifier>plus</span><span class=special>(</span><span class=number>100</span><span class=special>, </span><span class=number>200</span><span class=special>)          // </span><span class=number>300
87</span></pre></code>
88<p>
89A bound member function takes in a pointer or reference to an object as the first argument. For instance, given:</p>
90<code><pre>
91    <span class=keyword>struct </span><span class=identifier>xyz </span><span class=special>{ </span><span class=keyword>void </span><span class=identifier>foo</span><span class=special>(</span><span class=keyword>int</span><span class=special>) </span><span class=keyword>const</span><span class=special>; };
92</span></pre></code>
93<p>
94xyz's foo member function can be bound as:</p>
95<code><pre>
96    <span class=identifier>bind</span><span class=special>(&amp;</span><span class=identifier>xyz</span><span class=special>::</span><span class=identifier>foo</span><span class=special>)
97</span></pre></code>
98<p>
99or</p>
100<p>
101member_function_ptr&lt;void, xyz, int&gt; xyz_foo = &amp;xyz::foo;</p>
102<p>
103The template parameter of the member_function_ptr is the return, class and argument types of actual signature of the function to be bound, read from left to right:</p>
104<code>
105<pre>
106    <span class=keyword>void </span><span class=identifier>xyz</span><span class=special>::</span><span class=identifier>foo_</span><span class=special>(</span><span class=keyword>int</span><span class=special>);            ---&gt; </span><span class=identifier>member_function_ptr</span><span class=special>&lt;</span><span class=keyword>void</span><span class=special>, </span><span class=identifier>xyz</span><span class=special>, </span><span class=keyword>int</span><span class=special>&gt;
107    </span><span class=keyword>int </span><span class=identifier>abc</span><span class=special>::</span><span class=identifier>bar_</span><span class=special>(</span><span class=keyword>double</span><span class=special>, </span><span class=keyword>char</span><span class=special>);    ---&gt; </span><span class=identifier>member_function_ptr</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=identifier>abc</span><span class=special>, </span><span class=keyword>double</span><span class=special>, </span><span class=keyword>char</span><span class=special>&gt;
108</span></pre>
109</code>
110<p>
111Take note that a member_function_ptr lazy-function expects the first argument to be a pointer or reference to an object. Both the object (reference or pointer) and the arguments can be lazily bound. Examples:</p>
112<code><pre>
113    <span class=identifier>xyz </span><span class=identifier>obj</span><span class=special>;
114    </span><span class=identifier>xyz_foo</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>, </span><span class=identifier>arg2</span><span class=special>)     // </span><span class=identifier>arg1</span><span class=special>.</span><span class=identifier>foo</span><span class=special>(</span><span class=identifier>arg2</span><span class=special>)
115    </span><span class=identifier>xyz_foo</span><span class=special>(</span><span class=identifier>obj</span><span class=special>, </span><span class=identifier>arg1</span><span class=special>)      // </span><span class=identifier>obj</span><span class=special>.</span><span class=identifier>foo</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>)
116    </span><span class=identifier>xyz_foo</span><span class=special>(</span><span class=identifier>obj</span><span class=special>, </span><span class=number>100</span><span class=special>)       // </span><span class=identifier>obj</span><span class=special>.</span><span class=identifier>foo</span><span class=special>(</span><span class=number>100</span><span class=special>)
117</span></pre></code>
118<p>
119Be reminded that var(obj) must be used to call non-const member functions. For example, if xyz was declared as:</p>
120<code><pre>
121    <span class=keyword>struct </span><span class=identifier>xyz </span><span class=special>{ </span><span class=keyword>void </span><span class=identifier>foo</span><span class=special>(</span><span class=keyword>int</span><span class=special>); };  //  </span><span class=identifier>note </span><span class=identifier>non</span><span class=special>-</span><span class=keyword>const </span><span class=identifier>member </span><span class=identifier>function
122</span></pre></code>
123<p>
124the pointer or reference to the object must also be non-const since lazily bound arguments are stored as const value by default (see variable class in primitives).</p>
125<code><pre>
126    <span class=identifier>xyz_foo</span><span class=special>(</span><span class=identifier>var</span><span class=special>(</span><span class=identifier>obj</span><span class=special>), </span><span class=number>100</span><span class=special>)      // </span><span class=identifier>obj</span><span class=special>.</span><span class=identifier>foo</span><span class=special>(</span><span class=number>100</span><span class=special>)
127</span></pre></code>
128<p>
129arg1..argN are already implicitly mutable. There is no need to wrap arg1..argN in a var. It is an error to do so:</p>
130<code><pre>
131    <span class=identifier>var</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>)   //  </span><span class=identifier>ERROR</span><span class=special>! </span><span class=identifier>arg1 </span><span class=identifier>is </span><span class=identifier>already </span><span class=keyword>mutable
132    </span><span class=identifier>var</span><span class=special>(</span><span class=identifier>arg2</span><span class=special>)   //  </span><span class=identifier>ERROR</span><span class=special>! </span><span class=identifier>arg2 </span><span class=identifier>is </span><span class=identifier>already </span><span class=keyword>mutable
133</span></pre></code>
134<p>
135Finally, member variables can be bound much like member functions. For instance, given:</p>
136<code><pre>
137    <span class=keyword>struct </span><span class=identifier>xyz </span><span class=special>{ </span><span class=keyword>int </span><span class=identifier>v</span><span class=special>; };
138</span></pre></code>
139<p>
140xyz::v can be bound as:</p>
141<code><pre>
142    <span class=identifier>bind</span><span class=special>(&amp;</span><span class=identifier>xyz</span><span class=special>::</span><span class=identifier>v</span><span class=special>)
143</span></pre></code>
144<p>
145or</p>
146<code><pre>
147    <span class=identifier>member_var_ptr</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=identifier>xyz</span><span class=special>&gt; </span><span class=identifier>xyz_v </span><span class=special>= &amp;</span><span class=identifier>xyz</span><span class=special>::</span><span class=identifier>v</span><span class=special>;
148</span></pre></code>
149<p>
150The template parameter of the member_var_ptr is the type of the variable followed by the class:</p>
151<code><pre>
152    <span class=keyword>int </span><span class=identifier>xyz</span><span class=special>::</span><span class=identifier>v</span><span class=special>; ---&gt; </span><span class=identifier>member_var_ptr</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=identifier>xyz</span><span class=special>&gt;
153</span></pre></code>
154<p>
155Just like the member_function_ptr, member_var_ptr also expects the first argument to be a pointer or reference to an object. Both the object (reference or pointer) and the arguments can be lazily bound. Like member function binders, var(obj) must be used to access non-const member variables. Examples:</p>
156<code><pre>
157    <span class=identifier>xyz </span><span class=identifier>obj</span><span class=special>;
158    </span><span class=identifier>xyz_v</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>)             // </span><span class=identifier>arg1</span><span class=special>.</span><span class=identifier>v </span><span class=special>(</span><span class=keyword>const</span><span class=special>&amp; </span><span class=identifier>access</span><span class=special>)
159    </span><span class=identifier>xyz_v</span><span class=special>(</span><span class=identifier>obj</span><span class=special>)              // </span><span class=identifier>obj</span><span class=special>.</span><span class=identifier>v  </span><span class=special>(</span><span class=keyword>const</span><span class=special>&amp; </span><span class=identifier>access</span><span class=special>)
160
161    </span><span class=identifier>xyz_v</span><span class=special>(</span><span class=identifier>var</span><span class=special>(</span><span class=identifier>obj</span><span class=special>))() = </span><span class=number>3   </span><span class=comment>// obj.v = 3 (non-const&amp; access)
162    </span><span class=identifier>xyz_v</span><span class=special>(</span><span class=identifier>arg1</span><span class=special>)(</span><span class=identifier>obj</span><span class=special>) = </span><span class=number>4    </span><span class=comment>// obj.v = 4 (non-const&amp; access)
163</span></pre></code>
164<p>
165Be reminded once more that binders are monomorphic. This layer is provided only for compatibility with existing code such as prewritten STL functors and legacy APIs. Rather than binding functions or functors, the preferred method is to write true generic and polymorphic lazy-functions (see functions). However, since most of the time we are dealing with adaptation of exisiting code, binders are indeed indespensible.</p>
166<table border="0">
167  <tr>
168    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
169    <td width="30"><a href="statements.html"><img src="theme/l_arr.gif" border="0"></a></td>
170    <td width="20"><a href="adaptable_closures.html"><img src="theme/r_arr.gif" border="0"></a></td>
171   </tr>
172</table>
173<br>
174<hr size="1">
175<p class="copyright">Copyright &copy; 2001-2002 Joel de Guzman<font size="2"><br>
176  <br>
177<font size="2">Use, modification and distribution is subject to the Boost Software
178    License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
179    http://www.boost.org/LICENSE_1_0.txt) </font> </font></p>
180</body>
181</html>
Note: See TracBrowser for help on using the repository browser.