Boost_1_39_0/libs/python/doc/v2/return_by_value.html

   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/return_by_value.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
  29           &lt;boost/python/return_by_value.hpp&gt;</h2>
  30         </td>
  31       </tr>
  32     </table>
  33     <hr>
  34
  35     <h2>Contents</h2>
  36
  37     <dl class="page-index">
  38       <dt><a href="#classes">Classes</a></dt>
  39
  40       <dd>
  41         <dl class="page-index">
  42           <dt><a href="#return_by_value-spec">Class
  43           <code>return_by_value</code></a></dt>
  44
  45           <dd>
  46             <dl class="page-index">
  47               <dt><a href="#return_by_value-spec-synopsis">Class
  48               <code>return_by_value</code> synopsis</a></dt>
  49
  50               <dt><a href="#return_by_value-spec-metafunctions">Class
  51               <code>return_by_value</code> metafunctions</a></dt>
  52             </dl>
  53           </dd>
  54         </dl>
  55       </dd>
  56
  57       <dt><a href="#examples">Example</a></dt>
  58     </dl>
  59     <hr>
  60
  61     <h2><a name="classes"></a>Classes</h2>
  62
  63     <h3><a name="return_by_value-spec"></a>Class
  64     <code>return_by_value</code></h3>
  65
  66     <p><code>return_by_value</code> is a model of <a href=
  67     "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>
  68     which can be used to wrap C++ functions returning any reference or value
  69     type such that the return value is copied into a new Python object.</p>
  70
  71     <h4><a name="return_by_value-spec-synopsis"></a>Class
  72     <code>return_by_value</code> synopsis</h4>
  73 <pre>
  74 namespace boost { namespace python
  75 {
  76     struct return_by_value
  77     {
  78         template &lt;class T&gt; struct apply;
  79     };
  80 }}
  81 </pre>
  82
  83     <h4><a name="return_by_value-spec-metafunctions"></a>Class
  84     <code>return_by_value</code> metafunctions</h4>
  85 <pre>
  86 template &lt;class T&gt; struct apply
  87 </pre>
  88
  89     <dl class="metafunction-semantics">
  90       <dt><b>Returns:</b> <code>typedef <a href=
  91       "to_python_value.html#to_python_value-spec">to_python_value</a>&lt;T&gt;
  92       type;</code></dt>
  93     </dl>
  94
  95     <h2><a name="examples"></a>Example</h2>
  96
  97     <h3>C++ Module Definition</h3>
  98 <pre>
  99 #include &lt;boost/python/module.hpp&gt;
 100 #include &lt;boost/python/class.hpp&gt;
 101 #include &lt;boost/python/return_by_value.hpp&gt;
 102 #include &lt;boost/python/return_value_policy.hpp&gt;
 103
 104 // classes to wrap
 105 struct Bar { };
 106
 107 Bar global_bar;
 108
 109 // functions to wrap:
 110 Bar b1();
 111 Bar&amp; b2();
 112 Bar const&amp; b3();
 113
 114 // Wrapper code
 115 using namespace boost::python;
 116 template &lt;class R&gt;
 117 void def_void_function(char const* name, R (*f)())
 118 {
 119    def(name, f, return_value_policy&lt;return_by_value&gt;());
 120 }
 121
 122 BOOST_PYTHON_MODULE(my_module)
 123 {
 124     class_&lt;Bar&gt;("Bar");
 125     def_void_function("b1", b1);
 126     def_void_function("b2", b2);
 127     def_void_function("b3", b3);
 128 }
 129 </pre>
 130
 131     <h3>Python Code</h3>
 132 <pre>
 133 &gt;&gt;&gt; from my_module import *
 134 &gt;&gt;&gt; b = b1() # each of these calls
 135 &gt;&gt;&gt; b = b2() # creates a brand
 136 &gt;&gt;&gt; b = b3() # new Bar object
 137 </pre>
 138
 139     <p>Revised
 140     <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
 141   13 November, 2002
 142   <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
 143     </p>
 144
 145     <p><i>&copy; Copyright <a href=
 146     "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
 147   </body>
 148 </html>
 149