diff options
Diffstat (limited to 'libs/python/doc/v2/extract.html')
| -rw-r--r-- | libs/python/doc/v2/extract.html | 232 |
1 files changed, 0 insertions, 232 deletions
diff --git a/libs/python/doc/v2/extract.html b/libs/python/doc/v2/extract.html deleted file mode 100644 index 3c6b77f2f0..0000000000 --- a/libs/python/doc/v2/extract.html +++ /dev/null @@ -1,232 +0,0 @@ -<!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> - |