1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Tutorial</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 1. Boost.Contract 1.0.0"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Contract 1.0.0"> 9<link rel="prev" href="contract_programming_overview.html" title="Contract Programming Overview"> 10<link rel="next" href="advanced.html" title="Advanced"> 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="contract_programming_overview.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><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="advanced.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_contract.tutorial"></a><a class="link" href="tutorial.html" title="Tutorial">Tutorial</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.non_member_functions">Non-Member 31 Functions</a></span></dt> 32<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.preconditions">Preconditions</a></span></dt> 33<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.postconditions">Postconditions</a></span></dt> 34<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.return_values">Return Values</a></span></dt> 35<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.old_values">Old Values</a></span></dt> 36<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.exception_guarantees">Exception 37 Guarantees</a></span></dt> 38<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.class_invariants">Class Invariants</a></span></dt> 39<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.constructors">Constructors</a></span></dt> 40<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.destructors">Destructors</a></span></dt> 41<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.public_functions">Public Functions</a></span></dt> 42<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.virtual_public_functions">Virtual 43 Public Functions</a></span></dt> 44<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_">Public 45 Function Overrides (Subcontracting)</a></span></dt> 46<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.base_classes__subcontracting_">Base 47 Classes (Subcontracting)</a></span></dt> 48<dt><span class="section"><a href="tutorial.html#boost_contract.tutorial.static_public_functions">Static 49 Public Functions</a></span></dt> 50</dl></div> 51<p> 52 This section is a guide to basic usage of this library. 53 </p> 54<div class="section"> 55<div class="titlepage"><div><div><h3 class="title"> 56<a name="boost_contract.tutorial.non_member_functions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.non_member_functions" title="Non-Member Functions">Non-Member 57 Functions</a> 58</h3></div></div></div> 59<p> 60 Contracts for non-member functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code>. 61 For example (see <a href="../../../example/features/non_member.cpp" target="_top"><code class="literal">non_member.cpp</code></a>): 62 </p> 63<p> 64</p> 65<pre class="programlisting"><span class="preprocessor">#include</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">hpp</span><span class="special">></span> 66 67<span class="comment">// Contract for a non-member function.</span> 68<span class="keyword">int</span> <span class="identifier">inc</span><span class="special">(</span><span class="keyword">int</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> 69 <span class="keyword">int</span> <span class="identifier">result</span><span class="special">;</span> 70 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">old_x</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> 71 <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">c</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">function</span><span class="special">()</span> 72 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 73 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">x</span> <span class="special"><</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="keyword">int</span><span class="special">>::</span><span class="identifier">max</span><span class="special">());</span> 74 <span class="special">})</span> 75 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 76 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">x</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_x</span> <span class="special">+</span> <span class="number">1</span><span class="special">);</span> 77 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">result</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_x</span><span class="special">);</span> 78 <span class="special">})</span> 79 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> 80 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">x</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_x</span><span class="special">);</span> 81 <span class="special">})</span> 82 <span class="special">;</span> 83 84 <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">++;</span> <span class="comment">// Function body.</span> 85<span class="special">}</span> 86</pre> 87<p> 88 </p> 89<p> 90 All necessary header files of this library are included by <code class="computeroutput"><span class="preprocessor">#include</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">hpp</span><span class="special">></span></code>. 91 Alternatively, programmers can selectively include only the header files 92 they actually need among <code class="literal">boost/contract/*.hpp</code> (see <a class="link" href="getting_started.html" title="Getting Started">Getting Started</a>). 93 </p> 94<p> 95 It is possible to specify preconditions, postconditions, and exception guarantees 96 for non-member functions (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>, 97 <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>, 98 and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 99 Guarantees</a>). 100 </p> 101<p> 102 The <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 103 function returns an RAII object that must always be assigned to a local variable 104 of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 105 (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585506528.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>). 106 <a href="#ftn.boost_contract.tutorial.non_member_functions.f0" class="footnote" name="boost_contract.tutorial.non_member_functions.f0"><sup class="footnote">[19]</sup></a> Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> 107 declarations cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 108 type must be explicitly specified (otherwise this library will generate a 109 compile-time error prior C++17 and a run-time error post C++17). <a href="#ftn.boost_contract.tutorial.non_member_functions.f1" class="footnote" name="boost_contract.tutorial.non_member_functions.f1"><sup class="footnote">[20]</sup></a> The function body is programmed right after the declaration of 110 this RAII object. 111 </p> 112<div class="note"><table border="0" summary="Note"> 113<tr> 114<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 115<th align="left">Note</th> 116</tr> 117<tr><td align="left" valign="top"><p> 118 In some cases, it might be necessary to program some code before the contract. 119 For example for acquiring resources that will be used while checking the 120 contract like old values, but also to lock mutexes (or other synchronization 121 mechanisms) in multi-threaded programs. 122 </p></td></tr> 123</table></div> 124<p> 125 At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 126 RAII object for non-member functions does the following (enclosing function 127 entry): 128 </p> 129<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> 130 Check preconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 131 </li></ol></div> 132<p> 133 At destruction instead (enclosing function exit): 134 </p> 135<div class="orderedlist"><ol class="orderedlist" type="1"> 136<li class="listitem"> 137 If the function body did not throw an exception: 138 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 139 Check postconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 140 </li></ol></div> 141 </li> 142<li class="listitem"> 143 Else: 144 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 145 Check exception guarantees, by calling the nullary functor <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 146 </li></ol></div> 147 </li> 148</ol></div> 149<p> 150 This ensures that non-member function contracts are correctly checked at 151 run-time (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.function_calls" title="Function Calls">Function 152 Calls</a>). (Also note that functions will correctly check their contracts 153 even when they are called via function pointers, function objects, etc.) 154 </p> 155<div class="note"><table border="0" summary="Note"> 156<tr> 157<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 158<th align="left">Note</th> 159</tr> 160<tr><td align="left" valign="top"><p> 161 A non-member function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 162 for efficiency but only when it has no preconditions, no postconditions, 163 and no exception guarantees. 164 </p></td></tr> 165</table></div> 166</div> 167<div class="section"> 168<div class="titlepage"><div><div><h3 class="title"> 169<a name="boost_contract.tutorial.preconditions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a> 170</h3></div></div></div> 171<p> 172 When preconditions are specified, they are programmed using a functor <code class="literal"><span class="emphasis"><em>r</em></span></code> 173 passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">)</span></code> that can be called with no parameters as 174 in <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code>. 175 Contracts that do not have preconditions simply do not call <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code>. Preconditions must appear before postconditions 176 and exception guarantees when these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a> 177 and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 178 Guarantees</a>). 179 </p> 180<p> 181 C++11 lambda functions are convenient to program preconditions, but any other 182 nullary functor can be used (see <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 183 Lambda Functions</a>). <a href="#ftn.boost_contract.tutorial.preconditions.f0" class="footnote" name="boost_contract.tutorial.preconditions.f0"><sup class="footnote">[21]</sup></a> For example, for <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 184 (similarly for public functions, instead destructors do not have preconditions 185 and constructors use <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code>, 186 see <a class="link" href="tutorial.html#boost_contract.tutorial.public_functions" title="Public Functions">Public Functions</a>, 187 <a class="link" href="tutorial.html#boost_contract.tutorial.destructors" title="Destructors">Destructors</a>, and 188 <a class="link" href="tutorial.html#boost_contract.tutorial.constructors" title="Constructors">Constructors</a>): 189 </p> 190<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(...)</span> <span class="special">{</span> 191 <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">c</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">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span> 192 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference or value...</span> 193 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> <span class="comment">// ...and should not modify captures.</span> 194 <span class="special">...</span> 195 <span class="special">})</span> 196 <span class="special">...</span> 197 <span class="special">;</span> 198 199 <span class="special">...</span> 200<span class="special">}</span> 201</pre> 202<p> 203 The precondition functor should capture all the variables that it needs to 204 assert the preconditions. These variables can be captured by value when the 205 overhead of copying such variables is acceptable. <a href="#ftn.boost_contract.tutorial.preconditions.f1" class="footnote" name="boost_contract.tutorial.preconditions.f1"><sup class="footnote">[22]</sup></a> In any case, programmers should not write precondition assertions 206 that modify the value of the captured variables, even when those are captured 207 by reference (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 208 </p> 209<p> 210 Any code can be programmed in the precondition functor, but it is recommended 211 to keep this code simple using mainly assertions and if-statements (to avoid 212 programming complex preconditions that might be buggy and also slow to check 213 at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 214 to program precondition assertions because that enables this library to print 215 informative error messages when the asserted conditions are evaluated to 216 be false (note that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 217 Macros</a>): 218 </p> 219<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span> 220<span class="comment">// Or, if `boolean-condition` contains commas `,` not already within parenthesis `()`...</span> 221<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span> 222</pre> 223<p> 224 This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/precondition_failure.html" title="Function precondition_failure">boost::contract::precondition_failure</a></code> 225 if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 226 conditions are false or, more in general, if calling the functor specified 227 via <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> throws any exception. By default, this 228 failure handler prints an error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> 229 and terminates the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> 230 (see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 231 on Failures</a> to change the failure handler to throw exceptions, exit 232 the program with an error code, etc.). 233 </p> 234<div class="note"><table border="0" summary="Note"> 235<tr> 236<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 237<th align="left">Note</th> 238</tr> 239<tr><td align="left" valign="top"><p> 240 Contracts are most useful when their assertions only use public members 241 that are accessible to the caller so the caller can properly check and 242 use the contract. In particular, preconditions of a public function or 243 constructor that use non-public members are essentially incorrect because 244 they cannot be fully checked by the caller (in fact, Eiffel generates a 245 compile-time error in this case). However, this library does not enforce 246 such a constraint and it leaves it up to programmers to only use public 247 members when programming contracts, especially when asserting preconditions 248 (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.specifications_vs__implementation" title="Specifications vs. Implementation">Specifications 249 vs. Implementation</a>). 250 </p></td></tr> 251</table></div> 252</div> 253<div class="section"> 254<div class="titlepage"><div><div><h3 class="title"> 255<a name="boost_contract.tutorial.postconditions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a> 256</h3></div></div></div> 257<p> 258 When postconditions are specified, they are programmed using a functor <code class="literal"><span class="emphasis"><em>s</em></span></code> 259 passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code> that can be called with no parameters as 260 in <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code>. 261 Contracts that do not have postconditions simply do not call <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code>. Postconditions must appear after preconditions 262 but before exception guarantees when these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a> 263 and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 264 Guarantees</a>). 265 </p> 266<p> 267 C++11 lambda functions are convenient to program postconditions, but any 268 other nullary functor can be used (see <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 269 Lambda Functions</a>). For example, for <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 270 (similarly for all other contracts): 271 </p> 272<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(...)</span> <span class="special">{</span> 273 <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">c</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">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span> 274 <span class="special">...</span> 275 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference...</span> 276 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> <span class="comment">// ...but should not modify captures.</span> 277 <span class="special">...</span> 278 <span class="special">})</span> 279 <span class="special">...</span> 280 <span class="special">;</span> 281 282 <span class="special">...</span> 283<span class="special">}</span> 284</pre> 285<p> 286 The postcondition functor should capture all the variables that it needs 287 to assert the postconditions. In general, these variables should be captured 288 by reference and not by value (because postconditions need to access the 289 value that these variables will have at function exit, and not the value 290 these variables had when the postcondition functor was first declared). Postconditions 291 can also capture return and old values (see <a class="link" href="tutorial.html#boost_contract.tutorial.return_values" title="Return Values">Return 292 Values</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.old_values" title="Old Values">Old 293 Values</a>). In any case, programmers should not write postcondition assertions 294 that modify the value of the captured variables, even when those are captured 295 by reference (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 296 </p> 297<p> 298 Any code can be programmed in the postcondition functor, but it is recommended 299 to keep this code simple using mainly assertions and if-statements (to avoid 300 programming complex postconditions that might be buggy and slow to check 301 at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 302 to program postcondition assertions because that enables this library to 303 print informative error messages when the asserted conditions are evaluated 304 to be false (note that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 305 Macros</a>): 306 </p> 307<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span> 308<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span> 309<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span> 310</pre> 311<p> 312 This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/postcondition_failure.html" title="Function postcondition_failure">boost::contract::postcondition_failure</a></code> 313 if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 314 conditions are false or, more in general, if calling the functor specified 315 via <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code> throws any exception. By default, this 316 failure handler prints an error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> 317 and terminates the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> 318 (see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 319 on Failures</a> to change the failure handler to throw exceptions, exit 320 the program with an error code, etc.). 321 </p> 322<p> 323 For non-void virtual public functions and non-void public function overrides, 324 the functor <code class="literal"><span class="emphasis"><em>s</em></span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code> is not a nullary functor, instead it is 325 a unary functor taking a variable holding the return value as its one parameter 326 <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result</em></span></code><code class="computeroutput"><span class="special">)</span></code> (this is to properly support subcontracting, 327 see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 328 Public Functions</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 329 Function Overrides</a>). 330 </p> 331</div> 332<div class="section"> 333<div class="titlepage"><div><div><h3 class="title"> 334<a name="boost_contract.tutorial.return_values"></a><a class="link" href="tutorial.html#boost_contract.tutorial.return_values" title="Return Values">Return Values</a> 335</h3></div></div></div> 336<p> 337 In non-void functions, postconditions might need to access the function return 338 value to program assertions. In these cases, programmers are responsible 339 to declare a local variable before the contract and to assign it to the return 340 value at function exit (when the function does not throw an exception). 341 <a href="#ftn.boost_contract.tutorial.return_values.f0" class="footnote" name="boost_contract.tutorial.return_values.f0"><sup class="footnote">[23]</sup></a> For example, for <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 342 (similarly for all other contracts): 343 </p> 344<pre class="programlisting"><span class="identifier">return_type</span> <span class="identifier">f</span><span class="special">(...)</span> <span class="special">{</span> 345 <span class="identifier">return_type</span> <span class="identifier">result</span><span class="special">;</span> <span class="comment">// Must be later assigned to return value.</span> 346 <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">c</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">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span> 347 <span class="special">...</span> 348 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Also capture `result` reference...</span> 349 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">result</span> <span class="special">==</span> <span class="special">...);</span> <span class="comment">// ...but should not modify captures.</span> 350 <span class="special">...</span> 351 <span class="special">})</span> 352 <span class="special">...</span> 353 <span class="special">;</span> 354 355 <span class="special">...</span> 356 <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="special">...;</span> <span class="comment">// Assign `result` at each return.</span> 357<span class="special">}</span> 358</pre> 359<p> 360 At any point where the enclosing function returns, programmers are responsible 361 to assign the result variable to the expression being returned. This can 362 be done ensuring that <span class="emphasis"><em>all</em></span> <code class="computeroutput"><span class="keyword">return</span></code> 363 statements in the function are of the form: 364 </p> 365<pre class="programlisting"><code class="literal"><span class="emphasis"><em>return-type</em></span></code> <span class="identifier">result</span><span class="special">;</span> 366<span class="special">...</span> 367<span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <code class="literal"><span class="emphasis"><em>return-expression</em></span></code><span class="special">;</span> <span class="comment">// Assign `result` at each return.</span> 368</pre> 369<p> 370 The functor used to program postconditions should capture the result variable 371 by reference and not by value (because postconditions must access the value 372 the result variable will have at function exit, and not the value the result 373 variable had when the postcondition functor was first declared). The return 374 value should never be used in preconditions, old value copies, or exception 375 guarantees (because the return value is not yet correctly evaluated and set 376 when preconditions are checked, old values are copied, or if the function 377 throws an exception). In any case, programmers should not modify the result 378 variable in the contract assertions (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 379 </p> 380<p> 381 It is also possible to declared the result variable using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> 382 when the function return type does not have a default constructor, or if 383 the default constructor is too expensive or undesirable to execute when first 384 declaring the result variable (see <a class="link" href="advanced.html#boost_contract.advanced.optional_return_values" title="Optional Return Values">Optional 385 Return Values</a>). 386 </p> 387<p> 388 Non-void virtual public functions and non-void public function overrides 389 must always declare and use a result variable even when postconditions do 390 not directly use the function return value (this is to properly support subcontracting, 391 see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 392 Public Functions</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 393 Function Overrides</a>). 394 </p> 395</div> 396<div class="section"> 397<div class="titlepage"><div><div><h3 class="title"> 398<a name="boost_contract.tutorial.old_values"></a><a class="link" href="tutorial.html#boost_contract.tutorial.old_values" title="Old Values">Old Values</a> 399</h3></div></div></div> 400<p> 401 When old values are used in postconditions or in exception guarantees, programmes 402 are responsible to declare local variables before the contract and to assign 403 them to related old value expressions using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>. 404 <a href="#ftn.boost_contract.tutorial.old_values.f0" class="footnote" name="boost_contract.tutorial.old_values.f0"><sup class="footnote">[24]</sup></a> For example, for <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 405 (similarly for all other contracts): 406 </p> 407<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(...)</span> <span class="special">{</span> 408 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="identifier">old_type</span><span class="special">></span> <span class="identifier">old_var</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">old_expr</span><span class="special">);</span> 409 <span class="special">...</span> <span class="comment">// More old value declarations here if needed.</span> 410 <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">c</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">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span> 411 <span class="special">...</span> <span class="comment">// Preconditions shall not use old values.</span> 412 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference...</span> 413 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(*</span><span class="identifier">old_var</span> <span class="special">==</span> <span class="special">...);</span> <span class="comment">// ...but should not modify captures.</span> 414 <span class="special">...</span> 415 <span class="special">})</span> 416 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference...</span> 417 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">old_var</span><span class="special">->...);</span> <span class="comment">// ...but should not modify captures.</span> 418 <span class="special">...</span> 419 <span class="special">})</span> 420 <span class="special">;</span> 421 422 <span class="special">...</span> 423<span class="special">}</span> 424</pre> 425<p> 426 Old values are handled by this library using the smart pointer class template 427 <code class="computeroutput"><a class="link" href="../boost/contract/old_ptr.html" title="Class template old_ptr">boost::contract::old_ptr</a></code> 428 (so programmers do not directly manage allocation and deallocation of the 429 pointed memory). <a href="#ftn.boost_contract.tutorial.old_values.f1" class="footnote" name="boost_contract.tutorial.old_values.f1"><sup class="footnote">[25]</sup></a> The pointed old value type is automatically qualified as <code class="computeroutput"><span class="keyword">const</span></code> (so old values cannot be mistakenly 430 changed by contract assertions, see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 431 This library ensures that old value pointers are always not null by the time 432 postconditions and exception guarantees are checked (so programmers can safely 433 dereference and use these pointers in postcondition and exception guarantee 434 assertions using <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> 435 and <code class="computeroutput"><span class="keyword">operator</span><span class="special">-></span></code> 436 without having to check if old value pointers are not null first). 437 </p> 438<p> 439 Old values should not be used in preconditions and this library does not 440 guarantee that old value pointers are always not null when preconditions 441 are checked. <a href="#ftn.boost_contract.tutorial.old_values.f2" class="footnote" name="boost_contract.tutorial.old_values.f2"><sup class="footnote">[26]</sup></a> See <a class="link" href="advanced.html#boost_contract.advanced.old_values_copied_at_body" title="Old Values Copied at Body">Old 442 Values Copied at Body</a> for delaying the copy of old values until after 443 class invariants (for constructors, destructors, and public functions) and 444 preconditions are checked (when necessary, this allows to program old value 445 expressions under the simplifying assumption that class invariant and precondition 446 assertions are satisfied already). 447 </p> 448<p> 449 <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> is 450 a variadic macro and it takes an extra parameter when used in virtual public 451 functions or public function overrides (see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 452 Public Functions</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 453 Function Overrides</a>). C++11 auto declarations can be used with <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> for brevity 454 <code class="computeroutput"><span class="keyword">auto</span> </code><code class="literal">old_<span class="emphasis"><em>variable-name</em></span> 455 = BOOST_CONTRACT_OLDOF(<span class="emphasis"><em>expression</em></span>)</code> (but see 456 also <a class="link" href="extras.html#boost_contract.extras.old_value_requirements__templates_" title="Old Value Requirements (Templates)">Old 457 Value Requirements</a>). See <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 458 Macros</a> to program old values without using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 459 (e.g., on compilers that do not support variadic macros). 460 </p> 461<div class="note"><table border="0" summary="Note"> 462<tr> 463<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 464<th align="left">Note</th> 465</tr> 466<tr><td align="left" valign="top"><p> 467 This library ensures that old values are copied only once. This library 468 also ensures that old values are never copied when postconditions and exception 469 guarantees are disabled defining both <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585468496.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code> 470 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code> 471 (note that both these two macros must be defined, defining only <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585468496.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code> 472 or only <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code> 473 is not sufficient to prevent the run-time cost of old value copies). 474 </p></td></tr> 475</table></div> 476</div> 477<div class="section"> 478<div class="titlepage"><div><div><h3 class="title"> 479<a name="boost_contract.tutorial.exception_guarantees"></a><a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 480 Guarantees</a> 481</h3></div></div></div> 482<p> 483 When exception guarantees are specified, they are programmed using a functor 484 <code class="literal"><span class="emphasis"><em>e</em></span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code> that can be called with no parameters as 485 in <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code>. 486 Contracts that do not have exception guarantees simply do not call <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span></code>. Exception guarantees must appear after 487 both preconditions and postconditions when these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a> and 488 <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>). 489 </p> 490<p> 491 C++11 lambda functions are convenient to program exception guarantees, but 492 any other nullary functor can be used (see <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 493 Lambda Functions</a>). For example, for <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 494 (similarly for all other contracts): 495 </p> 496<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(...)</span> <span class="special">{</span> 497 <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">c</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">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span> 498 <span class="special">...</span> 499 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference...</span> 500 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> <span class="comment">// ...but should not modify captures.</span> 501 <span class="special">...</span> 502 <span class="special">})</span> 503 <span class="special">;</span> 504 505 <span class="special">...</span> 506<span class="special">}</span> 507</pre> 508<p> 509 The exception guarantee functor should capture all the variables that it 510 needs to assert the exception guarantees. In general, these variables should 511 be captured by reference and not by value (because exception guarantees need 512 to access the value that these variables will have when the function throws, 513 and not the value these variables had when the exception guarantee functor 514 was first declared). Exception guarantees can also capture old values (see 515 <a class="link" href="tutorial.html#boost_contract.tutorial.old_values" title="Old Values">Old Values</a>) but 516 they should not access the function return value instead (because the return 517 value is not be properly set when the function throws an exception). In any 518 case, programmers should not write exception guarantee assertions that modify 519 the value of the captured variables, even when those are captured by reference 520 (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 521 </p> 522<div class="note"><table border="0" summary="Note"> 523<tr> 524<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 525<th align="left">Note</th> 526</tr> 527<tr><td align="left" valign="top"><p> 528 In real production code, it might be difficult to program meaningful exception 529 guarantees without resorting to expensive old value copies that will slow 530 down execution. Therefore, the authors recognize that exception guarantees, 531 even if supported by this library, might not be used often in practice 532 (and they are not used in most of the examples listed in the rest of this 533 documentation). In any case, these performance considerations are ultimately 534 left to programmers and their specific application domains. 535 </p></td></tr> 536</table></div> 537<p> 538 Any code can be programmed in the exception guarantee functor, but it is 539 recommended to keep this code simple using mainly assertions and if-statements 540 (to avoid programming complex exception guarantees that might be buggy and 541 slow to check at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 542 to program exception guarantee assertions because that enables this library 543 to print informative error messages when the asserted conditions are evaluated 544 to be false (note that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 545 Macros</a>): 546 </p> 547<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span> 548<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span> 549<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span> 550</pre> 551<p> 552 This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/except_failure.html" title="Function except_failure">boost::contract::except_failure</a></code> 553 if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 554 conditions are false or, more in general, if calling the functor specified 555 via <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span></code> throws any exception. By default, this 556 failure handler prints an error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> 557 and terminates the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> 558 (see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 559 on Failures</a> to change the failure handler to exit the program with 560 an error code or to take some other custom action). 561 </p> 562<div class="note"><table border="0" summary="Note"> 563<tr> 564<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 565<th align="left">Note</th> 566</tr> 567<tr><td align="left" valign="top"><p> 568 While it is technically possible for programmers to specify an exception 569 guarantee handler that throws an exception in case of an exception guarantee 570 failure, this will force C++ to terminate the program. That is because 571 the handler will throw an exception while there is already an active exception 572 on the stack (the exception thrown by the function body that caused the 573 exception guarantees to be checked in the first place). Therefore, programmers 574 should not change the exception guarantee failure handler to throw exceptions. 575 </p></td></tr> 576</table></div> 577</div> 578<div class="section"> 579<div class="titlepage"><div><div><h3 class="title"> 580<a name="boost_contract.tutorial.class_invariants"></a><a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class Invariants</a> 581</h3></div></div></div> 582<p> 583 Public member functions, constructors, and destructors can be programmed 584 to also check class invariants. When class invariants are specified, they 585 are programmed in a public <code class="computeroutput"><span class="keyword">const</span></code> 586 function named <code class="computeroutput"><span class="identifier">invariant</span></code> 587 taking no argument and returning <code class="computeroutput"><span class="keyword">void</span></code>. 588 Classes that do not have invariants, simply do not declare the <code class="computeroutput"><span class="identifier">invariant</span></code> function. <a href="#ftn.boost_contract.tutorial.class_invariants.f0" class="footnote" name="boost_contract.tutorial.class_invariants.f0"><sup class="footnote">[27]</sup></a> For example: 589 </p> 590<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 591<span class="keyword">public</span><span class="special">:</span> <span class="comment">// Must be public.</span> 592 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="comment">// Must be const.</span> 593 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> 594 <span class="special">...</span> 595 <span class="special">}</span> 596 597 <span class="special">...</span> 598<span class="special">};</span> 599</pre> 600<p> 601 This member function must be <code class="computeroutput"><span class="keyword">const</span></code> 602 because contracts should not modify the object state (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 603 This library will generate a compile-time error if the <code class="computeroutput"><span class="keyword">const</span></code> 604 qualifier is missing (unless <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_PERMISSIVE.html" title="Macro BOOST_CONTRACT_PERMISSIVE">BOOST_CONTRACT_PERMISSIVE</a></code> 605 is defined). 606 </p> 607<p> 608 Any code can be programmed in the <code class="computeroutput"><span class="identifier">invariant</span></code> 609 function, but it is recommended to keep this code simple using mainly assertions 610 and if-statements (to avoid programming complex invariants that might be 611 buggy and slow to check at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> to program 612 class invariant assertions because that enables this library to print informative 613 error messages when the asserted conditions are evaluated to be false (note 614 that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 615 Macros</a>): 616 </p> 617<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span> 618<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span> 619<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span> 620</pre> 621<p> 622 This library will automatically call failure handlers <code class="computeroutput"><a class="link" href="../boost/contract/entry_invariant_failure.html" title="Function entry_invariant_failure">boost::contract::entry_invariant_failure</a></code> 623 or <code class="computeroutput"><a class="link" href="../boost/contract/exit_invariant_failure.html" title="Function exit_invariant_failure">boost::contract::exit_invariant_failure</a></code> 624 if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 625 conditions are false or, more in general, if the <code class="computeroutput"><span class="identifier">invariant</span></code> 626 function throws an exception when invariants are checked at function entry 627 or exit respectively. By default, these handlers print an error message to 628 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and terminate the program calling 629 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> (see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 630 on Failures</a> to change these failure handlers to throw exceptions, 631 exit the program with an error code, etc.). 632 </p> 633<p> 634 See <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a> 635 to avoid making the <code class="computeroutput"><span class="identifier">invariant</span></code> 636 member function <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.class_invariants.f1" class="footnote" name="boost_contract.tutorial.class_invariants.f1"><sup class="footnote">[28]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585536960.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code> 637 to use a name different from <code class="computeroutput"><span class="identifier">invariant</span></code> 638 (e.g., because <code class="computeroutput"><span class="identifier">invariant</span></code> 639 clashes with other names in user-defined classes). 640 </p> 641<div class="note"><table border="0" summary="Note"> 642<tr> 643<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 644<th align="left">Note</th> 645</tr> 646<tr><td align="left" valign="top"><p> 647 Contract assertions are not checked (not even class invariants) when data 648 members are accessed directly (this is different from Eiffel where even 649 accessing public data members checks class invariants). Therefore, it might 650 be best for both <code class="computeroutput"><span class="keyword">class</span></code>es and 651 <code class="computeroutput"><span class="keyword">struct</span></code>s (and also <code class="computeroutput"><span class="keyword">union</span></code>s, see <a class="link" href="extras.html#boost_contract.extras.unions" title="Unions">Unions</a>) 652 that have invariants to have no mutable public data members and to access 653 data members publicly only via appropriate public functions (e.g., setters 654 and getters) that can be programmed to check the class invariants using 655 this library. 656 </p></td></tr> 657</table></div> 658<p> 659 See <a class="link" href="extras.html#boost_contract.extras.volatile_public_functions" title="Volatile Public Functions">Volatile 660 Public Functions</a> to program invariants for classes with <code class="computeroutput"><span class="keyword">volatile</span></code> public functions. 661 </p> 662<h5> 663<a name="boost_contract.tutorial.class_invariants.h0"></a> 664 <span class="phrase"><a name="boost_contract.tutorial.class_invariants.static_class_invariants"></a></span><a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants.static_class_invariants">Static 665 Class Invariants</a> 666 </h5> 667<p> 668 Static public functions can be programmed to check static class invariants. 669 When static class invariants are specified, they are programmed in a public 670 <code class="computeroutput"><span class="keyword">static</span></code> function named <code class="computeroutput"><span class="identifier">static_invariant</span></code> taking no argument and 671 returning <code class="computeroutput"><span class="keyword">void</span></code>. Classes that 672 do not have static class invariants, simply do not declare the <code class="computeroutput"><span class="identifier">static_invariant</span></code> function. <a href="#ftn.boost_contract.tutorial.class_invariants.f2" class="footnote" name="boost_contract.tutorial.class_invariants.f2"><sup class="footnote">[29]</sup></a> For example: 673 </p> 674<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 675<span class="keyword">public</span><span class="special">:</span> <span class="comment">// Must be public.</span> 676 <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">static_invariant</span><span class="special">()</span> <span class="special">{</span> <span class="comment">// Must be static.</span> 677 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> 678 <span class="special">...</span> 679 <span class="special">}</span> 680 681 <span class="special">...</span> 682<span class="special">};</span> 683</pre> 684<p> 685 This member function must be <code class="computeroutput"><span class="keyword">static</span></code> 686 (and it correctly cannot access the object <code class="computeroutput"><span class="keyword">this</span></code>). 687 This library will generate a compile-time error if the <code class="computeroutput"><span class="keyword">static</span></code> 688 classifier is missing (unless the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_PERMISSIVE.html" title="Macro BOOST_CONTRACT_PERMISSIVE">BOOST_CONTRACT_PERMISSIVE</a></code> 689 macro is defined). 690 </p> 691<p> 692 Any code can be programmed in the <code class="computeroutput"><span class="identifier">static_invariant</span></code> 693 function, but it is recommended to keep this code simple using mainly assertions 694 and if-statements (to avoid programming complex static invariants that might 695 be buggy and slow to check at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> to program 696 the assertions because that enables this library to print informative error 697 messages when the asserted conditions are evaluated to be false (note that 698 this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 699 Macros</a>): 700 </p> 701<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span> 702<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span> 703<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span> 704</pre> 705<p> 706 This library will automatically call failure handlers <code class="computeroutput"><a class="link" href="../boost/contract/entry_invariant_failure.html" title="Function entry_invariant_failure">boost::contract::entry_invariant_failure</a></code> 707 or <code class="computeroutput"><a class="link" href="../boost/contract/exit_invariant_failure.html" title="Function exit_invariant_failure">boost::contract::exit_invariant_failure</a></code> 708 if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 709 conditions are false or, more in general, if the <code class="computeroutput"><span class="identifier">static_invariant</span></code> 710 function throws an exception when invariants are checked at function entry 711 or exit respectively. By default, these handlers print an error message to 712 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and terminate the program calling 713 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> (see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 714 on Failures</a> to change these failure handlers to throw exceptions, 715 exit the program with an error code, etc.). 716 </p> 717<p> 718 See <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a> 719 to avoid making <code class="computeroutput"><span class="identifier">static_invariant</span></code> 720 member function <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.class_invariants.f3" class="footnote" name="boost_contract.tutorial.class_invariants.f3"><sup class="footnote">[30]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585527232.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code> 721 to use a name different from <code class="computeroutput"><span class="identifier">static_invariant</span></code> 722 (e.g., because <code class="computeroutput"><span class="identifier">static_invariant</span></code> 723 clashes with other names in user-defined classes). <a href="#ftn.boost_contract.tutorial.class_invariants.f4" class="footnote" name="boost_contract.tutorial.class_invariants.f4"><sup class="footnote">[31]</sup></a> 724 </p> 725</div> 726<div class="section"> 727<div class="titlepage"><div><div><h3 class="title"> 728<a name="boost_contract.tutorial.constructors"></a><a class="link" href="tutorial.html#boost_contract.tutorial.constructors" title="Constructors">Constructors</a> 729</h3></div></div></div> 730<p> 731 Contracts for constructors are programmed using the <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 732 function and the <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 733 base class. For example (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>): 734 </p> 735<p> 736</p> 737<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">unique_identifiers</span> <span class="special">:</span> 738 <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"><</span><span class="identifier">unique_identifiers</span><span class="special">></span> 739<span class="special">{</span> 740<span class="keyword">public</span><span class="special">:</span> 741 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 742 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 743 <span class="special">}</span> 744</pre> 745<p> 746 </p> 747<p> 748</p> 749<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 750 <span class="comment">// Contract for a constructor.</span> 751 <span class="identifier">unique_identifiers</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">from</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">to</span><span class="special">)</span> <span class="special">:</span> 752 <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"><</span><span class="identifier">unique_identifiers</span><span class="special">>([&]</span> <span class="special">{</span> 753 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">from</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 754 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">to</span> <span class="special">>=</span> <span class="identifier">from</span><span class="special">);</span> 755 <span class="special">})</span> 756 <span class="special">{</span> 757 <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">c</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">constructor</span><span class="special">(</span><span class="keyword">this</span><span class="special">)</span> 758 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 759 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">to</span> <span class="special">-</span> <span class="identifier">from</span> <span class="special">+</span> <span class="number">1</span><span class="special">));</span> 760 <span class="special">})</span> 761 <span class="special">;</span> 762 763 <span class="comment">// Constructor body.</span> 764 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">id</span> <span class="special">=</span> <span class="identifier">from</span><span class="special">;</span> <span class="identifier">id</span> <span class="special"><=</span> <span class="identifier">to</span><span class="special">;</span> <span class="special">++</span><span class="identifier">id</span><span class="special">)</span> <span class="identifier">vect_</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">id</span><span class="special">);</span> 765 <span class="special">}</span> 766</pre> 767<p> 768 </p> 769<p> 770</p> 771<pre class="programlisting"> <span class="comment">/* ... */</span> 772<span class="special">};</span> 773</pre> 774<p> 775 </p> 776<p> 777 It is not possible to specify preconditions using <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> 778 for constructors (this library will generate a compile-time error if <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> is used on the object returned by <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>). 779 Constructor preconditions are specified using the <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 780 base class instead (same considerations as the ones made in <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a> 781 apply also to the precondition functor passed to <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code>). 782 Programmes should not access the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> from constructor preconditions (because 783 the object does not exists yet before the constructor body is executed). 784 <a href="#ftn.boost_contract.tutorial.constructors.f0" class="footnote" name="boost_contract.tutorial.constructors.f0"><sup class="footnote">[32]</sup></a> Constructors without preconditions simply do not explicitly initialize 785 the <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 786 base (because <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 787 default constructor checks no contract). When the <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 788 base class is used: <a href="#ftn.boost_contract.tutorial.constructors.f1" class="footnote" name="boost_contract.tutorial.constructors.f1"><sup class="footnote">[33]</sup></a> 789 </p> 790<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 791<li class="listitem"> 792 It should be specified as the <span class="emphasis"><em>first</em></span> class in the 793 inheritance list (so constructor preconditions are checked before initializing 794 any other base class or data member). 795 </li> 796<li class="listitem"> 797 Its inheritance access specifier should always be <code class="computeroutput"><span class="keyword">private</span></code> 798 (so this extra base class does not alter the public inheritance tree 799 of its derived classes). 800 </li> 801<li class="listitem"> 802 It should never be declared as a <code class="computeroutput"><span class="keyword">virtual</span></code> 803 base (because virtual bases are initialized only once across the entire 804 inheritance hierarchy preventing preconditions of other base classes 805 from being checked). 806 </li> 807<li class="listitem"> 808 It takes the derived class as template parameter. <a href="#ftn.boost_contract.tutorial.constructors.f2" class="footnote" name="boost_contract.tutorial.constructors.f2"><sup class="footnote">[34]</sup></a> 809 </li> 810</ul></div> 811<div class="note"><table border="0" summary="Note"> 812<tr> 813<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 814<th align="left">Note</th> 815</tr> 816<tr><td align="left" valign="top"><p> 817 A class can avoid inheriting from <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 818 for efficiency but only when all its constructors have no preconditions. 819 </p></td></tr> 820</table></div> 821<p> 822 It is possible to specify postconditions for constructors (see <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>), 823 but programmers should not access the old value of the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> in constructor 824 postconditions (because the object did not exist yet before the constructor 825 body was executed). <a href="#ftn.boost_contract.tutorial.constructors.f3" class="footnote" name="boost_contract.tutorial.constructors.f3"><sup class="footnote">[35]</sup></a> It is also possible to specify exceptions guarantees for constructors 826 (see <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 827 Guarantees</a>), but programmers should not access the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> or its 828 old value in constructor exception guarantees (because the object did not 829 exist before executing the constructor body and it was not properly constructed 830 given the constructor body threw an exception). <a href="#ftn.boost_contract.tutorial.constructors.f4" class="footnote" name="boost_contract.tutorial.constructors.f4"><sup class="footnote">[36]</sup></a> The <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 831 function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter 832 (because constructors check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 833 Invariants</a>). 834 </p> 835<p> 836 The <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 837 function returns an RAII object that must always be assigned to a local variable 838 of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 839 (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585506528.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>). 840 Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations 841 cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 842 type must be explicitly specified (otherwise this library will generate a 843 compile-time error prior C++17 and a run-time error post C++17). The constructor 844 body is programmed right after the declaration of this RAII object. 845 </p> 846<p> 847 At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 848 RAII object for constructors does the following (enclosing constructor entry): 849 </p> 850<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> 851 Check static class invariants, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> (but not non-static class invariants 852 because the object does not exist yet). 853 </li></ol></div> 854<p> 855 At destruction instead (enclosing constructor exit): 856 </p> 857<div class="orderedlist"><ol class="orderedlist" type="1"> 858<li class="listitem"> 859 Check static class invariants, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code>. 860 </li> 861<li class="listitem"> 862 If the constructor body did not throw an exception: 863 <div class="orderedlist"><ol class="orderedlist" type="a"> 864<li class="listitem"> 865 Check non-static class invariants, by calling <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code>. 866 </li> 867<li class="listitem"> 868 Check postconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 869 </li> 870</ol></div> 871 </li> 872<li class="listitem"> 873 Else: 874 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 875 Check exception guarantees, by calling the nullary functor <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 876 </li></ol></div> 877 </li> 878</ol></div> 879<p> 880 This together with C++ object construction mechanism of base classes and 881 the use of <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 882 ensures that the constructor contracts are correctly checked at run-time 883 (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constructor_calls" title="Constructor Calls">Constructor 884 Calls</a>). 885 </p> 886<div class="note"><table border="0" summary="Note"> 887<tr> 888<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 889<th align="left">Note</th> 890</tr> 891<tr><td align="left" valign="top"> 892<p> 893 A constructor can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 894 for efficiency but only when it has no postconditions, no exception guarantees, 895 and its class has no invariants (even if <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 896 is not used by a derived class, contracts of base class constructors will 897 still be correctly checked by C++ object construction mechanism). 898 </p> 899<p> 900 The default constructor and copy constructor automatically generated by 901 C++ will not check contracts. Therefore, unless these constructors are 902 not public or they have no preconditions, no postconditions, no exception 903 guarantees, and their class has no invariants, programmers should manually 904 define them using <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 905 and <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code>. 906 Similar considerations apply to all other constructors automatically generated 907 by C++ (e.g., the move constructor). 908 </p> 909</td></tr> 910</table></div> 911<h5> 912<a name="boost_contract.tutorial.constructors.h0"></a> 913 <span class="phrase"><a name="boost_contract.tutorial.constructors.private_and_protected_constructors"></a></span><a class="link" href="tutorial.html#boost_contract.tutorial.constructors.private_and_protected_constructors">Private 914 and Protected Constructors</a> 915 </h5> 916<p> 917 Private and protected constructors can omit <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code> 918 (because they are not part of the public interface of the class so they are 919 not required to check class invariants, see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constructor_calls" title="Constructor Calls">Constructor 920 Calls</a>). They could still use <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 921 to check preconditions before member initializations, and even use <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 922 (but not <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>) 923 to only check postconditions and exception guarantees without checking class 924 invariants and without calling <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> 925 (see <a class="link" href="advanced.html#boost_contract.advanced.private_and_protected_functions" title="Private and Protected Functions">Private 926 and Protected Functions</a>). For example: 927 </p> 928<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">:</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"><</span><span class="identifier">u</span><span class="special">></span> <span class="special">{</span> 929<span class="keyword">protected</span><span class="special">:</span> 930 <span class="comment">// Contract for a protected constructor (same for private constructors).</span> 931 <span class="identifier">u</span><span class="special">()</span> <span class="special">:</span> <span class="comment">// Still use this base class to check constructor preconditions.</span> 932 <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"><</span><span class="identifier">u</span><span class="special">>([&]</span> <span class="special">{</span> 933 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> 934 <span class="special">...</span> 935 <span class="special">})</span> 936 <span class="special">{</span> 937 <span class="comment">// Following will correctly not check class invariants.</span> 938 <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">c</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">function</span><span class="special">()</span> 939 <span class="comment">// Do not use `.precondition(...)` here.</span> 940 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 941 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> 942 <span class="special">...</span> 943 <span class="special">})</span> 944 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> 945 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> 946 <span class="special">...</span> 947 <span class="special">})</span> 948 <span class="special">;</span> 949 950 <span class="special">...</span> <span class="comment">// Constructor body.</span> 951 <span class="special">}</span> 952 953 <span class="special">...</span> 954<span class="special">};</span> 955</pre> 956</div> 957<div class="section"> 958<div class="titlepage"><div><div><h3 class="title"> 959<a name="boost_contract.tutorial.destructors"></a><a class="link" href="tutorial.html#boost_contract.tutorial.destructors" title="Destructors">Destructors</a> 960</h3></div></div></div> 961<p> 962 Contracts for destructors are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>. 963 For example (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>): 964 </p> 965<p> 966</p> 967<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">unique_identifiers</span> <span class="special">:</span> 968 <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"><</span><span class="identifier">unique_identifiers</span><span class="special">></span> 969<span class="special">{</span> 970<span class="keyword">public</span><span class="special">:</span> 971 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 972 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 973 <span class="special">}</span> 974</pre> 975<p> 976 </p> 977<p> 978</p> 979<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 980 <span class="comment">// Contract for a destructor.</span> 981 <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">unique_identifiers</span><span class="special">()</span> <span class="special">{</span> 982 <span class="comment">// Following contract checks class invariants.</span> 983 <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">c</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">destructor</span><span class="special">(</span><span class="keyword">this</span><span class="special">);</span> 984 985 <span class="comment">// Destructor body here... (do nothing in this example).</span> 986 <span class="special">}</span> 987</pre> 988<p> 989 </p> 990<p> 991</p> 992<pre class="programlisting"> <span class="comment">/* ... */</span> 993<span class="special">};</span> 994</pre> 995<p> 996 </p> 997<p> 998 It is not possible to specify preconditions for destructors (this library 999 will generate a compile-time error if <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> 1000 is used here and that is because destructors can be called at any time after 1001 construction so they have no precondition). It is possible to specify postconditions 1002 for destructors (see <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>, 1003 and also <a class="link" href="tutorial.html#boost_contract.tutorial.static_public_functions" title="Static Public Functions">Static 1004 Public Functions</a> for an example), but programmers should not access 1005 the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> 1006 in destructor postconditions (because the object no longer exists after the 1007 destructor body has been executed). <a href="#ftn.boost_contract.tutorial.destructors.f0" class="footnote" name="boost_contract.tutorial.destructors.f0"><sup class="footnote">[37]</sup></a> It is also possible to specify exceptions guarantees for destructors 1008 (see <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 1009 Guarantees</a>, even if destructors should usually be programmed to not 1010 throw exceptions in C++, in fact destructors are implicitly declared <code class="computeroutput"><span class="keyword">noexcept</span></code> since C++11). <a href="#ftn.boost_contract.tutorial.destructors.f1" class="footnote" name="boost_contract.tutorial.destructors.f1"><sup class="footnote">[38]</sup></a> The <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code> 1011 function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter 1012 (because destructors check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 1013 Invariants</a>). 1014 </p> 1015<p> 1016 The <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code> 1017 function returns an RAII object that must always be assigned to a local variable 1018 of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1019 (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585506528.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>). 1020 Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations 1021 cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1022 type must be explicitly specified (otherwise this library will generate a 1023 compile-time error prior C++17 and a run-time error post C++17). The destructor 1024 body is programmed right after the declaration of this RAII object. 1025 </p> 1026<p> 1027 At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1028 RAII object for destructors does the following (enclosing destructor entry): 1029 </p> 1030<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> 1031 Check static and non-static class invariants, by calling <span class="emphasis"><em><code class="literal">type-of</code></em></span><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1032 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code>. 1033 </li></ol></div> 1034<p> 1035 At destruction instead (enclosing destructor exit): 1036 </p> 1037<div class="orderedlist"><ol class="orderedlist" type="1"> 1038<li class="listitem"> 1039 Check static class invariants, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code>. 1040 </li> 1041<li class="listitem"> 1042 If the destructor body did not throw an exception: 1043 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1044 Check postconditions, by calling the nullay functor <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1045 </li></ol></div> 1046 </li> 1047<li class="listitem"> 1048 Else (even if destructors should generally be programmed not to throw 1049 in C++): 1050 <div class="orderedlist"><ol class="orderedlist" type="a"> 1051<li class="listitem"> 1052 Check non-static class invariants, by calling <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code> (because the object was not successfully 1053 destructed). 1054 </li> 1055<li class="listitem"> 1056 Check exception guarantees, by calling the nullary functor <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1057 </li> 1058</ol></div> 1059 </li> 1060</ol></div> 1061<p> 1062 This together with C++ object destruction mechanism of base classes ensures 1063 that destructor contracts are correctly checked at run-time (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.destructor_calls" title="Destructor Calls">Destructor 1064 Calls</a>). 1065 </p> 1066<div class="note"><table border="0" summary="Note"> 1067<tr> 1068<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1069<th align="left">Note</th> 1070</tr> 1071<tr><td align="left" valign="top"> 1072<p> 1073 A destructor can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code> 1074 for efficiency but only when it has no postconditions, no exception guarantees, 1075 and its class has no invariants (even if <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code> 1076 is not used by a derived class, contracts of base class destructors will 1077 still be correctly checked by C++ object destruction mechanism). 1078 </p> 1079<p> 1080 The default destructor automatically generated by C++ will not check contracts. 1081 Therefore, unless the destructor is not public or it has no postconditions, 1082 no exception guarantees, and its class has no invariants, programmers should 1083 manually define it using <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>. 1084 </p> 1085</td></tr> 1086</table></div> 1087<h5> 1088<a name="boost_contract.tutorial.destructors.h0"></a> 1089 <span class="phrase"><a name="boost_contract.tutorial.destructors.private_and_protected_destructors"></a></span><a class="link" href="tutorial.html#boost_contract.tutorial.destructors.private_and_protected_destructors">Private 1090 and Protected Destructors</a> 1091 </h5> 1092<p> 1093 Private and protected destructors can omit <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code> 1094 (because they are not part of the public interface of the class so they are 1095 not required to check class invariants, see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.destructor_calls" title="Destructor Calls">Destructor 1096 Calls</a>). They could use <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 1097 (but not <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>) 1098 to only check postconditions and exception guarantees without checking class 1099 invariants and without calling <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> 1100 (see <a class="link" href="advanced.html#boost_contract.advanced.private_and_protected_functions" title="Private and Protected Functions">Private 1101 and Protected Functions</a>). For example: 1102 </p> 1103<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 1104<span class="keyword">protected</span><span class="special">:</span> 1105 <span class="comment">// Contract for a protected destructor (same for private destructors).</span> 1106 <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">u</span><span class="special">()</span> <span class="special">{</span> 1107 <span class="comment">// Following will correctly not check class invariants.</span> 1108 <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">c</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">function</span><span class="special">()</span> 1109 <span class="comment">// Do not use `.precondition(...)` here.</span> 1110 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 1111 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(...);</span> 1112 <span class="special">...</span> 1113 <span class="special">})</span> 1114 <span class="comment">// Could use `.except(...)` here in rare cases of destructors declared to throw.</span> 1115 <span class="special">;</span> 1116 1117 <span class="special">...</span> <span class="comment">// Destructor body.</span> 1118 <span class="special">}</span> 1119 1120 <span class="special">...</span> 1121<span class="special">};</span> 1122</pre> 1123</div> 1124<div class="section"> 1125<div class="titlepage"><div><div><h3 class="title"> 1126<a name="boost_contract.tutorial.public_functions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.public_functions" title="Public Functions">Public Functions</a> 1127</h3></div></div></div> 1128<p> 1129 Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1130 In this section, let's consider public functions that are not static, not 1131 virtual, and do not override any function from base classes. For example 1132 (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>): 1133 </p> 1134<p> 1135</p> 1136<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">unique_identifiers</span> <span class="special">:</span> 1137 <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"><</span><span class="identifier">unique_identifiers</span><span class="special">></span> 1138<span class="special">{</span> 1139<span class="keyword">public</span><span class="special">:</span> 1140 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 1141 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 1142 <span class="special">}</span> 1143</pre> 1144<p> 1145 </p> 1146<p> 1147</p> 1148<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 1149 <span class="comment">// Contract for a public function (but no static, virtual, or override).</span> 1150 <span class="keyword">bool</span> <span class="identifier">find</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">id</span><span class="special">)</span> <span class="keyword">const</span> <span class="special">{</span> 1151 <span class="keyword">bool</span> <span class="identifier">result</span><span class="special">;</span> 1152 <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">c</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">public_function</span><span class="special">(</span><span class="keyword">this</span><span class="special">)</span> 1153 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 1154 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">id</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 1155 <span class="special">})</span> 1156 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 1157 <span class="keyword">if</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(!</span><span class="identifier">result</span><span class="special">);</span> 1158 <span class="special">})</span> 1159 <span class="special">;</span> 1160 1161 <span class="comment">// Function body.</span> 1162 <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">vect_</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">vect_</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">id</span><span class="special">)</span> <span class="special">!=</span> 1163 <span class="identifier">vect_</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> 1164 <span class="special">}</span> 1165</pre> 1166<p> 1167 </p> 1168<p> 1169</p> 1170<pre class="programlisting"> <span class="comment">/* ... */</span> 1171<span class="special">};</span> 1172</pre> 1173<p> 1174 </p> 1175<p> 1176 It is possible to specify preconditions, postconditions, and exception guarantees 1177 for public functions (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>, 1178 <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>, 1179 and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 1180 Guarantees</a>). When called from non-static public functions, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1181 function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter 1182 (because public functions check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 1183 Invariants</a>). 1184 </p> 1185<p> 1186 The <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1187 function returns an RAII object that must always be assigned to a local variable 1188 of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1189 (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585506528.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>). 1190 Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations 1191 cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1192 type must be explicitly specified (otherwise this library will generate a 1193 compile-time error prior C++17 and a run-time error post C++17). The public 1194 function body is programmed right after the declaration of this RAII object. 1195 </p> 1196<p> 1197 At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1198 RAII object for public functions does the following (enclosing public function 1199 entry): 1200 </p> 1201<div class="orderedlist"><ol class="orderedlist" type="1"> 1202<li class="listitem"> 1203 Check static and non-static class invariants, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1204 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code>. 1205 </li> 1206<li class="listitem"> 1207 Check preconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1208 </li> 1209</ol></div> 1210<p> 1211 At destruction instead (enclosing public function exit): 1212 </p> 1213<div class="orderedlist"><ol class="orderedlist" type="1"> 1214<li class="listitem"> 1215 Check static and non-static class invariants, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1216 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code> 1217 (even if the function body threw an exception). 1218 </li> 1219<li class="listitem"> 1220 If the function body did not throw an exception: 1221 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1222 Check postconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1223 </li></ol></div> 1224 </li> 1225<li class="listitem"> 1226 Else: 1227 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1228 Check exception guarantees, by calling the nullary functor <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1229 </li></ol></div> 1230 </li> 1231</ol></div> 1232<p> 1233 This ensures that public function contracts are correctly checked at run-time 1234 (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public 1235 Function Calls</a>). 1236 </p> 1237<div class="note"><table border="0" summary="Note"> 1238<tr> 1239<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1240<th align="left">Note</th> 1241</tr> 1242<tr><td align="left" valign="top"> 1243<p> 1244 A public function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1245 for efficiency but only when it has no preconditions, no postconditions, 1246 no exception guarantees, it is not virtual, it does not override any virtual 1247 function, and its class has no invariants. 1248 </p> 1249<p> 1250 The default copy assignment operator automatically generated by C++ will 1251 not check contracts. Therefore, unless this operator is not public or it 1252 has no preconditions, no postconditions, no exception guarantees, and its 1253 class has no invariants, programmers should manually define it using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1254 Similar considerations apply to all other operators automatically generated 1255 by C++ (e.g., the move operator). 1256 </p> 1257</td></tr> 1258</table></div> 1259</div> 1260<div class="section"> 1261<div class="titlepage"><div><div><h3 class="title"> 1262<a name="boost_contract.tutorial.virtual_public_functions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 1263 Public Functions</a> 1264</h3></div></div></div> 1265<p> 1266 Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1267 In this section, let's consider public functions that are virtual but that 1268 do not override any function from base classes. For example (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>): 1269 </p> 1270<p> 1271</p> 1272<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">unique_identifiers</span> <span class="special">:</span> 1273 <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"><</span><span class="identifier">unique_identifiers</span><span class="special">></span> 1274<span class="special">{</span> 1275<span class="keyword">public</span><span class="special">:</span> 1276 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 1277 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 1278 <span class="special">}</span> 1279</pre> 1280<p> 1281 </p> 1282<p> 1283</p> 1284<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 1285 <span class="comment">// Contract for a public virtual function (but no override).</span> 1286 <span class="keyword">virtual</span> <span class="keyword">int</span> <span class="identifier">push_back</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">id</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> <span class="comment">// Extra `v`.</span> 1287 <span class="keyword">int</span> <span class="identifier">result</span><span class="special">;</span> 1288 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span> <span class="identifier">old_find</span> <span class="special">=</span> 1289 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> <span class="comment">// Pass `v`.</span> 1290 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">old_size</span> <span class="special">=</span> 1291 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">size</span><span class="special">());</span> <span class="comment">// Pass `v`.</span> 1292 <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">c</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">public_function</span><span class="special">(</span> 1293 <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> <span class="comment">// Pass `v` and `result`.</span> 1294 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 1295 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">id</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 1296 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(!</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> <span class="comment">// ID cannot be already present.</span> 1297 <span class="special">})</span> 1298 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> 1299 <span class="keyword">if</span><span class="special">(!*</span><span class="identifier">old_find</span><span class="special">)</span> <span class="special">{</span> 1300 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> 1301 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_size</span> <span class="special">+</span> <span class="number">1</span><span class="special">);</span> 1302 <span class="special">}</span> 1303 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">result</span> <span class="special">==</span> <span class="identifier">id</span><span class="special">);</span> 1304 <span class="special">})</span> 1305 <span class="special">;</span> 1306 1307 <span class="comment">// Function body.</span> 1308 <span class="identifier">vect_</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">id</span><span class="special">);</span> 1309 <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">id</span><span class="special">;</span> 1310 <span class="special">}</span> 1311</pre> 1312<p> 1313 </p> 1314<p> 1315</p> 1316<pre class="programlisting"> <span class="comment">/* ... */</span> 1317<span class="special">};</span> 1318</pre> 1319<p> 1320 </p> 1321<p> 1322 Virtual public functions must declare an extra trailing parameter of type 1323 <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> with default value <code class="computeroutput"><span class="number">0</span></code> 1324 (i.e., <code class="computeroutput"><span class="keyword">nullptr</span></code>). <a href="#ftn.boost_contract.tutorial.virtual_public_functions.f0" class="footnote" name="boost_contract.tutorial.virtual_public_functions.f0"><sup class="footnote">[39]</sup></a> This extra parameter is the last parameter and it has a default 1325 value so it does not alter the calling interface of the virtual function 1326 (callers will rarely, if ever, have to explicitly deal with this extra parameter 1327 a part from when manipulating the virtual function type directly for function 1328 pointer type-casting, etc.). Programmers must pass the extra virtual parameter 1329 as the very first argument to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1330 and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1331 calls in the virtual public function definition. <a href="#ftn.boost_contract.tutorial.virtual_public_functions.f1" class="footnote" name="boost_contract.tutorial.virtual_public_functions.f1"><sup class="footnote">[40]</sup></a> 1332 </p> 1333<p> 1334 When called from virtual public functions, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1335 function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter 1336 (because public functions check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 1337 Invariants</a>). For virtual public functions returning <code class="computeroutput"><span class="keyword">void</span></code>: 1338 </p> 1339<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 1340<span class="keyword">public</span><span class="special">:</span> 1341 <span class="comment">// A void virtual public function (that does not override).</span> 1342 <span class="keyword">virtual</span> <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="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> 1343 <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">c</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">public_function</span><span class="special">(</span> 1344 <span class="identifier">v</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> <span class="comment">// No result parameter...</span> 1345 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1346 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> <span class="comment">// ...so nullary functor.</span> 1347 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1348 <span class="special">;</span> 1349 1350 <span class="special">...</span> 1351 <span class="special">}</span> 1352 1353 <span class="special">...</span> 1354<span class="special">}</span> 1355</pre> 1356<p> 1357 For virtual public functions not returning <code class="computeroutput"><span class="keyword">void</span></code>, 1358 programmers must also pass a reference to the function return value as the 1359 second argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1360 In this case, the library will pass this return value reference to the postcondition 1361 functor that must therefore take one single argument matching the return 1362 type, otherwise this library will generate a compile-time error (the functor 1363 parameter can be a constant reference <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code> to avoid extra copies of the return 1364 value): <a href="#ftn.boost_contract.tutorial.virtual_public_functions.f2" class="footnote" name="boost_contract.tutorial.virtual_public_functions.f2"><sup class="footnote">[41]</sup></a> 1365 </p> 1366<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 1367<span class="keyword">public</span><span class="special">:</span> 1368 <span class="comment">// A void virtual public function (that does not override).</span> 1369 <span class="keyword">virtual</span> <span class="identifier">t</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="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> 1370 <span class="identifier">t</span> <span class="identifier">result</span><span class="special">;</span> 1371 <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">c</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">public_function</span><span class="special">(</span> 1372 <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> <span class="comment">// Result parameter...</span> 1373 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1374 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="identifier">t</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> <span class="comment">// ...so unary functor.</span> 1375 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1376 <span class="special">;</span> 1377 1378 <span class="special">...</span> <span class="comment">// Assign `result` at each return.</span> 1379 <span class="special">}</span> 1380 1381 <span class="special">...</span> 1382<span class="special">}</span> 1383</pre> 1384<div class="important"><table border="0" summary="Important"> 1385<tr> 1386<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 1387<th align="left">Important</th> 1388</tr> 1389<tr><td align="left" valign="top"> 1390<p> 1391 It is the responsibility of the programmers to pass the extra virtual parameter 1392 <code class="computeroutput"><span class="identifier">v</span></code> to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1393 and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1394 calls within virtual public functions, and also to pass the return value 1395 reference after <code class="computeroutput"><span class="identifier">v</span></code> to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1396 for non-void virtual public functions. This library cannot automatically 1397 generate compile-time errors if programmers fail to do so (but in general 1398 this will prevent the library from correctly checking contracts at run-time). 1399 <a href="#ftn.boost_contract.tutorial.virtual_public_functions.f3" class="footnote" name="boost_contract.tutorial.virtual_public_functions.f3"><sup class="footnote">[42]</sup></a> 1400 </p> 1401<p> 1402 <span class="bold"><strong>Mnemonics:</strong></span> 1403 </p> 1404<div class="blockquote"><blockquote class="blockquote"><p> 1405 When <code class="computeroutput"><span class="identifier">v</span></code> is present, always 1406 pass it as the first argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1407 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>. 1408 </p></blockquote></div> 1409<div class="blockquote"><blockquote class="blockquote"><p> 1410 Always pass <code class="computeroutput"><span class="identifier">result</span></code> to 1411 <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1412 right after <code class="computeroutput"><span class="identifier">v</span></code> for non-void 1413 functions. 1414 </p></blockquote></div> 1415</td></tr> 1416</table></div> 1417<p> 1418 For the rest, considerations made in <a class="link" href="tutorial.html#boost_contract.tutorial.public_functions" title="Public Functions">Public 1419 Functions</a> apply to virtual public functions as well. 1420 </p> 1421<div class="note"><table border="0" summary="Note"> 1422<tr> 1423<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1424<th align="left">Note</th> 1425</tr> 1426<tr><td align="left" valign="top"><p> 1427 A virtual public function should always call <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1428 (even if it has no preconditions, no postconditions, no exception guarantees, 1429 and its class has no invariants), otherwise this library will not be able 1430 to correctly use it for subcontracting. 1431 </p></td></tr> 1432</table></div> 1433</div> 1434<div class="section"> 1435<div class="titlepage"><div><div><h3 class="title"> 1436<a name="boost_contract.tutorial.public_function_overrides__subcontracting_"></a><a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 1437 Function Overrides (Subcontracting)</a> 1438</h3></div></div></div> 1439<p> 1440 Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1441 In this section, let's consider public functions (virtual or not) that override 1442 virtual public functions from one or more of their public base classes. For 1443 example (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>): 1444 <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f0" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f0"><sup class="footnote">[43]</sup></a> 1445 </p> 1446<p> 1447</p> 1448<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">identifiers</span> 1449 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">public</span> <span class="identifier">unique_identifiers</span> 1450 <span class="special">:</span> <span class="identifier">BASES</span> 1451<span class="special">{</span> 1452<span class="keyword">public</span><span class="special">:</span> 1453 <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> <span class="comment">// Bases typedef.</span> 1454 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> 1455 1456 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="comment">// Check in AND with bases.</span> 1457 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">empty</span><span class="special">()</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">));</span> 1458 <span class="special">}</span> 1459</pre> 1460<p> 1461 </p> 1462<p> 1463</p> 1464<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 1465 <span class="comment">// Contract for a public function override.</span> 1466 <span class="keyword">int</span> <span class="identifier">push_back</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">id</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="comment">/* override */</span> <span class="special">{</span> 1467 <span class="keyword">int</span> <span class="identifier">result</span><span class="special">;</span> 1468 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span> <span class="identifier">old_find</span> <span class="special">=</span> 1469 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> 1470 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">old_size</span> <span class="special">=</span> 1471 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">size</span><span class="special">());</span> 1472 <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">c</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">public_function</span><span class="special"><</span> 1473 <span class="identifier">override_push_back</span> <span class="comment">// Pass override type plus below function pointer...</span> 1474 <span class="special">>(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="special">&</span><span class="identifier">identifiers</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> <span class="identifier">id</span><span class="special">)</span> <span class="comment">// ...and arguments.</span> 1475 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Check in OR with bases.</span> 1476 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">id</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 1477 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> <span class="comment">// ID can be already present.</span> 1478 <span class="special">})</span> 1479 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// Check in AND with bases.</span> 1480 <span class="keyword">if</span><span class="special">(*</span><span class="identifier">old_find</span><span class="special">)</span> <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_size</span><span class="special">);</span> 1481 <span class="special">})</span> 1482 <span class="special">;</span> 1483 1484 <span class="comment">// Function body.</span> 1485 <span class="keyword">if</span><span class="special">(!</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">))</span> <span class="identifier">unique_identifiers</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">id</span><span class="special">);</span> <span class="comment">// Else, do nothing.</span> 1486 <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">id</span><span class="special">;</span> 1487 <span class="special">}</span> 1488 <span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">push_back</span><span class="special">)</span> <span class="comment">// Define `override_push_back`.</span> 1489</pre> 1490<p> 1491 </p> 1492<p> 1493</p> 1494<pre class="programlisting"> <span class="comment">/* ... */</span> 1495<span class="special">};</span> 1496</pre> 1497<p> 1498 </p> 1499<p> 1500 The extra <code class="computeroutput"><span class="keyword">typedef</span></code> declared using 1501 <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 1502 is required by this library for derived classes and it is internally used 1503 to detect base classes for subcontracting (see <a class="link" href="tutorial.html#boost_contract.tutorial.base_classes__subcontracting_" title="Base Classes (Subcontracting)">Base 1504 Classes</a>). This library will generate a compile-time error if there 1505 is no suitable virtual function to override in any of the public base classes 1506 for subcontracting. <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f1"><sup class="footnote">[44]</sup></a> 1507 </p> 1508<p> 1509 When called from public function overrides, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1510 function template takes an explicit template argument <code class="computeroutput"><span class="identifier">override_</span></code><code class="literal"><span class="emphasis"><em>function-name</em></span></code> 1511 that must be defined using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>: 1512 </p> 1513<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>function-name</em></span></code><span class="special">)</span> 1514</pre> 1515<p> 1516 This can be declared at any point in the public section of the enclosing 1517 class (see <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access 1518 Specifiers</a> to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1519 also in a non-public section of the class). <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1520 is used only once in a class for a given function name and overloaded functions 1521 can reuse the same <code class="literal">override_<span class="emphasis"><em>function-name</em></span></code> 1522 definition (see <a class="link" href="advanced.html#boost_contract.advanced.function_overloads" title="Function Overloads">Function 1523 Overloads</a>). <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 1524 can be used to generate a name different than <code class="literal">override_<span class="emphasis"><em>function-name</em></span></code> 1525 (e.g., to avoid generating C++ reserved names containing double underscores 1526 "<code class="computeroutput"><span class="identifier">__</span></code>" for function 1527 names that already start with an underscore "<code class="computeroutput"><span class="identifier">_</span></code>", 1528 see <a class="link" href="advanced.html#boost_contract.advanced.named_overrides" title="Named Overrides">Named Overrides</a>). 1529 For convenience <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDES.html" title="Macro BOOST_CONTRACT_OVERRIDES">BOOST_CONTRACT_OVERRIDES</a></code> 1530 can be used with multiple function names instead of repeating <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> for each 1531 function name (on compilers that support variadic macros). For example, for 1532 three functions named <code class="computeroutput"><span class="identifier">f</span></code>, 1533 <code class="computeroutput"><span class="identifier">g</span></code>, and <code class="computeroutput"><span class="identifier">h</span></code> 1534 (but same for any other number of functions), the following: 1535 </p> 1536<pre class="programlisting"><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> <span class="identifier">h</span><span class="special">)</span> 1537</pre> 1538<p> 1539 Is equivalent to: <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f2"><sup class="footnote">[45]</sup></a> 1540 </p> 1541<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span> 1542<span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">g</span><span class="special">)</span> 1543<span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span> 1544</pre> 1545<p> 1546 Public function overrides must always list the extra trailing parameter of 1547 type <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> with default value <code class="computeroutput"><span class="number">0</span></code> 1548 (i.e., <code class="computeroutput"><span class="keyword">nullptr</span></code>), even when they 1549 are not declared <code class="computeroutput"><span class="keyword">virtual</span></code>, if 1550 this parameter is present in the signature of the virtual function being 1551 overridden from base classes. Programmers must pass the extra virtual parameter 1552 as the very first argument to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1553 and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1554 calls in the public function override definition (see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 1555 Public Functions</a>). 1556 </p> 1557<p> 1558 When called from public function overrides, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1559 function takes a pointer to the enclosing function, the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> (because 1560 public function overrides check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 1561 Invariants</a>), and references to each function argument in the order 1562 they appear in the function declaration. <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f3" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f3"><sup class="footnote">[46]</sup></a> For public function overrides returning <code class="computeroutput"><span class="keyword">void</span></code>: 1563 </p> 1564<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 1565<span class="keyword">public</span><span class="special">:</span> 1566 <span class="comment">// A void public function override.</span> 1567 <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="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="comment">/* override */</span> <span class="special">{</span> 1568 <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">c</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">public_function</span><span class="special"><</span><span class="identifier">override_f</span><span class="special">>(</span> 1569 <span class="identifier">v</span><span class="special">,</span> <span class="special">&</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="identifier">a_n</span><span class="special">)</span> <span class="comment">// No result parameter...</span> 1570 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1571 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> <span class="comment">// ...so nullary functor.</span> 1572 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1573 <span class="special">;</span> 1574 1575 <span class="special">...</span> 1576 <span class="special">}</span> 1577 <span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span> 1578 1579 <span class="special">...</span> 1580<span class="special">}</span> 1581</pre> 1582<p> 1583 For public function overrides not returning <code class="computeroutput"><span class="keyword">void</span></code>, 1584 programmers must also pass a reference to the function return value as the 1585 second argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1586 (this library will generate a compile-time error otherwise). <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f4" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f4"><sup class="footnote">[47]</sup></a> In this case, the library will pass this return value reference 1587 to the postcondition functor that must therefore take one single argument 1588 matching the return type, otherwise this library will generate a compile-time 1589 error (the functor parameter can be a constant reference <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code> to avoid extra copies of the return 1590 value, similarly to non-overriding non-void <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 1591 Public Functions</a>): 1592 </p> 1593<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 1594<span class="keyword">public</span><span class="special">:</span> 1595 <span class="comment">// A non-void public function override.</span> 1596 <span class="identifier">t</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="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="comment">/* override */</span> <span class="special">{</span> 1597 <span class="identifier">t</span> <span class="identifier">result</span><span class="special">;</span> 1598 <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">c</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">public_function</span><span class="special"><</span><span class="identifier">override_f</span><span class="special">>(</span> 1599 <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="special">&</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="identifier">a_n</span><span class="special">)</span> <span class="comment">// Result parameter...</span> 1600 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1601 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="identifier">t</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> <span class="comment">// ...so unary functor.</span> 1602 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1603 <span class="special">;</span> 1604 1605 <span class="special">...</span> <span class="comment">// Assign `result` at each return.</span> 1606 <span class="special">}</span> 1607 <span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span> 1608 1609 <span class="special">...</span> 1610<span class="special">}</span> 1611</pre> 1612<p> 1613 This library will throw <code class="computeroutput"><a class="link" href="../boost/contract/bad_virtual_result_cast.html" title="Class bad_virtual_result_cast">boost::contract::bad_virtual_result_cast</a></code> 1614 if programmers specify return values for public function overrides in derived 1615 classes that are not consistent with the return types of the virtual public 1616 functions being overridden in the base classes. <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f5" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f5"><sup class="footnote">[48]</sup></a> 1617 </p> 1618<div class="important"><table border="0" summary="Important"> 1619<tr> 1620<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 1621<th align="left">Important</th> 1622</tr> 1623<tr><td align="left" valign="top"> 1624<p> 1625 It is the responsibility of the programmers to pass the extra virtual parameter 1626 <code class="computeroutput"><span class="identifier">v</span></code> to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1627 and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1628 calls within public function overrides, and also to pass the return value 1629 reference after <code class="computeroutput"><span class="identifier">v</span></code> to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1630 for non-void public function overrides. This library cannot always generate 1631 compile-time errors if programmers fail to do so (but in general this will 1632 prevent the library from correctly checking contracts at run-time). 1633 </p> 1634<p> 1635 <span class="bold"><strong>Mnemonics:</strong></span> 1636 </p> 1637<div class="blockquote"><blockquote class="blockquote"><p> 1638 When <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> 1639 is present, always pass it as template parameter to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1640 </p></blockquote></div> 1641<div class="blockquote"><blockquote class="blockquote"><p> 1642 When <code class="computeroutput"><span class="identifier">v</span></code> is present, always 1643 pass it as the first argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1644 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>. 1645 </p></blockquote></div> 1646<div class="blockquote"><blockquote class="blockquote"><p> 1647 Always pass <code class="computeroutput"><span class="identifier">result</span></code> to 1648 <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1649 right after <code class="computeroutput"><span class="identifier">v</span></code> for non-void 1650 functions. 1651 </p></blockquote></div> 1652</td></tr> 1653</table></div> 1654<p> 1655 At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1656 RAII object for public function overrides does the following (enclosing public 1657 function override entry): 1658 </p> 1659<div class="orderedlist"><ol class="orderedlist" type="1"> 1660<li class="listitem"> 1661 Check static and non-static class invariants for all overridden bases 1662 and for the derived class in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1663 with each other, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span>(<span class="emphasis"><em>overridden-base_1</em></span>)</code><code class="computeroutput"><span class="special">::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1664 <code class="literal"><span class="emphasis"><em>overridden-base_1</em></span></code><code class="computeroutput"><span class="special">.</span><span class="identifier">invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a>... 1665 <code class="literal"><span class="emphasis"><em>type-of</em></span>(<span class="emphasis"><em>overridden-base_n</em></span>)</code><code class="computeroutput"><span class="special">::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1666 <code class="literal"><span class="emphasis"><em>overridden-base_n</em></span></code><code class="computeroutput"><span class="special">.</span><span class="identifier">invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1667 <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> 1668 <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1669 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code>. 1670 </li> 1671<li class="listitem"> 1672 Check preconditions for all overridden base functions and for the overriding 1673 derived function in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 1674 with each other, by calling the nullary functors <code class="literal"><span class="emphasis"><em>r_1</em></span></code><code class="computeroutput"><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a>... 1675 <code class="literal"><span class="emphasis"><em>r_n</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1676 <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 1677 <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1678 passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r_1</em></span></code><code class="computeroutput"><span class="special">)</span></code>, ... <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r_n</em></span></code><code class="computeroutput"><span class="special">)</span></code>, <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">)</span></code> for all of the overridden and overriding 1679 functions respectively. 1680 </li> 1681</ol></div> 1682<p> 1683 At destruction instead (enclosing public function override exit): 1684 </p> 1685<div class="orderedlist"><ol class="orderedlist" type="1"> 1686<li class="listitem"> 1687 Check static and non-static class invariants for all overridden bases 1688 and for the derived class in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1689 with each other, by calling <code class="literal"><span class="emphasis"><em>type-of</em></span>(<span class="emphasis"><em>overridden-base_1</em></span>)</code><code class="computeroutput"><span class="special">::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1690 <code class="literal"><span class="emphasis"><em>overridden-base_1</em></span></code><code class="computeroutput"><span class="special">.</span><span class="identifier">invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a>... 1691 <code class="literal"><span class="emphasis"><em>type-of</em></span>(<span class="emphasis"><em>overridden-base_n</em></span>)</code><code class="computeroutput"><span class="special">::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1692 <code class="literal"><span class="emphasis"><em>overridden-base_n</em></span></code><code class="computeroutput"><span class="special">.</span><span class="identifier">invariant</span><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1693 <code class="literal"><span class="emphasis"><em>type-of</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> 1694 <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1695 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">invariant</span><span class="special">()</span></code> 1696 (even if the function body threw an exception). 1697 </li> 1698<li class="listitem"> 1699 If the function body did not throw an exception: 1700 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1701 Check postconditions for all overridden base functions and for 1702 the overriding derived function in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1703 with each other, by calling the nullary functors <code class="literal"><span class="emphasis"><em>s_1</em></span></code><code class="computeroutput"><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a>... 1704 <code class="literal"><span class="emphasis"><em>s_n</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1705 <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1706 <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1707 passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s_1</em></span></code><code class="computeroutput"><span class="special">)</span></code>, ... <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s_n</em></span></code><code class="computeroutput"><span class="special">)</span></code>, <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code> for all of the overridden and 1708 overriding functions respectively (or the unary functors <code class="literal"><span class="emphasis"><em>s_1</em></span></code><code class="computeroutput"><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result</em></span></code><code class="computeroutput"><span class="special">)</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a>... 1709 <code class="literal"><span class="emphasis"><em>s_n</em></span></code><code class="computeroutput"><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result</em></span></code><code class="computeroutput"><span class="special">)</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1710 <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result</em></span></code><code class="computeroutput"><span class="special">)</span></code> for non-void public function overrides). 1711 </li></ol></div> 1712 </li> 1713<li class="listitem"> 1714 Else: 1715 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1716 Check exception guarantees for all overridden base functions and 1717 for the overriding derived function in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1718 with each other, by calling the nullary functors <code class="literal"><span class="emphasis"><em>e_1</em></span></code><code class="computeroutput"><span class="special">()</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a>... 1719 <code class="literal"><span class="emphasis"><em>e_n</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1720 <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 1721 <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1722 passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e_1</em></span></code><code class="computeroutput"><span class="special">)</span></code>, ... <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e_n</em></span></code><code class="computeroutput"><span class="special">)</span></code>, <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code> for all of the overridden and 1723 overriding functions respectively. 1724 </li></ol></div> 1725 </li> 1726</ol></div> 1727<p> 1728 This ensures that contracts and subcontracts of public function overrides 1729 are correctly checked at run-time in accordance with the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 1730 principle</a> (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public 1731 Function Calls</a>). 1732 </p> 1733<p> 1734 For the rest, considerations made in <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 1735 Public Functions</a> apply to public function overrides as well. 1736 </p> 1737<div class="note"><table border="0" summary="Note"> 1738<tr> 1739<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1740<th align="left">Note</th> 1741</tr> 1742<tr><td align="left" valign="top"><p> 1743 A public function override should always call <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1744 (even if it has no preconditions, no postconditions, no exception guarantees, 1745 and its class has no invariants), otherwise this library will not be able 1746 to correctly use it for subcontracting. 1747 </p></td></tr> 1748</table></div> 1749</div> 1750<div class="section"> 1751<div class="titlepage"><div><div><h3 class="title"> 1752<a name="boost_contract.tutorial.base_classes__subcontracting_"></a><a class="link" href="tutorial.html#boost_contract.tutorial.base_classes__subcontracting_" title="Base Classes (Subcontracting)">Base 1753 Classes (Subcontracting)</a> 1754</h3></div></div></div> 1755<p> 1756 In order for this library to support subcontracting, programmers must specify 1757 the bases of a derived class declaring a public member type named <code class="computeroutput"><span class="identifier">base_types</span></code> via a <code class="computeroutput"><span class="keyword">typedef</span></code> 1758 using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>. 1759 For example (see <a href="../../../example/features/base_types.cpp" target="_top"><code class="literal">base_types.cpp</code></a>): 1760 </p> 1761<p> 1762</p> 1763<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">chars</span> 1764 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="comment">/* local macro (for convenience) */</span> <span class="special">\</span> 1765 <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"><</span><span class="identifier">chars</span><span class="special">>,</span> <span class="special">\</span> 1766 <span class="keyword">public</span> <span class="identifier">unique_chars</span><span class="special">,</span> <span class="special">\</span> 1767 <span class="keyword">public</span> <span class="keyword">virtual</span> <span class="identifier">pushable</span><span class="special"><</span><span class="keyword">char</span><span class="special">>,</span> <span class="special">\</span> 1768 <span class="keyword">virtual</span> <span class="keyword">protected</span> <span class="identifier">has_size</span><span class="special">,</span> <span class="special">\</span> 1769 <span class="keyword">private</span> <span class="identifier">has_empty</span> 1770 <span class="special">:</span> <span class="identifier">BASES</span> <span class="comment">// Bases of this class.</span> 1771<span class="special">{</span> 1772<span class="keyword">public</span><span class="special">:</span> 1773 <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> <span class="comment">// Bases typedef.</span> 1774 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> <span class="comment">// Undefine local macro.</span> 1775 1776 <span class="comment">/* ... */</span> 1777</pre> 1778<p> 1779 </p> 1780<p> 1781 For convenience, a <span class="emphasis"><em>local macro</em></span> named <code class="computeroutput"><span class="identifier">BASES</span></code> 1782 can be used to avoid repeating the base list twice (first in the derived 1783 class declaration <code class="computeroutput"><span class="keyword">class</span> </code><code class="literal"><span class="emphasis"><em>class-name</em></span></code><code class="computeroutput"> 1784 <span class="special">:</span> </code><code class="literal"><span class="emphasis"><em>base-list</em></span></code> 1785 and then again when invoking <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_BASE_TYPES</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>base-list</em></span></code><code class="computeroutput"><span class="special">)</span></code>). Being a local macro, <code class="computeroutput"><span class="identifier">BASES</span></code> 1786 must be undefined using <code class="computeroutput"><span class="preprocessor">#undef</span> 1787 <span class="identifier">BASES</span></code> after it is used to declare 1788 the <code class="computeroutput"><span class="identifier">base_types</span></code> <code class="computeroutput"><span class="keyword">typedef</span></code> (to avoid name clashes and macro redefinition 1789 errors). <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f0" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f0"><sup class="footnote">[49]</sup></a> 1790 </p> 1791<p> 1792 <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 1793 is a variadic macro and accepts a list of bases separated by commas (see 1794 <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 1795 Macros</a> to program <code class="computeroutput"><span class="identifier">base_types</span></code> 1796 without using macros). As already noted in <a class="link" href="tutorial.html#boost_contract.tutorial.constructors" title="Constructors">Constructors</a>, 1797 when the extra base <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 1798 is used to program constructor preconditions, its inheritance access level 1799 must always be <code class="computeroutput"><span class="keyword">private</span></code> and it 1800 must be specified as the very first base. 1801 </p> 1802<div class="important"><table border="0" summary="Important"> 1803<tr> 1804<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 1805<th align="left">Important</th> 1806</tr> 1807<tr><td align="left" valign="top"> 1808<p> 1809 Each base passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 1810 must <span class="emphasis"><em>explicitly</em></span> specify its inheritance access level 1811 <code class="computeroutput"><span class="keyword">public</span></code>, <code class="computeroutput"><span class="keyword">protected</span></code>, 1812 or <code class="computeroutput"><span class="keyword">private</span></code> (but <code class="computeroutput"><span class="keyword">virtual</span></code> is optional and can be specified 1813 either before or after the access level as usual in C++). This library 1814 will generate a compile-time error if the first base is missing its inheritance 1815 access level, but this library will not be able to always generate an error 1816 if the access level is missing for bases after the first one. <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f1" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f1"><sup class="footnote">[50]</sup></a> It is the responsibility of the programmers to make sure that 1817 all bases passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 1818 explicitly specify their inheritance access level (inheritance access levels 1819 are instead optional in C++ because <code class="computeroutput"><span class="keyword">private</span></code> 1820 is implicitly assumed for <code class="computeroutput"><span class="keyword">class</span></code> 1821 types and <code class="computeroutput"><span class="keyword">public</span></code> for <code class="computeroutput"><span class="keyword">struct</span></code> types). 1822 </p> 1823<p> 1824 <span class="bold"><strong>Mnemonics:</strong></span> 1825 </p> 1826<div class="blockquote"><blockquote class="blockquote"><p> 1827 Always explicitly specify the inheritance access level <code class="computeroutput"><span class="keyword">public</span></code>, <code class="computeroutput"><span class="keyword">protected</span></code>, 1828 or <code class="computeroutput"><span class="keyword">private</span></code> for base classes 1829 passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>. 1830 </p></blockquote></div> 1831</td></tr> 1832</table></div> 1833<p> 1834 See <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a> 1835 to avoid making the <code class="computeroutput"><span class="identifier">base_types</span></code> 1836 member type <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f2" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f2"><sup class="footnote">[51]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585544864.html" title="Macro BOOST_CONTRACT_BASES_TYPEDEF">BOOST_CONTRACT_BASES_TYPEDEF</a></code> 1837 to use a name different from <code class="computeroutput"><span class="identifier">base_types</span></code> 1838 (e.g., because <code class="computeroutput"><span class="identifier">base_types</span></code> 1839 clashes with other names in user-defined classes). 1840 </p> 1841</div> 1842<div class="section"> 1843<div class="titlepage"><div><div><h3 class="title"> 1844<a name="boost_contract.tutorial.static_public_functions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.static_public_functions" title="Static Public Functions">Static 1845 Public Functions</a> 1846</h3></div></div></div> 1847<p> 1848 Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>. 1849 In this section, let's consider static public functions. For example (see 1850 <a href="../../../example/features/static_public.cpp" target="_top"><code class="literal">static_public.cpp</code></a>): 1851 </p> 1852<p> 1853</p> 1854<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">></span> 1855<span class="keyword">class</span> <span class="identifier">make</span> <span class="special">{</span> 1856<span class="keyword">public</span><span class="special">:</span> 1857 <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">static_invariant</span><span class="special">()</span> <span class="special">{</span> <span class="comment">// Static class invariants.</span> 1858 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">instances</span><span class="special">()</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span> 1859 <span class="special">}</span> 1860 1861 <span class="comment">// Contract for a static public function.</span> 1862 <span class="keyword">static</span> <span class="keyword">int</span> <span class="identifier">instances</span><span class="special">()</span> <span class="special">{</span> 1863 <span class="comment">// Explicit template parameter `make` (check static invariants).</span> 1864 <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">c</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">public_function</span><span class="special"><</span><span class="identifier">make</span><span class="special">>();</span> 1865 1866 <span class="keyword">return</span> <span class="identifier">instances_</span><span class="special">;</span> <span class="comment">// Function body.</span> 1867 <span class="special">}</span> 1868 1869 <span class="comment">/* ... */</span> 1870</pre> 1871<p> 1872 </p> 1873<p> 1874 It is possible to specify preconditions, postconditions, and exception guarantees 1875 for static public functions (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>, 1876 <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>, 1877 and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 1878 Guarantees</a>). When called from static public functions, <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1879 cannot take the object <code class="computeroutput"><span class="keyword">this</span></code> 1880 as a parameter (because there is no object <code class="computeroutput"><span class="keyword">this</span></code> 1881 in static member functions) so the enclosing class type is specified via 1882 an explicit template parameter as in <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code><code class="literal"><<span class="emphasis"><em>class-type</em></span>></code> 1883 (the class type is required to check static class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 1884 Invariants</a>): 1885 </p> 1886<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> 1887<span class="keyword">public</span><span class="special">:</span> 1888 <span class="comment">// A static public function.</span> 1889 <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{</span> 1890 <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">c</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">public_function</span><span class="special"><</span><span class="identifier">u</span><span class="special">>()</span> <span class="comment">// Class type `u` as explicit template parameter.</span> 1891 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1892 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1893 <span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">})</span> 1894 <span class="special">;</span> 1895 1896 <span class="special">...</span> 1897 <span class="special">}</span> 1898 1899 <span class="special">...</span> 1900<span class="special">};</span> 1901</pre> 1902<p> 1903 The <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1904 function returns an RAII object that must be assigned to a local variable 1905 of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1906 (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585506528.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>). 1907 Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations 1908 cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1909 type must be explicitly specified (otherwise this library will generate a 1910 compile-time error prior C++17 and a run-time error post C++17). The static 1911 public functions body is programmed right after the declaration of this RAII 1912 object. 1913 </p> 1914<p> 1915 At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1916 RAII object for static public functions does the following (enclosing static 1917 public function entry): 1918 </p> 1919<div class="orderedlist"><ol class="orderedlist" type="1"> 1920<li class="listitem"> 1921 Check static class invariants, by calling <code class="literal"><span class="emphasis"><em>class-type</em></span></code><code class="computeroutput"><span class="special">::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> (but never non-static class invariants). 1922 </li> 1923<li class="listitem"> 1924 Check preconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1925 </li> 1926</ol></div> 1927<p> 1928 At destruction instead (enclosing static public function exit): 1929 </p> 1930<div class="orderedlist"><ol class="orderedlist" type="1"> 1931<li class="listitem"> 1932 Check static class invariants, by calling <code class="literal"><span class="emphasis"><em>class-type</em></span></code><code class="computeroutput"><span class="special">::</span><span class="identifier">static_invariant</span><span class="special">()</span></code> (even if the function body threw an 1933 exception, but never non-static class invariants). 1934 </li> 1935<li class="listitem"> 1936 If the function body did not throw an exception: 1937 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1938 Check postconditions, by calling the nullary functor <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1939 </li></ol></div> 1940 </li> 1941<li class="listitem"> 1942 Else: 1943 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 1944 Check exception guarantees, by calling the nullary functor <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1945 </li></ol></div> 1946 </li> 1947</ol></div> 1948<p> 1949 This ensures that static public function contracts are correctly checked 1950 at run-time (static public functions do not subcontract because they have 1951 no object <code class="computeroutput"><span class="keyword">this</span></code> and therefore 1952 there is no inheritance, see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public 1953 Function Calls</a>). 1954 </p> 1955<div class="note"><table border="0" summary="Note"> 1956<tr> 1957<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1958<th align="left">Note</th> 1959</tr> 1960<tr><td align="left" valign="top"><p> 1961 A static public function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 1962 for efficiency but only when it has no preconditions, no postconditions, 1963 no exception guarantees, and its class has no static invariants (the class 1964 can still have non-static invariants or base classes instead). 1965 </p></td></tr> 1966</table></div> 1967</div> 1968<div class="footnotes"> 1969<br><hr style="width:100; text-align:left;margin-left: 0"> 1970<div id="ftn.boost_contract.tutorial.non_member_functions.f0" class="footnote"><p><a href="#boost_contract.tutorial.non_member_functions.f0" class="para"><sup class="para">[19] </sup></a> 1971 The name of this local variable is arbitrary, but <code class="computeroutput"><span class="identifier">c</span></code> 1972 is often used in this documentation for <span class="quote">“<span class="quote">c</span>”</span>heck or <span class="quote">“<span class="quote">c</span>”</span>aminiti 1973 <code class="literal">;-)</code> . 1974 </p></div> 1975<div id="ftn.boost_contract.tutorial.non_member_functions.f1" class="footnote"><p><a href="#boost_contract.tutorial.non_member_functions.f1" class="para"><sup class="para">[20] </sup></a> 1976 <span class="bold"><strong>Rationale:</strong></span> C++17 guaranteed copy elision 1977 on function return value voids the trick this library uses to force a compile-time 1978 error when <code class="computeroutput"><span class="keyword">auto</span></code> is incorrectly 1979 used instead of <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>. 1980 The library still generates a run-time error in this case (also on C++17). 1981 In any case, after reading this documentation it should be evident to programmers 1982 that <code class="computeroutput"><span class="keyword">auto</span></code> should not be used 1983 in <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1984 declarations so this misuse of <code class="computeroutput"><span class="keyword">auto</span></code> 1985 should not be an issue in practice. 1986 </p></div> 1987<div id="ftn.boost_contract.tutorial.preconditions.f0" class="footnote"><p><a href="#boost_contract.tutorial.preconditions.f0" class="para"><sup class="para">[21] </sup></a> 1988 Lambda functions with no parameters can be programmed in C++11 as <code class="computeroutput"><span class="special">[...]</span> <span class="special">()</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span></code> 1989 but also equivalently as <code class="computeroutput"><span class="special">[...]</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span></code>. 1990 This second from is often used in this documentation omitting the empty 1991 parameter list <code class="computeroutput"><span class="special">()</span></code> for brevity. 1992 </p></div> 1993<div id="ftn.boost_contract.tutorial.preconditions.f1" class="footnote"><p><a href="#boost_contract.tutorial.preconditions.f1" class="para"><sup class="para">[22] </sup></a> 1994 In this documentation preconditions often capture variables by reference 1995 to avoid extra copies. 1996 </p></div> 1997<div id="ftn.boost_contract.tutorial.return_values.f0" class="footnote"><p><a href="#boost_contract.tutorial.return_values.f0" class="para"><sup class="para">[23] </sup></a> 1998 The name of the local variable that holds the return value is arbitrary, 1999 but <code class="computeroutput"><span class="identifier">result</span></code> is often used 2000 in this documentation. 2001 </p></div> 2002<div id="ftn.boost_contract.tutorial.old_values.f0" class="footnote"><p><a href="#boost_contract.tutorial.old_values.f0" class="para"><sup class="para">[24] </sup></a> 2003 The name of a local variable that holds an old value is arbitrary, but 2004 <code class="literal">old_<span class="emphasis"><em>variable-name</em></span></code> is often used 2005 in this documentation. 2006 </p></div> 2007<div id="ftn.boost_contract.tutorial.old_values.f1" class="footnote"><p><a href="#boost_contract.tutorial.old_values.f1" class="para"><sup class="para">[25] </sup></a> 2008 <span class="bold"><strong>Rationale:</strong></span> Old values have to be optional 2009 values because they need to be left uninitialized when they are not used 2010 because both postconditions and exception guarantees are disabled (defining 2011 <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585468496.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code> 2012 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code>). 2013 That is to avoid old value copies when old values are not used, either 2014 a pointer or (better) a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> 2015 could have been used to achieve that. In addition, old values need to be 2016 pointers internally allocated by this library so that they are never copied 2017 twice even when calling an overridden function multiple times to check 2018 preconditions, postconditions, etc. to implement subcontracting, so a smart 2019 pointer class template was used. 2020 </p></div> 2021<div id="ftn.boost_contract.tutorial.old_values.f2" class="footnote"><p><a href="#boost_contract.tutorial.old_values.f2" class="para"><sup class="para">[26] </sup></a> 2022 For example, old value pointers might be null in preconditions when postconditions 2023 and exception guarantees are disabled defining <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585468496.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code> 2024 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code> 2025 (but also when checking an overridden virtual public function contract 2026 via subcontracting, etc.). 2027 </p></div> 2028<div id="ftn.boost_contract.tutorial.class_invariants.f0" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f0" class="para"><sup class="para">[27] </sup></a> 2029 This library uses template meta-programming (SFINAE-based introspection 2030 techniques) to check invariants only for classes that declare a member 2031 function named by <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585536960.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>. 2032 </p></div> 2033<div id="ftn.boost_contract.tutorial.class_invariants.f1" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f1" class="para"><sup class="para">[28] </sup></a> 2034 In this documentation the <code class="computeroutput"><span class="identifier">invariant</span></code> 2035 member function is often declared <code class="computeroutput"><span class="keyword">public</span></code> 2036 for simplicity. However, in production code it might not be acceptable 2037 to augment the public members of a class adding the <code class="computeroutput"><span class="identifier">invariant</span></code> 2038 function (and that can be avoided using <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 2039 as explained in <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access 2040 Specifiers</a>). 2041 </p></div> 2042<div id="ftn.boost_contract.tutorial.class_invariants.f2" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f2" class="para"><sup class="para">[29] </sup></a> 2043 This library uses template meta-programming (SFINAE-based introspection 2044 techniques) to check static invariants only for classes that declare a 2045 member function named by <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585527232.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>. 2046 </p></div> 2047<div id="ftn.boost_contract.tutorial.class_invariants.f3" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f3" class="para"><sup class="para">[30] </sup></a> 2048 In this documentation the <code class="computeroutput"><span class="identifier">static_invariant</span></code> 2049 member function is often declared <code class="computeroutput"><span class="keyword">public</span></code> 2050 for simplicity. However, in production code it might not be acceptable 2051 to augment the public members of a class adding the <code class="computeroutput"><span class="identifier">static_invariant</span></code> 2052 function (and that can be avoided using <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 2053 as explained in <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access 2054 Specifiers</a>). 2055 </p></div> 2056<div id="ftn.boost_contract.tutorial.class_invariants.f4" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f4" class="para"><sup class="para">[31] </sup></a> 2057 <span class="bold"><strong>Rationale:</strong></span> In C++, it is not possible 2058 to overload a member function based on the <code class="computeroutput"><span class="keyword">static</span></code> 2059 classifier. Therefore, this library has to use different names for the 2060 member functions checking non-static and static class invariants (namely 2061 for <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585536960.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code> 2062 and for <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585527232.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>). 2063 </p></div> 2064<div id="ftn.boost_contract.tutorial.constructors.f0" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f0" class="para"><sup class="para">[32] </sup></a> 2065 See <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 2066 Lambda Functions</a> to enforce this constraint at compile-time (but 2067 not recommended because of extra boiler-plate code). 2068 </p></div> 2069<div id="ftn.boost_contract.tutorial.constructors.f1" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f1" class="para"><sup class="para">[33] </sup></a> 2070 There is a MSVC bug that was fixed in MSVC 2013 for which lambdas cannot 2071 be used in constructor member initialization lists for templates. On MSVC 2072 compilers with that bug, an extra (static) member function can be used 2073 (together with <code class="computeroutput"><span class="identifier">bind</span></code> and 2074 <code class="computeroutput"><span class="identifier">cref</span></code> as needed) to program 2075 constructor preconditions instead of using lambdas (see <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 2076 Lambda Functions</a>). 2077 </p></div> 2078<div id="ftn.boost_contract.tutorial.constructors.f2" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f2" class="para"><sup class="para">[34] </sup></a> 2079 <span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 2080 takes the derived class as its template parameter (using the Curiously 2081 Recursive Template Pattern, CRTP) so the instantiated template type 2082 is unique for each derived class. This always avoids base class ambiguity 2083 resolution errors even when multiple inheritance is used. Note that, 2084 as already mentioned, virtual inheritance could not be used instead 2085 of the template parameter here to resolve ambiguities (because virtual 2086 bases are initialized only once by the outer-most derived class, and 2087 that would not allow to properly check preconditions of all base classes). 2088 </p></div> 2089<div id="ftn.boost_contract.tutorial.constructors.f3" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f3" class="para"><sup class="para">[35] </sup></a> 2090 See <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 2091 Lambda Functions</a> to enforce this constraint at compile-time (but 2092 not recommended because of extra boiler-plate code). 2093 </p></div> 2094<div id="ftn.boost_contract.tutorial.constructors.f4" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f4" class="para"><sup class="para">[36] </sup></a> 2095 See <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 2096 Lambda Functions</a> to enforce these constraints at compile-time (but 2097 not recommended because of extra boiler-plate code). 2098 </p></div> 2099<div id="ftn.boost_contract.tutorial.destructors.f0" class="footnote"><p><a href="#boost_contract.tutorial.destructors.f0" class="para"><sup class="para">[37] </sup></a> 2100 See <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 2101 Lambda Functions</a> to enforce this constraint at compile-time (but 2102 not recommended because of extra boiler-plate code). 2103 </p></div> 2104<div id="ftn.boost_contract.tutorial.destructors.f1" class="footnote"><p><a href="#boost_contract.tutorial.destructors.f1" class="para"><sup class="para">[38] </sup></a> 2105 Exceptions guarantees in destructors can access both the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> and 2106 its old value because the object existed before executing the destructor 2107 body and it still exists given the destructor body failed throwing an exception 2108 so technically the object should still be properly constructed and satisfy 2109 its class invariants. 2110 </p></div> 2111<div id="ftn.boost_contract.tutorial.virtual_public_functions.f0" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f0" class="para"><sup class="para">[39] </sup></a> 2112 The name of this extra parameter is arbitrary, but <code class="computeroutput"><span class="identifier">v</span></code> 2113 is often used in this documentation. 2114 </p></div> 2115<div id="ftn.boost_contract.tutorial.virtual_public_functions.f1" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f1" class="para"><sup class="para">[40] </sup></a> 2116 <span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> parameter is used by this library to determine 2117 that a function is virtual (in C++ it is not possible to introspect if 2118 a function is declared <code class="computeroutput"><span class="keyword">virtual</span></code>). 2119 Furthermore, this parameter is internally used by this library to implement 2120 subcontracting (specifically to pass result and old values that are evaluated 2121 by the overriding function to the contracts of overridden virtual functions 2122 in base classes, and also to check preconditions, postconditions, and exception 2123 guarantees of overridden virtual functions in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 2124 and <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 2125 with contracts of the overriding virtual function). 2126 </p></div> 2127<div id="ftn.boost_contract.tutorial.virtual_public_functions.f2" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f2" class="para"><sup class="para">[41] </sup></a> 2128 <span class="bold"><strong>Rationale:</strong></span> The extra function result parameter 2129 taken by the functor passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code> 2130 is used by this library to pass the return value evaluated by the overriding 2131 function to all its overridden virtual functions to support subcontracting. 2132 </p></div> 2133<div id="ftn.boost_contract.tutorial.virtual_public_functions.f3" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f3" class="para"><sup class="para">[42] </sup></a> 2134 <span class="bold"><strong>Rationale:</strong></span> This library does not require 2135 programmers to specify the function type when using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 2136 for non-overriding virtual public functions. Therefore, this library 2137 does not know if the enclosing function has a non-void return type so 2138 it cannot check if the return value reference is passed as required for 2139 non-overriding virtual public functions. Instead the function type is 2140 passed to this library for virtual public function overrides and that 2141 also allows this library to give a compile-time error if the return value 2142 reference is missing in those cases. 2143 </p></div> 2144<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f0" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f0" class="para"><sup class="para">[43] </sup></a> 2145 In this documentation, function overrides are often marked with the code 2146 comment <code class="computeroutput"><span class="comment">/* override */</span></code>. On 2147 compilers that support C++11 virtual specifiers, the <code class="computeroutput"><span class="identifier">override</span></code> 2148 identifier can be used instead (<code class="computeroutput"><span class="identifier">override</span></code> 2149 is not used in the documentation simply because virtual specifiers are 2150 not widely supported yet, even by compilers that support C++11 lambda functions). 2151 </p></div> 2152<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="para"><sup class="para">[44] </sup></a> 2153 The compile-time error generated by the library in this case is similar 2154 in principle to the error generated by the C++11 <code class="computeroutput"><span class="identifier">override</span></code> 2155 specifier, but it is limited to functions with the extra <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> parameter and searched recursively only 2156 in <code class="computeroutput"><span class="keyword">public</span></code> base classes passed 2157 to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 2158 because only those are considered for subcontracting. 2159 </p></div> 2160<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="para"><sup class="para">[45] </sup></a> 2161 There is no equivalent of <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 2162 that operates on multiple function names at once (<code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 2163 is not expected to be used often so it can simply be repeated multiple 2164 times when needed). 2165 </p></div> 2166<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f3" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f3" class="para"><sup class="para">[46] </sup></a> 2167 <span class="bold"><strong>Rationale:</strong></span> The object <code class="computeroutput"><span class="keyword">this</span></code> 2168 is passed after the function pointer to follow <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind</span></code>'s 2169 syntax. The function pointer and references to all function arguments are 2170 needed for public function overrides because this library has to internally 2171 call overridden virtual public functions to check their contracts for subcontracting 2172 (even if this library will not actually execute the bodies of the overridden 2173 functions). 2174 </p></div> 2175<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f4" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f4" class="para"><sup class="para">[47] </sup></a> 2176 <span class="bold"><strong>Rationale:</strong></span> As for non-overriding virtual 2177 public functions, also public function overrides use the extra return value 2178 parameter to pass it to the overridden functions when subcontracting. In 2179 the case of public function overrides, this library has the function pointer 2180 so it will generate a compile-time error if the function is non-void and 2181 programmers forget to specify the extra return value parameter (this extra 2182 error checking is not possible instead for non-overriding virtual public 2183 functions because their contracts do not take the function pointer as a 2184 parameter, see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 2185 Public Functions</a>). 2186 </p></div> 2187<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f5" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f5" class="para"><sup class="para">[48] </sup></a> 2188 <span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bad_any_cast</span></code> 2189 exception was not used here because it does not print the from- and to- 2190 type names (so it is not descriptive enough). 2191 </p></div> 2192<div id="ftn.boost_contract.tutorial.base_classes__subcontracting_.f0" class="footnote"><p><a href="#boost_contract.tutorial.base_classes__subcontracting_.f0" class="para"><sup class="para">[49] </sup></a> 2193 The name of this local macro is arbitrary, but <code class="computeroutput"><span class="identifier">BASES</span></code> 2194 is often used in this documentation. 2195 </p></div> 2196<div id="ftn.boost_contract.tutorial.base_classes__subcontracting_.f1" class="footnote"><p><a href="#boost_contract.tutorial.base_classes__subcontracting_.f1" class="para"><sup class="para">[50] </sup></a> 2197 <span class="bold"><strong>Rationale:</strong></span> This library explicitly requires 2198 the inheritance access level because derived classes must subcontract 2199 only from public bases, but not from protected or private bases (see 2200 <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public 2201 Function Calls</a>). <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 2202 inspects each inheritance access level using preprocessor meta-programming 2203 and removes non-public bases from the list of bases internally used for 2204 subcontracting. However, this library cannot always detect when programmers 2205 forget to specify the inheritance access level because, when commas are 2206 used to separate template parameters passed to base classes, the preprocessor 2207 will not be able to correctly use commas to identify the next base class 2208 token in the inheritance list (the preprocessor cannot distinguish between 2209 commas that are not protected by round parenthesis, like the ones used 2210 in templates). Therefore, this library uses the inheritance access level 2211 keyword <code class="computeroutput"><span class="keyword">public</span></code>, <code class="computeroutput"><span class="keyword">protected</span></code>, or <code class="computeroutput"><span class="keyword">private</span></code> 2212 instead of commas <code class="computeroutput"><span class="special">,</span></code> for 2213 the preprocessor to correctly find the next base class token in the inheritance 2214 list (thus inheritance access levels must always be explicit specified 2215 by programmers for each base). 2216 </p></div> 2217<div id="ftn.boost_contract.tutorial.base_classes__subcontracting_.f2" class="footnote"><p><a href="#boost_contract.tutorial.base_classes__subcontracting_.f2" class="para"><sup class="para">[51] </sup></a> 2218 In this documentation the <code class="computeroutput"><span class="identifier">base_type</span></code> 2219 member type is often declared <code class="computeroutput"><span class="keyword">public</span></code> 2220 for simplicity. However, in production code it might not be acceptable 2221 to augment the public members of a class adding the <code class="computeroutput"><span class="identifier">base_types</span></code> 2222 type (and that can be avoided using <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 2223 as explained in <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access 2224 Specifiers</a>). 2225 </p></div> 2226</div> 2227</div> 2228<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 2229<td align="left"></td> 2230<td align="right"><div class="copyright-footer">Copyright © 2008-2019 Lorenzo Caminiti<p> 2231 Distributed under the Boost Software License, Version 1.0 (see accompanying 2232 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>) 2233 </p> 2234</div></td> 2235</tr></table> 2236<hr> 2237<div class="spirit-nav"> 2238<a accesskey="p" href="contract_programming_overview.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><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="advanced.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 2239</div> 2240</body> 2241</html> 2242
