diff options
Diffstat (limited to 'libs/python/doc/v2/extract.html')
| -rw-r--r-- | libs/python/doc/v2/extract.html | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/libs/python/doc/v2/extract.html b/libs/python/doc/v2/extract.html new file mode 100644 index 000000000..3c6b77f2f --- /dev/null +++ b/libs/python/doc/v2/extract.html @@ -0,0 +1,232 @@ +<!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/extract.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/extract.hpp></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="#extract-spec">Class <code>extract</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#extract-spec-synopsis">Class <code>extract</code> + synopsis</a></dt> + + <dt><a href="#extract-spec-ctors">Class <code>extract</code> + constructors and destructor</a></dt> + + <dt><a href="#extract-spec-observers">Class + <code>extract</code> observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Exposes a mechanism for extracting C++ object values from + generalized Python objects. Note that + <code>extract<</code>...<code>></code> can also be used to + "downcast" an <a + href="object.html#object-spec">object</a> to some specific <a + href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>. Because + invoking a mutable python type with an argument of the same type + (e.g. <code>list([1,2])</code> typically makes a <em>copy</em> of + the argument object, this may be the only way to access the <a + href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>'s + interface on the original object. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="extract-spec"></a>Class template <code>extract</code></h3> + + <p><code>extract<T></code> can be used to extract a value of + an arbitrary C++ type from an instance of <code><a + href="object.html#object-spec">object</a></code>. Two usages are supported: +<ol> +<li><b><code>extract<T>(o)</code></b> is a temporary object +which is implicitly convertible to <code>T</code> (explicit conversion +is also available through the object's function-call +operator). However, if no conversion is available which can convert +<code>o</code> to an object of type <code>T</code>, a Python +<code>TypeError</code> exception will be <a +href="definitions.html#raise">raised</a>. + +<li><b><code>extract<T> x(o);</code></b> constructs an extractor +whose <code>check()</code> member function can be used to ask whether +a conversion is available without causing an exception to be thrown. +</ol> + + <h4><a name="extract-spec-synopsis"></a>Class template <code>extract</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> + struct extract + { + typedef <i>unspecified</i> result_type; + + extract(PyObject*); + extract(object const&); + + result_type operator()() const; + operator result_type() const; + + bool check() const; + }; +}} +</pre> + + <h4><a name="extract-spec-ctors"></a>Class <code>extract</code> + constructors and destructor</h4> +<pre> +extract(PyObject* p); +extract(object const&); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> The first form requires that <code>p</code> is non-null.</dt> + + <dt><b>Effects:</b>Stores a pointer to the Python object managed + by its constructor argument. In particular, the reference + count of the object is not incremented. The onus is on the user + to be sure it is not destroyed before the extractor's conversion + function is called.</dt> + </dl> + + <h4><a name="extract-spec-observers"></a>Class <code>extract</code> + observer functions</h4> +<pre> +result_type operator()() const; +operator result_type() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Converts the stored pointer to + <code>result_type</code>, which is either <code>T</code> or + <code>T const&</code>. + </dt> + + <dt><b>Returns:</b> An object of <code>result_type</code> + corresponding to the one referenced by the stored pointer.</dt> + + <dt><b>Throws:</b> <code><a + href="errors.html#error_already_set-spec">error_already_set</a></code> + and sets a <code>TypeError</code> if no such conversion is + available. May also emit other unspecified exceptions thrown by + the converter which is actually used.</dt> + </dl> + +<pre> +bool check() const; +</pre> + + <dl class="function-semantics"> + + <dt><b>Postconditions:</b> None. In particular, note that a + return value of <code>true</code> does not preclude an exception + being thrown from <code>operator result_type()</code> or + <code>operator()()</code>.</dt> + + <dt><b>Returns:</b> <code>false</code> <i>only</i> if no conversion from the + stored pointer to <code>T</code> is available.</dt> + + </dl> + + + <h2><a name="examples"></a>Examples</h2> + +<pre> +#include <cstdio> +using namespace boost::python; +int Print(str s) +{ + // extract a C string from the Python string object + char const* c_str = extract<char const*>(s); + + // Print it using printf + std::printf("%s\n", c_str); + + // Get the Python string's length and convert it to an int + return extract<int>(s.attr("__len__")()) +} +</pre> + +The following example shows how extract can be used along with +<code><a +href="class.html#class_-spec">class_</a><</code>...<code>></code> +to create and access an instance of a wrapped C++ class. + +<pre> +struct X +{ + X(int x) : v(x) {} + int value() { return v; } + private: + int v; +}; + +BOOST_PYTHON_MODULE(extract_ext) +{ + object x_class( + class_<X>("X", init<int>()) + .def("value", &X::value)) + ; + + // Instantiate an X object through the Python interface. + // Its lifetime is now managed by x_obj. + object x_obj = x_class(3); + + // Get a reference to the C++ object out of the Python object + X& x = extract<X&>(x_obj); + assert(x.value() == 3); +} +</pre> + <p>Revised 15 November, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + |