boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-21 17:12:22 +00:00
Code Issues Projects Releases Wiki Activity
Files
b7ae3540e23e6c5ce8c3351eedc4c696733567d3
python/doc/tutorial/doc/default_arguments.html
Dirk Gerrits af16728db7 Initial checkin: Copied original tutorial from Boost 1.29.0 
[SVN r747]
2002-12-05 22:12:40 +00:00

119 lines
9.0 KiB
HTML
Raw Blame History

<html>
<head>
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
<title>Default Arguments</title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
<link rel="prev" href="call_policies.html">
<link rel="next" href="object_interface.html">
</head>
<body>
<table width="100%" height="48" border="0" cellspacing="2">
<tr>
<td><img src="theme/c%2B%2Bboost.gif">
</td>
<td width="85%">
<font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Default Arguments</b></font>
</td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="call_policies.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><a href="object_interface.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>
Boost.Python wraps (member) function pointers. Unfortunately, C++ function
pointers carry no default argument info. Take a function <tt>f</tt> with default
arguments:</p>
<code><pre>
<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>&quot;hello&quot;</span><span class=special>);
</span></pre></code>
<p>
But the type of a pointer to the function <tt>f</tt> has no information
about its default arguments:</p>
<code><pre>
<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></pre></code>
<p>
When we pass this function pointer to the <tt>def</tt> function, there is no way
to retrieve the default arguments:</p>
<code><pre>
<span class=identifier>def</span><span class=special>(</span><span class=string>&quot;f&quot;</span><span class=special>, </span><span class=identifier>f</span><span class=special>); </span><span class=comment>// defaults lost!
</span></pre></code>
<p>
Because of this, when wrapping C++ code in earlier versions of
Boost.Python, we had to resort to writing thin wrappers:</p>
<code><pre>
<span class=comment>// write &quot;thin wrappers&quot;
</span><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=identifier>f</span><span class=special>(</span><span class=identifier>x</span><span class=special>); </span><span class=special>}
</span><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=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><span class=comment>/*...*/
// in module init
</span><span class=identifier>def</span><span class=special>(</span><span class=string>&quot;f&quot;</span><span class=special>, </span><span class=identifier>f</span><span class=special>); </span><span class=comment>// all arguments
</span><span class=identifier>def</span><span class=special>(</span><span class=string>&quot;f&quot;</span><span class=special>, </span><span class=identifier>f2</span><span class=special>); </span><span class=comment>// two arguments
</span><span class=identifier>def</span><span class=special>(</span><span class=string>&quot;f&quot;</span><span class=special>, </span><span class=identifier>f1</span><span class=special>); </span><span class=comment>// one argument
</span></pre></code>
<p>
When you want to wrap functions (or member functions) that either:</p>
<ul><li>have default arguments, or</li><li>are overloaded with a common sequence of initial arguments</li></ul><p>
Boost.Python now has a way to make it easier.</p>
<p>
For instance, given a function:</p>
<code><pre>
<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></pre></code>
<p>
The macro invocation:</p>
<code><pre>
<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></pre></code>
<p>
Will automatically create the thin wrappers for us. This macro will create
a class <tt>foo_overloads</tt> that can be passed on to <tt>def(...)</tt>. The third
and fourth macro argument are the minimum arguments and maximum arguments,
respectively. In our <tt>foo</tt> function the minimum number of arguments is 1
and the maximum number of arguments is 4. The <tt>def(...)</tt> function will
automatically add all the foo variants for us:</p>
<code><pre>
<span class=special>.</span><span class=identifier>def</span><span class=special>(</span><span class=string>&quot;foo&quot;</span><span class=special>, </span><span class=identifier>foo</span><span class=special>, </span><span class=identifier>foo_overloads</span><span class=special>());
</span></pre></code>
<p>
A similar facility is provided for class constructors, again, with
default arguments or a sequence of overloads. Remember init&lt;...&gt;? For example,
given a class X with a constructor:</p>
<code><pre>
<span class=keyword>struct </span><span class=identifier>X
</span><span class=special>{
</span><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=literal>'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>&quot;constructor&quot;</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><span class=comment>/*...*/
</span><span class=special>}
</span></pre></code>
<p>
You can easily add this constructor to Boost.Python in one shot:</p>
<code><pre>
<span class=special>.</span><span class=identifier>def</span><span class=special>(</span><span class=identifier>init</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=identifier>optional</span><span class=special>&lt;</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>&gt; </span><span class=special>&gt;())
</span></pre></code>
<p>
Notice the use of <tt>init&lt;...&gt;</tt> and <tt>optional&lt;...&gt;</tt> to signify the default
(optional arguments).</p>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="call_policies.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><a href="object_interface.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright &copy; 2002 David Abrahams<br>Copyright &copy; 2002 Joel de Guzman<br><br>
<font size="2">Permission to copy, use, modify, sell and distribute this document
is granted provided this copyright notice appears in all copies. This document
is provided &quot;as is&quot; without express or implied warranty, and with
no claim as to its suitability for any purpose. </font> </p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink