1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Functions</title> 5<link rel="stylesheet" href="../../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Python Tutorial"> 8<link rel="up" href="../index.html" title="Boost.Python Tutorial"> 9<link rel="prev" href="exposing.html" title="Exposing Classes"> 10<link rel="next" href="object.html" title="Object Interface"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> 14<hr> 15<div class="spirit-nav"> 16<a accesskey="p" href="exposing.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="object.html"><img src="../../images/next.png" alt="Next"></a> 17</div> 18<div class="section"> 19<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 20<a name="tutorial.functions"></a><a class="link" href="functions.html" title="Functions">Functions</a> 21</h2></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="functions.html#tutorial.functions.call_policies">Call Policies</a></span></dt> 24<dt><span class="section"><a href="functions.html#tutorial.functions.overloading">Overloading</a></span></dt> 25<dt><span class="section"><a href="functions.html#tutorial.functions.default_arguments">Default Arguments</a></span></dt> 26<dt><span class="section"><a href="functions.html#tutorial.functions.auto_overloading">Auto-Overloading</a></span></dt> 27</dl></div> 28<p> 29 In this chapter, we'll look at Boost.Python powered functions in closer detail. 30 We will see some facilities to make exposing C++ functions to Python safe from 31 potential pifalls such as dangling pointers and references. We will also see 32 facilities that will make it even easier for us to expose C++ functions that 33 take advantage of C++ features such as overloading and default arguments. 34 </p> 35<div class="blockquote"><blockquote class="blockquote"><p> 36 <span class="emphasis"><em>Read on...</em></span> 37 </p></blockquote></div> 38<p> 39 But before you do, you might want to fire up Python 2.2 or later and type 40 <code class="literal">>>> import this</code>. 41 </p> 42<pre class="programlisting">>>> import this 43The Zen of Python, by Tim Peters 44Beautiful is better than ugly. 45Explicit is better than implicit. 46Simple is better than complex. 47Complex is better than complicated. 48Flat is better than nested. 49Sparse is better than dense. 50Readability counts. 51Special cases aren't special enough to break the rules. 52Although practicality beats purity. 53Errors should never pass silently. 54Unless explicitly silenced. 55In the face of ambiguity, refuse the temptation to guess. 56There should be one-- and preferably only one --obvious way to do it 57Although that way may not be obvious at first unless you're Dutch. 58Now is better than never. 59Although never is often better than <span class="bold"><strong>right</strong></span> now. 60If the implementation is hard to explain, it's a bad idea. 61If the implementation is easy to explain, it may be a good idea. 62Namespaces are one honking great idea -- let's do more of those! 63</pre> 64<div class="section"> 65<div class="titlepage"><div><div><h3 class="title"> 66<a name="tutorial.functions.call_policies"></a><a class="link" href="functions.html#tutorial.functions.call_policies" title="Call Policies">Call Policies</a> 67</h3></div></div></div> 68<p> 69 In C++, we often deal with arguments and return types such as pointers and 70 references. Such primitive types are rather, ummmm, low level and they really 71 don't tell us much. At the very least, we don't know the owner of the pointer 72 or the referenced object. No wonder languages such as Java and Python never 73 deal with such low level entities. In C++, it's usually considered a good 74 practice to use smart pointers which exactly describe ownership semantics. 75 Still, even good C++ interfaces use raw references and pointers sometimes, 76 so Boost.Python must deal with them. To do this, it may need your help. Consider 77 the following C++ function: 78 </p> 79<pre class="programlisting"><span class="identifier">X</span><span class="special">&</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Y</span><span class="special">&</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">Z</span><span class="special">*</span> <span class="identifier">z</span><span class="special">);</span> 80</pre> 81<p> 82 How should the library wrap this function? A naive approach builds a Python 83 X object around result reference. This strategy might or might not work out. 84 Here's an example where it didn't 85 </p> 86<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">x</span> <span class="identifier">refers</span> <span class="identifier">to</span> <span class="identifier">some</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">X</span> 87<span class="special">>>></span> <span class="identifier">del</span> <span class="identifier">y</span> 88<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">some_method</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">CRASH</span><span class="special">!</span> 89</pre> 90<p> 91 What's the problem? 92 </p> 93<p> 94 Well, what if f() was implemented as shown below: 95 </p> 96<pre class="programlisting"><span class="identifier">X</span><span class="special">&</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Y</span><span class="special">&</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">Z</span><span class="special">*</span> <span class="identifier">z</span><span class="special">)</span> 97<span class="special">{</span> 98 <span class="identifier">y</span><span class="special">.</span><span class="identifier">z</span> <span class="special">=</span> <span class="identifier">z</span><span class="special">;</span> 99 <span class="keyword">return</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">x</span><span class="special">;</span> 100<span class="special">}</span> 101</pre> 102<p> 103 The problem is that the lifetime of result X& is tied to the lifetime 104 of y, because the f() returns a reference to a member of the y object. This 105 idiom is is not uncommon and perfectly acceptable in the context of C++. 106 However, Python users should not be able to crash the system just by using 107 our C++ interface. In this case deleting y will invalidate the reference 108 to X. We have a dangling reference. 109 </p> 110<p> 111 Here's what's happening: 112 </p> 113<div class="orderedlist"><ol class="orderedlist" type="1"> 114<li class="listitem"> 115 <code class="literal">f</code> is called passing in a reference to <code class="literal">y</code> 116 and a pointer to <code class="literal">z</code> 117 </li> 118<li class="listitem"> 119 A reference to <code class="literal">y.x</code> is returned 120 </li> 121<li class="listitem"> 122 <code class="literal">y</code> is deleted. <code class="literal">x</code> is a dangling reference 123 </li> 124<li class="listitem"> 125 <code class="literal">x.some_method()</code> is called 126 </li> 127<li class="listitem"> 128 <span class="bold"><strong>BOOM!</strong></span> 129 </li> 130</ol></div> 131<p> 132 We could copy result into a new object: 133 </p> 134<pre class="programlisting"><span class="special">>>></span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">).</span><span class="identifier">set</span><span class="special">(</span><span class="number">42</span><span class="special">)</span> <span class="comment"># Result disappears</span> 135<span class="special">>>></span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> <span class="comment"># No crash, but still bad</span> 136<span class="number">3.14</span> 137</pre> 138<p> 139 This is not really our intent of our C++ interface. We've broken our promise 140 that the Python interface should reflect the C++ interface as closely as 141 possible. 142 </p> 143<p> 144 Our problems do not end there. Suppose Y is implemented as follows: 145 </p> 146<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Y</span> 147<span class="special">{</span> 148 <span class="identifier">X</span> <span class="identifier">x</span><span class="special">;</span> <span class="identifier">Z</span><span class="special">*</span> <span class="identifier">z</span><span class="special">;</span> 149 <span class="keyword">int</span> <span class="identifier">z_value</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">z</span><span class="special">-></span><span class="identifier">value</span><span class="special">();</span> <span class="special">}</span> 150<span class="special">};</span> 151</pre> 152<p> 153 Notice that the data member <code class="literal">z</code> is held by class Y using 154 a raw pointer. Now we have a potential dangling pointer problem inside Y: 155 </p> 156<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">y</span> <span class="identifier">refers</span> <span class="identifier">to</span> <span class="identifier">z</span> 157<span class="special">>>></span> <span class="identifier">del</span> <span class="identifier">z</span> <span class="special">#</span> <span class="identifier">Kill</span> <span class="identifier">the</span> <span class="identifier">z</span> <span class="identifier">object</span> 158<span class="special">>>></span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">z_value</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">CRASH</span><span class="special">!</span> 159</pre> 160<p> 161 For reference, here's the implementation of <code class="literal">f</code> again: 162 </p> 163<pre class="programlisting"><span class="identifier">X</span><span class="special">&</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Y</span><span class="special">&</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">Z</span><span class="special">*</span> <span class="identifier">z</span><span class="special">)</span> 164<span class="special">{</span> 165 <span class="identifier">y</span><span class="special">.</span><span class="identifier">z</span> <span class="special">=</span> <span class="identifier">z</span><span class="special">;</span> 166 <span class="keyword">return</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">x</span><span class="special">;</span> 167<span class="special">}</span> 168</pre> 169<p> 170 Here's what's happening: 171 </p> 172<div class="orderedlist"><ol class="orderedlist" type="1"> 173<li class="listitem"> 174 <code class="literal">f</code> is called passing in a reference to <code class="literal">y</code> 175 and a pointer to <code class="literal">z</code> 176 </li> 177<li class="listitem"> 178 A pointer to <code class="literal">z</code> is held by <code class="literal">y</code> 179 </li> 180<li class="listitem"> 181 A reference to <code class="literal">y.x</code> is returned 182 </li> 183<li class="listitem"> 184 <code class="literal">z</code> is deleted. <code class="literal">y.z</code> is a dangling 185 pointer 186 </li> 187<li class="listitem"> 188 <code class="literal">y.z_value()</code> is called 189 </li> 190<li class="listitem"> 191 <code class="literal">z->value()</code> is called 192 </li> 193<li class="listitem"> 194 <span class="bold"><strong>BOOM!</strong></span> 195 </li> 196</ol></div> 197<h3> 198<a name="tutorial.functions.call_policies.h0"></a> 199 <span class="phrase"><a name="tutorial.functions.call_policies.call_policies"></a></span><a class="link" href="functions.html#tutorial.functions.call_policies.call_policies">Call 200 Policies</a> 201 </h3> 202<p> 203 Call Policies may be used in situations such as the example detailed above. 204 In our example, <code class="literal">return_internal_reference</code> and <code class="literal">with_custodian_and_ward</code> 205 are our friends: 206 </p> 207<pre class="programlisting"><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> 208 <span class="identifier">return_internal_reference</span><span class="special"><</span><span class="number">1</span><span class="special">,</span> 209 <span class="identifier">with_custodian_and_ward</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="special">>());</span> 210</pre> 211<p> 212 What are the <code class="literal">1</code> and <code class="literal">2</code> parameters, you 213 ask? 214 </p> 215<pre class="programlisting"><span class="identifier">return_internal_reference</span><span class="special"><</span><span class="number">1</span> 216</pre> 217<p> 218 Informs Boost.Python that the first argument, in our case <code class="literal">Y& 219 y</code>, is the owner of the returned reference: <code class="literal">X&</code>. 220 The "<code class="literal">1</code>" simply specifies the first argument. 221 In short: "return an internal reference <code class="literal">X&</code> owned 222 by the 1st argument <code class="literal">Y& y</code>". 223 </p> 224<pre class="programlisting"><span class="identifier">with_custodian_and_ward</span><span class="special"><</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">></span> 225</pre> 226<p> 227 Informs Boost.Python that the lifetime of the argument indicated by ward 228 (i.e. the 2nd argument: <code class="literal">Z* z</code>) is dependent on the lifetime 229 of the argument indicated by custodian (i.e. the 1st argument: <code class="literal">Y& 230 y</code>). 231 </p> 232<p> 233 It is also important to note that we have defined two policies above. Two 234 or more policies can be composed by chaining. Here's the general syntax: 235 </p> 236<pre class="programlisting"><span class="identifier">policy1</span><span class="special"><</span><span class="identifier">args</span><span class="special">...,</span> 237 <span class="identifier">policy2</span><span class="special"><</span><span class="identifier">args</span><span class="special">...,</span> 238 <span class="identifier">policy3</span><span class="special"><</span><span class="identifier">args</span><span class="special">...></span> <span class="special">></span> <span class="special">></span> 239</pre> 240<p> 241 Here is the list of predefined call policies. A complete reference detailing 242 these can be found <a href="../../reference/function_invocation_and_creation/models_of_callpolicies.html" target="_top">here</a>. 243 </p> 244<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 245<li class="listitem"> 246 <span class="bold"><strong>with_custodian_and_ward</strong></span>: Ties lifetimes 247 of the arguments 248 </li> 249<li class="listitem"> 250 <span class="bold"><strong>with_custodian_and_ward_postcall</strong></span>: Ties 251 lifetimes of the arguments and results 252 </li> 253<li class="listitem"> 254 <span class="bold"><strong>return_internal_reference</strong></span>: Ties lifetime 255 of one argument to that of result 256 </li> 257<li class="listitem"> 258 <span class="bold"><strong>return_value_policy<T> with T one of:</strong></span> 259 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 260<li class="listitem"> 261 <span class="bold"><strong>reference_existing_object</strong></span>: naive 262 (dangerous) approach 263 </li> 264<li class="listitem"> 265 <span class="bold"><strong>copy_const_reference</strong></span>: Boost.Python 266 v1 approach 267 </li> 268<li class="listitem"> 269 <span class="bold"><strong>copy_non_const_reference</strong></span>: 270 </li> 271<li class="listitem"> 272 <span class="bold"><strong>manage_new_object</strong></span>: Adopt a pointer 273 and hold the instance 274 </li> 275</ul></div> 276 </li> 277</ul></div> 278<div class="blurb"> 279<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 280<p> 281 <span class="inlinemediaobject"><img src="../../images/smiley.png"></span> 282 <span class="bold"><strong>Remember the Zen, Luke:</strong></span> 283 </p> 284<p> 285 "Explicit is better than implicit" 286 </p> 287<p> 288 "In the face of ambiguity, refuse the temptation to guess" 289 </p> 290</div> 291</div> 292<div class="section"> 293<div class="titlepage"><div><div><h3 class="title"> 294<a name="tutorial.functions.overloading"></a><a class="link" href="functions.html#tutorial.functions.overloading" title="Overloading">Overloading</a> 295</h3></div></div></div> 296<p> 297 The following illustrates a scheme for manually wrapping an overloaded member 298 functions. Of course, the same technique can be applied to wrapping overloaded 299 non-member functions. 300 </p> 301<p> 302 We have here our C++ class: 303 </p> 304<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> 305<span class="special">{</span> 306 <span class="keyword">bool</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">)</span> 307 <span class="special">{</span> 308 <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> 309 <span class="special">}</span> 310 311 <span class="keyword">bool</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">b</span><span class="special">)</span> 312 <span class="special">{</span> 313 <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> 314 <span class="special">}</span> 315 316 <span class="keyword">bool</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">char</span> <span class="identifier">c</span><span class="special">)</span> 317 <span class="special">{</span> 318 <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> 319 <span class="special">}</span> 320 321 <span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">c</span><span class="special">)</span> 322 <span class="special">{</span> 323 <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span> <span class="special">+</span> <span class="identifier">c</span><span class="special">;</span> 324 <span class="special">};</span> 325<span class="special">};</span> 326</pre> 327<p> 328 Class X has 4 overloaded functions. We will start by introducing some member 329 function pointer variables: 330 </p> 331<pre class="programlisting"><span class="keyword">bool</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">fx1</span><span class="special">)(</span><span class="keyword">int</span><span class="special">)</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">;</span> 332<span class="keyword">bool</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">fx2</span><span class="special">)(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">)</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">;</span> 333<span class="keyword">bool</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">fx3</span><span class="special">)(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">,</span> <span class="keyword">char</span><span class="special">)=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">;</span> 334<span class="keyword">int</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">fx4</span><span class="special">)(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">)</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">;</span> 335</pre> 336<p> 337 With these in hand, we can proceed to define and wrap this for Python: 338 </p> 339<pre class="programlisting"><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">fx1</span><span class="special">)</span> 340<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">fx2</span><span class="special">)</span> 341<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">fx3</span><span class="special">)</span> 342<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">fx4</span><span class="special">)</span> 343</pre> 344</div> 345<div class="section"> 346<div class="titlepage"><div><div><h3 class="title"> 347<a name="tutorial.functions.default_arguments"></a><a class="link" href="functions.html#tutorial.functions.default_arguments" title="Default Arguments">Default Arguments</a> 348</h3></div></div></div> 349<p> 350 Boost.Python wraps (member) function pointers. Unfortunately, C++ function 351 pointers carry no default argument info. Take a function <code class="literal">f</code> 352 with default arguments: 353 </p> 354<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span> <span class="special">=</span> <span class="number">3.14</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="special">=</span> <span class="string">"hello"</span><span class="special">);</span> 355</pre> 356<p> 357 But the type of a pointer to the function <code class="literal">f</code> has no information 358 about its default arguments: 359 </p> 360<pre class="programlisting"><span class="keyword">int</span><span class="special">(*</span><span class="identifier">g</span><span class="special">)(</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">double</span><span class="special">,</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*)</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">;</span> <span class="comment">// defaults lost!</span> 361</pre> 362<p> 363 When we pass this function pointer to the <code class="literal">def</code> function, 364 there is no way to retrieve the default arguments: 365 </p> 366<pre class="programlisting"><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">);</span> <span class="comment">// defaults lost!</span> 367</pre> 368<p> 369 Because of this, when wrapping C++ code, we had to resort to manual wrapping 370 as outlined in the <a class="link" href="functions.html#tutorial.functions.overloading" title="Overloading">previous 371 section</a>, or writing thin wrappers: 372 </p> 373<pre class="programlisting"><span class="comment">// write "thin wrappers"</span> 374<span class="keyword">int</span> <span class="identifier">f1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="special">}</span> 375<span class="keyword">int</span> <span class="identifier">f2</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span><span class="identifier">y</span><span class="special">);</span> <span class="special">}</span> 376 377<span class="comment">/*...*/</span> 378 379 <span class="comment">// in module init</span> 380 <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">);</span> <span class="comment">// all arguments</span> 381 <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f2</span><span class="special">);</span> <span class="comment">// two arguments</span> 382 <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f1</span><span class="special">);</span> <span class="comment">// one argument</span> 383</pre> 384<p> 385 When you want to wrap functions (or member functions) that either: 386 </p> 387<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 388<li class="listitem"> 389 have default arguments, or 390 </li> 391<li class="listitem"> 392 are overloaded with a common sequence of initial arguments 393 </li> 394</ul></div> 395<h3> 396<a name="tutorial.functions.default_arguments.h0"></a> 397 <span class="phrase"><a name="tutorial.functions.default_arguments.boost_python_function_overloads"></a></span><a class="link" href="functions.html#tutorial.functions.default_arguments.boost_python_function_overloads">BOOST_PYTHON_FUNCTION_OVERLOADS</a> 398 </h3> 399<p> 400 Boost.Python now has a way to make it easier. For instance, given a function: 401 </p> 402<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">char</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">c</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span> <span class="number">3</span><span class="special">)</span> 403<span class="special">{</span> 404 <span class="comment">/*...*/</span> 405<span class="special">}</span> 406</pre> 407<p> 408 The macro invocation: 409 </p> 410<pre class="programlisting"><span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">foo_overloads</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">4</span><span class="special">)</span> 411</pre> 412<p> 413 will automatically create the thin wrappers for us. This macro will create 414 a class <code class="literal">foo_overloads</code> that can be passed on to <code class="literal">def(...)</code>. 415 The third and fourth macro argument are the minimum arguments and maximum 416 arguments, respectively. In our <code class="literal">foo</code> function the minimum 417 number of arguments is 1 and the maximum number of arguments is 4. The <code class="literal">def(...)</code> 418 function will automatically add all the foo variants for us: 419 </p> 420<pre class="programlisting"><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="identifier">foo_overloads</span><span class="special">());</span> 421</pre> 422<h3> 423<a name="tutorial.functions.default_arguments.h1"></a> 424 <span class="phrase"><a name="tutorial.functions.default_arguments.boost_python_member_function_ove"></a></span><a class="link" href="functions.html#tutorial.functions.default_arguments.boost_python_member_function_ove">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a> 425 </h3> 426<p> 427 Objects here, objects there, objects here there everywhere. More frequently 428 than anything else, we need to expose member functions of our classes to 429 Python. Then again, we have the same inconveniences as before when default 430 arguments or overloads with a common sequence of initial arguments come into 431 play. Another macro is provided to make this a breeze. 432 </p> 433<p> 434 Like <code class="literal">BOOST_PYTHON_FUNCTION_OVERLOADS</code>, <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> 435 may be used to automatically create the thin wrappers for wrapping member 436 functions. Let's have an example: 437 </p> 438<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">george</span> 439<span class="special">{</span> 440 <span class="keyword">void</span> 441 <span class="identifier">wack_em</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">char</span> <span class="identifier">c</span> <span class="special">=</span> <span class="char">'x'</span><span class="special">)</span> 442 <span class="special">{</span> 443 <span class="comment">/*...*/</span> 444 <span class="special">}</span> 445<span class="special">};</span> 446</pre> 447<p> 448 The macro invocation: 449 </p> 450<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">george_overloads</span><span class="special">,</span> <span class="identifier">wack_em</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> 451</pre> 452<p> 453 will generate a set of thin wrappers for george's <code class="literal">wack_em</code> 454 member function accepting a minimum of 1 and a maximum of 3 arguments (i.e. 455 the third and fourth macro argument). The thin wrappers are all enclosed 456 in a class named <code class="literal">george_overloads</code> that can then be used 457 as an argument to <code class="literal">def(...)</code>: 458 </p> 459<pre class="programlisting"><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"wack_em"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">george</span><span class="special">::</span><span class="identifier">wack_em</span><span class="special">,</span> <span class="identifier">george_overloads</span><span class="special">());</span> 460</pre> 461<p> 462 See the <a href="../../reference/function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros" target="_top">overloads 463 reference</a> for details. 464 </p> 465<h3> 466<a name="tutorial.functions.default_arguments.h2"></a> 467 <span class="phrase"><a name="tutorial.functions.default_arguments.init_and_optional"></a></span><a class="link" href="functions.html#tutorial.functions.default_arguments.init_and_optional">init and 468 optional</a> 469 </h3> 470<p> 471 A similar facility is provided for class constructors, again, with default 472 arguments or a sequence of overloads. Remember <code class="literal">init<...></code>? 473 For example, given a class X with a constructor: 474 </p> 475<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> 476<span class="special">{</span> 477 <span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">char</span> <span class="identifier">b</span> <span class="special">=</span> <span class="char">'D'</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">c</span> <span class="special">=</span> <span class="string">"constructor"</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">);</span> 478 <span class="comment">/*...*/</span> 479<span class="special">}</span> 480</pre> 481<p> 482 You can easily add this constructor to Boost.Python in one shot: 483 </p> 484<pre class="programlisting"><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="keyword">char</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">double</span><span class="special">></span> <span class="special">>())</span> 485</pre> 486<p> 487 Notice the use of <code class="literal">init<...></code> and <code class="literal">optional<...></code> 488 to signify the default (optional arguments). 489 </p> 490</div> 491<div class="section"> 492<div class="titlepage"><div><div><h3 class="title"> 493<a name="tutorial.functions.auto_overloading"></a><a class="link" href="functions.html#tutorial.functions.auto_overloading" title="Auto-Overloading">Auto-Overloading</a> 494</h3></div></div></div> 495<p> 496 It was mentioned in passing in the previous section that <code class="literal">BOOST_PYTHON_FUNCTION_OVERLOADS</code> 497 and <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> can also be 498 used for overloaded functions and member functions with a common sequence 499 of initial arguments. Here is an example: 500 </p> 501<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span> 502<span class="special">{</span> 503 <span class="comment">/*...*/</span> 504<span class="special">}</span> 505 506<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">a</span><span class="special">)</span> 507<span class="special">{</span> 508 <span class="comment">/*...*/</span> 509<span class="special">}</span> 510 511<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">)</span> 512<span class="special">{</span> 513 <span class="comment">/*...*/</span> 514<span class="special">}</span> 515 516<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">char</span> <span class="identifier">c</span><span class="special">)</span> 517<span class="special">{</span> 518 <span class="comment">/*...*/</span> 519<span class="special">}</span> 520</pre> 521<p> 522 Like in the previous section, we can generate thin wrappers for these overloaded 523 functions in one-shot: 524 </p> 525<pre class="programlisting"><span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">foo_overloads</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> 526</pre> 527<p> 528 Then... 529 </p> 530<pre class="programlisting"><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="special">(</span><span class="keyword">void</span><span class="special">(*)(</span><span class="keyword">bool</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">))</span><span class="number">0</span><span class="special">,</span> <span class="identifier">foo_overloads</span><span class="special">());</span> 531</pre> 532<p> 533 Notice though that we have a situation now where we have a minimum of zero 534 (0) arguments and a maximum of 3 arguments. 535 </p> 536<h3> 537<a name="tutorial.functions.auto_overloading.h0"></a> 538 <span class="phrase"><a name="tutorial.functions.auto_overloading.manual_wrapping"></a></span><a class="link" href="functions.html#tutorial.functions.auto_overloading.manual_wrapping">Manual 539 Wrapping</a> 540 </h3> 541<p> 542 It is important to emphasize however that <span class="bold"><strong>the overloaded 543 functions must have a common sequence of initial arguments</strong></span>. Otherwise, 544 our scheme above will not work. If this is not the case, we have to wrap 545 our functions <a class="link" href="functions.html#tutorial.functions.overloading" title="Overloading">manually</a>. 546 </p> 547<p> 548 Actually, we can mix and match manual wrapping of overloaded functions and 549 automatic wrapping through <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> 550 and its sister, <code class="literal">BOOST_PYTHON_FUNCTION_OVERLOADS</code>. Following 551 up on our example presented in the section <a class="link" href="functions.html#tutorial.functions.overloading" title="Overloading">on 552 overloading</a>, since the first 4 overload functins have a common sequence 553 of initial arguments, we can use <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> 554 to automatically wrap the first three of the <code class="literal">def</code>s and 555 manually wrap just the last. Here's how we'll do this: 556 </p> 557<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">xf_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">4</span><span class="special">)</span> 558</pre> 559<p> 560 Create a member function pointers as above for both X::f overloads: 561 </p> 562<pre class="programlisting"><span class="keyword">bool</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">fx1</span><span class="special">)(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">,</span> <span class="keyword">char</span><span class="special">)</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">;</span> 563<span class="keyword">int</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">fx2</span><span class="special">)(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">)</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">;</span> 564</pre> 565<p> 566 Then... 567 </p> 568<pre class="programlisting"><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">fx1</span><span class="special">,</span> <span class="identifier">xf_overloads</span><span class="special">());</span> 569<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">fx2</span><span class="special">)</span> 570</pre> 571</div> 572</div> 573<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 574<td align="left"></td> 575<td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel 576 de Guzman, David Abrahams<p> 577 Distributed under the Boost Software License, Version 1.0. (See accompanying 578 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> 579 </p> 580</div></td> 581</tr></table> 582<hr> 583<div class="spirit-nav"> 584<a accesskey="p" href="exposing.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="object.html"><img src="../../images/next.png" alt="Next"></a> 585</div> 586</body> 587</html> 588
