libs/contract/doc/html/BOOST_CO_idm45123869363568.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Macro BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="Chapter&#160;1.&#160;Boost.Contract 1.0.0">
   8 <link rel="up" href="reference.html#header.boost.contract_macro_hpp" title="Header &lt;boost/contract_macro.hpp&gt;">
   9 <link rel="prev" href="BOOST_CO_idm45123869395440.html" title="Macro BOOST_CONTRACT_PUBLIC_FUNCTION">
  10 <link rel="next" href="boost_contract/release_notes.html" title="Release Notes">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="BOOST_CO_idm45123869395440.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="reference.html#header.boost.contract_macro_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_contract/release_notes.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="refentry">
  26 <a name="BOOST_CO_idm45123869363568"></a><div class="titlepage"></div>
  27 <div class="refnamediv">
  28 <h2><span class="refentrytitle">Macro BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE</span></h2>
  29 <p>BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE &#8212; Program contracts that can be completely disabled at compile-time for public function overrides. </p>
  30 </div>
  31 <h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
  32 <div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis"><span class="comment">// In header: &lt;<a class="link" href="reference.html#header.boost.contract_macro_hpp" title="Header &lt;boost/contract_macro.hpp&gt;">boost/contract_macro.hpp</a>&gt;
  33
  34 </span>BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE(...)</pre></div>
  35 <div class="refsect1">
  36 <a name="idm45751725425584"></a><h2>Description</h2>
  37 <p>This is used together with <code class="computeroutput"><a class="link" href="BOOST_CO_idm45123869622736.html" title="Macro BOOST_CONTRACT_PRECONDITION">BOOST_CONTRACT_PRECONDITION</a></code>,  <code class="computeroutput"><a class="link" href="BOOST_CO_idm45123869611056.html" title="Macro BOOST_CONTRACT_POSTCONDITION">BOOST_CONTRACT_POSTCONDITION</a></code>, <code class="computeroutput"><a class="link" href="BOOST_CONTRACT_EXCEPT.html" title="Macro BOOST_CONTRACT_EXCEPT">BOOST_CONTRACT_EXCEPT</a></code>, and <code class="computeroutput"><a class="link" href="BOOST_CONTRACT_OLD.html" title="Macro BOOST_CONTRACT_OLD">BOOST_CONTRACT_OLD</a></code> to specify preconditions, postconditions, exception guarantees, and old value copies at body that can be completely disabled at compile-time for public function overrides (virtual or not):</p>
  38 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span>
  39     <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">private</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">constructor_precondition</span><span class="special">&lt;</span><span class="identifier">u</span><span class="special">&gt;</span><span class="special">,</span> \
  40             <span class="keyword">public</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">private</span> <span class="identifier">w</span>
  41     <span class="special">:</span> <span class="identifier">BASES</span>
  42 <span class="special">{</span>
  43     <span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">access</span><span class="special">;</span>
  44
  45     <span class="keyword">typedef</span> <span class="identifier">BOOST_CONTRACT_BASE_TYPES</span><span class="special">(</span><span class="identifier">BASES</span><span class="special">)</span> <span class="identifier">base_types</span><span class="special">;</span>
  46     <span class="preprocessor">#undef</span> <span class="identifier">BASES</span>
  47
  48     <span class="identifier">BOOST_CONTRACT_INVARIANT</span><span class="special">(</span><span class="special">{</span> <span class="comment">// Optional (as for static and volatile).</span>
  49         <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="special">...</span><span class="special">)</span><span class="special">;</span>
  50         <span class="special">...</span>
  51     <span class="special">}</span><span class="special">)</span>
  52
  53     <span class="identifier">BOOST_CONTRACT_OVERRIDES</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">g</span><span class="special">)</span>
  54
  55 <span class="keyword">public</span><span class="special">:</span>
  56     <span class="comment">// Override from `b::f`, and void.</span>
  57     <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">t_1</span> <span class="identifier">a_1</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="identifier">t_n</span> <span class="identifier">a_n</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">virtual_</span><span class="special">*</span> <span class="identifier">v</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
  58         <span class="identifier">BOOST_CONTRACT_OLD_PTR</span><span class="special">(</span><span class="identifier">old_type</span><span class="special">)</span><span class="special">(</span><span class="identifier">old_var</span><span class="special">)</span><span class="special">;</span>
  59         <span class="identifier">BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE</span><span class="special">(</span><span class="identifier">override_f</span><span class="special">)</span><span class="special">(</span>
  60                 <span class="identifier">v</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">u</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> <span class="identifier">a_1</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="identifier">a_n</span><span class="special">)</span>
  61             <span class="identifier">BOOST_CONTRACT_PRECONDITION</span><span class="special">(</span><span class="special">[</span><span class="special">&amp;</span><span class="special">]</span> <span class="special">{</span> <span class="comment">// Optional.</span>
  62                 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="special">...</span><span class="special">)</span><span class="special">;</span>
  63                 <span class="special">...</span>
  64             <span class="special">}</span><span class="special">)</span>
  65             <span class="identifier">BOOST_CONTRACT_OLD</span><span class="special">(</span><span class="special">[</span><span class="special">&amp;</span><span class="special">]</span> <span class="special">{</span> <span class="comment">// Optional.</span>
  66                 <span class="identifier">old_var</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">old_expr</span><span class="special">)</span><span class="special">;</span>
  67                 <span class="special">...</span>
  68             <span class="special">}</span><span class="special">)</span>
  69             <span class="identifier">BOOST_CONTRACT_POSTCONDITION</span><span class="special">(</span><span class="special">[</span><span class="special">&amp;</span><span class="special">]</span> <span class="special">{</span> <span class="comment">// Optional.</span>
  70                 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="special">...</span><span class="special">)</span><span class="special">;</span>
  71                 <span class="special">...</span>
  72             <span class="special">}</span><span class="special">)</span>
  73             <span class="identifier">BOOST_CONTRACT_EXCEPT</span><span class="special">(</span><span class="special">[</span><span class="special">&amp;</span><span class="special">]</span> <span class="special">{</span> <span class="comment">// Optional.</span>
  74                 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="special">...</span><span class="special">)</span><span class="special">;</span>
  75                 <span class="special">...</span>
  76             <span class="special">}</span><span class="special">)</span>
  77         <span class="special">;</span>
  78
  79         <span class="special">...</span> <span class="comment">// Function body.</span>
  80     <span class="special">}</span>
  81
  82     <span class="comment">// Override from `b::g`, and void.</span>
  83     <span class="identifier">t</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">t_1</span> <span class="identifier">a_1</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="identifier">t_n</span> <span class="identifier">a_n</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">virtual_</span><span class="special">*</span> <span class="identifier">v</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
  84         <span class="identifier">t</span> <span class="identifier">result</span><span class="special">;</span>
  85         <span class="identifier">BOOST_CONTRACT_OLD_PTR</span><span class="special">(</span><span class="identifier">old_type</span><span class="special">)</span><span class="special">(</span><span class="identifier">old_var</span><span class="special">)</span><span class="special">;</span>
  86         <span class="identifier">BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE</span><span class="special">(</span><span class="identifier">override_g</span><span class="special">)</span><span class="special">(</span>
  87                 <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">u</span><span class="special">::</span><span class="identifier">g</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> <span class="identifier">a_1</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="identifier">a_n</span><span class="special">)</span>
  88             <span class="special">...</span>
  89             <span class="identifier">BOOST_CONTRACT_OLD</span><span class="special">(</span><span class="special">[</span><span class="special">&amp;</span><span class="special">]</span> <span class="special">{</span> <span class="comment">// Optional.</span>
  90                 <span class="identifier">old_var</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">old_expr</span><span class="special">)</span><span class="special">;</span>
  91                 <span class="special">...</span>
  92             <span class="special">}</span><span class="special">)</span>
  93             <span class="identifier">BOOST_CONTRACT_POSTCONDITION</span><span class="special">(</span><span class="special">[</span><span class="special">&amp;</span><span class="special">]</span> <span class="special">(</span><span class="identifier">t</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// Optional</span>
  94                 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="special">...</span><span class="special">)</span><span class="special">;</span>
  95                 <span class="special">...</span>
  96             <span class="special">}</span><span class="special">)</span>
  97             <span class="special">...</span>
  98         <span class="special">;</span>
  99
 100         <span class="special">...</span> <span class="comment">// Function body (use `return result = return_expr`).</span>
 101     <span class="special">}</span>
 102
 103     <span class="special">...</span>
 104 <span class="special">}</span><span class="special">;</span>
 105 </pre>
 106 <p>Public function overrides should always use  <code class="computeroutput"><a class="link" href="BOOST_CO_idm45123869363568.html" title="Macro BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE">BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE</a></code> otherwise this library will not be able to correctly use it for subcontracting.</p>
 107 <p>This is an overloaded variadic macro and it can be used in the following different ways (note that no code is generated when  <code class="computeroutput"><a class="link" href="BOOST_CO_idm45123870441776.html" title="Macro BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS">BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS</a></code> is defined).</p>
 108 <p>1. <code class="computeroutput">BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE(override_type)(v, f, obj, ...)</code> expands to code equivalent to the following (for public function overrides that return void):</p>
 109 <pre class="programlisting"><span class="preprocessor">#ifndef</span> <span class="identifier">BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS</span>
 110     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">internal_var</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span>
 111             <span class="identifier">public_function</span><span class="special">&lt;</span><span class="identifier">override_type</span><span class="special">&gt;</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">obj</span><span class="special">,</span> <span class="special">...</span><span class="special">)</span>
 112 <span class="preprocessor">#endif</span>
 113 </pre>
 114 <p>2. <code class="computeroutput">BOOST_CONTRACT_PUBLIC_FUNCTION_OVERRIDE(override_type)(v, r, f, obj, ...)</code> expands to code equivalent to the following (for public function overrides that do not return void):</p>
 115 <pre class="programlisting"><span class="preprocessor">#ifndef</span> <span class="identifier">BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS</span>
 116     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">internal_var</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span>
 117             <span class="identifier">public_function</span><span class="special">&lt;</span><span class="identifier">override_type</span><span class="special">&gt;</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">obj</span><span class="special">,</span> <span class="special">...</span><span class="special">)</span>
 118 <span class="preprocessor">#endif</span>
 119 </pre>
 120 <p>Where (these are all variadic macro parameters so they can contain commas not protected by round parenthesis):</p>
 121 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 122 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>override_type</strong></span></code> is the type <code class="computeroutput">override_<span class="emphasis"><em>function-name</em></span></code> declared using the  <code class="computeroutput"><a class="link" href="BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> or related macros. </p></li>
 123 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>v</strong></span></code> is the extra parameter of type  <code class="computeroutput"><a class="link" href="boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput">*</code> and default value <code class="computeroutput">0</code> from the enclosing virtual public function declaring the contract. </p></li>
 124 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>r</strong></span></code> is a reference to the return value of the enclosing virtual public function declaring the contract. This is usually a local variable declared by the enclosing virtual public function just before the contract, but programmers must set it to the actual value being returned by the function at each <code class="computeroutput">return</code> statement. </p></li>
 125 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>f</strong></span></code> is a pointer to the enclosing public function override declaring the contract. </p></li>
 126 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>obj</strong></span></code> is the object <code class="computeroutput">this</code> from the scope of the enclosing public function declaring the contract. This object might be mutable, <code class="computeroutput">const</code>, <code class="computeroutput">volatile</code>, or <code class="computeroutput">const volatile</code> depending on the cv-qualifier of the enclosing function (volatile public functions will check volatile class invariants, see <a class="link" href="boost_contract/extras.html#boost_contract.extras.volatile_public_functions" title="Volatile Public Functions">
 127         Volatile Public Functions</a>). </p></li>
 128 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>...</strong></span></code> is a variadic macro parameter listing all the arguments passed to the enclosing public function override declaring the contract (by reference and in order they appear in the enclosing function declaration), but excluding the trailing argument <code class="computeroutput">v</code>. </p></li>
 129 <li class="listitem"><p><code class="computeroutput"><span class="bold"><strong>internal_var</strong></span></code> is a variable name internally generated by this library (this name is unique but only on different line numbers so this macro cannot be expanded multiple times on the same line).</p></li>
 130 </ul></div>
 131 <p>
 132 </p>
 133 <p><span class="bold"><strong>See Also:</strong></span></p>
 134 <p> <a class="link" href="boost_contract/extras.html#boost_contract.extras.disable_contract_compilation__macro_interface_" title="Disable Contract Compilation (Macro Interface)">
 135         Disable Contract Compilation</a>,  <a class="link" href="boost_contract/tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">
 136         Public Function Overrides</a> </p>
 137 <p>
 138 </p>
 139 <p>
 140 </p>
 141 </div>
 142 </div>
 143 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 144 <td align="left"></td>
 145 <td align="right"><div class="copyright-footer">Copyright &#169; 2008-2018 Lorenzo Caminiti<p>
 146         Distributed under the Boost Software License, Version 1.0 (see accompanying
 147         file LICENSE_1_0.txt or a copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 148       </p>
 149 </div></td>
 150 </tr></table>
 151 <hr>
 152 <div class="spirit-nav">
 153 <a accesskey="p" href="BOOST_CO_idm45123869395440.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="reference.html#header.boost.contract_macro_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_contract/release_notes.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
 154 </div>
 155 </body>
 156 </html>