1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Advanced</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="tutorial.html" title="Tutorial"> 10<link rel="next" href="extras.html" title="Extras"> 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="tutorial.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="extras.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.advanced"></a><a class="link" href="advanced.html" title="Advanced">Advanced</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="advanced.html#boost_contract.advanced.pure_virtual_public_functions">Pure 31 Virtual Public Functions</a></span></dt> 32<dt><span class="section"><a href="advanced.html#boost_contract.advanced.optional_return_values">Optional 33 Return Values</a></span></dt> 34<dt><span class="section"><a href="advanced.html#boost_contract.advanced.private_and_protected_functions">Private 35 and Protected Functions</a></span></dt> 36<dt><span class="section"><a href="advanced.html#boost_contract.advanced.friend_functions">Friend Functions</a></span></dt> 37<dt><span class="section"><a href="advanced.html#boost_contract.advanced.function_overloads">Function 38 Overloads</a></span></dt> 39<dt><span class="section"><a href="advanced.html#boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__">Lambdas, 40 Loops, Code Blocks (and <code class="computeroutput"><span class="keyword">constexpr</span></code>)</a></span></dt> 41<dt><span class="section"><a href="advanced.html#boost_contract.advanced.implementation_checks">Implementation 42 Checks</a></span></dt> 43<dt><span class="section"><a href="advanced.html#boost_contract.advanced.old_values_copied_at_body">Old 44 Values Copied at Body</a></span></dt> 45<dt><span class="section"><a href="advanced.html#boost_contract.advanced.named_overrides">Named Overrides</a></span></dt> 46<dt><span class="section"><a href="advanced.html#boost_contract.advanced.access_specifiers">Access Specifiers</a></span></dt> 47<dt><span class="section"><a href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__">Throw 48 on Failures (and <code class="computeroutput"><span class="keyword">noexcept</span></code>)</a></span></dt> 49</dl></div> 50<p> 51 This section is a guide to advanced usage of this library. 52 </p> 53<div class="section"> 54<div class="titlepage"><div><div><h3 class="title"> 55<a name="boost_contract.advanced.pure_virtual_public_functions"></a><a class="link" href="advanced.html#boost_contract.advanced.pure_virtual_public_functions" title="Pure Virtual Public Functions">Pure 56 Virtual Public Functions</a> 57</h3></div></div></div> 58<p> 59 In C++, pure virtual functions are allowed to have a <a href="http://en.cppreference.com/w/cpp/language/abstract_class" target="_top">default 60 implementation</a> as long as such implementation is programmed out-of-line 61 so defined outside the class declaring the pure virtual function <code class="computeroutput"><span class="keyword">virtual</span> <span class="special">...</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span></code>. 62 </p> 63<p> 64 Contracts for pure virtual public functions are programmed using 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> 65 function like for (non-pure) virtual public functions (all consideration 66 made in <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 67 Public Functions</a> apply). However, contracts have to be programmed 68 out-of-line, in the default implementation of the pure virtual function. 69 For example (see <a href="../../../example/features/pure_virtual_public.cpp" target="_top"><code class="literal">pure_virtual_public.cpp</code></a>): 70 </p> 71<p> 72</p> 73<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">></span> 74<span class="keyword">class</span> <span class="identifier">range</span> <span class="special">{</span> 75<span class="keyword">public</span><span class="special">:</span> 76 <span class="comment">// Pure virtual function declaration (contract in definition below).</span> 77 <span class="keyword">virtual</span> <span class="identifier">Iterator</span> <span class="identifier">begin</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="number">0</span><span class="special">;</span> 78</pre> 79<p> 80 </p> 81<p> 82</p> 83<pre class="programlisting"> <span class="comment">/* ... */</span> 84<span class="special">};</span> 85</pre> 86<p> 87 </p> 88<p> 89</p> 90<pre class="programlisting"><span class="comment">// Pure virtual function default implementation (out-of-line in C++).</span> 91<span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">></span> 92<span class="identifier">Iterator</span> <span class="identifier">range</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">begin</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="special">{</span> 93 <span class="identifier">Iterator</span> <span class="identifier">result</span><span class="special">;</span> <span class="comment">// As usual, virtual pass `result` right after `v`...</span> 94 <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">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 95 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> 96 <span class="keyword">if</span><span class="special">(</span><span class="identifier">empty</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> <span class="identifier">end</span><span class="special">());</span> 97 <span class="special">})</span> 98 <span class="special">;</span> 99 100 <span class="comment">// Pure function body (never executed by this library).</span> 101 <span class="identifier">assert</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 102 <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> 103<span class="special">}</span> 104</pre> 105<p> 106 </p> 107<p> 108 This library will never actually execute the pure virtual function body while 109 it is calling the pure virtual function default implementation to check contracts 110 for subcontracting. Therefore, programmers can safely <code class="computeroutput"><span class="identifier">assert</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span></code> 111 at the beginning of the body if they intend for that body to never be executed 112 (or they can program a working body in case they need to use pure virtual 113 function default implementations as usual in C++). 114 </p> 115<h5> 116<a name="boost_contract.advanced.pure_virtual_public_functions.h0"></a> 117 <span class="phrase"><a name="boost_contract.advanced.pure_virtual_public_functions.subcontracting_preconditions_always_true_or_false"></a></span><a class="link" href="advanced.html#boost_contract.advanced.pure_virtual_public_functions.subcontracting_preconditions_always_true_or_false">Subcontracting 118 Preconditions Always True or False</a> 119 </h5> 120<p> 121 As seen in <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 122 Function Overrides</a>, preconditions of overriding public functions are 123 checked in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 124 with preconditions of overridden virtual public functions. Therefore, if 125 a virtual public function in a base class specifies no precondition then 126 preconditions specified by all its overriding functions in derived classes 127 will have no effect (because when checked in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 128 with the overridden function from the base class that has no preconditions, 129 they will always pass): 130 </p> 131<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> <span class="comment">// Some base class.</span> 132<span class="keyword">public</span><span class="special">:</span> 133 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">f</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> 134 <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">v</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 135 <span class="comment">// No preconditions, same as `ASSERT(true)`.</span> 136 <span class="special">...</span> 137 <span class="special">;</span> 138 139 <span class="special">...</span> 140 <span class="special">}</span> 141 142 <span class="special">...</span> 143<span class="special">};</span> 144</pre> 145<p> 146 This correctly reflects the fact that the overridden function in the base 147 class can be called from any context (because it has no precondition) and 148 so must all its overriding functions in all derived classes in accordance 149 to the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 150 principle</a>. <a href="#ftn.boost_contract.advanced.pure_virtual_public_functions.f0" class="footnote" name="boost_contract.advanced.pure_virtual_public_functions.f0"><sup class="footnote">[52]</sup></a> In other words, the code above has the same effect as declaring 151 the virtual public function in the base class with a single precondition 152 <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="keyword">true</span><span class="special">)</span></code> that 153 will always trivially pass: 154 </p> 155<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span> <span class="comment">// Some base class.</span> 156<span class="keyword">public</span><span class="special">:</span> 157 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">f</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> 158 <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">v</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 159 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([]</span> <span class="special">{</span> 160 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span> <span class="comment">// Same as no preconditions.</span> 161 <span class="special">})</span> 162 <span class="special">...</span> 163 <span class="special">;</span> 164 165 <span class="special">...</span> 166 <span class="special">}</span> 167 168 <span class="special">...</span> 169<span class="special">};</span> 170</pre> 171<p> 172 On the flip side, programmers might sometimes consider to declare a pure 173 virtual public function in a base class with a single precondition <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span></code> that 174 will always fail. This indicates that the pure virtual public function can 175 never be called unless it is redefined by a derived class (which is already 176 the case with C++ pure virtual functions) and also that the base class designers 177 have intentionally left it up to derived classes to specify preconditions 178 for the pure virtual function in question. This technique might make sense 179 only for preconditions of pure virtual public functions (otherwise <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span></code> will 180 prevent calling virtual public functions in concrete bases). For example 181 (see <a href="../../../example/features/named_override.cpp" target="_top"><code class="literal">named_override.cpp</code></a>): 182 </p> 183<p> 184</p> 185<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 186<span class="keyword">class</span> <span class="identifier">generic_unary_pack</span> <span class="special">{</span> 187<span class="keyword">public</span><span class="special">:</span> 188 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">_1</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</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="number">0</span><span class="special">;</span> 189 <span class="keyword">virtual</span> <span class="identifier">T</span> <span class="identifier">_1</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="keyword">const</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> 190<span class="special">};</span> 191 192<span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 193<span class="keyword">void</span> <span class="identifier">generic_unary_pack</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">_1</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</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="special">{</span> 194 <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">v</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 195 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 196 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> <span class="comment">// Defer preconditions to overrides.</span> 197 <span class="special">})</span> 198 <span class="special">;</span> 199 <span class="identifier">assert</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 200<span class="special">}</span> 201 202<span class="comment">/* ... */</span> 203</pre> 204<p> 205 </p> 206<p> 207 That said, the need to declare such a precondition <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span></code> 208 that will always fail might also be an indication that the base class interface 209 is not correctly designed. In general, the base class interface should still 210 contain all functions (eventually as pure virtual) that are necessary to 211 program its contracts. 212 </p> 213</div> 214<div class="section"> 215<div class="titlepage"><div><div><h3 class="title"> 216<a name="boost_contract.advanced.optional_return_values"></a><a class="link" href="advanced.html#boost_contract.advanced.optional_return_values" title="Optional Return Values">Optional 217 Return Values</a> 218</h3></div></div></div> 219<p> 220 It is possible to use <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> 221 to handle return values when programmers cannot construct the result variable 222 at its point of declaration before the contract (e.g., because an appropriate 223 constructor for the return type is not available at that point, or just because 224 it would be too expensive to execute an extra initialization of the return 225 value at run-time). <a href="#ftn.boost_contract.advanced.optional_return_values.f0" class="footnote" name="boost_contract.advanced.optional_return_values.f0"><sup class="footnote">[53]</sup></a> For example (see <a href="../../../example/features/optional_result.cpp" target="_top"><code class="literal">optional_result.cpp</code></a>): 226 </p> 227<p> 228</p> 229<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">Index</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 230<span class="identifier">T</span><span class="special">&</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">vect</span><span class="special">)</span> <span class="special">{</span> 231 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span> <span class="identifier">result</span><span class="special">;</span> <span class="comment">// Result not initialized here...</span> 232 <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> 233 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 234 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">Index</span> <span class="special"><</span> <span class="identifier">vect</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span> 235 <span class="special">})</span> 236 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 237 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(*</span><span class="identifier">result</span> <span class="special">==</span> <span class="identifier">vect</span><span class="special">[</span><span class="identifier">Index</span><span class="special">]);</span> 238 <span class="special">})</span> 239 <span class="special">;</span> 240 241 <span class="comment">// Function body (executed after preconditions checked).</span> 242 <span class="keyword">return</span> <span class="special">*(</span><span class="identifier">result</span> <span class="special">=</span> <span class="identifier">vect</span><span class="special">[</span><span class="identifier">Index</span><span class="special">]);</span> <span class="comment">// ...result initialized here instead.</span> 243<span class="special">}</span> 244</pre> 245<p> 246 </p> 247<p> 248 In this example the return type is a reference so it does not have default 249 constructor that can be used to initialize <code class="computeroutput"><span class="identifier">result</span></code> 250 when it is declared before the contract declaration. In addition, <code class="computeroutput"><span class="identifier">Index</span></code> needs to be validated to be smaller 251 than <code class="computeroutput"><span class="identifier">size</span><span class="special">()</span></code> 252 by the precondition before it can be used to retrieve the reference to assign 253 to <code class="computeroutput"><span class="identifier">result</span></code> so <code class="computeroutput"><span class="identifier">vect</span><span class="special">[</span><span class="identifier">Index</span><span class="special">]</span></code> cannot be used to initialize <code class="computeroutput"><span class="identifier">result</span></code> when it is declared before the contract 254 declaration. Therefore, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> 255 is used to defer <code class="computeroutput"><span class="identifier">result</span></code> real 256 initialization until the execution of the function body, after the contract 257 declaration, where <code class="computeroutput"><span class="identifier">Index</span></code> 258 has been validated by the precondition and <code class="computeroutput"><span class="identifier">vect</span><span class="special">[</span><span class="identifier">Index</span><span class="special">]</span></code> can be safely evaluated to initialize <code class="computeroutput"><span class="identifier">result</span></code>. 259 </p> 260<p> 261 As seen in <a class="link" href="tutorial.html#boost_contract.tutorial.return_values" title="Return Values">Return Values</a>, 262 it is the responsibility of the programmers to ensure that <code class="computeroutput"><span class="identifier">result</span></code> is always set to the return value 263 (when the function exits without trowing an exception). This also ensures 264 that <code class="computeroutput"><span class="identifier">result</span></code> is always set 265 before the postconditions are checked so programmers can always dereference 266 <code class="computeroutput"><span class="identifier">result</span></code> in postconditions 267 to access the return value (using <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> and <code class="computeroutput"><span class="keyword">operator</span><span class="special">-></span></code> as usual with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>, 268 and without having to explicitly check if <code class="computeroutput"><span class="identifier">result</span></code> 269 is an empty <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> object or not). This can be done 270 ensuring that <span class="emphasis"><em>all</em></span> <code class="computeroutput"><span class="keyword">return</span></code> 271 statements in the function are of the form: 272 </p> 273<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><code class="literal"><span class="emphasis"><em>return-type</em></span></code><span class="special">></span> <span class="identifier">result</span><span class="special">;</span> 274<span class="special">...</span> 275<span class="keyword">return</span> <span class="special">*(</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> 276</pre> 277<h5> 278<a name="boost_contract.advanced.optional_return_values.h0"></a> 279 <span class="phrase"><a name="boost_contract.advanced.optional_return_values.optional_results_in_virtual_public_functions"></a></span><a class="link" href="advanced.html#boost_contract.advanced.optional_return_values.optional_results_in_virtual_public_functions">Optional 280 Results in Virtual Public Functions</a> 281 </h5> 282<p> 283 Similarly, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> can be used to handle the return 284 value passed to contracts of virtual public functions (pure or not) and of 285 public function overrides. As seen in <a class="link" href="advanced.html#boost_contract.advanced.pure_virtual_public_functions" title="Pure Virtual Public Functions">Pure 286 Virtual Public Functions</a>, <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 287 Public Functions</a>, and <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 288 Function Overrides</a>, in these cases the return value <code class="computeroutput"><span class="identifier">result</span></code> must be passed as a parameter to 289 <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 290 right after the parameter <code class="computeroutput"><span class="identifier">v</span></code> 291 of 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>. Then the functor passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code> takes one single parameter of type 292 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span></code><code class="literal"><span class="emphasis"><em>return-type</em></span></code><code class="computeroutput"> 293 <span class="keyword">const</span><span class="special">&></span> 294 <span class="keyword">const</span><span class="special">&</span></code>. 295 For example (see <a href="../../../example/features/optional_result_virtual.cpp" target="_top"><code class="literal">optional_result_virtual.cpp</code></a>): 296 </p> 297<p> 298</p> 299<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 300<span class="identifier">T</span><span class="special">&</span> <span class="identifier">accessible</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">at</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">index</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="special">{</span> 301 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span> <span class="identifier">result</span><span class="special">;</span> 302 <span class="comment">// Pass `result` right after `v`...</span> 303 <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">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 304 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 305 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">index</span> <span class="special"><</span> <span class="identifier">size</span><span class="special">());</span> 306 <span class="special">})</span> 307 <span class="comment">// ...plus postconditions take `result` as a parameter (not capture).</span> 308 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> 309 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(*</span><span class="identifier">result</span> <span class="special">==</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">index</span><span class="special">));</span> 310 <span class="special">})</span> 311 <span class="special">;</span> 312 313 <span class="identifier">assert</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 314 <span class="keyword">return</span> <span class="special">*</span><span class="identifier">result</span><span class="special">;</span> 315<span class="special">}</span> 316</pre> 317<p> 318 </p> 319<p> 320 The inner <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code> 321 in the postcondition functor parameter type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><...</span> <span class="keyword">const</span><span class="special">&></span> <span class="special">...</span></code> 322 is mandatory (while the outer <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code> in the postcondition functor parameter 323 type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><...></span> 324 <span class="keyword">const</span><span class="special">&</span></code> 325 is not). <a href="#ftn.boost_contract.advanced.optional_return_values.f1" class="footnote" name="boost_contract.advanced.optional_return_values.f1"><sup class="footnote">[54]</sup></a> 326 </p> 327</div> 328<div class="section"> 329<div class="titlepage"><div><div><h3 class="title"> 330<a name="boost_contract.advanced.private_and_protected_functions"></a><a class="link" href="advanced.html#boost_contract.advanced.private_and_protected_functions" title="Private and Protected Functions">Private 331 and Protected Functions</a> 332</h3></div></div></div> 333<p> 334 Private and protected functions do not check class invariants (because they 335 are not part of the public class interface) and they do not subcontract (because 336 they are not accessible at the calling site where the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 337 principle</a> applies, see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.function_calls" title="Function Calls">Function 338 Calls</a>). However, programmers may still want to specify preconditions 339 and postconditions for private and protected functions when they want to 340 check correctness of their implementation and use (from within the class, 341 base classes, friend classes or functions, etc.). When programmers decide 342 to specify contracts for private and protected functions, they can use <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 343 (because, like for non-member functions, this does not check class invariants 344 and does not subcontract). For example (see <a href="../../../example/features/private_protected.cpp" target="_top"><code class="literal">private_protected.cpp</code></a>): 345 </p> 346<p> 347</p> 348<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">counter</span> <span class="special">{</span> 349<span class="keyword">protected</span><span class="special">:</span> <span class="comment">// Protected functions use `function()` (like non-members).</span> 350 <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">)</span> <span class="special">{</span> 351 <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> 352 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 353 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">n</span> <span class="special"><=</span> <span class="number">0</span><span class="special">);</span> 354 <span class="special">})</span> 355 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 356 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">n</span><span class="special">);</span> 357 <span class="special">})</span> 358 <span class="special">;</span> 359 360 <span class="identifier">n_</span> <span class="special">=</span> <span class="identifier">n</span><span class="special">;</span> 361 <span class="special">}</span> 362 363<span class="keyword">private</span><span class="special">:</span> <span class="comment">// Private functions use `function()` (like non-members).</span> 364 <span class="keyword">void</span> <span class="identifier">dec</span><span class="special">()</span> <span class="special">{</span> 365 <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_get</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">get</span><span class="special">());</span> 366 <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> 367 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 368 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 369 <span class="identifier">get</span><span class="special">()</span> <span class="special">+</span> <span class="number">1</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">min</span><span class="special">());</span> 370 <span class="special">})</span> 371 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 372 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_get</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span> 373 <span class="special">})</span> 374 <span class="special">;</span> 375 376 <span class="identifier">set</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span> 377 <span class="special">}</span> 378 379 <span class="keyword">int</span> <span class="identifier">n_</span><span class="special">;</span> 380 381 <span class="comment">/* ... */</span> 382</pre> 383<p> 384 </p> 385<p> 386 Considerations made in <a class="link" href="tutorial.html#boost_contract.tutorial.non_member_functions" title="Non-Member Functions">Non-Member 387 Functions</a> apply to private and protected functions as well. See <a class="link" href="tutorial.html#boost_contract.tutorial.constructors" title="Constructors">Constructors</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.destructors" title="Destructors">Destructors</a> on how to 388 program contracts for private and protected constructors and destructors 389 instead. 390 </p> 391<h5> 392<a name="boost_contract.advanced.private_and_protected_functions.h0"></a> 393 <span class="phrase"><a name="boost_contract.advanced.private_and_protected_functions.virtual_private_and_protected_functions"></a></span><a class="link" href="advanced.html#boost_contract.advanced.private_and_protected_functions.virtual_private_and_protected_functions">Virtual 394 Private and Protected Functions</a> 395 </h5> 396<p> 397 When private and protected functions are virtual they should still declare 398 the extra virtual parameter of type <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> with default value <code class="computeroutput"><span class="number">0</span></code> 399 (see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual 400 Public Functions</a>) even if that parameter does not have to be passed 401 to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 402 and <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 403 takes no such an argument (so the extra virtual parameter will remain unused 404 and it does not need a name). <a href="#ftn.boost_contract.advanced.private_and_protected_functions.f0" class="footnote" name="boost_contract.advanced.private_and_protected_functions.f0"><sup class="footnote">[55]</sup></a> That is necessary otherwise the private and protected virtual 405 functions cannot be overridden by public functions in derived classes that 406 specify contracts (because the <code class="computeroutput"><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="special">=</span> <span class="number">0</span></code> 407 parameter has to be part of signatures for public function overrides). For 408 example (see <a href="../../../example/features/private_protected_virtual.cpp" target="_top"><code class="literal">private_protected_virtual.cpp</code></a>): 409 </p> 410<p> 411</p> 412<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">counter</span> <span class="special">{</span> 413 <span class="comment">// Virtual private and protected functions still declare extra</span> 414 <span class="comment">// `virtual_* = 0` parameter (otherwise they cannot be overridden), but...</span> 415<span class="keyword">protected</span><span class="special">:</span> 416 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">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="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span> 417 <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">// ...no `v`.</span> 418 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 419 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">n</span> <span class="special"><=</span> <span class="number">0</span><span class="special">);</span> 420 <span class="special">})</span> 421 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 422 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">n</span><span class="special">);</span> 423 <span class="special">})</span> 424 <span class="special">;</span> 425 426 <span class="identifier">n_</span> <span class="special">=</span> <span class="identifier">n</span><span class="special">;</span> 427 <span class="special">}</span> 428 429<span class="keyword">private</span><span class="special">:</span> 430 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">dec</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="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span> 431 <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_get</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">get</span><span class="special">());</span> <span class="comment">// ...no `v`.</span> 432 <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">// ...no `v`.</span> 433 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 434 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 435 <span class="identifier">get</span><span class="special">()</span> <span class="special">+</span> <span class="number">1</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">min</span><span class="special">());</span> 436 <span class="special">})</span> 437 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 438 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_get</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span> 439 <span class="special">})</span> 440 <span class="special">;</span> 441 442 <span class="identifier">set</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span> 443 <span class="special">}</span> 444 445 <span class="keyword">int</span> <span class="identifier">n_</span><span class="special">;</span> 446 447 <span class="comment">/* ... */</span> 448</pre> 449<p> 450 </p> 451<p> 452 However, public functions in derived classes overriding private or protected 453 virtual functions from base classes shall not specify the extra <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> 454 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> 455 because the overridden functions are private or protected and, not being 456 public, they do not participate to subcontracting (this library will generate 457 a compile-time error if <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> is specified because there will be no 458 virtual <span class="emphasis"><em>public</em></span> function to override from the base class). 459 For example (see <a href="../../../example/features/private_protected_virtual.cpp" target="_top"><code class="literal">private_protected_virtual.cpp</code></a>): 460 </p> 461<p> 462</p> 463<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">counter10</span> 464 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">public</span> <span class="identifier">counter</span> 465 <span class="special">:</span> <span class="identifier">BASES</span> 466<span class="special">{</span> 467<span class="keyword">public</span><span class="special">:</span> 468 <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> 469 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> 470 471 <span class="comment">// Overriding from non-public members so no subcontracting, no override_...</span> 472 473 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">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> 474 <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">v</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 475 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 476 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">n</span> <span class="special">%</span> <span class="number">10</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span> 477 <span class="special">})</span> 478 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 479 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">n</span><span class="special">);</span> 480 <span class="special">})</span> 481 <span class="special">;</span> 482 483 <span class="identifier">counter</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span> 484 <span class="special">}</span> 485 486 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">dec</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> 487 <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_get</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">get</span><span class="special">());</span> 488 <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">v</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 489 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 490 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 491 <span class="identifier">get</span><span class="special">()</span> <span class="special">+</span> <span class="number">10</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">min</span><span class="special">());</span> 492 <span class="special">})</span> 493 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 494 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_get</span> <span class="special">-</span> <span class="number">10</span><span class="special">);</span> 495 <span class="special">})</span> 496 <span class="special">;</span> 497 498 <span class="identifier">set</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">-</span> <span class="number">10</span><span class="special">);</span> 499 <span class="special">}</span> 500 501 <span class="comment">/* ... */</span> 502</pre> 503<p> 504 </p> 505<p> 506 Furthermore, using multiple inheritance it is possible to override functions 507 that are private or protected from one base but public from another base. 508 In this case, public function overrides in derived classes will specify the 509 extra <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> 510 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> 511 (because the overridden functions are private or protected in one base and 512 those do not participate to subcontracting, but public in another base and 513 these participate to subcontracting instead). For example (see <a href="../../../example/features/private_protected_virtual_multi.cpp" target="_top"><code class="literal">private_protected_virtual_multi.cpp</code></a>): 514 </p> 515<p> 516</p> 517<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">countable</span> <span class="special">{</span> 518<span class="keyword">public</span><span class="special">:</span> 519 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 520 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special"><=</span> <span class="number">0</span><span class="special">);</span> 521 <span class="special">}</span> 522 523 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">dec</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="number">0</span><span class="special">;</span> 524 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">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> <span class="number">0</span><span class="special">;</span> 525 <span class="keyword">virtual</span> <span class="keyword">int</span> <span class="identifier">get</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="keyword">const</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> 526<span class="special">};</span> 527 528<span class="comment">/* ... */</span> 529</pre> 530<p> 531 </p> 532<p> 533</p> 534<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">counter10</span> 535 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">public</span> <span class="identifier">countable</span><span class="special">,</span> <span class="keyword">public</span> <span class="identifier">counter</span> <span class="comment">// Multiple inheritance.</span> 536 <span class="special">:</span> <span class="identifier">BASES</span> 537<span class="special">{</span> 538<span class="keyword">public</span><span class="special">:</span> 539 <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> 540 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> 541 542 <span class="comment">// Overriding from public members from `countable` so use `override_...`.</span> 543 544 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">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> 545 <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> 546 <span class="identifier">override_set</span><span class="special">>(</span><span class="identifier">v</span><span class="special">,</span> <span class="special">&</span><span class="identifier">counter10</span><span class="special">::</span><span class="identifier">set</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> <span class="identifier">n</span><span class="special">)</span> 547 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 548 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">n</span> <span class="special">%</span> <span class="number">10</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span> 549 <span class="special">})</span> 550 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 551 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">n</span><span class="special">);</span> 552 <span class="special">})</span> 553 <span class="special">;</span> 554 555 <span class="identifier">counter</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span> 556 <span class="special">}</span> 557 558 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">dec</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> 559 <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_get</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">get</span><span class="special">());</span> 560 <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> 561 <span class="identifier">override_dec</span><span class="special">>(</span><span class="identifier">v</span><span class="special">,</span> <span class="special">&</span><span class="identifier">counter10</span><span class="special">::</span><span class="identifier">dec</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> 562 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 563 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 564 <span class="identifier">get</span><span class="special">()</span> <span class="special">+</span> <span class="number">10</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">min</span><span class="special">());</span> 565 <span class="special">})</span> 566 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 567 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_get</span> <span class="special">-</span> <span class="number">10</span><span class="special">);</span> 568 <span class="special">})</span> 569 <span class="special">;</span> 570 571 <span class="identifier">set</span><span class="special">(</span><span class="identifier">get</span><span class="special">()</span> <span class="special">-</span> <span class="number">10</span><span class="special">);</span> 572 <span class="special">}</span> 573 574 <span class="identifier">BOOST_CONTRACT_OVERRIDES</span><span class="special">(</span><span class="identifier">set</span><span class="special">,</span> <span class="identifier">dec</span><span class="special">)</span> 575 576 <span class="comment">/* ... */</span> 577</pre> 578<p> 579 </p> 580<div class="warning"><table border="0" summary="Warning"> 581<tr> 582<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td> 583<th align="left">Warning</th> 584</tr> 585<tr><td align="left" valign="top"><p> 586 Unfortunately, the code above does not compile on MSVC (at least up to 587 Visual Studio 2015) because MSVC incorrectly gives a compile-time error 588 when SFINAE fails due to private or protected access levels. Instead, GCC 589 and Clang correctly implement SFINAE failures due to private and protected 590 functions so the code above correctly complies on GCC and Clang. Therefore, 591 currently it is not possible to override a function that is public in one 592 base but private or protected in other base using this library on MSVC 593 (at least up to Visual Studio 2015), but that can correctly be done on 594 GCC or Clang instead. 595 </p></td></tr> 596</table></div> 597</div> 598<div class="section"> 599<div class="titlepage"><div><div><h3 class="title"> 600<a name="boost_contract.advanced.friend_functions"></a><a class="link" href="advanced.html#boost_contract.advanced.friend_functions" title="Friend Functions">Friend Functions</a> 601</h3></div></div></div> 602<p> 603 In general, friend functions are not member functions so <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 604 is used to program their contracts and all considerations made in <a class="link" href="tutorial.html#boost_contract.tutorial.non_member_functions" title="Non-Member Functions">Non-Member 605 Functions</a> apply. For example (see <a href="../../../example/features/friend.cpp" target="_top"><code class="literal">friend.cpp</code></a>): 606 </p> 607<p> 608</p> 609<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">buffer</span><span class="special">;</span> 610 611<span class="keyword">class</span> <span class="identifier">byte</span> <span class="special">{</span> 612 <span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">buffer</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">left</span><span class="special">,</span> <span class="identifier">byte</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">right</span><span class="special">);</span> 613 614<span class="keyword">private</span><span class="special">:</span> 615 <span class="keyword">char</span> <span class="identifier">value_</span><span class="special">;</span> 616 617 <span class="comment">/* ... */</span> 618</pre> 619<p> 620 </p> 621<p> 622</p> 623<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">buffer</span> <span class="special">{</span> 624 <span class="comment">// Friend functions are not member functions...</span> 625 <span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">buffer</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">left</span><span class="special">,</span> <span class="identifier">byte</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">right</span><span class="special">)</span> <span class="special">{</span> 626 <span class="comment">// ...so check contracts via `function` (which won't check invariants).</span> 627 <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> 628 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 629 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(!</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">empty</span><span class="special">());</span> 630 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(!</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">empty</span><span class="special">());</span> 631 <span class="special">})</span> 632 <span class="special">;</span> 633 634 <span class="keyword">for</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">left</span><span class="special">.</span><span class="identifier">values_</span><span class="special">.</span><span class="identifier">c_str</span><span class="special">();</span> <span class="special">*</span><span class="identifier">x</span> <span class="special">!=</span> <span class="char">'\0'</span><span class="special">;</span> <span class="special">++</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> 635 <span class="keyword">if</span><span class="special">(*</span><span class="identifier">x</span> <span class="special">!=</span> <span class="identifier">right</span><span class="special">.</span><span class="identifier">value_</span><span class="special">)</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span> 636 <span class="special">}</span> 637 <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> 638 <span class="special">}</span> 639 640<span class="keyword">private</span><span class="special">:</span> 641 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">values_</span><span class="special">;</span> 642 643 <span class="comment">/* ... */</span> 644</pre> 645<p> 646 </p> 647<p> 648 However, in some cases a friend function might take an object as parameter 649 and it can be logically considered an extension of that object's public interface 650 (essentially at the same level as the object's public functions). In these 651 cases, programmers might chose to program the friend function contracts using 652 <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 653 (instead of <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code>) 654 so to also check the class invariants of the object passed as parameter (and 655 not just pre- and postconditions). For example (see <a href="../../../example/features/friend_invariant.cpp" target="_top"><code class="literal">friend_invariant.cpp</code></a>): 656 <a href="#ftn.boost_contract.advanced.friend_functions.f0" class="footnote" name="boost_contract.advanced.friend_functions.f0"><sup class="footnote">[56]</sup></a> 657 </p> 658<p> 659</p> 660<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 661<span class="keyword">class</span> <span class="identifier">positive</span> <span class="special">{</span> 662<span class="keyword">public</span><span class="special">:</span> 663 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 664 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">value</span><span class="special">()</span> <span class="special">></span> <span class="number">0</span><span class="special">);</span> 665 <span class="special">}</span> 666 667 <span class="comment">// Can be considered an extension of enclosing class' public interface...</span> 668 <span class="keyword">friend</span> <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span><span class="identifier">positive</span><span class="special">&</span> <span class="identifier">object</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">value</span><span class="special">)</span> <span class="special">{</span> 669 <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">T</span><span class="special">></span> <span class="identifier">old_object_value</span> <span class="special">=</span> 670 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">object</span><span class="special">.</span><span class="identifier">value</span><span class="special">());</span> 671 <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">T</span><span class="special">></span> <span class="identifier">old_value</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">value</span><span class="special">);</span> 672 <span class="comment">// ...so it can be made to check invariants via `public_function`.</span> 673 <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">object</span><span class="special">)</span> 674 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 675 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">value</span> <span class="special">></span> <span class="number">0</span><span class="special">);</span> 676 <span class="special">})</span> 677 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 678 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">object</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_value</span><span class="special">);</span> 679 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">value</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_object_value</span><span class="special">);</span> 680 <span class="special">})</span> 681 <span class="special">;</span> 682 683 <span class="identifier">T</span> <span class="identifier">saved</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">.</span><span class="identifier">value_</span><span class="special">;</span> 684 <span class="identifier">object</span><span class="special">.</span><span class="identifier">value_</span> <span class="special">=</span> <span class="identifier">value</span><span class="special">;</span> 685 <span class="identifier">value</span> <span class="special">=</span> <span class="identifier">saved</span><span class="special">;</span> 686 <span class="special">}</span> 687 688<span class="keyword">private</span><span class="special">:</span> 689 <span class="identifier">T</span> <span class="identifier">value_</span><span class="special">;</span> 690 691 <span class="comment">/* ... */</span> 692</pre> 693<p> 694 </p> 695<p> 696 This technique can also be extended to friend functions that take multiple 697 objects as parameters and can be logically considered extensions to the public 698 interfaces of each of these objects. For example: 699 </p> 700<pre class="programlisting"><span class="comment">// Can be considered an extension of multiple objects' public interfaces.</span> 701<span class="keyword">friend</span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">class1</span><span class="special">&</span> <span class="identifier">object1</span><span class="special">,</span> <span class="identifier">class2</span><span class="special">*</span> <span class="identifier">object2</span><span class="special">,</span> <span class="identifier">type3</span><span class="special">&</span> <span class="identifier">value3</span><span class="special">)</span> <span class="special">{</span> 702 <span class="comment">// Check preconditions.</span> 703 <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">pre</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> 704 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 705 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">object2</span> <span class="special">!=</span> <span class="keyword">nullptr</span><span class="special">);</span> 706 <span class="special">...</span> 707 <span class="special">})</span> 708 <span class="special">;</span> 709 <span class="comment">// Check class invariants for each object (programmers chose the order).</span> 710 <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">inv1</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">object1</span><span class="special">);</span> 711 <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">inv2</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">object2</span><span class="special">);</span> 712 <span class="comment">// Check postconditions and exception guarantees.</span> 713 <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">postex</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> 714 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span> 715 <span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span> 716 <span class="special">;</span> 717 718 <span class="special">...</span> <span class="comment">// Function body.</span> 719<span class="special">}</span> 720</pre> 721<p> 722 Changing the order of the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 723 declarations above, programmers can chose the order for checking class invariants 724 among the different objects passed to the friend function and also whether 725 to check these invariants before or after preconditions, postconditions, 726 and exception guarantees of the friend function (see <a class="link" href="tutorial.html#boost_contract.tutorial.non_member_functions" title="Non-Member Functions">Non-Member 727 Functions</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.public_functions" title="Public Functions">Public 728 Functions</a> for information on how the RAII objects returned by <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 729 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> 730 check contract conditions). The example above is programmed to check <code class="computeroutput"><span class="identifier">class1</span></code> invariants before <code class="computeroutput"><span class="identifier">class2</span></code> invariants (but that order could 731 have been inverted if programmers so chose). 732 </p> 733<div class="note"><table border="0" summary="Note"> 734<tr> 735<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 736<th align="left">Note</th> 737</tr> 738<tr><td align="left" valign="top"><p> 739 In the example above, preconditions are intentionally programmed to be 740 checked before class invariants so the objects passed to the friend function 741 can be validated by the preconditions before they are passed as pointers 742 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> 743 (e.g., check <code class="computeroutput"><span class="identifier">object2</span></code> is 744 not null). (Within member functions instead, the object pointer <code class="computeroutput"><span class="keyword">this</span></code> is always well-formed, its validation 745 is never needed, 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> 746 checks class invariants before checking preconditions so programming preconditions 747 can be simplified assuming the class invariants are satisfied already, 748 see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public 749 Function Calls</a>.) 750 </p></td></tr> 751</table></div> 752</div> 753<div class="section"> 754<div class="titlepage"><div><div><h3 class="title"> 755<a name="boost_contract.advanced.function_overloads"></a><a class="link" href="advanced.html#boost_contract.advanced.function_overloads" title="Function Overloads">Function 756 Overloads</a> 757</h3></div></div></div> 758<p> 759 No special attention is required when using this library with overloaded 760 functions or constructors. The only exception is for the function pointer 761 passed 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> 762 from public function overrides (see <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 763 Function Overrides</a>). When the name of public function override are 764 also overloaded, the related function pointer cannot be automatically deduced 765 by the compiler so programmers have to use <code class="computeroutput"><span class="keyword">static_cast</span></code> 766 to resolve ambiguities (as usual with pointers to overloaded functions in 767 C++). <a href="#ftn.boost_contract.advanced.function_overloads.f0" class="footnote" name="boost_contract.advanced.function_overloads.f0"><sup class="footnote">[57]</sup></a> For example, note how <code class="computeroutput"><span class="keyword">static_cast</span></code> 768 is used in the following calls 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> 769 (see <a href="../../../example/features/overload.cpp" target="_top"><code class="literal">overload.cpp</code></a>): 770 </p> 771<p> 772</p> 773<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">string_lines</span> 774 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">public</span> <span class="identifier">lines</span> 775 <span class="special">:</span> <span class="identifier">BASES</span> 776<span class="special">{</span> 777<span class="keyword">public</span><span class="special">:</span> 778 <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> 779 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> 780 781 <span class="identifier">BOOST_CONTRACT_OVERRIDES</span><span class="special">(</span><span class="identifier">str</span><span class="special">)</span> <span class="comment">// Invoked only once for all `str` overloads.</span> 782 783 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">str</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="keyword">const</span> <span class="comment">/* override */</span> <span class="special">{</span> 784 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">result</span><span class="special">;</span> 785 <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> 786 <span class="identifier">override_str</span><span class="special">>(</span> 787 <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> 788 <span class="comment">// `static_cast` resolves overloaded function pointer ambiguities.</span> 789 <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">(</span><span class="identifier">string_lines</span><span class="special">::*)(</span> 790 <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="keyword">const</span><span class="special">>(&</span><span class="identifier">string_lines</span><span class="special">::</span><span class="identifier">str</span><span class="special">),</span> 791 <span class="keyword">this</span> 792 <span class="special">);</span> 793 794 <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">str_</span><span class="special">;</span> 795 <span class="special">}</span> 796 797 <span class="comment">// Overload on (absence of) `const` qualifier.</span> 798 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">str</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> 799 <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> 800 <span class="identifier">override_str</span><span class="special">>(</span> 801 <span class="identifier">v</span><span class="special">,</span> <span class="identifier">str_</span><span class="special">,</span> 802 <span class="comment">// `static_cast` resolves overloaded function pointer ambiguities.</span> 803 <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="special">(</span><span class="identifier">string_lines</span><span class="special">::*)(</span> 804 <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">string_lines</span><span class="special">::</span><span class="identifier">str</span><span class="special">),</span> 805 <span class="keyword">this</span> 806 <span class="special">);</span> 807 808 <span class="keyword">return</span> <span class="identifier">str_</span><span class="special">;</span> 809 <span class="special">}</span> 810 811 <span class="identifier">BOOST_CONTRACT_OVERRIDES</span><span class="special">(</span><span class="identifier">put</span><span class="special">)</span> <span class="comment">// Invoked only once for all `put` overloads.</span> 812 813 <span class="keyword">void</span> <span class="identifier">put</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> 814 <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> 815 <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">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">old_str</span> <span class="special">=</span> 816 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">str</span><span class="special">());</span> 817 <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> 818 <span class="identifier">override_put</span><span class="special">>(</span> 819 <span class="identifier">v</span><span class="special">,</span> 820 <span class="comment">// `static_cast` resolves overloaded function pointer ambiguities.</span> 821 <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(</span><span class="identifier">string_lines</span><span class="special">::*)(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&,</span> 822 <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">string_lines</span><span class="special">::</span><span class="identifier">put</span><span class="special">),</span> 823 <span class="keyword">this</span><span class="special">,</span> <span class="identifier">x</span> 824 <span class="special">)</span> 825 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 826 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_str</span> <span class="special">+</span> <span class="identifier">x</span> <span class="special">+</span> <span class="char">'\n'</span><span class="special">);</span> 827 <span class="special">})</span> 828 <span class="special">;</span> 829 830 <span class="identifier">str_</span> <span class="special">=</span> <span class="identifier">str_</span> <span class="special">+</span> <span class="identifier">x</span> <span class="special">+</span> <span class="char">'\n'</span><span class="special">;</span> 831 <span class="special">}</span> 832 833 <span class="comment">// Overload on argument type.</span> 834 <span class="keyword">void</span> <span class="identifier">put</span><span class="special">(</span><span class="keyword">char</span> <span class="identifier">x</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> 835 <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">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">old_str</span> <span class="special">=</span> 836 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">str</span><span class="special">());</span> 837 <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> 838 <span class="identifier">override_put</span><span class="special">>(</span> 839 <span class="identifier">v</span><span class="special">,</span> 840 <span class="comment">// `static_cast` resolves overloaded function pointer ambiguities.</span> 841 <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(</span><span class="identifier">string_lines</span><span class="special">::*)(</span><span class="keyword">char</span><span class="special">,</span> 842 <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">string_lines</span><span class="special">::</span><span class="identifier">put</span><span class="special">),</span> 843 <span class="keyword">this</span><span class="special">,</span> <span class="identifier">x</span> 844 <span class="special">)</span> 845 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 846 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_str</span> <span class="special">+</span> <span class="identifier">x</span> <span class="special">+</span> <span class="char">'\n'</span><span class="special">);</span> 847 <span class="special">})</span> 848 <span class="special">;</span> 849 850 <span class="identifier">str_</span> <span class="special">=</span> <span class="identifier">str_</span> <span class="special">+</span> <span class="identifier">x</span> <span class="special">+</span> <span class="char">'\n'</span><span class="special">;</span> 851 <span class="special">}</span> 852 853 <span class="comment">// Overload on argument type and arity (also with default parameter).</span> 854 <span class="keyword">void</span> <span class="identifier">put</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">tab</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> 855 <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> 856 <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">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">old_str</span> <span class="special">=</span> 857 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">str</span><span class="special">());</span> 858 <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> 859 <span class="identifier">override_put</span><span class="special">>(</span> 860 <span class="identifier">v</span><span class="special">,</span> 861 <span class="comment">// `static_cast` resolves overloaded function pointer ambiguities.</span> 862 <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(</span><span class="identifier">string_lines</span><span class="special">::*)(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">,</span> 863 <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">string_lines</span><span class="special">::</span><span class="identifier">put</span><span class="special">),</span> 864 <span class="keyword">this</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">tab</span> 865 <span class="special">)</span> 866 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 867 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">s</span><span class="special">;</span> 868 <span class="identifier">s</span> <span class="special"><<</span> <span class="identifier">x</span><span class="special">;</span> 869 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 870 <span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_str</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">tab</span> <span class="special">?</span> <span class="string">"\t"</span> <span class="special">:</span> <span class="string">""</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">+</span> <span class="char">'\n'</span><span class="special">);</span> 871 <span class="special">})</span> 872 <span class="special">;</span> 873 874 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">s</span><span class="special">;</span> 875 <span class="identifier">s</span> <span class="special"><<</span> <span class="identifier">str_</span> <span class="special"><<</span> <span class="special">(</span><span class="identifier">tab</span> <span class="special">?</span> <span class="string">"\t"</span> <span class="special">:</span> <span class="string">""</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">x</span> <span class="special"><<</span> <span class="char">'\n'</span><span class="special">;</span> 876 <span class="identifier">str_</span> <span class="special">=</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">str</span><span class="special">();</span> 877 <span class="special">}</span> 878 879<span class="keyword">private</span><span class="special">:</span> 880 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">str_</span><span class="special">;</span> 881<span class="special">};</span> 882</pre> 883<p> 884 </p> 885<p> 886 Overloaded functions have the same function name so the same <code class="literal">override_<span class="emphasis"><em>function-name</em></span></code> 887 type can be reused as template parameter for all <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code> 888 calls in a given class. Therefore, <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 889 only needs to be invoked once for a function name in a given class, even 890 when that function name is overloaded. 891 </p> 892</div> 893<div class="section"> 894<div class="titlepage"><div><div><h3 class="title"> 895<a name="boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__"></a><a class="link" href="advanced.html#boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__" title="Lambdas, Loops, Code Blocks (and constexpr)">Lambdas, 896 Loops, Code Blocks (and <code class="computeroutput"><span class="keyword">constexpr</span></code>)</a> 897</h3></div></div></div> 898<p> 899 While contracts are usually most useful to program specifications of functions 900 and class interfaces, this library also allows to check contract conditions 901 for implementation code (lambda functions, loops, code blocks, etc.). 902 </p> 903<p> 904 Lambda functions are not member functions, they are not part of class public 905 interfaces so they do not check class invariants and they do not subcontract. 906 They can use <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 907 to specify preconditions, postconditions, and exception guarantees (considerations 908 made in <a class="link" href="tutorial.html#boost_contract.tutorial.non_member_functions" title="Non-Member Functions">Non-Member 909 Functions</a> apply). For example (see <a href="../../../example/features/lambda.cpp" target="_top"><code class="literal">lambda.cpp</code></a>): 910 </p> 911<p> 912</p> 913<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">total</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> 914<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">cbegin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">cend</span><span class="special">(),</span> 915 <span class="comment">// Contract for a lambda function.</span> 916 <span class="special">[&</span><span class="identifier">total</span><span class="special">]</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> 917 <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_total</span> <span class="special">=</span> 918 <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">total</span><span class="special">);</span> 919 <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> 920 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 921 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 922 <span class="identifier">total</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> <span class="special">-</span> <span class="identifier">x</span><span class="special">);</span> 923 <span class="special">})</span> 924 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 925 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">total</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_total</span> <span class="special">+</span> <span class="identifier">x</span><span class="special">);</span> 926 <span class="special">})</span> 927 <span class="special">;</span> 928 929 <span class="identifier">total</span> <span class="special">+=</span> <span class="identifier">x</span><span class="special">;</span> <span class="comment">// Lambda function body.</span> 930 <span class="special">}</span> 931<span class="special">);</span> 932</pre> 933<p> 934 </p> 935<p> 936 Similarly, <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 937 can be used to program preconditions, postconditions, and exception guarantees 938 for loops. For example, for a for-loop but same for while- and all other 939 loops (see <a href="../../../example/features/loop.cpp" target="_top"><code class="literal">loop.cpp</code></a>): 940 </p> 941<p> 942</p> 943<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">total</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> 944<span class="comment">// Contract for a for-loop (same for while- and all other loops).</span> 945<span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">>::</span><span class="identifier">const_iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">i</span> <span class="special">!=</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> 946 <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_total</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">total</span><span class="special">);</span> 947 <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> 948 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 949 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span> 950 <span class="identifier">total</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> <span class="special">-</span> <span class="special">*</span><span class="identifier">i</span><span class="special">);</span> 951 <span class="special">})</span> 952 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 953 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">total</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_total</span> <span class="special">+</span> <span class="special">*</span><span class="identifier">i</span><span class="special">);</span> 954 <span class="special">})</span> 955 <span class="special">;</span> 956 957 <span class="identifier">total</span> <span class="special">+=</span> <span class="special">*</span><span class="identifier">i</span><span class="special">;</span> <span class="comment">// For-loop body.</span> 958<span class="special">}</span> 959</pre> 960<p> 961 </p> 962<p> 963 More in general, <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 964 can be used to program preconditions, postconditions, and exception guarantees 965 of any block of code in a given function. For example (see <a href="../../../example/features/code_block.cpp" target="_top"><code class="literal">code_block.cpp</code></a>): 966 </p> 967<p> 968</p> 969<pre class="programlisting"><span class="comment">/* ... */</span> 970 971<span class="comment">// Contract for a code block.</span> 972<span class="special">{</span> <span class="comment">// Code block entry (check preconditions).</span> 973 <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_total</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">total</span><span class="special">);</span> 974 <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> 975 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 976 <span class="identifier">BOOST_CONTRACT_ASSERT</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="special">==</span> <span class="number">3</span><span class="special">);</span> 977 <span class="special">})</span> 978 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 979 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">total</span> <span class="special">==</span> <span class="special">*</span><span class="identifier">old_total</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="identifier">v</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">+</span> <span class="identifier">v</span><span class="special">[</span><span class="number">2</span><span class="special">]);</span> 980 <span class="special">})</span> 981 <span class="special">;</span> 982 983 <span class="identifier">total</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="identifier">v</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">+</span> <span class="identifier">v</span><span class="special">[</span><span class="number">2</span><span class="special">];</span> <span class="comment">// Code block body.</span> 984<span class="special">}</span> <span class="comment">// Code block exit (check postconditions and exceptions guarantees).</span> 985 986<span class="comment">/* ... */</span> 987</pre> 988<p> 989 </p> 990<p> 991 The library does not support contracts for functions and classes declared 992 <code class="computeroutput"><span class="keyword">constexpr</span></code>. <a href="#ftn.boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__.f0" class="footnote" name="boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__.f0"><sup class="footnote">[58]</sup></a> 993 </p> 994</div> 995<div class="section"> 996<div class="titlepage"><div><div><h3 class="title"> 997<a name="boost_contract.advanced.implementation_checks"></a><a class="link" href="advanced.html#boost_contract.advanced.implementation_checks" title="Implementation Checks">Implementation 998 Checks</a> 999</h3></div></div></div> 1000<p> 1001 This library provides also a mechanism to check assertions within implementation 1002 code (differently from preconditions, postconditions, exceptions guarantees, 1003 and class invariants that are instead checked before or after code that implements 1004 a function body). These <span class="emphasis"><em>implementation checks</em></span> are programmed 1005 using a nullary functor that is directly assigned to a <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1006 object declaration right at the place within the code where the checks need 1007 to be performed (without calling <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code>, 1008 <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>, 1009 etc. in this case). For example (see <a href="../../../example/features/check.cpp" target="_top"><code class="literal">check.cpp</code></a>): 1010 </p> 1011<p> 1012</p> 1013<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span> 1014 <span class="comment">// Implementation checks (via nullary functor).</span> 1015 <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="special">[]</span> <span class="special">{</span> 1016 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">gcd</span><span class="special">(</span><span class="number">12</span><span class="special">,</span> <span class="number">28</span><span class="special">)</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span> 1017 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">gcd</span><span class="special">(</span><span class="number">4</span><span class="special">,</span> <span class="number">14</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span> 1018 <span class="special">};</span> 1019 1020 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 1021<span class="special">}</span> 1022</pre> 1023<p> 1024 </p> 1025<p> 1026 The implementation check functor should capture all the variables that it 1027 needs for its assertions. These variables can be captured by value when the 1028 overhead of copying such variables is acceptable. In any case, programmers 1029 should not write implementation checks that modify the value of the captured 1030 variables, even when those are captured by reference (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 1031 </p> 1032<p> 1033 Any code can be programmed in the implementation check functor, but it is 1034 recommended to keep this code simple using mainly assertions and if-statements 1035 (to avoid programming complex checks that might be buggy and also slow to 1036 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> 1037 to program the assertions because that enables this library to print informative 1038 error messages when the asserted conditions are evaluated to be false (note 1039 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 1040 Macros</a>): 1041 </p> 1042<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> 1043<span class="comment">// Or, if `boolean-condition` contains commas `,` not already within parenthesis `()`...</span> 1044<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> 1045</pre> 1046<p> 1047 This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/check_failure.html" title="Function check_failure">boost::contract::check_failure</a></code> 1048 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> 1049 conditions are false or, more in general, if calling the implementation check 1050 functor throws any exception. By default, this failure handler prints an 1051 error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and terminates the program calling 1052 <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 1053 on Failures</a> to change the failure handler to throw exceptions, exit 1054 the program with an error code, etc.). 1055 </p> 1056<p> 1057 Similarly to the C-style <code class="computeroutput"><span class="identifier">assert</span></code> 1058 macro that is disabled when <code class="computeroutput"><span class="identifier">NDEBUG</span></code> 1059 is defined, implementation checks are disabled when <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_CHECKS.html" title="Macro BOOST_CONTRACT_NO_CHECKS">BOOST_CONTRACT_NO_CHECKS</a></code> 1060 is defined (see <a class="link" href="extras.html#boost_contract.extras.disable_contract_checking" title="Disable Contract Checking">Disable 1061 Contract Checking</a>). That will skip all implementation checks at run-time 1062 but it will not eliminate some of the overhead of executing and compiling 1063 the related <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1064 declarations. Alternatively, this library provides the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_CHECK.html" title="Macro BOOST_CONTRACT_CHECK">BOOST_CONTRACT_CHECK</a></code> 1065 macro that allows to completely remove run- and compile-time overheads of 1066 implementation checks when <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_CHECKS.html" title="Macro BOOST_CONTRACT_NO_CHECKS">BOOST_CONTRACT_NO_CHECKS</a></code> 1067 is defined (note that this is not a variadic macro): 1068 </p> 1069<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_CHECK</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span> 1070<span class="comment">// Or, if `boolean-condition` contains commas `,` not already within parenthesis `()`...</span> 1071<span class="identifier">BOOST_CONTRACT_CHECK</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> 1072</pre> 1073<p> 1074 For example (see <a href="../../../example/features/check_macro.cpp" target="_top"><code class="literal">check_macro.cpp</code></a>): 1075 </p> 1076<p> 1077</p> 1078<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span> 1079 <span class="comment">// Implementation checks (via macro, disable run-/compile-time overhead).</span> 1080 <span class="identifier">BOOST_CONTRACT_CHECK</span><span class="special">(</span><span class="identifier">gcd</span><span class="special">(</span><span class="number">12</span><span class="special">,</span> <span class="number">28</span><span class="special">)</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span> 1081 <span class="identifier">BOOST_CONTRACT_CHECK</span><span class="special">(</span><span class="identifier">gcd</span><span class="special">(</span><span class="number">4</span><span class="special">,</span> <span class="number">14</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span> 1082 1083 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 1084<span class="special">}</span> 1085</pre> 1086<p> 1087 </p> 1088<p> 1089 The <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_CHECK.html" title="Macro BOOST_CONTRACT_CHECK">BOOST_CONTRACT_CHECK</a></code> 1090 macro is similar to the C-style assert macro as it accepts a boolean condition 1091 (instead of a nullary functor like <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code> 1092 does). <a href="#ftn.boost_contract.advanced.implementation_checks.f0" class="footnote" name="boost_contract.advanced.implementation_checks.f0"><sup class="footnote">[59]</sup></a> Using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_CHECK.html" title="Macro BOOST_CONTRACT_CHECK">BOOST_CONTRACT_CHECK</a></code> 1093 is essentially equivalent to using the C-style <code class="computeroutput"><span class="identifier">assert</span></code> 1094 macro a part from the following: 1095 </p> 1096<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1097<li class="listitem"> 1098 Implementation checks are disabled defining <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_CHECKS.html" title="Macro BOOST_CONTRACT_NO_CHECKS">BOOST_CONTRACT_NO_CHECKS</a></code> 1099 (instead of <code class="computeroutput"><span class="identifier">NDEBUG</span></code> for 1100 disabling <code class="computeroutput"><span class="identifier">assert</span></code>). 1101 </li> 1102<li class="listitem"> 1103 If the asserted boolean condition is either false or it throws an exception 1104 then this library will call <code class="computeroutput"><a class="link" href="../boost/contract/check_failure.html" title="Function check_failure">boost::contract::check_failure</a></code> 1105 (instead <code class="computeroutput"><span class="identifier">assert</span></code> calls 1106 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">abort</span></code> if the asserted condition is 1107 false and it unwinds the stack if evaluating the condition throws an 1108 exception). 1109 </li> 1110<li class="listitem"> 1111 Implementation checks are automatically disabled when other contract 1112 conditions specified using this library are already being checked (to 1113 avoid infinite recursion, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585491840.html" title="Macro BOOST_CONTRACT_ALL_DISABLE_NO_ASSERTION">BOOST_CONTRACT_ALL_DISABLE_NO_ASSERTION</a></code>). 1114 </li> 1115</ul></div> 1116</div> 1117<div class="section"> 1118<div class="titlepage"><div><div><h3 class="title"> 1119<a name="boost_contract.advanced.old_values_copied_at_body"></a><a class="link" href="advanced.html#boost_contract.advanced.old_values_copied_at_body" title="Old Values Copied at Body">Old 1120 Values Copied at Body</a> 1121</h3></div></div></div> 1122<p> 1123 In the examples seen so far, old value variables of type <code class="computeroutput"><a class="link" href="../boost/contract/old_ptr.html" title="Class template old_ptr">boost::contract::old_ptr</a></code> 1124 are initialized to a copy of the expression passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1125 as soon as they are declared. That correctly happens before the function 1126 body is executed but also before the contract is declared, therefore even 1127 before class invariants (for public functions) and preconditions are checked 1128 at function entry. This might work well in most practical cases however, 1129 technically speaking, old values should be copied before executing the function 1130 body but <span class="emphasis"><em>after</em></span> checking class invariants and preconditions 1131 at function entry (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.assertions" title="Assertions">Assertions</a>). 1132 Specifically, there could be cases in which it makes sense to evaluate the 1133 expressions passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1134 only under the assumption that assertions programmed in class invariants 1135 and preconditions are true. 1136 </p> 1137<p> 1138 This library allows to construct <code class="computeroutput"><a class="link" href="../boost/contract/old_ptr.html" title="Class template old_ptr">boost::contract::old_ptr</a></code> 1139 variables using their default constructor (equivalent to a null pointer) 1140 and then to later assign them to a copy of the expression specified by <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> in a nullary 1141 functor <code class="literal"><span class="emphasis"><em>d</em></span></code><code class="computeroutput"><span class="special">()</span></code> 1142 passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>d</em></span></code><code class="computeroutput"><span class="special">)</span></code>. The functor <code class="literal"><span class="emphasis"><em>d</em></span></code><code class="computeroutput"><span class="special">()</span></code> is called by this library before the function 1143 body is executed but only after class invariants and preconditions are checked. 1144 Old value assignments via <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> 1145 must appear after preconditions but before postconditions and exception guarantees 1146 wen these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>, 1147 <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>, 1148 and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception 1149 Guarantees</a>). <a href="#ftn.boost_contract.advanced.old_values_copied_at_body.f0" class="footnote" name="boost_contract.advanced.old_values_copied_at_body.f0"><sup class="footnote">[60]</sup></a> 1150 </p> 1151<p> 1152 For example, the following old value expression <code class="computeroutput"><span class="identifier">s</span><span class="special">[</span><span class="identifier">index</span><span class="special">]</span></code> passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1153 is valid only after the precondition has checked that <code class="computeroutput"><span class="identifier">index</span></code> 1154 is within the valid range <code class="computeroutput"><span class="identifier">index</span> 1155 <span class="special"><</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span></code>. 1156 Therefore, <code class="computeroutput"><span class="identifier">old_char</span></code> is first 1157 declared using its default constructor (i.e., initialized to a null pointer) 1158 and later assigned to a copy of <code class="computeroutput"><span class="identifier">s</span><span class="special">[</span><span class="identifier">index</span><span class="special">]</span></code> in <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> 1159 after the precondition has checked <code class="computeroutput"><span class="identifier">index</span></code> 1160 (see <a href="../../../example/features/old.cpp" target="_top"><code class="literal">old.cpp</code></a>): 1161 </p> 1162<p> 1163</p> 1164<pre class="programlisting"><span class="keyword">char</span> <span class="identifier">replace</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">s</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">index</span><span class="special">,</span> <span class="keyword">char</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> 1165 <span class="keyword">char</span> <span class="identifier">result</span><span class="special">;</span> 1166 <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">char</span><span class="special">></span> <span class="identifier">old_char</span><span class="special">;</span> <span class="comment">// Null, old value copied later...</span> 1167 <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> 1168 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 1169 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">index</span> <span class="special"><</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span> 1170 <span class="special">})</span> 1171 <span class="special">.</span><span class="identifier">old</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// ...after preconditions (and invariants) checked.</span> 1172 <span class="identifier">old_char</span> <span class="special">=</span> <span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">s</span><span class="special">[</span><span class="identifier">index</span><span class="special">]);</span> 1173 <span class="special">})</span> 1174 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 1175 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">s</span><span class="special">[</span><span class="identifier">index</span><span class="special">]</span> <span class="special">==</span> <span class="identifier">x</span><span class="special">);</span> 1176 <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_char</span><span class="special">);</span> 1177 <span class="special">})</span> 1178 <span class="special">;</span> 1179 1180 <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">s</span><span class="special">[</span><span class="identifier">index</span><span class="special">];</span> 1181 <span class="identifier">s</span><span class="special">[</span><span class="identifier">index</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> 1182 <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> 1183<span class="special">}</span> 1184</pre> 1185<p> 1186 </p> 1187<p> 1188 The functor passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> should capture all the variables that 1189 it needs to evaluate the old value expressions passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>. 1190 In general, these variables should be captured by reference and not by value 1191 (because old values need to copy the values the captured variables will have 1192 just before executing the function body, and not the values these variables 1193 had when the functor passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> 1194 was first declared). In any case, programmers should write the functor passed 1195 to <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> so that it modifies only old values 1196 and not the values of other captured variables, even when those are captured 1197 by reference (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 1198 </p> 1199<p> 1200 This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/old_failure.html" title="Function old_failure">boost::contract::old_failure</a></code> 1201 if calling the functor specified via <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> 1202 throws an exception (by default, this handler prints an error message to 1203 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and terminates the program calling 1204 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code>, but see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 1205 on Failures</a> to throw exceptions, exit the program with an error code, 1206 etc.). 1207 </p> 1208<div class="note"><table border="0" summary="Note"> 1209<tr> 1210<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1211<th align="left">Note</th> 1212</tr> 1213<tr><td align="left" valign="top"><p> 1214 If old value pointers are initialized at the point of their construction 1215 instead of using <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> then an exception thrown by the old 1216 value expression passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>, 1217 or more in general any exception thrown by the old value pointer initialization, 1218 will result in that exception being thrown up the stack by the enclosing 1219 function. This is arguably less correct than calling <code class="computeroutput"><a class="link" href="../boost/contract/old_failure.html" title="Function old_failure">boost::contract::old_failure</a></code> 1220 because an exception thrown by an old value copy causes the program to 1221 fail to check its postconditions and exception guarantees but should not 1222 automatically causes the enclosing function to thrown an exception (this 1223 might not be a significant difference in practice, but it could be an additional 1224 reason to use <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> instead of assigning old values when 1225 they are declared before the contract). <a href="#ftn.boost_contract.advanced.old_values_copied_at_body.f1" class="footnote" name="boost_contract.advanced.old_values_copied_at_body.f1"><sup class="footnote">[61]</sup></a> 1226 </p></td></tr> 1227</table></div> 1228</div> 1229<div class="section"> 1230<div class="titlepage"><div><div><h3 class="title"> 1231<a name="boost_contract.advanced.named_overrides"></a><a class="link" href="advanced.html#boost_contract.advanced.named_overrides" title="Named Overrides">Named Overrides</a> 1232</h3></div></div></div> 1233<p> 1234 As seen in <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 1235 Function Overrides</a>, the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1236 macro has to be used to declare the type <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> that is passed as an explicit template 1237 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> 1238 for public function overrides. The function names passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1239 (and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDES.html" title="Macro BOOST_CONTRACT_OVERRIDES">BOOST_CONTRACT_OVERRIDES</a></code>) 1240 should never start with an underscore to avoid generating names containing 1241 double underscores <code class="computeroutput"><span class="identifier">override__</span><span class="special">...</span></code> (because all symbols containing double 1242 underscores <code class="computeroutput"><span class="special">...</span><span class="identifier">__</span><span class="special">...</span></code> are reserved symbols in the C++ standard). 1243 There is a separate macro <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 1244 that can be used to explicitly specify the name of the type being declared: 1245 <a href="#ftn.boost_contract.advanced.named_overrides.f0" class="footnote" name="boost_contract.advanced.named_overrides.f0"><sup class="footnote">[62]</sup></a> 1246 </p> 1247<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> <span class="comment">// Generate `override_...`.</span> 1248<span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDE</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>type-name</em></span></code><span class="special">,</span> <code class="literal"><span class="emphasis"><em>function-name</em></span></code><span class="special">)</span> <span class="comment">// Generate `type-name`.</span> 1249</pre> 1250<p> 1251 For example, the following public function override is named <code class="computeroutput"><span class="identifier">_1</span></code> so <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">_1</span><span class="special">)</span></code> 1252 would declare a type named <code class="computeroutput"><span class="identifier">override__1</span></code> 1253 (which is reserved symbol in C++ because it contains a double underscore 1254 <code class="computeroutput"><span class="identifier">__</span></code>), thus <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDE</span><span class="special">(</span><span class="identifier">override1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span></code> 1255 is used to name the type <code class="computeroutput"><span class="identifier">override1</span></code> 1256 instead (see <a href="../../../example/features/named_override.cpp" target="_top"><code class="literal">named_override.cpp</code></a>): 1257 </p> 1258<p> 1259</p> 1260<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 1261<span class="keyword">class</span> <span class="identifier">positive_unary_pack</span> 1262 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">public</span> <span class="identifier">generic_unary_pack</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> 1263 <span class="special">:</span> <span class="identifier">BASES</span> 1264<span class="special">{</span> 1265<span class="keyword">public</span><span class="special">:</span> 1266 <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> 1267 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> 1268 1269 <span class="comment">// BOOST_CONTRACT_OVERRIDE(_1) would generate reserved name `override__1`.</span> 1270 <span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDE</span><span class="special">(</span><span class="identifier">override1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="comment">// Generate `override1`.</span> 1271 1272 <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">_1</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</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> 1273 <span class="comment">/* override */</span> <span class="special">{</span> 1274 <span class="comment">// Use `override1` generated by BOOST_CONTRACT_NAMED_OVERRIDE above.</span> 1275 <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">override1</span><span class="special">>(</span> 1276 <span class="identifier">v</span><span class="special">,</span> 1277 <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(</span><span class="identifier">positive_unary_pack</span><span class="special">::*)(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&,</span> 1278 <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">positive_unary_pack</span><span class="special">::</span><span class="identifier">_1</span><span class="special">),</span> 1279 <span class="keyword">this</span><span class="special">,</span> 1280 <span class="identifier">value</span> 1281 <span class="special">)</span> 1282 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 1283 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">value</span> <span class="special">></span> <span class="number">0</span><span class="special">);</span> 1284 <span class="special">})</span> 1285 <span class="special">;</span> 1286 <span class="identifier">value1_</span> <span class="special">=</span> <span class="identifier">value</span><span class="special">;</span> 1287 <span class="special">}</span> 1288 1289 <span class="comment">/* ... */</span> 1290</pre> 1291<p> 1292 </p> 1293<p> 1294 The <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 1295 macro can also be used when the name <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> generated by <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1296 would clash with other names in user code, to generate names in CamelCase 1297 or in any other preferred style, and in any other case when programmers need 1298 or prefer to generate names different from <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code>. 1299 </p> 1300<p> 1301 Note that there is not a <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDES</span></code> 1302 macro so <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 1303 needs to be invoked separately on each function name (there is instead a 1304 <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDES.html" title="Macro BOOST_CONTRACT_OVERRIDES">BOOST_CONTRACT_OVERRIDES</a></code> 1305 macro as seen in <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 1306 Function Overrides</a>). <a href="#ftn.boost_contract.advanced.named_overrides.f1" class="footnote" name="boost_contract.advanced.named_overrides.f1"><sup class="footnote">[63]</sup></a> 1307 </p> 1308</div> 1309<div class="section"> 1310<div class="titlepage"><div><div><h3 class="title"> 1311<a name="boost_contract.advanced.access_specifiers"></a><a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a> 1312</h3></div></div></div> 1313<p> 1314 As seen thus far, this library requires programmers to decorate their classes 1315 declaring the following extra members: 1316 </p> 1317<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1318<li class="listitem"> 1319 The <code class="computeroutput"><span class="identifier">invariant</span></code> and <code class="computeroutput"><span class="identifier">static_invariant</span></code> member functions (used 1320 to check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class 1321 Invariants</a>). 1322 </li> 1323<li class="listitem"> 1324 The <code class="computeroutput"><span class="identifier">base_types</span></code> member 1325 <code class="computeroutput"><span class="keyword">typedef</span></code> declared via <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code> 1326 (used to implement subcontracting, see <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 1327 Function Overrides</a>). 1328 </li> 1329<li class="listitem"> 1330 The <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> 1331 member types declared via <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>, 1332 <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>, 1333 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDES.html" title="Macro BOOST_CONTRACT_OVERRIDES">BOOST_CONTRACT_OVERRIDES</a></code> 1334 (used to implement subcontracting for overriding functions, see <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public 1335 Function Overrides</a>). <a href="#ftn.boost_contract.advanced.access_specifiers.f0" class="footnote" name="boost_contract.advanced.access_specifiers.f0"><sup class="footnote">[64]</sup></a> 1336 </li> 1337</ul></div> 1338<p> 1339 In general, these members must be declared <code class="computeroutput"><span class="keyword">public</span></code> 1340 in the user class in order for this library to be able to access them. <a href="#ftn.boost_contract.advanced.access_specifiers.f1" class="footnote" name="boost_contract.advanced.access_specifiers.f1"><sup class="footnote">[65]</sup></a> However, programmers might need to more precisely control the 1341 public members of their classes to prevent incorrect access of encapsulated 1342 members. All these members can be declared <code class="computeroutput"><span class="keyword">private</span></code> 1343 as long as the <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 1344 class is declared as <code class="computeroutput"><span class="keyword">friend</span></code> 1345 of the user class. For example (see <a href="../../../example/features/access.cpp" target="_top"><code class="literal">access.cpp</code></a>): 1346 </p> 1347<p> 1348</p> 1349<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> 1350<span class="keyword">class</span> <span class="identifier">vector</span> 1351 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">public</span> <span class="identifier">pushable</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> 1352 <span class="special">:</span> <span class="identifier">BASES</span> 1353<span class="special">{</span> <span class="comment">// Private section of the class.</span> 1354 <span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">access</span><span class="special">;</span> <span class="comment">// Friend `access` class so...</span> 1355 1356 <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">// ...private bases.</span> 1357 <span class="preprocessor">#undef</span> <span class="identifier">BASES</span> 1358 1359 <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">// ...private invariants.</span> 1360 <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="identifier">capacity</span><span class="special">());</span> 1361 <span class="special">}</span> 1362 1363 <span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">push_back</span><span class="special">)</span> <span class="comment">// ...private overrides.</span> 1364 1365<span class="keyword">public</span><span class="special">:</span> <span class="comment">// Public section of the class.</span> 1366 <span class="keyword">void</span> <span class="identifier">push_back</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</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> 1367 <span class="comment">/* override */</span> <span class="special">{</span> 1368 <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">unsigned</span><span class="special">></span> <span class="identifier">old_size</span> <span class="special">=</span> 1369 <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> 1370 <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> 1371 <span class="identifier">override_push_back</span><span class="special">>(</span><span class="identifier">v</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vector</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">value</span><span class="special">)</span> 1372 <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> 1373 <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="identifier">max_size</span><span class="special">());</span> 1374 <span class="special">})</span> 1375 <span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> 1376 <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> 1377 <span class="special">})</span> 1378 <span class="special">;</span> 1379 1380 <span class="identifier">vect_</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">value</span><span class="special">);</span> 1381 <span class="special">}</span> 1382 1383 <span class="comment">/* ... */</span> 1384</pre> 1385<p> 1386 </p> 1387<p> 1388 This technique is not used in most examples of this documentation only for 1389 brevity. Programmers are encouraged to use <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 1390 in real production code freely as they see fit. 1391 </p> 1392<div class="warning"><table border="0" summary="Warning"> 1393<tr> 1394<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td> 1395<th align="left">Warning</th> 1396</tr> 1397<tr><td align="left" valign="top"><p> 1398 Not declaring <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 1399 friend of user classes might cause compiler errors on some compilers (e.g., 1400 MSVC) because the private members needed to check the contracts will not 1401 be accessible. On other compilers (e.g., GCC and Clang), the private access 1402 level will instead fail SFINAE and no compiler error will be reported while 1403 invariants and subcontracting will be silently skipped at run-time. Therefore, 1404 programmers should always make sure to either declare invariant functions 1405 and base types <code class="computeroutput"><span class="keyword">typedef</span></code> as 1406 public members or to declare <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> 1407 as friend. 1408 </p></td></tr> 1409</table></div> 1410</div> 1411<div class="section"> 1412<div class="titlepage"><div><div><h3 class="title"> 1413<a name="boost_contract.advanced.throw_on_failures__and__noexcept__"></a><a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 1414 on Failures (and <code class="computeroutput"><span class="keyword">noexcept</span></code>)</a> 1415</h3></div></div></div> 1416<p> 1417 If a condition checked using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1418 is evaluated to be false or, more in general, if any of the specified contract 1419 code throws an exception (<code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1420 simply expands to code that throws a <code class="computeroutput"><a class="link" href="../boost/contract/assertion_failure.html" title="Class assertion_failure">boost::contract::assertion_failure</a></code> 1421 exception, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 1422 Macros</a>), this library will call an appropriate <span class="emphasis"><em>contract 1423 failure handler</em></span> function as follow: 1424 </p> 1425<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1426<li class="listitem"> 1427 Preconditions: False <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1428 assertions and exceptions thrown from within <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> 1429 call <code class="computeroutput"><a class="link" href="../boost/contract/precondition_failure.html" title="Function precondition_failure">boost::contract::precondition_failure</a></code>. 1430 </li> 1431<li class="listitem"> 1432 Postconditions: False <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1433 assertions and exceptions thrown from within <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code> 1434 call <code class="computeroutput"><a class="link" href="../boost/contract/postcondition_failure.html" title="Function postcondition_failure">boost::contract::postcondition_failure</a></code>. 1435 </li> 1436<li class="listitem"> 1437 Exceptions guarantees: False <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1438 assertions and exceptions thrown from within <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span></code> 1439 call <code class="computeroutput"><a class="link" href="../boost/contract/except_failure.html" title="Function except_failure">boost::contract::except_failure</a></code>. 1440 </li> 1441<li class="listitem"> 1442 Class invariants: False <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1443 assertions and exceptions thrown from <code class="computeroutput"><span class="identifier">invariant</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">static_invariant</span><span class="special">()</span></code> call <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> 1444 when checked at function entry and <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> 1445 when checked at function exit. 1446 </li> 1447<li class="listitem"> 1448 Old values copied at body: Exceptions thrown from old values copied at 1449 body within <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> call <code class="computeroutput"><a class="link" href="../boost/contract/old_failure.html" title="Function old_failure">boost::contract::old_failure</a></code>. 1450 </li> 1451<li class="listitem"> 1452 Implementation checks: False <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1453 assertions and exceptions thrown from implementation checks <code class="computeroutput"><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> 1454 <span class="special">=</span> </code><code class="literal"><span class="emphasis"><em>nullary-functor</em></span></code> 1455 and <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_CHECK</span><span class="special">(...)</span></code> call <code class="computeroutput"><a class="link" href="../boost/contract/check_failure.html" title="Function check_failure">boost::contract::check_failure</a></code>. 1456 </li> 1457</ul></div> 1458<p> 1459 By default, these contract failure handlers print a message to the standard 1460 error <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and then terminate the program calling 1461 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code>. <a href="#ftn.boost_contract.advanced.throw_on_failures__and__noexcept__.f0" class="footnote" name="boost_contract.advanced.throw_on_failures__and__noexcept__.f0"><sup class="footnote">[66]</sup></a> However, programmers can override the default contract failure 1462 handlers to perform any custom action on contract failure using the following 1463 functions respectively: 1464 </p> 1465<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1466<li class="listitem"> 1467 Preconditions: <code class="computeroutput"><a class="link" href="../boost/contract/set_precondition_failure.html" title="Function set_precondition_failure">boost::contract::set_precondition_failure</a></code>. 1468 </li> 1469<li class="listitem"> 1470 Postconditions: <code class="computeroutput"><a class="link" href="../boost/contract/set_postcondition_failure.html" title="Function set_postcondition_failure">boost::contract::set_postcondition_failure</a></code>. 1471 </li> 1472<li class="listitem"> 1473 Exception guarantees: <code class="computeroutput"><a class="link" href="../boost/contract/set_except_failure.html" title="Function set_except_failure">boost::contract::set_except_failure</a></code>. 1474 </li> 1475<li class="listitem"> 1476 Class invariants: <code class="computeroutput"><a class="link" href="../boost/contract/set_entr_idm46268585146336.html" title="Function set_entry_invariant_failure">boost::contract::set_entry_invariant_failure</a></code> 1477 and <code class="computeroutput"><a class="link" href="../boost/contract/set_exit_invariant_failure.html" title="Function set_exit_invariant_failure">boost::contract::set_exit_invariant_failure</a></code>, 1478 or <code class="computeroutput"><a class="link" href="../boost/contract/set_invariant_failure.html" title="Function set_invariant_failure">boost::contract::set_invariant_failure</a></code> 1479 (to set both entry and exit invariant failure handlers at once for convenience). 1480 </li> 1481<li class="listitem"> 1482 Old values copied at body: <code class="computeroutput"><a class="link" href="../boost/contract/set_old_failure.html" title="Function set_old_failure">boost::contract::set_old_failure</a></code>. 1483 </li> 1484<li class="listitem"> 1485 Implementation checks: <code class="computeroutput"><a class="link" href="../boost/contract/set_check_failure.html" title="Function set_check_failure">boost::contract::set_check_failure</a></code>. 1486 </li> 1487</ul></div> 1488<p> 1489 These <code class="computeroutput"><span class="identifier">set_</span><span class="special">...</span><span class="identifier">_failure</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>f</em></span></code><code class="computeroutput"><span class="special">)</span></code> function calls return a reference to the 1490 contract failure handler functor <code class="literal"><span class="emphasis"><em>f</em></span></code> 1491 that they take as input parameter (so they can be concatenated). <a href="#ftn.boost_contract.advanced.throw_on_failures__and__noexcept__.f1" class="footnote" name="boost_contract.advanced.throw_on_failures__and__noexcept__.f1"><sup class="footnote">[67]</sup></a> For example (see <a href="../../../example/features/throw_on_failure.cpp" target="_top"><code class="literal">throw_on_failure.cpp</code></a>): 1492 </p> 1493<p> 1494</p> 1495<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span> 1496 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_precondition_failure</span><span class="special">(</span> 1497 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_postcondition_failure</span><span class="special">(</span> 1498 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_invariant_failure</span><span class="special">(</span> 1499 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_old_failure</span><span class="special">(</span> 1500 <span class="special">[]</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">from</span> <span class="identifier">where</span><span class="special">)</span> <span class="special">{</span> 1501 <span class="keyword">if</span><span class="special">(</span><span class="identifier">where</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">from_destructor</span><span class="special">)</span> <span class="special">{</span> 1502 <span class="comment">// Shall not throw from C++ destructors.</span> 1503 <span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span> <span class="special"><<</span> <span class="string">"ignored destructor contract failure"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 1504 <span class="special">}</span> <span class="keyword">else</span> <span class="keyword">throw</span><span class="special">;</span> <span class="comment">// Re-throw (assertion_failure, user-defined, etc.).</span> 1505 <span class="special">}</span> 1506 <span class="special">))));</span> 1507 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_except_failure</span><span class="special">(</span> 1508 <span class="special">[]</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">from</span><span class="special">)</span> <span class="special">{</span> 1509 <span class="comment">// Already an active exception so shall not throw another...</span> 1510 <span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span> <span class="special"><<</span> <span class="string">"ignored exception guarantee failure"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 1511 <span class="special">}</span> 1512 <span class="special">);</span> 1513 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_check_failure</span><span class="special">(</span> 1514 <span class="special">[]</span> <span class="special">{</span> 1515 <span class="comment">// But now CHECK shall not be used in destructor implementations.</span> 1516 <span class="keyword">throw</span><span class="special">;</span> <span class="comment">// Re-throw (assertion_failure, user-defined, etc.).</span> 1517 <span class="special">}</span> 1518 <span class="special">);</span> 1519 1520 <span class="comment">/* ... */</span> 1521</pre> 1522<p> 1523 </p> 1524<p> 1525 When programming custom failure handlers that trow exceptions instead of 1526 terminating the program, programmers should be wary of the following: 1527 </p> 1528<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1529<li class="listitem"> 1530 In order to comply with C++ and STL exception safety, destructors should 1531 never throw (in fact destructors are implicitly declared <code class="computeroutput"><span class="keyword">noexcept</span></code> since C++11). This library passes 1532 a <code class="computeroutput"><a class="link" href="../boost/contract/from.html" title="Type from">boost::contract::from</a></code> 1533 parameter to the contract failure handlers for preconditions, postconditions, 1534 class invariants, and old values copied at body (see <code class="computeroutput"><a class="link" href="../boost/contract/precondition_failure.html" title="Function precondition_failure">boost::contract::precondition_failure</a></code>, 1535 <code class="computeroutput"><a class="link" href="../boost/contract/postcondition_failure.html" title="Function postcondition_failure">boost::contract::postcondition_failure</a></code>, 1536 <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>, 1537 <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>, 1538 and <code class="computeroutput"><a class="link" href="../boost/contract/old_failure.html" title="Function old_failure">boost::contract::old_failure</a></code> 1539 respectively). This <code class="computeroutput"><a class="link" href="../boost/contract/from.html" title="Type from">boost::contract::from</a></code> 1540 parameter indicates if the contract failure occurred in a destructor, 1541 constructor, or function call so programmers can use it to code custom 1542 contract failure hander functions that never throw from destructors. 1543 (In the example above, contract failures from destructors are simply 1544 ignored even if that is probably never a safe thing to do in real production 1545 code.) 1546 </li> 1547<li class="listitem"> 1548 C++ stack-unwinding will execute base class destructors even when the 1549 derived class destructor trows an exception. Therefore, the contracts 1550 of base class destructors will continue to be checked when contract failure 1551 handlers are programmed to throw exceptions on contract failures from 1552 destructors (yet another reason not to throw exceptions from destructors, 1553 not even because of contract failures). 1554 </li> 1555<li class="listitem"> 1556 The contract failure handler for exception guarantees <code class="computeroutput"><a class="link" href="../boost/contract/except_failure.html" title="Function except_failure">boost::contract::except_failure</a></code> 1557 should never throw (regardless of the value of its <code class="computeroutput"><a class="link" href="../boost/contract/from.html" title="Type from">boost::contract::from</a></code> 1558 parameter) because when <code class="computeroutput"><a class="link" href="../boost/contract/except_failure.html" title="Function except_failure">boost::contract::except_failure</a></code> 1559 is called there is already an active exception on the stack, the exception 1560 that triggered the exception guarantees to be checked in the first place 1561 (throwing an exception while there is already an active exception will 1562 force program termination or lead to undefined behaviour in C++). 1563 </li> 1564<li class="listitem"> 1565 Implementation checks can appear in any code, including destructor implementation 1566 code, so <code class="computeroutput"><a class="link" href="../boost/contract/check_failure.html" title="Function check_failure">boost::contract::check_failure</a></code> 1567 should also never throw, or implementation checks should never be used 1568 in destructors otherwise these destructors will throw (note that <code class="computeroutput"><a class="link" href="../boost/contract/check_failure.html" title="Function check_failure">boost::contract::check_failure</a></code> 1569 does not provide the <code class="computeroutput"><a class="link" href="../boost/contract/from.html" title="Type from">boost::contract::from</a></code> 1570 parameter so it is not possible to differentiate from implementation 1571 checks failing from destructors instead than from other parts of the 1572 code). 1573 </li> 1574</ul></div> 1575<div class="note"><table border="0" summary="Note"> 1576<tr> 1577<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 1578<th align="left">Note</th> 1579</tr> 1580<tr><td align="left" valign="top"><p> 1581 Programmers need to decide how to handle contract failures from destructors 1582 when they write custom contract failure handlers that throw exceptions 1583 instead of terminating the program (given that C++ and STL exception safety 1584 rules requires destructors to never throw). This is not a simple dilemma 1585 and it might be a good reason to terminate the program instead of throwing 1586 exceptions when assertions fail in C++ (as this library and also C-style 1587 <code class="computeroutput"><span class="identifier">assert</span></code> do by default). 1588 </p></td></tr> 1589</table></div> 1590<h5> 1591<a name="boost_contract.advanced.throw_on_failures__and__noexcept__.h0"></a> 1592 <span class="phrase"><a name="boost_contract.advanced.throw_on_failures__and__noexcept__.throw_user_defined_exceptions"></a></span><a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__.throw_user_defined_exceptions">Throw 1593 User-Defined Exceptions</a> 1594 </h5> 1595<p> 1596 Contract assertions can be programmed to throw <code class="computeroutput"><a class="link" href="../boost/contract/assertion_failure.html" title="Class assertion_failure">boost::contract::assertion_failure</a></code> 1597 using <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>condition</em></span></code><code class="computeroutput"><span class="special">)</span></code> as we have seen so far (see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 1598 Macros</a>). Alternatively, contract assertions can be programmed to throw 1599 any other exception (including user-defined exceptions) using code similar 1600 to the following: 1601 </p> 1602<pre class="programlisting"><span class="keyword">if</span><span class="special">(!</span><code class="literal"><span class="emphasis"><em>condition</em></span></code><span class="special">)</span> <span class="keyword">throw</span> <code class="literal"><span class="emphasis"><em>exception-object</em></span></code><span class="special">;</span> 1603</pre> 1604<p> 1605 For example, the following precondition functor throws <code class="computeroutput"><a class="link" href="../boost/contract/assertion_failure.html" title="Class assertion_failure">boost::contract::assertion_failure</a></code> 1606 (via <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>) 1607 on its first assertion and the user-defined exception <code class="computeroutput"><span class="identifier">too_large_error</span></code> 1608 on its second assertion (both exceptions will cause this library to call 1609 the customized <code class="computeroutput"><a class="link" href="../boost/contract/precondition_failure.html" title="Function precondition_failure">boost::contract::precondition_failure</a></code> 1610 listed above which will in turn re-throw the exceptions up the stack, see 1611 <a href="../../../example/features/throw_on_failure.cpp" target="_top"><code class="literal">throw_on_failure.cpp</code></a>): 1612 </p> 1613<p> 1614</p> 1615<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">too_large_error</span> <span class="special">{};</span> 1616 1617<span class="keyword">template</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">MaxSize</span><span class="special">></span> 1618<span class="keyword">class</span> <span class="identifier">cstring</span> 1619 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">private</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">constructor_precondition</span><span class="special"><</span><span class="identifier">cstring</span><span class="special"><</span> <span class="special">\</span> 1620 <span class="identifier">MaxSize</span><span class="special">></span> <span class="special">></span> 1621 <span class="special">:</span> <span class="identifier">BASES</span> 1622<span class="special">{</span> 1623</pre> 1624<p> 1625 </p> 1626<p> 1627</p> 1628<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 1629 <span class="comment">/* implicit */</span> <span class="identifier">cstring</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">)</span> <span class="special">:</span> 1630 <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">cstring</span><span class="special">>([&]</span> <span class="special">{</span> 1631 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">chars</span><span class="special">);</span> <span class="comment">// Throw `assertion_failure`.</span> 1632 <span class="comment">// Or, throw user-defined exception.</span> 1633 <span class="keyword">if</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">strlen</span><span class="special">(</span><span class="identifier">chars</span><span class="special">)</span> <span class="special">></span> <span class="identifier">MaxSize</span><span class="special">)</span> <span class="keyword">throw</span> <span class="identifier">too_large_error</span><span class="special">();</span> 1634 <span class="special">})</span> 1635 <span class="special">{</span> 1636</pre> 1637<p> 1638 </p> 1639<p> 1640</p> 1641<pre class="programlisting"> <span class="comment">/* ... */</span> 1642<span class="special">};</span> 1643</pre> 1644<p> 1645 </p> 1646<h5> 1647<a name="boost_contract.advanced.throw_on_failures__and__noexcept__.h1"></a> 1648 <span class="phrase"><a name="boost_contract.advanced.throw_on_failures__and__noexcept__.exception_specifiers___code__phrase_role__keyword__noexcept__phrase___code__and__code__phrase_role__keyword__throw__phrase___code___"></a></span><a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__.exception_specifiers___code__phrase_role__keyword__noexcept__phrase___code__and__code__phrase_role__keyword__throw__phrase___code___">Exception 1649 Specifiers (<code class="computeroutput"><span class="keyword">noexcept</span></code> and <code class="computeroutput"><span class="keyword">throw</span></code>`)</a> 1650 </h5> 1651<p> 1652 Exception specifiers <code class="computeroutput"><span class="keyword">noexcept</span></code> 1653 (since C++11) and <code class="computeroutput"><span class="keyword">throw</span></code> (deprecated 1654 in C++11) of the enclosing function, constructor, or destructor declaring 1655 the contract correctly apply to the contract code as well. Therefore, even 1656 if the contract failure handlers are reprogrammed to throw exceptions in 1657 case of contract failures, those exceptions will never be thrown outside 1658 the context of the enclosing operation if that is not in accordance with 1659 the exception specifiers of that operation (specifically, note that all destructors 1660 are implicitly declared <code class="computeroutput"><span class="keyword">noexcept</span></code> 1661 in C++11). 1662 </p> 1663<p> 1664 For example, the following code will correctly never throw from the <code class="computeroutput"><span class="keyword">noexcept</span></code> destructor, not even if the class 1665 invariants checked at destructor entry throw <code class="computeroutput"><span class="identifier">too_large_error</span></code> 1666 and the contract failure handlers for invariants are programmed to throw 1667 from destructors (the program will always terminate in this case instead, 1668 see <a href="../../../example/features/throw_on_failure.cpp" target="_top"><code class="literal">throw_on_failure.cpp</code></a>): 1669 </p> 1670<p> 1671</p> 1672<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">too_large_error</span> <span class="special">{};</span> 1673 1674<span class="keyword">template</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">MaxSize</span><span class="special">></span> 1675<span class="keyword">class</span> <span class="identifier">cstring</span> 1676 <span class="preprocessor">#define</span> <span class="identifier">BASES</span> <span class="keyword">private</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">constructor_precondition</span><span class="special"><</span><span class="identifier">cstring</span><span class="special"><</span> <span class="special">\</span> 1677 <span class="identifier">MaxSize</span><span class="special">></span> <span class="special">></span> 1678 <span class="special">:</span> <span class="identifier">BASES</span> 1679<span class="special">{</span> 1680</pre> 1681<p> 1682 </p> 1683<p> 1684</p> 1685<pre class="programlisting"><span class="keyword">public</span><span class="special">:</span> 1686 <span class="keyword">void</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> 1687 <span class="keyword">if</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">></span> <span class="identifier">MaxSize</span><span class="special">)</span> <span class="keyword">throw</span> <span class="identifier">too_large_error</span><span class="special">();</span> <span class="comment">// Throw user-defined ex.</span> 1688 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">chars_</span><span class="special">);</span> <span class="comment">// Or, throw `assertion_failure`.</span> 1689 <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">chars_</span><span class="special">[</span><span class="identifier">size</span><span class="special">()]</span> <span class="special">==</span> <span class="char">'\0'</span><span class="special">);</span> 1690 <span class="special">}</span> 1691 1692 <span class="special">~</span><span class="identifier">cstring</span><span class="special">()</span> <span class="keyword">noexcept</span> <span class="special">{</span> <span class="comment">// Exception specifiers apply to contract code.</span> 1693 <span class="comment">// Check invariants.</span> 1694 <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> 1695 <span class="special">}</span> 1696</pre> 1697<p> 1698 </p> 1699<p> 1700</p> 1701<pre class="programlisting"> <span class="comment">/* ... */</span> 1702<span class="special">};</span> 1703</pre> 1704<p> 1705 </p> 1706<p> 1707</p> 1708<pre class="programlisting"><span class="comment">/* ... */</span> 1709 1710<span class="comment">// Warning... might cause destructors to throw (unless declared noexcept).</span> 1711<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">set_invariant_failure</span><span class="special">(</span> 1712 <span class="special">[]</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">from</span><span class="special">)</span> <span class="special">{</span> 1713 <span class="keyword">throw</span><span class="special">;</span> <span class="comment">// Throw no matter if from destructor, etc.</span> 1714 <span class="special">}</span> 1715<span class="special">);</span> 1716 1717<span class="comment">/* ... */</span> 1718</pre> 1719<p> 1720 </p> 1721</div> 1722<div class="footnotes"> 1723<br><hr style="width:100; text-align:left;margin-left: 0"> 1724<div id="ftn.boost_contract.advanced.pure_virtual_public_functions.f0" class="footnote"><p><a href="#boost_contract.advanced.pure_virtual_public_functions.f0" class="para"><sup class="para">[52] </sup></a> 1725 This consequence of the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 1726 principle</a> <span class="quote">“<span class="quote">that if any function in an inheritance hierarchy 1727 has no preconditions, then preconditions on functions overriding it have 1728 no useful effect</span>”</span> is also explicitly mentioned in the contract documentation 1729 of the D Programming Language (see <a class="link" href="bibliography.html#Bright04_anchor">[Bright04]</a>). 1730 </p></div> 1731<div id="ftn.boost_contract.advanced.optional_return_values.f0" class="footnote"><p><a href="#boost_contract.advanced.optional_return_values.f0" class="para"><sup class="para">[53] </sup></a> 1732 <span class="bold"><strong>Rationale:</strong></span> This library uses <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> instead of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">optional</span></code> 1733 to support a larger number of compilers and their versions (because <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">optional</span></code> was not available before C++17). 1734 </p></div> 1735<div id="ftn.boost_contract.advanced.optional_return_values.f1" class="footnote"><p><a href="#boost_contract.advanced.optional_return_values.f1" class="para"><sup class="para">[54] </sup></a> 1736 <span class="bold"><strong>Rationale:</strong></span> This library requires the postcondition 1737 functor parameter to be of type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><...</span> <span class="keyword">const</span><span class="special">&></span></code> so the return value does not have 1738 to be copied (because of <code class="computeroutput"><span class="special">&</span></code>) 1739 while postconditions are still not allowed to change its value (because 1740 of <code class="computeroutput"><span class="keyword">const</span></code>, see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>). 1741 In addition, programmers are encouraged to declare the postcondition functor 1742 to take its argument also as a constant reference <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><...</span> <span class="keyword">const</span><span class="special">&></span> <span class="keyword">const</span><span class="special">&</span></code> to avoid possibly expensive copies 1743 of the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> type itself. 1744 </p></div> 1745<div id="ftn.boost_contract.advanced.private_and_protected_functions.f0" class="footnote"><p><a href="#boost_contract.advanced.private_and_protected_functions.f0" class="para"><sup class="para">[55] </sup></a> 1746 Technically, the extra virtual parameter can still be passed to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> but that is 1747 not necessary and it has no effect so it is not done in this documentation. 1748 </p></div> 1749<div id="ftn.boost_contract.advanced.friend_functions.f0" class="footnote"><p><a href="#boost_contract.advanced.friend_functions.f0" class="para"><sup class="para">[56] </sup></a> 1750 <span class="bold"><strong>Rationale:</strong></span> Contract programming proposals 1751 for C++ like <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> do not provide 1752 a mechanism for friend functions to check class invariants of objects passed 1753 as parameters. In other words, these proposals do not enable contracts 1754 to recognize that in C++ some friend functions logically act as if they 1755 were part of the public interface of the objects they take as parameters. 1756 This is reasonable for proposals that add contracts to the core language 1757 because friend functions are not always meant to extend an object public 1758 interface and C++ does not provide a mechanism to programmatically specify 1759 when they do and when they do not. However, this library provides the flexibility 1760 to let programmers manually specify when friend functions should also check 1761 class invariants of the objects they take as parameters (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>) 1762 and when they should not (using <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code> 1763 instead). 1764 </p></div> 1765<div id="ftn.boost_contract.advanced.function_overloads.f0" class="footnote"><p><a href="#boost_contract.advanced.function_overloads.f0" class="para"><sup class="para">[57] </sup></a> 1766 <span class="bold"><strong>Rationale:</strong></span> In order to avoid copies, this 1767 library takes all function arguments and the return value passed 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> 1768 as references when used within public function overrides. Therefore, the 1769 library cannot differentiate when the actual function argument and return 1770 types are passed by reference and when they are not. As a result, the library 1771 cannot automatically reconstruct the type of the enclosing public function 1772 so this type must be deduced from the function pointer passed by programmers 1773 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>. 1774 When this automatic deduction is not possible due to overloaded function 1775 names, programmers must explicitly use <code class="computeroutput"><span class="keyword">static_cast</span></code> 1776 to resolve ambiguities as usual in C++ with pointers to overloaded functions. 1777 </p></div> 1778<div id="ftn.boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__.f0" class="footnote"><p><a href="#boost_contract.advanced.lambdas__loops__code_blocks__and__constexpr__.f0" class="para"><sup class="para">[58] </sup></a> 1779 <span class="bold"><strong>Rationale:</strong></span> In general, it might be useful 1780 to specify contracts for <code class="computeroutput"><span class="keyword">constexpr</span></code> 1781 functions and literal classes. However, the current implementation of this 1782 library cannot support contracts for <code class="computeroutput"><span class="keyword">constexpr</span></code> 1783 functions and classes because C++ does not currently allow <code class="computeroutput"><span class="keyword">constexpr</span></code> functions to do the following: 1784 Declare local variables of (literal) types with non-trivial <code class="computeroutput"><span class="keyword">constexpr</span></code> destructors (this RAII technique 1785 is used by this library to check invariants, postconditions, and exceptions 1786 guarantees at exit); Call other <code class="computeroutput"><span class="keyword">constexpr</span></code> 1787 functions using try-catch statements (used by this library to report contract 1788 assertion failures and catch any other exception that might be thrown when 1789 evaluating the asserted conditions); Use lambda functions (used by this 1790 library for convenience to program functors that that check preconditions, 1791 postconditions, and exception guarantees). Also note that even if supported, 1792 contracts for <code class="computeroutput"><span class="keyword">constexpr</span></code> functions 1793 probably would not use old values (because <code class="computeroutput"><span class="keyword">constexpr</span></code> 1794 prevents functions from having any side effect visible to the caller and 1795 variables recording such side-effects are usually the candidates for old 1796 value copies) and subcontracting (because <code class="computeroutput"><span class="keyword">constexpr</span></code> 1797 functions cannot be virtual). 1798 </p></div> 1799<div id="ftn.boost_contract.advanced.implementation_checks.f0" class="footnote"> 1800<p><a href="#boost_contract.advanced.implementation_checks.f0" class="para"><sup class="para">[59] </sup></a> 1801 Of course, nothing prevents programmers from calling functors within <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_CHECK.html" title="Macro BOOST_CONTRACT_CHECK">BOOST_CONTRACT_CHECK</a></code> to specify 1802 boolean conditions when if-guards and other statements are required to 1803 assert the implementation checks. For example, programmers can use C++11 1804 lambda functions to define and call such functors in place where the implementation 1805 checks are specified: 1806</p> 1807<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_CHECK</span><span class="special">([&]</span> <span class="special">-></span> <span class="keyword">bool</span> <span class="special">{</span> 1808 <span class="keyword">if</span><span class="special">(</span><span class="identifier">even_numbers</span><span class="special">)</span> <span class="keyword">return</span> <span class="identifier">gcd</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span><span class="special">;</span> 1809 <span class="keyword">else</span> <span class="keyword">return</span> <span class="identifier">gcd</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">==</span> <span class="number">3</span><span class="special">;</span> 1810<span class="special">}</span> <span class="special">());</span> 1811</pre> 1812<p> 1813 </p> 1814</div> 1815<div id="ftn.boost_contract.advanced.old_values_copied_at_body.f0" class="footnote"><p><a href="#boost_contract.advanced.old_values_copied_at_body.f0" class="para"><sup class="para">[60] </sup></a> 1816 <span class="bold"><strong>Rationale:</strong></span> Functors for preconditions, 1817 old value assignments, postconditions, and exception guarantees are all 1818 optional but when specified, they must be specified in that order. Such 1819 order is enforced by the fact that <code class="computeroutput"><a class="link" href="../boost/contract/specify__idm46268584991504.html" title="Class template specify_precondition_old_postcondition_except">boost::contract::specify_precondition_old_postcondition_except</a></code>, 1820 <code class="computeroutput"><a class="link" href="../boost/contract/specify__idm46268585058320.html" title="Class template specify_old_postcondition_except">boost::contract::specify_old_postcondition_except</a></code>, 1821 <code class="computeroutput"><a class="link" href="../boost/contract/specify__idm46268585020256.html" title="Class template specify_postcondition_except">boost::contract::specify_postcondition_except</a></code>, 1822 <code class="computeroutput"><a class="link" href="../boost/contract/specify_except.html" title="Class specify_except">boost::contract::specify_except</a></code>, 1823 and <code class="computeroutput"><a class="link" href="../boost/contract/specify_nothing.html" title="Class specify_nothing">boost::contract::specify_nothing</a></code> 1824 provide a progressively smaller subset of their <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code>, 1825 <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code>, <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code>, 1826 and <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span></code> member functions. The enforced order 1827 for specifying preconditions, old value assignments, postconditions, and 1828 exception guarantees makes logical sense because it follows the order at 1829 which these are executed at run-time. Other contract programming frameworks 1830 allow to mix this order, that could have been implemented for this library 1831 as well but it would have complicated somewhat the library implementation 1832 while adding no real value (arguably creating confusion in user code by 1833 not enforcing a consistent order for specifying contract conditions). 1834 </p></div> 1835<div id="ftn.boost_contract.advanced.old_values_copied_at_body.f1" class="footnote"><p><a href="#boost_contract.advanced.old_values_copied_at_body.f1" class="para"><sup class="para">[61] </sup></a> 1836 <span class="bold"><strong>Rationale:</strong></span> It would be possible for 1837 this library to internally wrap all old value operations (<code class="computeroutput"><a class="link" href="../boost/contract/old_ptr.html" title="Class template old_ptr">boost::contract::old_ptr</a></code> copy 1838 constructor, <code class="computeroutput"><a class="link" href="../boost/contract/make_old_idm46268584781184.html" title="Function make_old">boost::contract::make_old</a></code>, 1839 etc.) with try-catch statements so to call <code class="computeroutput"><a class="link" href="../boost/contract/old_failure.html" title="Function old_failure">boost::contract::old_failure</a></code> 1840 also when old values are copied when they are constructed outside <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code>. However, that will prevent this 1841 library from knowing the <code class="computeroutput"><a class="link" href="../boost/contract/from.html" title="Type from">boost::contract::from</a></code> 1842 parameter and that would be problematic (specifically because destructors 1843 can have postconditions so that parameter is necessary to make sure user-defined 1844 failure handlers can be programmed to never throw from destructors as 1845 C++ usually requires). 1846 </p></div> 1847<div id="ftn.boost_contract.advanced.named_overrides.f0" class="footnote"><p><a href="#boost_contract.advanced.named_overrides.f0" class="para"><sup class="para">[62] </sup></a> 1848 <span class="bold"><strong>Rationale:</strong></span> A different macro <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 1849 is used instead of overloading <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1850 using variadic macros because the override macro cannot be programmed manually 1851 by users so making it a variadic would prevent to use this library on compilers 1852 that do not support variadic macros (see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 1853 Macros</a>). 1854 </p></div> 1855<div id="ftn.boost_contract.advanced.named_overrides.f1" class="footnote"><p><a href="#boost_contract.advanced.named_overrides.f1" class="para"><sup class="para">[63] </sup></a> 1856 <span class="bold"><strong>Rationale:</strong></span> The syntax for invoking a possible 1857 <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDES</span></code> 1858 macro would need to be something like <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDES</span><span class="special">(</span><span class="identifier">type_name1</span><span class="special">,</span> <span class="identifier">func_name1</span><span class="special">,</span> <span class="identifier">type_name2</span><span class="special">,</span> <span class="identifier">func_name2</span><span class="special">,</span> <span class="special">...)</span></code>. 1859 The authors found such a syntax less readable than repeating single <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584725152.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code> 1860 invocations as in <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDE</span><span class="special">(</span><span class="identifier">type_name1</span><span class="special">,</span> <span class="identifier">func_name1</span><span class="special">)</span> <span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDE</span><span class="special">(</span><span class="identifier">type_name2</span><span class="special">,</span> <span class="identifier">func_name2</span><span class="special">)</span> <span class="special">...</span></code> so 1861 decided not to provide the <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_NAMED_OVERRIDES</span></code> 1862 macro. 1863 </p></div> 1864<div id="ftn.boost_contract.advanced.access_specifiers.f0" class="footnote"><p><a href="#boost_contract.advanced.access_specifiers.f0" class="para"><sup class="para">[64] </sup></a> 1865 <span class="bold"><strong>Rationale:</strong></span> Note that the internals 1866 of the <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> 1867 type generated by <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code> 1868 use names reserved by this library so programmers should not actually 1869 use such a type even when it is declared <code class="computeroutput"><span class="keyword">public</span></code>. 1870 </p></div> 1871<div id="ftn.boost_contract.advanced.access_specifiers.f1" class="footnote"><p><a href="#boost_contract.advanced.access_specifiers.f1" class="para"><sup class="para">[65] </sup></a> 1872 There is some variability among compiler implementations: The <code class="computeroutput"><span class="identifier">base_types</span></code> member type needs to be declared 1873 <code class="computeroutput"><span class="keyword">public</span></code> on MSVC, GCC, and Clang; 1874 The <code class="computeroutput"><span class="identifier">invariant</span></code> and <code class="computeroutput"><span class="identifier">static_invariant</span></code> member functions need 1875 to be declared <code class="computeroutput"><span class="keyword">public</span></code> on MSVC, 1876 but not on GCC and Clang; The <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code> member types do not have to be declared 1877 <code class="computeroutput"><span class="keyword">public</span></code> on any compiler. In 1878 any case, declaring these extra members all <code class="computeroutput"><span class="keyword">public</span></code> 1879 or all <code class="computeroutput"><span class="keyword">private</span></code> when the <code class="computeroutput"><a class="link" href="../boost/contract/access.html" title="Class access">boost::contract::access</a></code> class 1880 is also declared <code class="computeroutput"><span class="keyword">friend</span></code> always 1881 works on all compilers. 1882 </p></div> 1883<div id="ftn.boost_contract.advanced.throw_on_failures__and__noexcept__.f0" class="footnote"><p><a href="#boost_contract.advanced.throw_on_failures__and__noexcept__.f0" class="para"><sup class="para">[66] </sup></a> 1884 <span class="bold"><strong>Rationale:</strong></span> In general, when a contract 1885 fails the only safe thing to do is to terminate program execution (because 1886 the contract failure indicates a bug in the program, and in general a buggy 1887 program will be in a state for which no operation can be successfully and 1888 safely performed, so the program should be stopped as soon as possible). 1889 Therefore, this library terminates the program by default. However, for 1890 specific applications, programmers could implement some fail-safe mechanism 1891 for which some mission-critical operations could always be performed upon 1892 handling failures so this library allows programmers to override the default 1893 contract failure handlers to fully customize how to handle contract failures. 1894 </p></div> 1895<div id="ftn.boost_contract.advanced.throw_on_failures__and__noexcept__.f1" class="footnote"><p><a href="#boost_contract.advanced.throw_on_failures__and__noexcept__.f1" class="para"><sup class="para">[67] </sup></a> 1896 <span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><span class="identifier">set_</span><span class="special">...</span><span class="identifier">_failure</span></code> 1897 functions take a functor as parameter (to accept not just function pointers 1898 but also lambdas, binds, etc.) and they return this same functor as result 1899 so they can be concatenated (this interface is a bit different from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">set_terminate</span></code>). The related <code class="computeroutput"><span class="identifier">get_</span><span class="special">...</span><span class="identifier">_failure</span></code> functions can be used to query 1900 the functors currently set as failure handlers (this interface is similar 1901 to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">get_terminate</span></code>). 1902 </p></div> 1903</div> 1904</div> 1905<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 1906<td align="left"></td> 1907<td align="right"><div class="copyright-footer">Copyright © 2008-2019 Lorenzo Caminiti<p> 1908 Distributed under the Boost Software License, Version 1.0 (see accompanying 1909 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>) 1910 </p> 1911</div></td> 1912</tr></table> 1913<hr> 1914<div class="spirit-nav"> 1915<a accesskey="p" href="tutorial.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="extras.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 1916</div> 1917</body> 1918</html> 1919
