Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/python/doc/v2/extract.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 7.2 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
4<!-- Software License, Version 1.0. (See accompanying -->
5<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
6<html>
7  <head>
8    <meta name="generator" content=
9    "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
10    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11    <link rel="stylesheet" type="text/css" href="../boost.css">
12
13    <title>Boost.Python - &lt;boost/python/extract.hpp&gt;</title>
14  </head>
15
16  <body>
17    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
18    "header">
19      <tr>
20        <td valign="top" width="300">
21          <h3><a href="../../../../index.htm"><img height="86" width="277"
22          alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3>
23        </td>
24
25        <td valign="top">
26          <h1 align="center"><a href="../index.html">Boost.Python</a></h1>
27
28          <h2 align="center">Header &lt;boost/python/extract.hpp&gt;</h2>
29        </td>
30      </tr>
31    </table>
32    <hr>
33
34    <h2>Contents</h2>
35
36    <dl class="page-index">
37      <dt><a href="#introduction">Introduction</a></dt>
38
39      <dt><a href="#classes">Classes</a></dt>
40
41      <dd>
42        <dl class="page-index">
43          <dt><a href="#extract-spec">Class <code>extract</code></a></dt>
44
45          <dd>
46            <dl class="page-index">
47              <dt><a href="#extract-spec-synopsis">Class <code>extract</code>
48              synopsis</a></dt>
49
50              <dt><a href="#extract-spec-ctors">Class <code>extract</code>
51              constructors and destructor</a></dt>
52
53              <dt><a href="#extract-spec-observers">Class
54              <code>extract</code> observer functions</a></dt>
55            </dl>
56          </dd>
57        </dl>
58      </dd>
59
60
61      <dt><a href="#examples">Example</a></dt>
62    </dl>
63    <hr>
64
65    <h2><a name="introduction"></a>Introduction</h2>
66
67    <p>Exposes a mechanism for extracting C++ object values from
68    generalized Python objects. Note that
69    <code>extract&lt;</code>...<code>&gt;</code> can also be used to
70    &quot;downcast&quot; an <a
71    href="object.html#object-spec">object</a> to some specific <a
72    href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>. Because
73    invoking a mutable python type with an argument of the same type
74    (e.g. <code>list([1,2])</code> typically makes a <em>copy</em> of
75    the argument object, this may be the only way to access the <a
76    href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>'s
77    interface on the original object.
78
79    <h2><a name="classes"></a>Classes</h2>
80
81    <h3><a name="extract-spec"></a>Class template <code>extract</code></h3>
82
83    <p><code>extract&lt;T&gt;</code> can be used to extract a value of
84    an arbitrary C++ type from an instance of <code><a
85    href="object.html#object-spec">object</a></code>. Two usages are supported:
86<ol>
87<li><b><code>extract&lt;T&gt;(o)</code></b> is a temporary object
88which is implicitly convertible to <code>T</code> (explicit conversion
89is also available through the object's function-call
90operator). However, if no conversion is available which can convert
91<code>o</code> to an object of type <code>T</code>, a Python
92<code>TypeError</code> exception will be <a
93href="definitions.html#raise">raised</a>.
94
95<li><b><code>extract&lt;T&gt; x(o);</code></b> constructs an extractor
96whose <code>check()</code> member function can be used to ask whether
97a conversion is available without causing an exception to be thrown.
98</ol>
99
100    <h4><a name="extract-spec-synopsis"></a>Class template <code>extract</code>
101    synopsis</h4>
102<pre>
103namespace boost { namespace python
104{
105  template &lt;class T&gt;
106  struct extract
107  {
108      typedef <i>unspecified</i> result_type;
109
110      extract(PyObject*);
111      extract(object const&amp;);
112
113      result_type operator()() const;
114      operator result_type() const;
115
116      bool check() const;
117  };
118}}
119</pre>
120
121    <h4><a name="extract-spec-ctors"></a>Class <code>extract</code>
122    constructors and destructor</h4>
123<pre>
124extract(PyObject* p);
125extract(object const&amp;);
126</pre>
127
128    <dl class="function-semantics">
129      <dt><b>Requires:</b> The first form requires that <code>p</code> is non-null.</dt>
130
131      <dt><b>Effects:</b>Stores a pointer to the Python object managed
132      by its constructor argument. In particular, the reference
133      count of the object is not incremented. The onus is on the user
134      to be sure it is not destroyed before the extractor's conversion
135      function is called.</dt>
136    </dl>
137
138    <h4><a name="extract-spec-observers"></a>Class <code>extract</code>
139    observer functions</h4>
140<pre>
141result_type operator()() const;
142operator result_type() const;
143</pre>
144
145    <dl class="function-semantics">
146      <dt><b>Effects:</b> Converts the stored pointer to
147      <code>result_type</code>, which is either <code>T</code> or
148      <code>T const&amp;</code>.
149      </dt>
150
151      <dt><b>Returns:</b> An object of <code>result_type</code>
152      corresponding to the one referenced by the stored pointer.</dt>
153
154      <dt><b>Throws:</b> <code><a
155      href="errors.html#error_already_set-spec">error_already_set</a></code>
156      and sets a <code>TypeError</code> if no such conversion is
157      available. May also emit other unspecified exceptions thrown by
158      the converter which is actually used.</dt>
159    </dl>
160
161<pre>
162bool check() const;
163</pre>
164
165    <dl class="function-semantics">
166
167      <dt><b>Postconditions:</b> None. In particular, note that a
168      return value of <code>true</code> does not preclude an exception
169      being thrown from <code>operator result_type()</code> or
170      <code>operator()()</code>.</dt>
171
172      <dt><b>Returns:</b> <code>false</code> <i>only</i> if no conversion from the
173      stored pointer to <code>T</code> is available.</dt>
174
175    </dl>
176
177
178    <h2><a name="examples"></a>Examples</h2>
179
180<pre>
181#include &lt;cstdio&gt;
182using namespace boost::python;
183int Print(str s)
184{
185   // extract a C string from the Python string object
186   char const* c_str = extract&lt;char const*&gt;(s);
187
188   // Print it using printf
189   std::printf(&quot;%s\n&quot;, c_str);
190
191   // Get the Python string's length and convert it to an int
192   return extract&lt;int&gt;(s.attr(&quot;__len__&quot;)())
193}
194</pre>
195
196The following example shows how extract can be used along with
197<code><a
198href="class.html#class_-spec">class_</a>&lt;</code>...<code>&gt;</code>
199to create and access an instance of a wrapped C++ class.
200
201<pre>
202struct X
203{
204   X(int x) : v(x) {}
205   int value() { return v; }
206 private:
207   int v;
208};
209
210BOOST_PYTHON_MODULE(extract_ext)
211{
212    object x_class(
213       class_&lt;X&gt;(&quot;X&quot;, init&lt;int&gt;())
214          .def(&quot;value&quot;, &amp;X::value))
215          ;
216       
217    // Instantiate an X object through the Python interface.
218    // Its lifetime is now managed by x_obj.
219    object x_obj = x_class(3);
220
221    // Get a reference to the C++ object out of the Python object
222    X&amp; x = extract&lt;X&amp;&gt;(x_obj);
223    assert(x.value() == 3);
224}
225</pre>
226    <p>Revised 15 November, 2002</p>
227
228    <p><i>&copy; Copyright <a href=
229    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
230  </body>
231</html>
232
Note: See TracBrowser for help on using the repository browser.