boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-22 17:32:55 +00:00
Code Issues Projects Releases Wiki Activity

doc update

Browse Source 
[SVN r15702]
This commit is contained in:
Dave Abrahams
2002-10-04 00:45:29 +00:00
parent 2b5f421501
commit a91112e5d9
3 changed files with 361 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
doc/v2/definitions.html
View File

@@ -34,26 +34,49 @@
hidden "<code>this</code>" argument to member functions is not counted
when specifying arity</dt>
<dd><br>
</dd>
<dt><b><a name="ntbs">ntbs</a>:</b> Null-Terminated Byte String, or
`C'-string. C++ string literals are <strong>ntbs</strong>es. An
<strong>ntbs</strong> must never be null.</dt>
<dd><br>
</dd>
<dt><b><a name="raise">raise</a>:</b> Exceptions in Python are
&quot;raised&quot;, not &quot;thrown&quot;, as they are in
C++. When this documentation says that some Python exception is
&quot;raised&quot; in the context of C++ code, it means that the
corresponding Python exception is set via the <a
href="http://www.python.org/doc/current/api/exceptionHandling.html">Python/'C'
API</a>, and <code><a
href="errors.html#throw_error_already_set-spec">throw_error_already_set</a>()</code>
"raised", not "thrown", as they are in C++. When this documentation
says that some Python exception is "raised" in the context of C++ code,
it means that the corresponding Python exception is set via the <a
href=
"http://www.python.org/doc/current/api/exceptionHandling.html">Python/'C'
API</a>, and <code><a href=
"errors.html#throw_error_already_set-spec">throw_error_already_set</a>()</code>
is called.</dt>
<dd><br>
</dd>
<dt><b><a name="POD">POD</a>:</b> A technical term from the C++
standard. Short for "Plain Ol'Data": A POD-struct is an aggregate class
that has no non-static data members of type pointer to member,
non-POD-struct, non-POD-union (or array of such types) or reference,
and has no user-defined copy assign- ment operator and no user-defined
destructor. Similarly, a POD-union is an aggregate union that has no
non-static data members of type pointer to member, non-POD-struct,
non-POD-union (or array of such types) or reference, and has no
user-defined copy assignment operator and no user-defined destructor. A
POD class is a class that is either a POD-struct or a POD-union. An
aggregate is an array or a class (clause 9) with no user-declared
constructors (12.1), no private or protected non-static data members
(clause 11), no base classes (clause 10), and no virtual functions
(10.3).</dt>
</dl>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
30 September, 2002
03 October, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>

322
doc/v2/handle.html Normal file
View File

@@ -0,0 +1,322 @@
<!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 - &lt;boost/python/handle.hpp&gt;</title>
<style type="text/css">
p.c4 {font-style: italic}
span.c3 {color: #ff0000}
h2.c2 {text-align: center}
h1.c1 {text-align: center}
</style>
</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 class="c1">Boost.Python</h1>
<h2 class="c2">Header &lt;boost/python/handle.hpp&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#classes">Classes</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#handle-spec">Class template
<code>handle</code></a></dt>
<dd>
<dl class="page-index">
<dt><a href="#handle-spec-synopsis">Class <code>handle</code>
synopsis</a></dt>
<dt><a href="#handle-spec-ctors">Class <code>handle</code>
constructors and destructor</a></dt>
<dt><a href="#handle-spec-modifiers">Class <code>handle</code>
modifier functions</a></dt>
<dt><a href="#handle-spec-observers">Class <code>handle</code>
observer functions</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#functions">Functions</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#borrowed-spec"><code>borrowed</code></a></dt>
<dt><a href="#allow_null-spec"><code>allow_null</code></a></dt>
</dl>
</dd>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p><code>&lt;boost/python/handle.hpp&gt;</code> provides
<code>class&nbsp;template&nbsp;handle</code>, a smart pointer for
managing reference-counted Python objects.</p>
<h2><a name="classes"></a>Classes</h2>
<h3><a name="handle-spec"></a>Class template <code>handle</code></h3>
<p><code>handle</code> is a smart pointer to a Python object type; it
holds a pointer of type <code>T*</code>, where T is its template
parameter. <code>T</code> must be either a type derived from
<code>PyObject</code> or a <a href="definitions.html#POD">POD</a>
type whose initial <code>sizeof(PyObject)</code> bytes are
layout-compatible with <code>PyObject</code>. Use
<code>handle&lt;&gt;</code> at the boundary between tehe
Python/'C' API and high-level code; prefer <code><a
href="object.html#object-spec">object</a></code> for a generalized
interface to Python objects.
<p><a name="upcast"></a>In this document, the term "upcast" refers to an
operation which converts a pointer <code>Y*</code> to a base class
pointer <code>T*</code> via <code>static_cast&lt;T*&gt;</code> if
<code>Y</code> is derived from <code>T</code>, or via C-style cast
<code>(T*)</code> if it is not. However, in the latter case the "upcast"
is ill-formed if the initial <code>sizeof(PyObject)</code> bytes of
<code>Y</code> are not layout-compatible with <code>PyObject</code>.</p>
<h4><a name="handle-spec-synopsis"></a>Class template handle
synopsis</h4>
<pre>
namespace boost { namespace python
{
template &lt;class T&gt;
class handle
{
typedef <i>unspecified-member-function-pointer</i> bool_type;
public: // types
typedef T element_type;
public: // member functions
~handle();
template &lt;class Y&gt;
explicit handle(detail::borrowed&lt;null_ok&lt;Y&gt; &gt;* p);
template &lt;class Y&gt;
explicit handle(null_ok&lt;detail::borrowed&lt;Y&gt; &gt;* p);
template &lt;class Y&gt;
explicit handle(detail::borrowed&lt;Y&gt;* p);
template &lt;class Y&gt;
explicit handle(null_ok&lt;Y&gt;* p);
template &lt;class Y&gt;
explicit handle(Y* p);
handle();
handle&amp; operator=(handle const&amp; r);
template&lt;typename Y&gt;
handle&amp; operator=(handle&lt;Y&gt; const &amp; r); // never throws
template &lt;typename Y&gt;
handle(handle&lt;Y&gt; const&amp; r);
handle(handle const&amp; r);
T* operator-&gt; () const;
T&amp; operator* () const;
T* get() const;
T* release();
operator bool_type() const; // never throws
private:
T* m_p;
};
template &lt;class T&gt; struct null_ok;
namespace detail { template &lt;class T&gt; struct borrowed; }
}}
</pre>
<h4><a name="handle-spec-ctors">Class <code>handle</code> constructors
and destructor</a></h4>
<pre>
virtual ~handle();
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b> <code>Py_XDECREF(m_p)</code></dt>
</dl>
<pre>
template &lt;class Y&gt;
explicit handle(detail::borrowed&lt;null_ok&lt;Y&gt; &gt;* p);
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b> <code>Py_XDECREF(m_p)</code></dt>
</dl>
<pre>
template &lt;class Y&gt;
explicit handle(null_ok&lt;detail::borrowed&lt;Y&gt; &gt;* p);
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b>
<code>m_p&nbsp;=&nbsp;</code><i>upcast</i><code>&lt;T*&gt;(p);</code></dt>
</dl>
<pre>
template &lt;class Y&gt;
explicit handle(detail::borrowed&lt;Y&gt;* p);
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b>
<code>m_p&nbsp;=&nbsp;</code><i>upcast</i><code>&lt;T*&gt;(<a href=
"errors.html#expect_non_null-spec">expect_non_null</a>(p));</code></dt>
</dl>
<pre>
template &lt;class Y&gt;
explicit handle(null_ok&lt;Y&gt;* p);
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b>
<code>Py_XINCREF(p);&nbsp;m_p&nbsp;=&nbsp;</code><i>upcast</i><code>&lt;T*&gt;(p);</code></dt>
</dl>
<pre>
template &lt;class Y&gt;
explicit handle(Y* p);
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b>
<code>Py_XINCREF(p);&nbsp;m_p&nbsp;=&nbsp;</code><i>upcast</i><code>&lt;T*&gt;(<a
href=
"errors.html#expect_non_null-spec">expect_non_null</a>(p));</code></dt>
</dl>
<pre>
handle();
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b> <code>m_p&nbsp;=&nbsp;0;</code></dt>
</dl>
<pre>
template &lt;typename Y&gt;
handle(handle&lt;Y&gt; const&amp; r);
handle(handle const&amp; r);
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b>
<code>m_p&nbsp;=&nbsp;r.m_p;&nbsp;Py_XINCREF(m_p);</code></dt>
</dl>
<h4><a name="handle-spec-modifiers">Class <code>handle</code>
modifiers</a></h4>
<pre>
handle&amp; operator=(handle const&amp; r);
template&lt;typename Y&gt;
handle&amp; operator=(handle&lt;Y&gt; const &amp; r); // never throws
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b>
<code>Py_XINCREF(r.m_p);&nbsp;Py_XDECREF(m_p);&nbsp;m_p&nbsp;=&nbsp;r.m_p;</code></dt>
</dl>
<pre>
T* release();
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b> <code>T* x = m_p;&nbsp;m_p&nbsp;=&nbsp;0;return
x;</code></dt>
</dl>
<h4><a name="handle-spec-observers">Class <code>handle</code>
observers</a></h4>
<pre>
T* operator-&gt; () const;
T* get() const;
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> <code>m_p;</code></dt>
</dl>
<pre>
T&amp; operator* () const;
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> <code>*m_p;</code></dt>
</dl>
<pre>
operator bool_type() const; // never throws
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> 0 if <code>m_p&nbsp;==&nbsp;0</code>, a pointer
convertible to <code>true</code> otherwise.</dt>
</dl>
<h2><a name="functions"></a>Functions</h2>
<h3><a name="borrowed-spec"></a><code>borrowed</code></h3>
<pre>
template <class T>
detail::borrowed<T>* borrowed(T* p)
{
return (detail::borrowed<T>*)p;
}
</pre>
<h3><a name="allow_null-spec"></a><code>allow_null</code></h3>
<pre>
template <class T>
null_ok<T>* allow_null(T* p)
{
return (null_ok<T>*)p;
}
</pre>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
03 October, 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p class="c4">&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
Reserved.</p>
</body>
</html>

14
doc/v2/reference.html
View File

@@ -771,24 +771,26 @@
</dl>
</dd>
<dt><a href="reference_hpp.html">reference.hpp</a></dt>
<dt><a href="handle.html">handle.hpp</a></dt>
<dd>
<dl class="index">
<dt><a href="reference_hpp.html#classes">Classes</a></dt>
<dt><a href="handle.html#classes">Classes</a></dt>
<dd>
<dl class="index">
<dt><a href=
"reference_hpp.html#reference-spec">reference</a></dt>
"handle.html#handle-spec">handle</a></dt>
</dl>
</dd>
<dt><a href="reference_hpp.html#types">Types</a></dt>
<dt><a href="handle.html#functions">Functions</a></dt>
<dd>
<dl class="index">
<dt><a href="reference_hpp.html#ref-spec">ref</a></dt>
<dt><a href=
"handle.html#borrowed-spec">borrowed</a></dt>
<dt><a href=
"handle.html#allow_null-spec">allow_null</a></dt>
</dl>
</dd>
</dl>