mirror of
https://github.com/boostorg/python.git
synced 2026-01-30 08:02:38 +00:00
doc update
[SVN r15621]
This commit is contained in:
Dave Abrahams
@@ -345,7 +345,7 @@ class_& def(Init init_expr);
|
||||
generated constructs an object of <code>HeldType</code> according to
|
||||
the semantics described <a href="#HeldType">above</a>, using a copy of
|
||||
<code>init_expr</code>'s <a href="CallPolicies.html">call policies</a>.
|
||||
If the longest valid prefix of <code>Init</code> contains <em>N</em>
|
||||
If the longest <a href="init.html#init-expressions">valid prefix</a> of <code>Init</code> contains <em>N</em>
|
||||
types and <code>init_expr</code> holds <em>M</em> keywords, an initial
|
||||
sequence of the keywords are used for all but the first
|
||||
<em>N</em> - <em>M</em> arguments of each overload.</dt>
|
||||
@@ -378,17 +378,21 @@ class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2, A3
|
||||
<ul>
|
||||
<li>
|
||||
If <code>a1</code> is the result of an <a href=
|
||||
"OverloadDispatch.html"><em>overload-dispatch-expression</em></a>,
|
||||
only the second is allowed and fn must be a pointer to function
|
||||
or pointer to member function whose signature is compatible with
|
||||
A1.
|
||||
"overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>,
|
||||
only the second form is allowed and fn must be a pointer
|
||||
to function or pointer to member function whose <a
|
||||
href="definitions.html#arity">arity</a> is the same as A1's <a href=
|
||||
"overloads.html#overload-dispatch-expression"><em>maximum arity</em></a>.
|
||||
|
||||
<dl>
|
||||
<dt><b>Effects:</b> For each <a href=
|
||||
"OverloadDispatch.html#valid-prefix">valid prefix</a>
|
||||
<em>P</em> of <code>A1</code>, adds a
|
||||
<code><em>name</em>(</code>...<code>)</code> function overload
|
||||
to the extension class. Each overload generated invokes
|
||||
<dt><b>Effects:</b> For each prefix <em>P</em> of
|
||||
<code>Fn</code>'s sequence of argument types, beginning
|
||||
with the one whose length is <code>A1</code>'s <a href=
|
||||
"overloads.html#overload-dispatch-expression"><em>minimum
|
||||
arity</em></a>, adds a
|
||||
<code><em>name</em>(</code>...<code>)</code> method
|
||||
overload to the extension class. Each overload generated
|
||||
invokes
|
||||
<code>a1</code>'s call-expression with <em>P</em>, using a copy
|
||||
of <code>a1</code>'s <a href="CallPolicies.html">call
|
||||
policies</a>. If the longest valid prefix of <code>A1</code>
|
||||
|
||||
250
doc/v2/init.html
Normal file
250
doc/v2/init.html
Normal file
@@ -0,0 +1,250 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<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/init.hpp></title>
|
||||
</head>
|
||||
|
||||
<body link="#0000ff" vlink="#800080">
|
||||
<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="../../../../c++boost.gif" border="0"></a></h3>
|
||||
</td>
|
||||
|
||||
<td valign="top">
|
||||
<h1 align="center">Boost.Python</h1>
|
||||
|
||||
<h2 align="center">Headers <boost/python/init.hpp>,
|
||||
<boost/python/class_fwd.hpp></h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
|
||||
<h2>Contents</h2>
|
||||
|
||||
<dl class="page-index">
|
||||
<dt><a href="#introduction">Introduction</a></dt>
|
||||
|
||||
<dt><a href=
|
||||
"#init-expressions"><em>init-expressions</em></a></dt>
|
||||
|
||||
<dt><a href="#classes">Classes</a></dt>
|
||||
|
||||
<dd>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#init-spec">Class template <code>init</code></a></dt>
|
||||
|
||||
<dd>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#init-spec-synopsis">Class template
|
||||
<code>init</code> synopsis</a></dt>
|
||||
|
||||
<dt><a href="#init-spec-ctors">Class <code>init</code>
|
||||
constructors</a></dt>
|
||||
|
||||
</dl>
|
||||
</dd>
|
||||
|
||||
<dt><a href="#optional-spec">Class template
|
||||
<code>optional</code></a></dt>
|
||||
|
||||
<dd>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#optional-spec-synopsis">Class template
|
||||
<code>optional</code> synopsis</a></dt>
|
||||
</dl>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd>
|
||||
|
||||
<dt><a href="#examples">Example(s)</a></dt>
|
||||
</dl>
|
||||
<hr>
|
||||
|
||||
<h2><a name="introduction"></a>Introduction</h2>
|
||||
|
||||
<p><code><boost/python/init.hpp></code> defines the interface for
|
||||
exposing C++ constructors to Python as extension class
|
||||
<code>__init__</code> functions.</p>
|
||||
|
||||
<h2><a name="init-expressions"><em>init-expressions</em></a></h2>
|
||||
An <em>init-expression</em> is used to describe a family of
|
||||
<code>__init__</code> methods to be generated for an extension class, and
|
||||
the result 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 method's <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 <code>__init__</code> function(s).</dt>
|
||||
|
||||
<dt><b>call policies:</b> An instance of a model of <a href=
|
||||
"CallPolicies.html">CallPolicies</a>.</dt>
|
||||
|
||||
<dt><b>argument types:</b> An MPL sequence of C++ argument types
|
||||
which will be used to construct the wrapped C++ object. An init
|
||||
expression has one or more
|
||||
<b>valid prefixes</b> which are given by a sequence of
|
||||
prefixes of its argument types.</dt>
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="classes"></a>Classes</h2>
|
||||
|
||||
<h3><a name="init-spec"></a>Class template <code>init<T1 =</code>
|
||||
<i>unspecified</i><code>, T2 =</code>
|
||||
<i>unspecified</i><code>,</code>...<code>Tn</code> =
|
||||
<i>unspecified</i><code>></code></h3>
|
||||
|
||||
<p>A <a href="../../../mpl/doc/ref/Sequences.html">MPL sequence</a> which
|
||||
can be used to specify a family of one or more <code>__init__</code>
|
||||
functions. Only the last <code>T</code><i><small>i</small></i> supplied
|
||||
may be an instantiation of <a href=
|
||||
"#optional-spec"><code>optional</code></a><code><</code>...<code>></code>.</p>
|
||||
|
||||
<h4><a name="init-spec-synopsis"></a>Class template <code>init</code>
|
||||
synopsis</h4>
|
||||
<pre>
|
||||
namespace boost { namespace python
|
||||
{
|
||||
template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>>
|
||||
struct init
|
||||
{
|
||||
init(char const* doc = 0);
|
||||
template <class Keywords> init(Keywords const& kw, char const* doc = 0);
|
||||
template <class Keywords> init(char const* doc, Keywords const& kw);
|
||||
|
||||
template <class CallPolicies>
|
||||
<em>unspecified</em> operator[](CallPolicies const& policies) const
|
||||
};
|
||||
}}
|
||||
</pre>
|
||||
|
||||
<h4><a name="init-spec-ctors"></a>Class template <code>init</code>
|
||||
constructors</h4>
|
||||
<pre>
|
||||
init(char const* doc = 0);
|
||||
template <class Keywords> init(Keywords const& kw, char const* doc = 0);
|
||||
template <class Keywords> init(char const* doc, Keywords const& kw);
|
||||
</pre>
|
||||
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Requires:</b> If supplied, <code>doc</code> is an <a href=
|
||||
"definitions.html#ntbs">ntbs</a>. If supplied, <code>kw</code> is the
|
||||
result of a <a href="args.html#keyword-expression"></a></dt>
|
||||
|
||||
<dt><b>Effects:</b> The result is an <em>init-expression</em> whose
|
||||
<em>docstring</em> is <code>doc</code> and whose <em>keywords</em> are
|
||||
a reference to <code>kw</code>. If the first form is used, the
|
||||
resulting expression's <em>keywords</em> are empty. The expression's
|
||||
<em>call policies</em> are an instance of <a href=
|
||||
"default_call_policies.html#default_call_policies-spec">default_call_policies</a>.
|
||||
If <code>T</code><i><small>n</small></i> is <a href=
|
||||
"#optional-spec"><code>optional</code></a><code><U1, U2,</code>...
|
||||
<code>U</code><small><i>m</i></small><code>></code>, the
|
||||
expression's <em>valid prefixes</em> are given by:</dt>
|
||||
|
||||
<dd>
|
||||
<blockquote>
|
||||
(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>),
|
||||
(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>
|
||||
<code>, U1</code>),
|
||||
(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>
|
||||
<code>, U1, U2</code>),
|
||||
...(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>
|
||||
<code>, U1, U2,</code>...<code>U</code><i><small>m</small></i>).
|
||||
</blockquote>
|
||||
Otherwise, the expression has one <em>valid prefix</em> given by the
|
||||
the template arguments the user specified.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h4><a name="init-spec-observers"></a>Class template <code>init</code>
|
||||
observer functions</h4>
|
||||
<pre>
|
||||
template <class Policies>
|
||||
<em>unspecified</em> operator[](Policies const& policies) const
|
||||
</pre>
|
||||
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Requires:</b> Policies is a model of <a href=
|
||||
"CallPolicies.html">CallPolicies</a>.</dt>
|
||||
|
||||
<dt><b>Effects:</b> Returns a new <a href=
|
||||
"#init-expressions"><em>init-expression</em></a> with all the same
|
||||
properties as the <code>init</code> object except that its <em>call
|
||||
policies</em> are replaced by a reference to
|
||||
<code>policies</code>.</dt>
|
||||
</dl>
|
||||
|
||||
<h3><a name="optional-spec"></a>Class template <code>optional<T1
|
||||
=</code> <i>unspecified</i><code>, T2 =</code>
|
||||
<i>unspecified</i><code>,</code>...<code>Tn</code> =
|
||||
<i>unspecified</i><code>></code></h3>
|
||||
|
||||
<p>A <a href="../../../mpl/doc/ref/Sequences.html">MPL sequence</a> which
|
||||
can be used to specify the optional arguments to an <code>__init__</code>
|
||||
function.</p>
|
||||
|
||||
<h4><a name="optional-spec-synopsis"></a>Class template
|
||||
<code>optional</code> synopsis</h4>
|
||||
<pre>
|
||||
namespace boost { namespace python
|
||||
{
|
||||
template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>>
|
||||
struct optional {};
|
||||
}}
|
||||
</pre>
|
||||
|
||||
<h2><a name="examples"></a>Example(s)</h2>
|
||||
|
||||
<p>Given the C++ declarations:</p>
|
||||
<pre>
|
||||
class Y;
|
||||
class X
|
||||
{
|
||||
public:
|
||||
X(int x, Y* y) : m_y(y) {}
|
||||
X(double);
|
||||
private:
|
||||
Y* m_y;
|
||||
};
|
||||
</pre>
|
||||
A corresponding Boost.Python extension class can be created with:
|
||||
<pre>
|
||||
using namespace boost::python;
|
||||
|
||||
class_<X>("X", "This is X's docstring.",
|
||||
init<int,char const*>(args("x","y"), "X.__init__'s docstring")[
|
||||
with_custodian_and_ward<1,3>()]
|
||||
)
|
||||
.def(init<double>())
|
||||
;
|
||||
</pre>
|
||||
<hr>
|
||||
Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
||||
1 October, 2002
|
||||
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
||||
|
||||
|
||||
<p><i>© Copyright <a href=
|
||||
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
|
||||
Reserved.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
225
doc/v2/overloads.html
Normal file
225
doc/v2/overloads.html
Normal file
@@ -0,0 +1,225 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<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="../../../../c++boost.gif" border="0"></a></h3>
|
||||
</td>
|
||||
|
||||
<td valign="top">
|
||||
<h1 align="center">Boost.Python</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)
|
||||
|
||||
stryct Y {};
|
||||
struct X
|
||||
{
|
||||
Y& f(int x, double y = 4.25, char const* z = "wow")
|
||||
{
|
||||
return inner;
|
||||
}
|
||||
Y inner;
|
||||
};
|
||||
|
||||
BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 1, 3)
|
||||
|
||||
BOOST_PYTHON_MODULE(args_ext)
|
||||
{
|
||||
def("f", f, args("x", "y", "z")
|
||||
, "This is f's docstring"
|
||||
);
|
||||
|
||||
|
||||
class_<Y>("Y")
|
||||
;
|
||||
|
||||
class_<X>("X", "This is X's docstring")
|
||||
.def("f1", &X::f,
|
||||
X_f_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 -->
|
||||
01 October, 2002
|
||||
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
||||
</p>
|
||||
|
||||
<p><i>© Copyright <a href=
|
||||
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
|
||||
Reserved.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user