boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-22 05:22:45 +00:00
Code Issues Projects Releases Wiki Activity
Files
19eff7791d88254f09b749fc06dc4187751bc77c
python/doc/tutorial/doc/default_arguments.html
Joel de Guzman 42fc57d761 tweaks 
[SVN r18255]
2003-04-15 12:48:27 +00:00

159 lines
12 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="overloading.html">
<link rel="next" href="auto_overloading.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="overloading.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><a href="auto_overloading.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=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=identifier>f</span><span class=special>; // </span><span class=identifier>defaults </span><span class=identifier>lost</span><span class=special>!
</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=identifier>defaults </span><span class=identifier>lost</span><span class=special>!
</span></pre></code>
<p>
Because of this, when wrapping C++ code, we had to resort to manual
wrapping as outlined in the <a href="overloading.html">
previous section</a>, or
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=identifier>f</span><span class=special>(</span><span class=identifier>x</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=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=identifier>in </span><span class=identifier>module </span><span class=identifier>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=identifier>all </span><span class=identifier>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=identifier>two </span><span class=identifier>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=identifier>one </span><span class=identifier>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><a name="boost_python_function_overloads"></a><h2>BOOST_PYTHON_FUNCTION_OVERLOADS</h2><p>
Boost.Python now has a way to make it easier. 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=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>
<a name="boost_python_member_function_overloads"></a><h2>BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</h2><p>
Objects here, objects there, objects here there everywhere. More frequently
than anything else, we need to expose member functions of our classes to
Python. Then again, we have the same inconveniences as before when default
arguments or overloads with a common sequence of initial arguments come
into play. Another macro is provided to make this a breeze.</p>
<p>
Like <tt>BOOST_PYTHON_FUNCTION_OVERLOADS</tt>,
<tt>BOOST_PYTHON_FUNCTION_OVERLOADS</tt> may be used to automatically create
the thin wrappers for wrapping member functions. Let's have an example:</p>
<code><pre>
<span class=keyword>struct </span><span class=identifier>george
</span><span class=special>{
</span><span class=keyword>void
</span><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=literal>'x'</span><span class=special>)
{
/*...*/
}
};
</span></pre></code>
<p>
The macro invocation:</p>
<code><pre>
<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></pre></code>
<p>
will generate a set of thin wrappers for george's <tt>wack_em</tt> member function
accepting a minimum of 1 and a maximum of 3 arguments (i.e. the third and
fourth macro argument). The thin wrappers are all enclosed in a class named
<tt>george_overloads</tt> that can then be used as an argument to <tt>def(...)</tt>:</p>
<code><pre>
<span class=special>.</span><span class=identifier>def</span><span class=special>(</span><span class=string>&quot;wack_em&quot;</span><span class=special>, &amp;</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></pre></code>
<p>
See the <a href="../../v2/overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">
overloads reference</a>
for details.</p>
<a name="init_and_optional"></a><h2>init and optional</h2><p>
A similar facility is provided for class constructors, again, with
default arguments or a sequence of overloads. Remember <tt>init&lt;...&gt;</tt>? 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></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; &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="overloading.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><a href="auto_overloading.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright &copy; 2002-2003 David Abrahams<br>Copyright &copy; 2002-2003 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