mirror of
https://github.com/boostorg/python.git
synced 2026-01-20 16:52:15 +00:00
230 lines
7.5 KiB
HTML
230 lines
7.5 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
|
|
<!-- Software License, Version 1.0. (See accompanying -->
|
|
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="../boost.css">
|
|
|
|
<title>Boost.Python - <boost/python/overloads.hpp></title>
|
|
</head>
|
|
|
|
<body>
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../../index.htm"><img height="86" width="277"
|
|
alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center"><a href="../index.html">Boost.Python</a></h1>
|
|
|
|
<h2 align="center">Header <boost/python/overloads.hpp></h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<h2>Contents</h2>
|
|
|
|
<dl class="page-index">
|
|
<dt><a href="#introduction">Introduction</a></dt>
|
|
|
|
<dt><a href=
|
|
"#overload-dispatch-expression"><i>overload-dispatch-expressions</i></a></dt>
|
|
|
|
<dt><a href= "#OverloadDispatcher-concept">OverloadDispatcher</a> concept</dt>
|
|
|
|
<dt><a href="#macros">Macros</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href=
|
|
"#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS</a></dt>
|
|
|
|
<dt><a href=
|
|
"#BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a></dt>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#examples">Example(s)</a></dt>
|
|
</dl>
|
|
<hr>
|
|
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
|
|
<p>Defines facilities for generating families of overloaded Python
|
|
functions and extension class methods from C++ functions and
|
|
member functions with default arguments, or from similar families
|
|
of C++ overloads</p>
|
|
|
|
<h2><a name=
|
|
"overload-dispatch-expression"></a><i>overload-dispatch-expressions</i></h2>
|
|
|
|
<p>
|
|
An <em>overload-dispatch-expression</em> is used to describe a
|
|
family of overloaded methods to be generated for an extension
|
|
class. It has the following properties:
|
|
|
|
<blockquote>
|
|
<dl class="properties">
|
|
<dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a>
|
|
whose value will bound to the methods' <code>__doc__</code>
|
|
attribute</dt>
|
|
|
|
<dt><b>keywords:</b> A <a href=
|
|
"args.html#keyword-expression">keyword-expression</a> which
|
|
will be used to name (a trailing subsequence of) the arguments
|
|
to the generated methods.</dt>
|
|
|
|
<dt><b>call policies:</b> An instance of some type which models <a href=
|
|
"CallPolicies.html">CallPolicies</a>.</dt>
|
|
|
|
<dt><b>minimum <a href="definitions.html#arity">arity</a></b>
|
|
The minimum number of arguments to be accepted by a generated
|
|
method overload.</dt>
|
|
|
|
<dt><b>maximum <a href="definitions.html#arity">arity</a></b>
|
|
The maximum number of arguments to be accepted by a generated
|
|
method overload.</dt>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h2><a name="OverloadDispatcher-concept"></a>OverloadDispatcher Concept</h2>
|
|
|
|
An OverloadDispatcher <code>X</code> is a class which has a
|
|
<em>minimum arity</em> and a <em>maximum arity</em>, and for which
|
|
the following following are valid <a
|
|
href="#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>s,
|
|
with the same minimum and maximum arity as the OverloadDispatcher.
|
|
|
|
<pre>
|
|
X()
|
|
X(docstring)
|
|
X(docstring, keywords)
|
|
X(keywords, docstring)
|
|
X()[policies]
|
|
X(docstring)[policies]
|
|
X(docstring, keywords)[policies]
|
|
X(keywords, docstring)[policies]
|
|
</pre>
|
|
|
|
<ul>
|
|
<li>If <code>policies</code> are supplied, it must be an instance of a
|
|
type which models <a
|
|
href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>, and
|
|
will be used as the result's call policies. Otherwise the result's
|
|
call policies will be an instance of <a
|
|
href="default_call_policies.html#default_call_policies-spec">default_call_policies</a>.
|
|
|
|
<li>If <code>docstring</code> is supplied it must be an <a
|
|
href="definitions.html#ntbs">ntbs</a>, and will be used as the result's docstring. Otherwise the result has an empty docstring.
|
|
|
|
<li>If <code>keywords</code> is supplied it must be the result of a <a
|
|
href= "args.html#keyword-expression">keyword-expression</a>
|
|
whose length is no greater than <code>X</code>'s maximum
|
|
arity, and will be used as the result's keywords. Otherwise
|
|
the result's keywords will be empty.
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h2><a name="macros"></a>Macros</h2>
|
|
|
|
<h3><a name=
|
|
"BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS(name, func_id, min_args, max_args)</a></h3>
|
|
Expands to the definition of an OverloadDispatcher called
|
|
<code>name</code> in the current scope which can be used to
|
|
generate the following function invocation:
|
|
<pre>
|
|
func_id(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>);
|
|
</pre>
|
|
|
|
for all <code>min_args</code> <= <i>i</i> <= <code>max_args</code>.
|
|
|
|
<h3><a name=
|
|
"BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name, member_name, min_args, max_args)</a></h3>
|
|
|
|
Expands to the definition of an OverloadDispatcher called
|
|
<code>name</code> in the current scope which can be used to
|
|
generate the following function invocation:
|
|
<pre>
|
|
x.member_name(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>);
|
|
</pre>
|
|
|
|
for all <code>min_args</code> <= <i>i</i> <=
|
|
<code>max_args</code>, where <code>x</code> is a reference to an
|
|
object of class type.
|
|
|
|
<h2><a name="examples"></a>Example(s)</h2>
|
|
|
|
<pre>
|
|
#include <boost/python/module.hpp>
|
|
#include <boost/python/def.hpp>
|
|
#include <boost/python/args.hpp>
|
|
#include <boost/python/tuple.hpp>
|
|
#include <boost/python/class.hpp>
|
|
#include <boost/python/overloads.hpp>
|
|
#include <boost/python/return_internal_reference.hpp>
|
|
|
|
using namespace boost::python;
|
|
|
|
tuple f(int x = 1, double y = 4.25, char const* z = "wow")
|
|
{
|
|
return make_tuple(x, y, z);
|
|
}
|
|
|
|
BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3)
|
|
|
|
struct Y {};
|
|
struct X
|
|
{
|
|
Y& f(int x, double y = 4.25, char const* z = "wow")
|
|
{
|
|
return inner;
|
|
}
|
|
Y inner;
|
|
};
|
|
|
|
BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(f_member_overloads, f, 1, 3)
|
|
|
|
BOOST_PYTHON_MODULE(args_ext)
|
|
{
|
|
def("f", f,
|
|
f_overloads(
|
|
args("x", "y", "z"), "This is f's docstring"
|
|
));
|
|
|
|
|
|
class_<Y>("Y")
|
|
;
|
|
|
|
class_<X>("X", "This is X's docstring")
|
|
.def("f1", &X::f,
|
|
f_member_overloads(
|
|
args("x", "y", "z"), "f's docstring"
|
|
)[return_internal_reference<>()]
|
|
)
|
|
;
|
|
}
|
|
</pre>
|
|
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
15 April, 2003
|
|
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
</p>
|
|
|
|
<p><i>© Copyright <a href=
|
|
"http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
|
|
</body>
|
|
</html>
|
|
|