1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Contract Programming Overview</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="getting_started.html" title="Getting Started"> 10<link rel="next" href="tutorial.html" title="Tutorial"> 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="getting_started.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="tutorial.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.contract_programming_overview"></a><a class="link" href="contract_programming_overview.html" title="Contract Programming Overview">Contract 28 Programming Overview</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.assertions">Assertions</a></span></dt> 32<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.benefits_and_costs">Benefits 33 and Costs</a></span></dt> 34<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.function_calls">Function 35 Calls</a></span></dt> 36<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls">Public 37 Function Calls</a></span></dt> 38<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.constructor_calls">Constructor 39 Calls</a></span></dt> 40<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.destructor_calls">Destructor 41 Calls</a></span></dt> 42<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness">Constant-Correctness</a></span></dt> 43<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.specifications_vs__implementation">Specifications 44 vs. Implementation</a></span></dt> 45<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.on_contract_failures">On 46 Contract Failures</a></span></dt> 47<dt><span class="section"><a href="contract_programming_overview.html#boost_contract.contract_programming_overview.feature_summary">Feature 48 Summary</a></span></dt> 49</dl></div> 50<div class="blockquote"><blockquote class="blockquote"><p> 51 <span class="emphasis"><em><span class="quote">“<span class="quote">It is absurd to make elaborate security checks on debugging 52 runs, when no trust is put in the results, and then remove them in production 53 runs, when an erroneous result could be expensive or disastrous. What would 54 we think of a sailing enthusiast who wears his life-jacket when training 55 on dry land but takes it off as soon as he goes to sea?</span>”</span></em></span> 56 </p></blockquote></div> 57<div class="blockquote"><blockquote class="blockquote"><p> 58 <span class="emphasis"><em>-- Charles Antony Richard Hoare (see <a class="link" href="bibliography.html#Hoare73_anchor">[Hoare73]</a>)</em></span> 59 </p></blockquote></div> 60<p> 61 This section gives an overview of contract programming (see <a class="link" href="bibliography.html#Meyer97_anchor">[Meyer97]</a>, 62 <a class="link" href="bibliography.html#Mitchell02_anchor">[Mitchell02]</a>, and <a class="link" href="bibliography.html#N1613_anchor">[N1613]</a> 63 for more extensive introductions to contract programming). Readers that already 64 have a basic understanding of contract programming can skip this section and 65 maybe come back to it after reading the <a class="link" href="tutorial.html" title="Tutorial">Tutorial</a>. 66 </p> 67<div class="note"><table border="0" summary="Note"> 68<tr> 69<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 70<th align="left">Note</th> 71</tr> 72<tr><td align="left" valign="top"><p> 73 The objective of this library is not to convince programmers to use contract 74 programming. It is assumed that programmes understand the benefits and trade-offs 75 associated with contract programming and they have already decided to use 76 this methodology in their code. Then, this library aims to be the best and 77 more complete contract programming library for C++ (without using programs 78 and tools external to the C++ language and its preprocessor). 79 </p></td></tr> 80</table></div> 81<div class="section"> 82<div class="titlepage"><div><div><h3 class="title"> 83<a name="boost_contract.contract_programming_overview.assertions"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.assertions" title="Assertions">Assertions</a> 84</h3></div></div></div> 85<p> 86 Contract programming is characterized by the following assertion mechanisms: 87 </p> 88<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 89<li class="listitem"> 90 <span class="emphasis"><em>Preconditions</em></span>: These are logical conditions that 91 programmers expect to be true when a function is called (e.g., to check 92 constraints on function arguments). Operations that logically have no 93 preconditions (i.e., that are always well-defined for the entire domain 94 of their inputs) are also referred to as having a <span class="emphasis"><em>wide contract</em></span>. 95 This is in contrast to operations that have preconditions which are also 96 referred to as having a <span class="emphasis"><em>narrow contract</em></span> (note that 97 operations with truly narrow contracts are also expected to never throw 98 exceptions because the implementation body of these operations is always 99 expected to succeed after its preconditions are checked to be true). 100 <a href="#ftn.boost_contract.contract_programming_overview.assertions.f0" class="footnote" name="boost_contract.contract_programming_overview.assertions.f0"><sup class="footnote">[6]</sup></a> 101 </li> 102<li class="listitem"> 103 <span class="emphasis"><em>Postconditions</em></span>: These are logical conditions that 104 programmers expect to be true when a function exits without throwing 105 an exception (e.g., to check the result and any side effect that a function 106 might have). Postconditions can access the function return value (for 107 non-void functions) and also <span class="emphasis"><em>old values</em></span> (which are 108 the values that expressions had before the function implementation was 109 executed). 110 </li> 111<li class="listitem"> 112 <span class="emphasis"><em>Exception guarantees</em></span>: These are logical conditions 113 that programmers except to be true when a function exits throwing an 114 exception. Exception guarantees can access old values (but not the function 115 return value). <a href="#ftn.boost_contract.contract_programming_overview.assertions.f1" class="footnote" name="boost_contract.contract_programming_overview.assertions.f1"><sup class="footnote">[7]</sup></a> 116 </li> 117<li class="listitem"> 118 <span class="emphasis"><em>Class invariants</em></span>: These are logical conditions that 119 programmers expect to be true after a constructor exits without throwing 120 an exception, before and after the execution of every non-static public 121 function (even if they throw exceptions), before the destructor is executed 122 (and also after the destructor is executed but only when the destructor 123 throws an exception). Class invariants define valid states for all objects 124 of a given class. It is possible to specify a different set of class 125 invariants for volatile public functions, namely <span class="emphasis"><em>volatile class 126 invariants</em></span>. It is also possible to specify <span class="emphasis"><em>static 127 class invariants</em></span> which are excepted to be true before and 128 after the execution of any constructor, destructor (even if it does not 129 throw an exception), and public function (even if static). <a href="#ftn.boost_contract.contract_programming_overview.assertions.f2" class="footnote" name="boost_contract.contract_programming_overview.assertions.f2"><sup class="footnote">[8]</sup></a> 130 </li> 131<li class="listitem"> 132 <span class="emphasis"><em>Subcontracting</em></span>: This indicates that preconditions 133 cannot be strengthen, while postconditions and class invariants cannot 134 be weaken when a public function in a derived class overrides public 135 functions in one or more of its base classes (this is formally defined 136 according to the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 137 principle</a>). 138 </li> 139</ul></div> 140<p> 141 The actual function implementation code, that remains outside of these contract 142 assertions, is often referred to as the <span class="emphasis"><em>function body</em></span> 143 in contract programming. 144 </p> 145<p> 146 Class invariants can also be used to specify <span class="emphasis"><em>basic</em></span> exception 147 safety guarantees for an object (because they are checked at exit of public 148 functions even when those throw exceptions). Contract assertions for exception 149 guarantees can be used to specify <span class="emphasis"><em>strong</em></span> exception safety 150 guarantees for a given operation on the same object. 151 </p> 152<p> 153 It is also a common requirement for contract programming to automatically 154 disable contract checking while already checking assertions from another 155 contract (in order to avoid infinite recursion while checking contract assertions). 156 </p> 157<div class="note"><table border="0" summary="Note"> 158<tr> 159<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 160<th align="left">Note</th> 161</tr> 162<tr><td align="left" valign="top"><p> 163 This library implements this requirement but in order to globally disable 164 assertions while checking another assertion some kind of global arbitrating 165 variable needs to be used by this library implementation. This library 166 will automatically protect such a global variable from race conditions 167 in multi-threated programs, but this will effectively introduce a global 168 lock in the program (the <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585556352.html" title="Macro BOOST_CONTRACT_DISABLE_THREADS">BOOST_CONTRACT_DISABLE_THREADS</a></code> 169 macro can be defined to disable this global lock but at the risk of incurring 170 in race conditions). <a href="#ftn.boost_contract.contract_programming_overview.assertions.f3" class="footnote" name="boost_contract.contract_programming_overview.assertions.f3"><sup class="footnote">[9]</sup></a> 171 </p></td></tr> 172</table></div> 173<p> 174 In general, it is recommended to specify different contract conditions using 175 separate assertion statements and not to group them together into a single 176 condition using logical operators (<code class="computeroutput"><span class="special">&&</span></code>, 177 <code class="computeroutput"><span class="special">||</span></code>, etc.). This is because when 178 contract conditions are programmed together in a single assertion using logical 179 operators, it might not be clear which condition actually failed in case 180 the entire assertion fails at run-time. 181 </p> 182<h5> 183<a name="boost_contract.contract_programming_overview.assertions.h0"></a> 184 <span class="phrase"><a name="boost_contract.contract_programming_overview.assertions.c_style_assertions"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.assertions.c_style_assertions">C-Style 185 Assertions</a> 186 </h5> 187<p> 188 A limited form of contract programming (typically some form of precondition 189 and basic postcondition checking) can be achieved using the C-style <code class="computeroutput"><span class="identifier">assert</span></code> macro. Using <code class="computeroutput"><span class="identifier">assert</span></code> 190 is common practice for many programmers but it suffers of the following limitations: 191 </p> 192<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 193<li class="listitem"> 194 <code class="computeroutput"><span class="identifier">assert</span></code> does not distinguish 195 between preconditions and postconditions. In well-tested production code, 196 postconditions can usually be disabled trusting the correctness of the 197 implementation while preconditions might still need to remain enabled 198 because of possible changes in the calling code (e.g., postconditions 199 of a given library could be disabled after testing while keeping the 200 library preconditions enabled given that future changes in the user code 201 that calls the library cannot be anticipated). Using <code class="computeroutput"><span class="identifier">assert</span></code> 202 it is not possible to selectively disable only postconditions and all 203 assertions must be disabled at once. 204 </li> 205<li class="listitem"> 206 <code class="computeroutput"><span class="identifier">assert</span></code> requires to manually 207 program extra code to correctly check postconditions (specifically to 208 handle functions with multiple return statements, to not check postconditions 209 when functions throw exceptions, and to implement old values). 210 </li> 211<li class="listitem"> 212 <code class="computeroutput"><span class="identifier">assert</span></code> requires to manually 213 program extra code to check class invariants (extra member functions, 214 try blocks, etc.). 215 </li> 216<li class="listitem"> 217 <code class="computeroutput"><span class="identifier">assert</span></code> does not support 218 subcontracting. 219 </li> 220<li class="listitem"> 221 <code class="computeroutput"><span class="identifier">assert</span></code> calls are usually 222 scattered within function implementations thus the asserted conditions 223 are not immediately visible in their entirety by programmers (as they 224 are instead when the assertions appear in the function declaration or 225 at least at the very top of the function definition). 226 </li> 227</ul></div> 228<p> 229 Contract programming does not suffer of these limitations. 230 </p> 231</div> 232<div class="section"> 233<div class="titlepage"><div><div><h3 class="title"> 234<a name="boost_contract.contract_programming_overview.benefits_and_costs"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.benefits_and_costs" title="Benefits and Costs">Benefits 235 and Costs</a> 236</h3></div></div></div> 237<h5> 238<a name="boost_contract.contract_programming_overview.benefits_and_costs.h0"></a> 239 <span class="phrase"><a name="boost_contract.contract_programming_overview.benefits_and_costs.benefits"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.benefits_and_costs.benefits">Benefits</a> 240 </h5> 241<p> 242 The main use of contract programming is to improve software quality. <a class="link" href="bibliography.html#Meyer97_anchor">[Meyer97]</a> discusses how contract programming 243 can be used as the basic tool to write <span class="quote">“<span class="quote">correct</span>”</span> software. 244 <a class="link" href="bibliography.html#Stroustrup94_anchor">[Stroustrup94]</a> discusses the key 245 importance of class invariants plus advantages and disadvantages of preconditions 246 and postconditions. 247 </p> 248<p> 249 The following is a short summary of benefits associated with contract programming 250 inspired mainly by <a class="link" href="bibliography.html#N1613_anchor">[N1613]</a>: 251 </p> 252<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 253<li class="listitem"> 254 Preconditions and postconditions: Using function preconditions and postconditions, 255 programmers can give a precise semantic description of what a function 256 requires at its entry and what it ensures at its exit (if it does not 257 throw an exception). In particular, using postcondition old values, contract 258 programming provides a mechanism that allows programmers to compare values 259 of an expression before and after the function body execution. This mechanism 260 is powerful enough to enable programmers to express many correctness 261 constraints within the code itself, constraints that would otherwise 262 have to be captured at best only informally by documentation. 263 </li> 264<li class="listitem"> 265 Class invariants: Using class invariants, programmers can describe what 266 to expect from a class and the logic dependencies between the class members. 267 It is the job of the constructor to ensure that the class invariants 268 are satisfied when the object is first created. Then the implementation 269 of the member functions can be largely simplified as they can be written 270 knowing that the class invariants are satisfied because contract programming 271 checks them before and after the execution of every public function. 272 Finally, the destructor makes sure that the class invariants held for 273 the entire life of the object checking the class invariants one last 274 time before the object is destructed. Class invariants can also be used 275 as a criteria for good abstractions: If it is not possible to specify 276 an invariant, it might be an indication that the design abstraction maybe 277 be poor and it should not have been made into a class (maybe a namespace 278 would have sufficed instead). 279 </li> 280<li class="listitem"> 281 Self-documenting code: Contracts are part of the source code, they are 282 checked at run-time so they are always up-to-date with the code itself. 283 Therefore program specifications, as documented by the contracts, can 284 be trusted to always be up-to-date with the implementation. 285 </li> 286<li class="listitem"> 287 Easier debugging: Contract programming can provide a powerful debugging 288 facility because, if contracts are well-written, bugs will cause contract 289 assertions to fail exactly where the problem first occurs instead than 290 at some later stage of the program execution in an apparently unrelated 291 (and often hard to debug) manner. Note that a precondition failure points 292 to a bug in the function caller, a postcondition failure points instead 293 to a bug in the function implementation. <a href="#ftn.boost_contract.contract_programming_overview.benefits_and_costs.f0" class="footnote" name="boost_contract.contract_programming_overview.benefits_and_costs.f0"><sup class="footnote">[10]</sup></a> 294 </li> 295<li class="listitem"> 296 Easier testing: Contract programming facilitates testing because a contract 297 naturally specifies what a test should check. For example, preconditions 298 of a function state which inputs cause the function to fail and postconditions 299 state which outputs are produced by the function on successful exit (contract 300 programming should be seen as a tool to complement and guide, but obviously 301 not to replace, testing). 302 </li> 303<li class="listitem"> 304 Formal design: Contract programming can serve to reduce the gap between 305 designers and programmers by providing a precise and unambiguous specification 306 language in terms of contract assertions. Moreover, contracts can make 307 code reviews easier by clarifying some of the semantics and usage of 308 the code. 309 </li> 310<li class="listitem"> 311 Formalize inheritance: Contract programming formalizes the virtual function 312 overriding mechanism using subcontracting as justified by the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 313 principle</a>. This keeps the base class programmers in control as 314 overriding functions always have to fully satisfy the contracts of their 315 base classes. 316 </li> 317<li class="listitem"> 318 Replace defensive programming: Contract programming assertions can replace 319 <a href="http://en.wikipedia.org/wiki/Defensive_programming" target="_top">defensive 320 programming</a> checks localizing these checks within the contracts 321 and making the code more readable. 322 </li> 323</ul></div> 324<p> 325 Of course, not all formal contract specifications can be asserted in C++. 326 For example, in C++ is it not possible to assert the validity of an iterator 327 range in the general case (because the only way to check if two iterators 328 form a valid range is to keep incrementing the first iterator until it reaches 329 the second iterator, but if the iterator range is invalid then such a code 330 would render undefined behaviour or run forever instead of failing an assertion). 331 Nevertheless, a large amount of contract assertions can be successfully programmed 332 in C++ as illustrated by the numerous examples in this documentation and 333 from the literature (for example see how much of STL <a class="link" href="examples.html#N1962_vector_anchor"><code class="computeroutput"><span class="identifier">vector</span></code></a> contract assertions can actually 334 be programmed in C++ using this library). 335 </p> 336<h5> 337<a name="boost_contract.contract_programming_overview.benefits_and_costs.h1"></a> 338 <span class="phrase"><a name="boost_contract.contract_programming_overview.benefits_and_costs.costs"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.benefits_and_costs.costs">Costs</a> 339 </h5> 340<p> 341 In general, contract programming benefits come at the cost of performance 342 as discussed in detail by both <a class="link" href="bibliography.html#Stroustrup94_anchor">[Stroustrup94]</a> 343 and <a class="link" href="bibliography.html#Meyer97_anchor">[Meyer97]</a>. While performance trade-offs 344 should be carefully considered depending on the specific application domain, 345 software quality cannot be sacrificed: It is difficult to see value in software 346 that quickly and efficiently provides incorrect results. 347 </p> 348<p> 349 The run-time performances are negatively impacted by contract programming 350 mainly because of extra time require to: 351 </p> 352<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 353<li class="listitem"> 354 Check the asserted conditions. 355 </li> 356<li class="listitem"> 357 Copy old values when these are used in postconditions or exception guarantees. 358 </li> 359<li class="listitem"> 360 Call additional functors that check preconditions, postconditions, exception 361 guarantees, class invariants, etc. (these can add up to many extra calls 362 especially when using subcontracting). 363 </li> 364</ul></div> 365<div class="note"><table border="0" summary="Note"> 366<tr> 367<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 368<th align="left">Note</th> 369</tr> 370<tr><td align="left" valign="top"><p> 371 In general, contracts introduce at least three extra functor calls to check 372 preconditions, postconditions, and exception guarantees for any given non-member 373 function call. Public functions introduce also two more function calls 374 to check class invariants (at entry and at exit). For subcontracting, these 375 extra calls (some of which become virtual calls) are repeated for the number 376 of functions being overridden from the base classes (possibly deep in the 377 inheritance tree). In addition to that, this library introduces a number 378 of function calls internal to its implementation in order to properly check 379 the contracts. 380 </p></td></tr> 381</table></div> 382<p> 383 To mitigate the run-time performance impact, programmers can selectively 384 disable run-time checking of some of the contract assertions. Programmers 385 will have to decide based on the performance trade-offs required by their 386 specific applications, but a reasonable approach often is to (see <a class="link" href="extras.html#boost_contract.extras.disable_contract_checking" title="Disable Contract Checking">Disable 387 Contract Checking</a>): 388 </p> 389<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 390<li class="listitem"> 391 Always write contracts to clarify the semantics of the design embedding 392 the specifications directly in the code and making the code self-documenting. 393 </li> 394<li class="listitem"> 395 Check preconditions, postconditions, class invariants, and maybe even 396 exception guarantees during initial testing. 397 </li> 398<li class="listitem"> 399 Check only preconditions (and maybe class invariants, but not postconditions 400 and exception guarantees) during release testing and for the final release. 401 </li> 402</ul></div> 403<p> 404 This approach is usually reasonable because in well-tested production code, 405 validating the function body implementation using postconditions is rarely 406 needed since the function has shown itself to be <span class="quote">“<span class="quote">correct</span>”</span> during 407 testing. On the other hand, checking function arguments using preconditions 408 is always needed because of changes that can be made to the calling code 409 (without having to necessarily re-test and re-release the called code). Furthermore, 410 postconditions and also exception guarantees, with related old value copies, 411 are often computationally more expensive to check than preconditions and 412 class invariants. 413 </p> 414</div> 415<div class="section"> 416<div class="titlepage"><div><div><h3 class="title"> 417<a name="boost_contract.contract_programming_overview.function_calls"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.function_calls" title="Function Calls">Function 418 Calls</a> 419</h3></div></div></div> 420<h5> 421<a name="boost_contract.contract_programming_overview.function_calls.h0"></a> 422 <span class="phrase"><a name="boost_contract.contract_programming_overview.function_calls.non_member_functions"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.function_calls.non_member_functions">Non-Member 423 Functions</a> 424 </h5> 425<p> 426 A call to a non-member function with a contract executes the following steps 427 (see <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code>): 428 </p> 429<div class="orderedlist"><ol class="orderedlist" type="1"> 430<li class="listitem"> 431 Check function preconditions. 432 </li> 433<li class="listitem"> 434 Execute the function body. 435 </li> 436<li class="listitem"> 437 If the body did not throw an exception, check function postconditions. 438 </li> 439<li class="listitem"> 440 Else, check function exception guarantees. 441 </li> 442</ol></div> 443<h5> 444<a name="boost_contract.contract_programming_overview.function_calls.h1"></a> 445 <span class="phrase"><a name="boost_contract.contract_programming_overview.function_calls.private_and_protected_functions"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.function_calls.private_and_protected_functions">Private 446 and Protected Functions</a> 447 </h5> 448<p> 449 Private and protected functions do not have to satisfy class invariants because 450 these functions are part of the class implementation and not of the class 451 public interface. Furthermore, the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 452 principle</a> does not apply to private and protected functions because 453 these functions are not accessible to the user at the calling site where 454 the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 455 principle</a> applies. 456 </p> 457<p> 458 Therefore, calls to private and protected functions with contracts execute 459 the same steps as the ones indicated above for non-member functions (checking 460 only preconditions and postconditions, without checking class invariants 461 and without subcontracting). 462 </p> 463</div> 464<div class="section"> 465<div class="titlepage"><div><div><h3 class="title"> 466<a name="boost_contract.contract_programming_overview.public_function_calls"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public 467 Function Calls</a> 468</h3></div></div></div> 469<h5> 470<a name="boost_contract.contract_programming_overview.public_function_calls.h0"></a> 471 <span class="phrase"><a name="boost_contract.contract_programming_overview.public_function_calls.overriding_public_functions"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls.overriding_public_functions">Overriding 472 Public Functions</a> 473 </h5> 474<p> 475 Let's consider a public function in a derived class that overrides public 476 virtual functions declared by its public base classes (because of C++ multiple 477 inheritance, the function could override from more than one of its base classes). 478 We refer to the function in the derived class as the <span class="emphasis"><em>overriding 479 function</em></span>, and to the set of base classes containing all the <span class="emphasis"><em>overridden 480 functions</em></span> as <span class="emphasis"><em>overridden bases</em></span>. 481 </p> 482<p> 483 When subcontracting, overridden functions are searched (at compile-time) 484 deeply in all public branches of the inheritance tree (i.e., not just the 485 derived class' direct public parents are inspected, but also all its public 486 grandparents, etc.). In case of multiple inheritance, this search also extends 487 (at compile-time) widely to all public trees of the multiple inheritance 488 forest (multiple public base classes are searched following their order of 489 declaration in the derived class' inheritance list). As usual with C++ multiple 490 inheritance, this search could result in multiple overridden functions and 491 therefore in subcontracting from multiple public base classes. Note that 492 only public base classes are considered for subcontracting because private 493 and protected base classes are not accessible to the user at the calling 494 site where the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 495 principle</a> applies. 496 </p> 497<p> 498 A call to the overriding public function with a contract executes the following 499 steps (see <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>): 500 </p> 501<div class="orderedlist"><ol class="orderedlist" type="1"> 502<li class="listitem"> 503 Check static class invariants <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 504 non-static class invariants for all overridden bases, <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 505 then check the derived class static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 506 non-static invariants. 507 </li> 508<li class="listitem"> 509 Check preconditions of overridden public functions from all overridden 510 bases in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 511 with each other, <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 512 else check the overriding function preconditions in the derived class. 513 </li> 514<li class="listitem"> 515 Execute the overriding function body. 516 </li> 517<li class="listitem"> 518 Check static class invariants <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 519 non-static class invariants for all overridden bases, <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 520 then check the derived class static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 521 non-static invariants (even if the body threw an exception). 522 </li> 523<li class="listitem"> 524 If the body did not throw an exception, check postconditions of overridden 525 public functions from all overridden bases in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 526 with each other, <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 527 then check the overriding function postconditions in the derived class. 528 </li> 529<li class="listitem"> 530 Else, check exception guarantees of overridden public functions from 531 all overridden bases in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 532 with each other, <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 533 then check the overriding function exception guarantees in the derived 534 class. 535 </li> 536</ol></div> 537<p> 538 Volatile public functions check static class invariants <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 539 volatile class invariants instead. Preconditions and postconditions of volatile 540 public functions and volatile class invariants access the object as <code class="computeroutput"><span class="keyword">volatile</span></code>. 541 </p> 542<p> 543 Class invariants are checked before preconditions and postconditions so programming 544 precondition and postcondition assertions can be simplified assuming that 545 class invariants are satisfied already (e.g., if class invariants assert 546 that a pointer cannot be null then preconditions and postconditions can safety 547 dereference that pointer without additional checking). Similarly, static 548 class invariants are checked before non-static class invariants so programming 549 non-static class invariant (volatile and non) can be simplified assuming 550 that static class invariants are satisfied already. Furthermore, subcontracting 551 checks contracts of public base classes before checking the derived class 552 contracts so programming derived class contract assertions can be simplified 553 by assuming that public base class contracts are satisfied already. 554 </p> 555<div class="note"><table border="0" summary="Note"> 556<tr> 557<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 558<th align="left">Note</th> 559</tr> 560<tr><td align="left" valign="top"> 561<p> 562 <a name="and_anchor"></a><a name="or_anchor"></a>In this documentation 563 <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 564 and <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 565 indicate the logic <span class="emphasis"><em>and</em></span> and <span class="emphasis"><em>or</em></span> 566 operations evaluated in <span class="emphasis"><em>short-circuit</em></span>. For example: 567 <code class="computeroutput"><span class="identifier">p</span></code> <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 568 <code class="computeroutput"><span class="identifier">q</span></code> is true if and only if 569 both <code class="computeroutput"><span class="identifier">p</span></code> and <code class="computeroutput"><span class="identifier">q</span></code> are true, but <code class="computeroutput"><span class="identifier">q</span></code> 570 is never evaluated when <code class="computeroutput"><span class="identifier">p</span></code> 571 is false; <code class="computeroutput"><span class="identifier">p</span></code> <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 572 <code class="computeroutput"><span class="identifier">q</span></code> is true if and only if 573 either <code class="computeroutput"><span class="identifier">p</span></code> or <code class="computeroutput"><span class="identifier">q</span></code> are true, but <code class="computeroutput"><span class="identifier">q</span></code> 574 is never evaluated when <code class="computeroutput"><span class="identifier">p</span></code> 575 is true. 576 </p> 577<p> 578 As indicated by the steps above and in accordance with the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 579 principle</a>, subcontracting checks preconditions in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 580 while class invariants, postconditions, and exceptions guarantees are checked 581 in <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 582 with preconditions, class invariants, postconditions, and exceptions guarantees 583 of base classes respectively. 584 </p> 585</td></tr> 586</table></div> 587<h5> 588<a name="boost_contract.contract_programming_overview.public_function_calls.h1"></a> 589 <span class="phrase"><a name="boost_contract.contract_programming_overview.public_function_calls.non_overriding_public_functions"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls.non_overriding_public_functions">Non-Overriding 590 Public Functions</a> 591 </h5> 592<p> 593 A call to a non-static public function with a contract (that does not override 594 functions from any of its public base classes) executes the following steps 595 (see <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>): 596 </p> 597<div class="orderedlist"><ol class="orderedlist" type="1"> 598<li class="listitem"> 599 Check class static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 600 non-static invariants (but none of the invariants from base classes). 601 </li> 602<li class="listitem"> 603 Check function preconditions (but none of the preconditions from functions 604 in base classes). 605 </li> 606<li class="listitem"> 607 Execute the function body. 608 </li> 609<li class="listitem"> 610 Check the class static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 611 non-static invariants (even if the body threw an exception, but none 612 of the invariants from base classes). 613 </li> 614<li class="listitem"> 615 If the body did not throw an exception, check function postconditions 616 (but none of the postconditions from functions in base classes). 617 </li> 618<li class="listitem"> 619 Else, check function exception guarantees (but none of the exception 620 guarantees from functions in base classes). 621 </li> 622</ol></div> 623<p> 624 Volatile public functions check static class invariants <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 625 volatile class invariants instead. Preconditions and postconditions of volatile 626 functions and volatile class invariants access the object as <code class="computeroutput"><span class="keyword">volatile</span></code>. 627 </p> 628<p> 629 Class invariants are checked because this function is part of the class public 630 interface. However, none of the contracts of the base classes are checked 631 because this function does not override any functions from any of the public 632 base classes (so the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 633 principle</a> does not require to subcontract in this case). 634 </p> 635<h5> 636<a name="boost_contract.contract_programming_overview.public_function_calls.h2"></a> 637 <span class="phrase"><a name="boost_contract.contract_programming_overview.public_function_calls.static_public_functions"></a></span><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls.static_public_functions">Static 638 Public Functions</a> 639 </h5> 640<p> 641 A call to a static public function with a contract executes the following 642 steps (see <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm46268584697584.html" title="Function template public_function">boost::contract::public_function</a></code>): 643 </p> 644<div class="orderedlist"><ol class="orderedlist" type="1"> 645<li class="listitem"> 646 Check static class invariants (but not the non-static invariants and 647 none of the invariants from base classes). 648 </li> 649<li class="listitem"> 650 Check function preconditions (but none of the preconditions from functions 651 in base classes). 652 </li> 653<li class="listitem"> 654 Execute the function body. 655 </li> 656<li class="listitem"> 657 Check static class invariants (even if the body threw an exception, but 658 not the non-static invariants and none of the invariants from base classes). 659 </li> 660<li class="listitem"> 661 If the body did not throw an exception, check function postconditions 662 (but none of the postconditions from functions in base classes). 663 </li> 664<li class="listitem"> 665 Else, check function exception guarantees (but none of the exception 666 guarantees from functions in base classes). 667 </li> 668</ol></div> 669<p> 670 Class invariants are checked because this function is part of the class public 671 interface, but only static class invariants can be checked (because this 672 is a static function so it cannot access the object that would instead be 673 required to check non-static class invariants, volatile or not). Furthermore, 674 static functions cannot override any function so the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 675 principle</a> does not apply and they do not subcontract. 676 </p> 677<p> 678 Preconditions and postconditions of static functions and static class invariants 679 cannot access the object (because they are checked from <code class="computeroutput"><span class="keyword">static</span></code> 680 member functions). 681 </p> 682</div> 683<div class="section"> 684<div class="titlepage"><div><div><h3 class="title"> 685<a name="boost_contract.contract_programming_overview.constructor_calls"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constructor_calls" title="Constructor Calls">Constructor 686 Calls</a> 687</h3></div></div></div> 688<p> 689 A call to a constructor with a contract executes the following steps (see 690 <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code> 691 and <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>): 692 </p> 693<div class="orderedlist"><ol class="orderedlist" type="1"> 694<li class="listitem"> 695 Check constructor preconditions (but these cannot access the object because 696 the object is not constructed yet). 697 </li> 698<li class="listitem"> 699 Execute the constructor member initialization list (if present). 700 <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> 701 Construct any base class (public or not) according with C++ construction 702 mechanism and also check the contracts of these base constructors 703 (according with steps similar to the ones listed here). 704 </li></ol></div> 705 </li> 706<li class="listitem"> 707 Check static class invariants (but not the non-static or volatile class 708 invariants, because the object is not constructed yet). 709 </li> 710<li class="listitem"> 711 Execute the constructor body. 712 </li> 713<li class="listitem"> 714 Check static class invariants (even if the body threw an exception). 715 </li> 716<li class="listitem"> 717 If the body did not throw an exception: 718 <div class="orderedlist"><ol class="orderedlist" type="a"> 719<li class="listitem"> 720 Check non-static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 721 volatile class invariants (because the object is now successfully 722 constructed). 723 </li> 724<li class="listitem"> 725 Check constructor postconditions (but these cannot access the object 726 old value <code class="literal"><span class="emphasis"><em>oldof</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)</span></code> because the object was not constructed 727 before the execution of the constructor body). 728 </li> 729</ol></div> 730 </li> 731<li class="listitem"> 732 Else, check constructor exception guarantees (but these cannot access 733 the object old value <code class="literal"><span class="emphasis"><em>oldof</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)</span></code> because the object was not constructed 734 before the execution of the constructor body, plus they can only access 735 class' static members because the object has not been successfully constructed 736 given the constructor body threw an exception in this case). 737 </li> 738</ol></div> 739<p> 740 Constructor preconditions are checked before executing the member initialization 741 list so programming these initializations can be simplified assuming the 742 constructor preconditions are satisfied (e.g., constructor arguments can 743 be validated by the constructor preconditions before they are used to initialize 744 base classes and data members). 745 </p> 746<p> 747 As indicated in step 2.a. above, C++ object construction mechanism will automatically 748 check base class contracts when these bases are initialized (no explicit 749 subcontracting behaviour is required here). 750 </p> 751</div> 752<div class="section"> 753<div class="titlepage"><div><div><h3 class="title"> 754<a name="boost_contract.contract_programming_overview.destructor_calls"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.destructor_calls" title="Destructor Calls">Destructor 755 Calls</a> 756</h3></div></div></div> 757<p> 758 A call to a destructor with a contract executes the following steps (see 759 <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>): 760 </p> 761<div class="orderedlist"><ol class="orderedlist" type="1"> 762<li class="listitem"> 763 Check static class invariants <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 764 non-static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 765 volatile class invariants. 766 </li> 767<li class="listitem"> 768 Execute the destructor body (destructors have no parameters and they 769 can be called at any time after object construction so they have no preconditions). 770 </li> 771<li class="listitem"> 772 Check static class invariants (even if the body threw an exception). 773 </li> 774<li class="listitem"> 775 If the body did not throw an exception: 776 <div class="orderedlist"><ol class="orderedlist" type="a"> 777<li class="listitem"> 778 Check destructor postconditions (but these can only access class' 779 static members and the object old value <code class="literal"><span class="emphasis"><em>oldof</em></span></code><code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)</span></code> because the object has been destroyed 780 after successful execution of the destructor body). <a href="#ftn.boost_contract.contract_programming_overview.destructor_calls.f0" class="footnote" name="boost_contract.contract_programming_overview.destructor_calls.f0"><sup class="footnote">[11]</sup></a> 781 </li> 782<li class="listitem"> 783 Destroy any base class (public or not) according with C++ destruction 784 mechanism and also check the contracts of these base destructors 785 (according with steps similar to the ones listed here). 786 </li> 787</ol></div> 788 </li> 789<li class="listitem"> 790 Else (even if destructors should rarely, if ever, be allowed to throw 791 exceptions in C++): 792 <div class="orderedlist"><ol class="orderedlist" type="a"> 793<li class="listitem"> 794 Check non-static <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a> 795 volatile class invariants (because the object was not successfully 796 destructed so it still exists and should satisfy its invariants). 797 </li> 798<li class="listitem"> 799 Check destructor exception guarantees. 800 </li> 801</ol></div> 802 </li> 803</ol></div> 804<p> 805 As indicated in step 4.b. above, C++ object destruction mechanism will automatically 806 check base class contracts when the destructor exits without throwing an 807 exception (no explicit subcontracting behaviour is required here). 808 </p> 809<div class="note"><table border="0" summary="Note"> 810<tr> 811<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 812<th align="left">Note</th> 813</tr> 814<tr><td align="left" valign="top"><p> 815 Given that C++ allows destructors to throw, this library handles the case 816 when the destructor body throws an exception as indicated above. However, 817 in order to comply with STL exception safety guarantees and good C++ programming 818 practices, programmers should implement destructor bodies to rarely, if 819 ever, throw exceptions (in fact destructors are implicitly declared <code class="computeroutput"><span class="keyword">noexcept</span></code> in C++11). 820 </p></td></tr> 821</table></div> 822</div> 823<div class="section"> 824<div class="titlepage"><div><div><h3 class="title"> 825<a name="boost_contract.contract_programming_overview.constant_correctness"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a> 826</h3></div></div></div> 827<p> 828 Contracts should not be allowed to modify the program state because they 829 are only responsible to check (and not to change) the program state in order 830 to verify its compliance with the specifications. Therefore, contracts should 831 only access objects, function arguments, function return values, old values, 832 and all other program variables in <code class="computeroutput"><span class="keyword">const</span></code> 833 context (via <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code>, 834 <code class="computeroutput"><span class="keyword">const</span><span class="special">*</span> 835 <span class="keyword">const</span></code>, <code class="computeroutput"><span class="keyword">const</span> 836 <span class="keyword">volatile</span></code>, etc.). 837 </p> 838<p> 839 Whenever possible (e.g., class invariants and postcondition old values), 840 this library automatically enforces this <span class="emphasis"><em>constant-correctness constraint</em></span> 841 at compile-time using <code class="computeroutput"><span class="keyword">const</span></code>. 842 However, this library cannot automatically enforce this constraint in all 843 cases (for preconditions and postconditions of mutable member functions, 844 for global variables, etc.). See <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No 845 Lambda Functions</a> for ways of using this library that enforce the constant-correctness 846 constraint at compile-time (but at the cost of significant boiler-plate code 847 to be programmed manually so not recommended in general). 848 </p> 849<div class="note"><table border="0" summary="Note"> 850<tr> 851<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 852<th align="left">Note</th> 853</tr> 854<tr><td align="left" valign="top"><p> 855 In general, it is the responsibility of the programmers to code assertions 856 that only check, and do not change, program variables. <a href="#ftn.boost_contract.contract_programming_overview.constant_correctness.f0" class="footnote" name="boost_contract.contract_programming_overview.constant_correctness.f0"><sup class="footnote">[12]</sup></a> 857 </p></td></tr> 858</table></div> 859</div> 860<div class="section"> 861<div class="titlepage"><div><div><h3 class="title"> 862<a name="boost_contract.contract_programming_overview.specifications_vs__implementation"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.specifications_vs__implementation" title="Specifications vs. Implementation">Specifications 863 vs. Implementation</a> 864</h3></div></div></div> 865<p> 866 Contracts are part of the program specification and not of its implementation. 867 Therefore, contracts should ideally be programmed within C++ declarations, 868 and not within definitions. 869 </p> 870<p> 871 In general, this library cannot satisfy this requirement. However, even when 872 contracts are programmed together with the body in the function definition, 873 it is still fairly easy for users to identify and read just the contract 874 portion of the function definition (because the contract code must always 875 be programmed at the very top of the function definition). See <a class="link" href="extras.html#boost_contract.extras.separate_body_implementation" title="Separate Body Implementation">Separate 876 Body Implementation</a> for ways of using this library to program contract 877 specifications outside of the body implementation (but at the cost of writing 878 one extra function for any given function so not recommended in general). 879 </p> 880<p> 881 Furthermore, contracts are most useful when they assert conditions only using 882 public members (in most cases, the need for using non-public members to check 883 contracts, especially in preconditions, indicates an error in the class design). 884 For example, the caller of a public function cannot in general make sure 885 that the function preconditions are satisfied if the precondition assertions 886 use private members that are not callable by the caller (therefore, a failure 887 in the preconditions will not necessarily indicate a bug in the caller given 888 that the caller was made unable to fully check the preconditions in the first 889 place). However, given that C++ provides programmers ways around access level 890 restrictions (<code class="computeroutput"><span class="keyword">friend</span></code>, function 891 pointers, etc.), this library leaves it up to programmers to make sure that 892 only public members are used in contract assertions (especially in preconditions). 893 (<a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> follows the same approach not 894 restricting contracts to only use public members, Eiffel instead generates 895 a compile-time error if preconditions are asserted using non-public members.) 896 <a href="#ftn.boost_contract.contract_programming_overview.specifications_vs__implementation.f0" class="footnote" name="boost_contract.contract_programming_overview.specifications_vs__implementation.f0"><sup class="footnote">[13]</sup></a> 897 </p> 898</div> 899<div class="section"> 900<div class="titlepage"><div><div><h3 class="title"> 901<a name="boost_contract.contract_programming_overview.on_contract_failures"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.on_contract_failures" title="On Contract Failures">On 902 Contract Failures</a> 903</h3></div></div></div> 904<p> 905 If preconditions, postconditions, exception guarantees, or class invariants 906 are either checked to be false or their evaluation throws an exception at 907 run-time then this library will call specific <span class="emphasis"><em>failure handler functions</em></span>. 908 <a href="#ftn.boost_contract.contract_programming_overview.on_contract_failures.f0" class="footnote" name="boost_contract.contract_programming_overview.on_contract_failures.f0"><sup class="footnote">[14]</sup></a> 909 </p> 910<p> 911 By default, these failure handler functions print a message to the standard 912 error <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> (with detailed information about the 913 failure) and then terminate the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code>. 914 However, using <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>, 915 <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>, 916 <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>, 917 <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>, 918 etc. programmers can define their own failure handler functions that can 919 take any user-specified action (throw an exception, exit the program with 920 an error code, etc., see <a class="link" href="advanced.html#boost_contract.advanced.throw_on_failures__and__noexcept__" title="Throw on Failures (and noexcept)">Throw 921 on Failures</a>). <a href="#ftn.boost_contract.contract_programming_overview.on_contract_failures.f1" class="footnote" name="boost_contract.contract_programming_overview.on_contract_failures.f1"><sup class="footnote">[15]</sup></a> 922 </p> 923<div class="note"><table border="0" summary="Note"> 924<tr> 925<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 926<th align="left">Note</th> 927</tr> 928<tr><td align="left" valign="top"><p> 929 In C++ there are a number of issues with programming contract failure handlers 930 that throw exceptions instead of terminating the program. Specifically, 931 destructors check class invariants so they will throw if programmers change 932 class invariant failure handlers to throw instead of terminating the program, 933 but in general destructors should not throw in C++ (to comply with STL 934 exception safety, C++11 implicit <code class="computeroutput"><span class="keyword">noexcept</span></code> 935 declarations for destructors, etc.). Furthermore, programming a failure 936 handler that throws on exception guarantee failures results in throwing 937 an exception (the one reporting the contract failure) while there is already 938 an active exception (the one that caused the exception guarantees to be 939 checked in the first place), and this will force C++ to terminate the program 940 anyway. 941 </p></td></tr> 942</table></div> 943<p> 944 Therefore, it is recommended to terminate the program at least for contract 945 failures from destructors and exception guarantees (if not in all other cases 946 of contract failures as it is done by default by this library). The contract 947 failure handler functions programmed using this library have information 948 about the failed contract (preconditions, postconditions, etc.) and the operation 949 that was checking the contract (constructor, destructor, etc.) so programmers 950 can granularly distinguish all cases and decide when it is appropriate to 951 terminate, throw, or take some other user-specific action. 952 </p> 953</div> 954<div class="section"> 955<div class="titlepage"><div><div><h3 class="title"> 956<a name="boost_contract.contract_programming_overview.feature_summary"></a><a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.feature_summary" title="Feature Summary">Feature 957 Summary</a> 958</h3></div></div></div> 959<p> 960 The contract programming features supported by this library are largely based 961 on <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> and on the Eiffel programming 962 language. 963 </p> 964<p> 965 The following table compares contract programming features among this library, 966 <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> (unfortunately the C++ standard 967 committee rejected this proposal commenting on a lack of interest in adding 968 contract programming to C++ at that time, even if <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> 969 itself is sound), a more recent proposal <a class="link" href="bibliography.html#P0380_anchor">[P0380]</a> 970 (which was accepted in the C++20 standard but unfortunately only supports 971 preconditions and postconditions, while does not support class invariants, 972 old values, and subcontracting), the Eiffel and D programming languages. 973 Some of the items listed in this summary table will become clear in detail 974 after reading the remaining sections of this documentation. 975 </p> 976<div class="informaltable"><table class="table"> 977<colgroup> 978<col> 979<col> 980<col> 981<col> 982<col> 983<col> 984</colgroup> 985<thead><tr> 986<th> 987 <p> 988 Feature 989 </p> 990 </th> 991<th> 992 <p> 993 This Library 994 </p> 995 </th> 996<th> 997 <p> 998 <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> Proposal (not accepted 999 in C++) 1000 </p> 1001 </th> 1002<th> 1003 <p> 1004 C++20 (see <a class="link" href="bibliography.html#P0380_anchor">[P0380]</a>) 1005 </p> 1006 </th> 1007<th> 1008 <p> 1009 ISE Eiffel 5.4 (see <a class="link" href="bibliography.html#Meyer97_anchor">[Meyer97]</a>) 1010 </p> 1011 </th> 1012<th> 1013 <p> 1014 D (see <a class="link" href="bibliography.html#Bright04_anchor">[Bright04]</a>) 1015 </p> 1016 </th> 1017</tr></thead> 1018<tbody> 1019<tr> 1020<td> 1021 <p> 1022 <span class="emphasis"><em>Keywords and specifiers</em></span> 1023 </p> 1024 </td> 1025<td> 1026 <p> 1027 Specifiers: <code class="computeroutput"><span class="identifier">precondition</span></code>, 1028 <code class="computeroutput"><span class="identifier">postcondition</span></code>, 1029 <code class="computeroutput"><span class="identifier">invariant</span></code>, <code class="computeroutput"><span class="identifier">static_invariant</span></code>, and <code class="computeroutput"><span class="identifier">base_types</span></code>. The last three specifiers 1030 appear in user code so their names can be referred to or changed 1031 using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_INVARIANT.html" title="Macro BOOST_CONTRACT_INVARIANT">BOOST_CONTRACT_INVARIANT</a></code>, 1032 <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268584433936.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT">BOOST_CONTRACT_STATIC_INVARIANT</a></code>, 1033 and <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585544864.html" title="Macro BOOST_CONTRACT_BASES_TYPEDEF">BOOST_CONTRACT_BASES_TYPEDEF</a></code> 1034 macros respectively to avoid name clashes. 1035 </p> 1036 </td> 1037<td> 1038 <p> 1039 Keywords: <code class="computeroutput"><span class="identifier">precondition</span></code>, 1040 <code class="computeroutput"><span class="identifier">postcondition</span></code>, 1041 <code class="computeroutput"><span class="identifier">oldof</span></code>, and <code class="computeroutput"><span class="identifier">invariant</span></code>. 1042 </p> 1043 </td> 1044<td> 1045 <p> 1046 Attributes: <code class="computeroutput"><span class="special">[[</span><span class="identifier">expects</span><span class="special">]]</span></code> and <code class="computeroutput"><span class="special">[[</span><span class="identifier">ensures</span><span class="special">]]</span></code>. 1047 </p> 1048 </td> 1049<td> 1050 <p> 1051 Keywords: <code class="literal">require</code>, <code class="literal">require else</code>, 1052 <code class="literal">ensure</code>, <code class="literal">ensure then</code>, <code class="literal">old</code>, 1053 <code class="literal">result</code>, <code class="literal">do</code>, and <code class="literal">invariant</code>. 1054 </p> 1055 </td> 1056<td> 1057 <p> 1058 Keywords: <code class="literal">in</code>, <code class="literal">out</code>, <code class="literal">do</code>, 1059 <code class="literal">assert</code>, and <code class="literal">invariant</code>. 1060 </p> 1061 </td> 1062</tr> 1063<tr> 1064<td> 1065 <p> 1066 <span class="emphasis"><em>On contract failures</em></span> 1067 </p> 1068 </td> 1069<td> 1070 <p> 1071 Print an error to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> 1072 and call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> (but can be customized 1073 to throw exceptions, exit with an error code, etc.). 1074 </p> 1075 </td> 1076<td> 1077 <p> 1078 Call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> (but can be customized 1079 to throw exceptions, exit with an error code, etc.). 1080 </p> 1081 </td> 1082<td> 1083 <p> 1084 Call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">abort</span></code> (but can be customized 1085 to throw exceptions, exit with an error code, etc.). 1086 </p> 1087 </td> 1088<td> 1089 <p> 1090 Throw exceptions. 1091 </p> 1092 </td> 1093<td> 1094 <p> 1095 Throw exceptions. 1096 </p> 1097 </td> 1098</tr> 1099<tr> 1100<td> 1101 <p> 1102 <span class="emphasis"><em>Return values in postconditions</em></span> 1103 </p> 1104 </td> 1105<td> 1106 <p> 1107 Yes, captured by or passed as a parameter to (for virtual functions) 1108 the postcondition functor. 1109 </p> 1110 </td> 1111<td> 1112 <p> 1113 Yes, <code class="computeroutput"><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result-variable-name</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1114 </p> 1115 </td> 1116<td> 1117 <p> 1118 Yes, <code class="computeroutput"><span class="special">[[</span><span class="identifier">ensures</span> 1119 </code><code class="literal"><span class="emphasis"><em>result-variable-name</em></span></code><code class="computeroutput"><span class="special">:</span> <span class="special">...]]</span></code>. 1120 </p> 1121 </td> 1122<td> 1123 <p> 1124 Yes, <code class="literal">result</code> keyword. 1125 </p> 1126 </td> 1127<td> 1128 <p> 1129 Yes, <code class="computeroutput"><span class="identifier">out</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result-variable-name</em></span></code><code class="computeroutput"><span class="special">)</span></code>. 1130 </p> 1131 </td> 1132</tr> 1133<tr> 1134<td> 1135 <p> 1136 <span class="emphasis"><em>Old values in postconditions</em></span> 1137 </p> 1138 </td> 1139<td> 1140 <p> 1141 Yes, <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> 1142 macro and <code class="computeroutput"><a class="link" href="../boost/contract/old_ptr.html" title="Class template old_ptr">boost::contract::old_ptr</a></code> 1143 (but copied before preconditions unless <code class="computeroutput"><span class="special">.</span><span class="identifier">old</span><span class="special">(...)</span></code> 1144 is used as shown in <a class="link" href="advanced.html#boost_contract.advanced.old_values_copied_at_body" title="Old Values Copied at Body">Old 1145 Values Copied at Body</a>). For templates, <code class="computeroutput"><a class="link" href="../boost/contract/old_ptr_if_copyable.html" title="Class template old_ptr_if_copyable">boost::contract::old_ptr_if_copyable</a></code> 1146 skips old value copies for non-copyable types and <code class="computeroutput"><a class="link" href="../boost/contract/condition_if.html" title="Function template condition_if">boost::contract::condition_if</a></code> 1147 skips old value copies selectively based on old expression type 1148 requirements (on compilers that do not support <code class="computeroutput"><span class="keyword">if</span> 1149 <span class="keyword">constexpr</span></code>). 1150 </p> 1151 </td> 1152<td> 1153 <p> 1154 Yes, <code class="computeroutput"><span class="identifier">oldof</span></code> keyword 1155 (copied right after preconditions). (Never skipped, not even in 1156 templates for non-copyable types.) 1157 </p> 1158 </td> 1159<td> 1160 <p> 1161 No. 1162 </p> 1163 </td> 1164<td> 1165 <p> 1166 Yes, <code class="literal">old</code> keyword (copied right after preconditions). 1167 (Never skipped, but all types are copyable in Eiffel.) 1168 </p> 1169 </td> 1170<td> 1171 <p> 1172 No. 1173 </p> 1174 </td> 1175</tr> 1176<tr> 1177<td> 1178 <p> 1179 <span class="emphasis"><em>Class invariants</em></span> 1180 </p> 1181 </td> 1182<td> 1183 <p> 1184 Yes, checked at constructor exit, at destructor entry and throw, 1185 and at public function entry, exit, and throw. Same for volatile 1186 class invariants. Static class invariants checked at entry, exit, 1187 and throw for constructors, destructors, and any (also <code class="computeroutput"><span class="keyword">static</span></code>) public function. 1188 </p> 1189 </td> 1190<td> 1191 <p> 1192 Yes, checked at constructor exit, at destructor entry and throw, 1193 and at public function entry, exit, and throw. (Volatile and static 1194 class invariants not supported.) 1195 </p> 1196 </td> 1197<td> 1198 <p> 1199 No. 1200 </p> 1201 </td> 1202<td> 1203 <p> 1204 Yes, checked at constructor exit, and around public functions. 1205 (Volatile and static class invariants do not apply to Eiffel.) 1206 </p> 1207 </td> 1208<td> 1209 <p> 1210 Yes, checked at constructor exit, at destructor entry, and around 1211 public functions. However, invariants cannot call public functions 1212 (to avoid infinite recursion because D does not disable contracts 1213 while checking other contracts). (Volatile and static class invariants 1214 not supported, <code class="computeroutput"><span class="keyword">volatile</span></code> 1215 was deprecated all together in D.) 1216 </p> 1217 </td> 1218</tr> 1219<tr> 1220<td> 1221 <p> 1222 <span class="emphasis"><em>Subcontracting</em></span> 1223 </p> 1224 </td> 1225<td> 1226 <p> 1227 Yes, also supports subcontracting for multiple inheritance (<code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>, 1228 <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>, 1229 and <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code> 1230 are used to declare base classes, overrides and virtual public 1231 functions respectively). 1232 </p> 1233 </td> 1234<td> 1235 <p> 1236 Yes, also supports subcontracting for multiple inheritance, but 1237 preconditions cannot be subcontracted. <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f0" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f0"><sup class="footnote">[a]</sup></a> 1238 </p> 1239 </td> 1240<td> 1241 <p> 1242 No. 1243 </p> 1244 </td> 1245<td> 1246 <p> 1247 Yes. 1248 </p> 1249 </td> 1250<td> 1251 <p> 1252 Yes. 1253 </p> 1254 </td> 1255</tr> 1256<tr> 1257<td> 1258 <p> 1259 <span class="emphasis"><em>Contracts for pure virtual functions</em></span> 1260 </p> 1261 </td> 1262<td> 1263 <p> 1264 Yes (programmed via out-of-line functions as always in C++ with 1265 pure virtual function definitions). 1266 </p> 1267 </td> 1268<td> 1269 <p> 1270 Yes. 1271 </p> 1272 </td> 1273<td> 1274 <p> 1275 No (because no subcontracting). 1276 </p> 1277 </td> 1278<td> 1279 <p> 1280 Yes (contracts for abstract functions). 1281 </p> 1282 </td> 1283<td> 1284 <p> 1285 No. 1286 </p> 1287 </td> 1288</tr> 1289<tr> 1290<td> 1291 <p> 1292 <span class="emphasis"><em>Arbitrary code in contracts</em></span> 1293 </p> 1294 </td> 1295<td> 1296 <p> 1297 Yes (but users are generally recommended to only program assertions 1298 using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> 1299 and if-guard statements within contracts to avoid introducing bugs 1300 and expensive code in contracts, and also to only use public functions 1301 to program preconditions). 1302 </p> 1303 </td> 1304<td> 1305 <p> 1306 No, assertions only (use of only public functions to program preconditions 1307 is recommended but not prescribed). 1308 </p> 1309 </td> 1310<td> 1311 <p> 1312 No, assertions only (in addition contracts of public, protected, 1313 and private members can only use other public, public/protected, 1314 and public/protected/private members respectively). 1315 </p> 1316 </td> 1317<td> 1318 <p> 1319 No, assertions only (in addition only public members can be used 1320 in preconditions). 1321 </p> 1322 </td> 1323<td> 1324 <p> 1325 Yes. 1326 </p> 1327 </td> 1328</tr> 1329<tr> 1330<td> 1331 <p> 1332 <span class="emphasis"><em>Constant-correctness</em></span> 1333 </p> 1334 </td> 1335<td> 1336 <p> 1337 No, enforced only for class invariants and old values (making also 1338 preconditions and postconditions constant-correct is possible but 1339 requires users to program a fare amount of boiler-plate code). 1340 </p> 1341 </td> 1342<td> 1343 <p> 1344 Yes. 1345 </p> 1346 </td> 1347<td> 1348 <p> 1349 Yes (side effects in contracts lead to undefined behaviour). 1350 </p> 1351 </td> 1352<td> 1353 <p> 1354 Yes. 1355 </p> 1356 </td> 1357<td> 1358 <p> 1359 No, enforced only for class invariants. 1360 </p> 1361 </td> 1362</tr> 1363<tr> 1364<td> 1365 <p> 1366 <span class="emphasis"><em>Contracts in specifications</em></span> 1367 </p> 1368 </td> 1369<td> 1370 <p> 1371 No, in function definitions instead (unless programmers manually 1372 write an extra function for any given function). 1373 </p> 1374 </td> 1375<td> 1376 <p> 1377 Yes (in function declarations). 1378 </p> 1379 </td> 1380<td> 1381 <p> 1382 Yes (in function declarations). 1383 </p> 1384 </td> 1385<td> 1386 <p> 1387 Yes. 1388 </p> 1389 </td> 1390<td> 1391 <p> 1392 Yes. 1393 </p> 1394 </td> 1395</tr> 1396<tr> 1397<td> 1398 <p> 1399 <span class="emphasis"><em>Function code ordering</em></span> 1400 </p> 1401 </td> 1402<td> 1403 <p> 1404 Preconditions, postconditions, exception guarantees, body. 1405 </p> 1406 </td> 1407<td> 1408 <p> 1409 Preconditions, postconditions, body. 1410 </p> 1411 </td> 1412<td> 1413 <p> 1414 Preconditions, postconditions, body. 1415 </p> 1416 </td> 1417<td> 1418 <p> 1419 Preconditions, body, postconditions. 1420 </p> 1421 </td> 1422<td> 1423 <p> 1424 Preconditions, postconditions, body. 1425 </p> 1426 </td> 1427</tr> 1428<tr> 1429<td> 1430 <p> 1431 <span class="emphasis"><em>Disable assertion checking within assertions checking 1432 (to avoid infinite recursion when checking contracts)</em></span> 1433 </p> 1434 </td> 1435<td> 1436 <p> 1437 Yes, but use <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585497648.html" title="Macro BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTION">BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTION</a></code> 1438 to disable no assertion while checking preconditions (see also 1439 <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>). 1440 <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f1" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f1"><sup class="footnote">[b]</sup></a> (In multi-threaded programs this introduces a global 1441 lock, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585556352.html" title="Macro BOOST_CONTRACT_DISABLE_THREADS">BOOST_CONTRACT_DISABLE_THREADS</a></code>.) 1442 </p> 1443 </td> 1444<td> 1445 <p> 1446 Yes for class invariants and postconditions, but preconditions 1447 disable no assertion. 1448 </p> 1449 </td> 1450<td> 1451 <p> 1452 No. 1453 </p> 1454 </td> 1455<td> 1456 <p> 1457 Yes. 1458 </p> 1459 </td> 1460<td> 1461 <p> 1462 No. 1463 </p> 1464 </td> 1465</tr> 1466<tr> 1467<td> 1468 <p> 1469 <span class="emphasis"><em>Nested member function calls</em></span> 1470 </p> 1471 </td> 1472<td> 1473 <p> 1474 Disable nothing. <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f2" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f2"><sup class="footnote">[c]</sup></a> 1475 </p> 1476 </td> 1477<td> 1478 <p> 1479 Disable nothing. 1480 </p> 1481 </td> 1482<td> 1483 <p> 1484 Disable nothing. 1485 </p> 1486 </td> 1487<td> 1488 <p> 1489 Disable all contract assertions. 1490 </p> 1491 </td> 1492<td> 1493 <p> 1494 Disable nothing. 1495 </p> 1496 </td> 1497</tr> 1498<tr> 1499<td> 1500 <p> 1501 <span class="emphasis"><em>Disable contract checking</em></span> 1502 </p> 1503 </td> 1504<td> 1505 <p> 1506 Yes, contract checking can be skipped at run-time by defining combinations 1507 of the <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585474880.html" title="Macro BOOST_CONTRACT_NO_PRECONDITIONS">BOOST_CONTRACT_NO_PRECONDITIONS</a></code>, 1508 <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585468496.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>, 1509 <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585434496.html" title="Macro BOOST_CONTRACT_NO_INVARIANTS">BOOST_CONTRACT_NO_INVARIANTS</a></code>, 1510 <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585449728.html" title="Macro BOOST_CONTRACT_NO_ENTRY_INVARIANTS">BOOST_CONTRACT_NO_ENTRY_INVARIANTS</a></code>, 1511 and <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585442112.html" title="Macro BOOST_CONTRACT_NO_EXIT_INVARIANTS">BOOST_CONTRACT_NO_EXIT_INVARIANTS</a></code> 1512 macros (completely removing contract code from compiled object 1513 code is also possible but requires using macros as shown in <a class="link" href="extras.html#boost_contract.extras.disable_contract_compilation__macro_interface_" title="Disable Contract Compilation (Macro Interface)">Disable 1514 Contract Compilation</a>). 1515 </p> 1516 </td> 1517<td> 1518 <p> 1519 Yes (contract code also removed from compiled object code, but 1520 details are compiler-implementation specific). 1521 </p> 1522 </td> 1523<td> 1524 <p> 1525 Yes (contract code also removed from compiled object code, but 1526 details are compiler-implementation specific). 1527 </p> 1528 </td> 1529<td> 1530 <p> 1531 Yes, but only predefined combinations of preconditions, postconditions, 1532 and class invariants can be disabled (contract code also removed 1533 from compiled object code). 1534 </p> 1535 </td> 1536<td> 1537 <p> 1538 Yes. 1539 </p> 1540 </td> 1541</tr> 1542<tr> 1543<td> 1544 <p> 1545 <span class="emphasis"><em>Assertion levels</em></span> 1546 </p> 1547 </td> 1548<td> 1549 <p> 1550 Yes, predefined default, audit, and axiom, in addition programmers 1551 can also define their own levels. 1552 </p> 1553 </td> 1554<td> 1555 <p> 1556 No (but a previous revision of this proposal considered adding 1557 assertion levels under the name of "assertion ordering"). 1558 </p> 1559 </td> 1560<td> 1561 <p> 1562 Yes, predefined default, audit, and axiom. 1563 </p> 1564 </td> 1565<td> 1566 <p> 1567 No. 1568 </p> 1569 </td> 1570<td> 1571 <p> 1572 No. 1573 </p> 1574 </td> 1575</tr> 1576</tbody> 1577<tbody class="footnotes"><tr><td colspan="6"> 1578<div id="ftn.boost_contract.contract_programming_overview.feature_summary.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.feature_summary.f0" class="para"><sup class="para">[a] </sup></a> 1579 <span class="bold"><strong>Rationale:</strong></span> The authors of <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> decided to forbid derived 1580 classes from subcontracting preconditions because they found 1581 that such a feature was rarely, if ever, used (see <a href="http://lists.boost.org/Archives/boost/2010/04/164862.php" target="_top">Re: 1582 [boost] [contract] diff n1962</a>). Still, it should be noted 1583 that even in <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> if a 1584 derived class overrides two functions with preconditions coming 1585 from two different base classes via multiple inheritance, the 1586 overriding function contract will check preconditions from its 1587 two base class functions in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a> 1588 (so even in <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> preconditions 1589 can indirectly subcontract when multiple inheritance is used). 1590 Furthermore, subcontracting preconditions is soundly defined 1591 by the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution 1592 principle</a> so this library allows to subcontract preconditions 1593 as Eiffel does (users can always avoid using this feature if 1594 they have no need for it). (This is essentially the only feature 1595 on which this library deliberately differs from <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a>.) 1596 </p></div> 1597<div id="ftn.boost_contract.contract_programming_overview.feature_summary.f1" class="footnote"><p><a href="#boost_contract.contract_programming_overview.feature_summary.f1" class="para"><sup class="para">[b] </sup></a> 1598 <span class="bold"><strong>Rationale:</strong></span> Technically, it can 1599 be shown that an invalid argument can reach the function body 1600 when assertion checking is disabled while checking preconditions 1601 (that is why <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> does 1602 not disable any assertion while checking preconditions, see 1603 <a href="http://lists.boost.org/Archives/boost/2010/04/164862.php" target="_top">Re: 1604 [boost] [contract] diff n1962</a>). However, this can only 1605 happen while checking contracts when an invalid argument passed 1606 to the body, which should results in the body either throwing 1607 an exception or returning an incorrect result, will in turn fail 1608 the contract assertion being checked by the caller of the body 1609 and invoke the related contract failure handler as desired in 1610 the first place. Furthermore, not disabling assertions while 1611 checking preconditions (like <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> 1612 does) makes it possible to have infinite recursion while checking 1613 preconditions. Therefore, this library by default disables assertion 1614 checking also while checking preconditions (like Eiffel does), 1615 but it also provides the <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585497648.html" title="Macro BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTION">BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTION</a></code> 1616 configuration macro so users can change this behaviour to match 1617 <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> if needed. 1618 </p></div> 1619<div id="ftn.boost_contract.contract_programming_overview.feature_summary.f2" class="footnote"><p><a href="#boost_contract.contract_programming_overview.feature_summary.f2" class="para"><sup class="para">[c] </sup></a> 1620 <span class="bold"><strong>Rationale:</strong></span> Older versions of 1621 this library defined a data member in the user class that was 1622 automatically used to disable checking of class invariants within 1623 nested member function calls (similarly to Eiffel). This feature 1624 was required by older revisions of <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> 1625 but it is no longer required by <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> 1626 (because it seems to be motivated purely by optimization reasons 1627 while similar performances can be achieved by disabling invariants 1628 for release builds). Furthermore, in multi-threaded programs 1629 this feature would introduce a lock that synchronizes all member 1630 functions calls for a given object. Therefore, this feature was 1631 removed in the current revision of this library. 1632 </p></div> 1633</td></tr></tbody> 1634</table></div> 1635<p> 1636 The authors of this library consulted the following references that implement 1637 contract programming for C++ (but usually for only a limited set of features, 1638 or using preprocessing tools other than the C++ preprocessor and external 1639 to the language itself) and for other languages (see <a class="link" href="bibliography.html" title="Bibliography">Bibliography</a> 1640 for a complete list of all references consulted during the design and development 1641 of this library): 1642 </p> 1643<div class="informaltable"><table class="table"> 1644<colgroup> 1645<col> 1646<col> 1647<col> 1648</colgroup> 1649<thead><tr> 1650<th> 1651 <p> 1652 Reference 1653 </p> 1654 </th> 1655<th> 1656 <p> 1657 Language 1658 </p> 1659 </th> 1660<th> 1661 <p> 1662 Notes 1663 </p> 1664 </th> 1665</tr></thead> 1666<tbody> 1667<tr> 1668<td> 1669 <p> 1670 <a class="link" href="bibliography.html#Bright04b_anchor">[Bright04b]</a> 1671 </p> 1672 </td> 1673<td> 1674 <p> 1675 Digital Mars C++ 1676 </p> 1677 </td> 1678<td> 1679 <p> 1680 The Digital Mars C++ compiler extends C++ adding contract programming 1681 language support (among many other features). 1682 </p> 1683 </td> 1684</tr> 1685<tr> 1686<td> 1687 <p> 1688 <a class="link" href="bibliography.html#Maley99_anchor">[Maley99]</a> 1689 </p> 1690 </td> 1691<td> 1692 <p> 1693 C++ 1694 </p> 1695 </td> 1696<td> 1697 <p> 1698 This supports contract programming including subcontracting but 1699 with limitations (e.g., programmers need to manually build an inheritance 1700 tree using artificial template parameters), it does not use macros 1701 but programmers are required to write by hand a significant amount 1702 of boiler-plate code. (The authors have found this work very inspiring 1703 when developing initial revisions of this library especially for 1704 its attempt to support subcontracting.) 1705 </p> 1706 </td> 1707</tr> 1708<tr> 1709<td> 1710 <p> 1711 <a class="link" href="bibliography.html#Lindrud04_anchor">[Lindrud04]</a> 1712 </p> 1713 </td> 1714<td> 1715 <p> 1716 C++ 1717 </p> 1718 </td> 1719<td> 1720 <p> 1721 This supports class invariants and old values but it does not support 1722 subcontracting (contracts are specified within definitions instead 1723 of declarations and assertions are not constant-correct). 1724 </p> 1725 </td> 1726</tr> 1727<tr> 1728<td> 1729 <p> 1730 <a class="link" href="bibliography.html#Tandin04_anchor">[Tandin04]</a> 1731 </p> 1732 </td> 1733<td> 1734 <p> 1735 C++ 1736 </p> 1737 </td> 1738<td> 1739 <p> 1740 Interestingly, these contract macros automatically generate Doxygen 1741 documentation <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f3" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f3"><sup class="footnote">[a]</sup></a> but old values, class invariants, and subcontracting 1742 are not supported (plus contracts are specified within definitions 1743 instead of declarations and assertions are not constant-correct). 1744 </p> 1745 </td> 1746</tr> 1747<tr> 1748<td> 1749 <p> 1750 <a class="link" href="bibliography.html#Nana_anchor">[Nana]</a> 1751 </p> 1752 </td> 1753<td> 1754 <p> 1755 GCC C++ 1756 </p> 1757 </td> 1758<td> 1759 <p> 1760 This uses macros but it only works on GCC (and maybe Clang, but 1761 it does not work on MSVC, etc.). It does not support subcontracting. 1762 It requires extra care to program postconditions for functions 1763 with multiple return statements. It seems that it might not check 1764 class invariants when functions throw exceptions (unless the <code class="computeroutput"><span class="identifier">END</span></code> macro does that...). (In 1765 addition, it provides tools for logging and integration with GDB.) 1766 </p> 1767 </td> 1768</tr> 1769<tr> 1770<td> 1771 <p> 1772 <a class="link" href="bibliography.html#C2_anchor">[C2]</a> 1773 </p> 1774 </td> 1775<td> 1776 <p> 1777 C++ 1778 </p> 1779 </td> 1780<td> 1781 <p> 1782 This uses an external preprocessing tool (the authors could no 1783 longer find this project's code to evaluate it). 1784 </p> 1785 </td> 1786</tr> 1787<tr> 1788<td> 1789 <p> 1790 <a class="link" href="bibliography.html#iContract_anchor">[iContract]</a> 1791 </p> 1792 </td> 1793<td> 1794 <p> 1795 Java 1796 </p> 1797 </td> 1798<td> 1799 <p> 1800 This uses an external preprocessing tool. 1801 </p> 1802 </td> 1803</tr> 1804<tr> 1805<td> 1806 <p> 1807 <a class="link" href="bibliography.html#Jcontract_anchor">[Jcontract]</a> 1808 </p> 1809 </td> 1810<td> 1811 <p> 1812 Java 1813 </p> 1814 </td> 1815<td> 1816 <p> 1817 This uses an external preprocessing tool. 1818 </p> 1819 </td> 1820</tr> 1821<tr> 1822<td> 1823 <p> 1824 <a class="link" href="bibliography.html#CodeContracts_anchor">[CodeContracts]</a> 1825 </p> 1826 </td> 1827<td> 1828 <p> 1829 .NET 1830 </p> 1831 </td> 1832<td> 1833 <p> 1834 Microsoft contract programming for .NET programming languages. 1835 </p> 1836 </td> 1837</tr> 1838<tr> 1839<td> 1840 <p> 1841 <a class="link" href="bibliography.html#SpecSharp_anchor">[SpecSharp]</a> 1842 </p> 1843 </td> 1844<td> 1845 <p> 1846 C# 1847 </p> 1848 </td> 1849<td> 1850 <p> 1851 This is a C# extension with contract programming language support. 1852 </p> 1853 </td> 1854</tr> 1855<tr> 1856<td> 1857 <p> 1858 <a class="link" href="bibliography.html#Chrome_anchor">[Chrome]</a> 1859 </p> 1860 </td> 1861<td> 1862 <p> 1863 Object Pascal 1864 </p> 1865 </td> 1866<td> 1867 <p> 1868 This is the .NET version of Object Pascal and it has language support 1869 for contract programming. 1870 </p> 1871 </td> 1872</tr> 1873<tr> 1874<td> 1875 <p> 1876 <a class="link" href="bibliography.html#SPARKAda_anchor">[SPARKAda]</a> 1877 </p> 1878 </td> 1879<td> 1880 <p> 1881 Ada 1882 </p> 1883 </td> 1884<td> 1885 <p> 1886 This is an Ada-like programming language with support for contract 1887 programming. 1888 </p> 1889 </td> 1890</tr> 1891</tbody> 1892<tbody class="footnotes"><tr><td colspan="3"><div id="ftn.boost_contract.contract_programming_overview.feature_summary.f3" class="footnote"><p><a href="#boost_contract.contract_programming_overview.feature_summary.f3" class="para"><sup class="para">[a] </sup></a> 1893 <span class="bold"><strong>Rationale:</strong></span> Older versions of 1894 this library also automatically generated Doxygen documentation 1895 from contract definition macros. This functionality was abandoned 1896 for a number of reasons: This library no longer uses macros to 1897 program contracts; even before that, the implementation of this 1898 library macros became too complex and the Doxygen preprocessor 1899 was no longer able to expand them; the Doxygen documentation 1900 was just a repeat of the contract code (so programmers could 1901 directly look at contracts in the source code); Doxygen might 1902 not necessarily be the documentation tool used by all C++ programmers. 1903 </p></div></td></tr></tbody> 1904</table></div> 1905<p> 1906 To the best knowledge of the authors, this the only library that fully supports 1907 all contract programming features for C++ (without using preprocessing tools 1908 external to the language itself). In general: 1909 </p> 1910<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1911<li class="listitem"> 1912 Implementing preconditions and postconditions in C++ is not difficult 1913 (e.g., using some kind of RAII object). 1914 </li> 1915<li class="listitem"> 1916 Implementing postcondition old values is also not too difficult (usually 1917 requiring programmers to copy old values into local variables), but it 1918 is already somewhat more difficult to ensure such copies are not performed 1919 when postconditions are disabled. <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f4" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f4"><sup class="footnote">[16]</sup></a> 1920 </li> 1921<li class="listitem"> 1922 Implementing class invariants is more involved (especially if done automatically, 1923 without requiring programmers to manually invoke extra functions to check 1924 the invariants). <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f5" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f5"><sup class="footnote">[17]</sup></a> In addition, all references reviewed by the authors seem 1925 to not consider static and volatile functions not supporting static and 1926 volatile invariants respectively. 1927 </li> 1928<li class="listitem"> 1929 Implementing subcontracting involves a significant amount of complexity 1930 and it seems to not be properly supported by any C++ library other than 1931 this one (especially when handling multiple inheritance, correctly copying 1932 postcondition old values across all overridden contracts deep in the 1933 inheritance tree, and correctly reporting the return value to the postconditions 1934 of overridden virtual functions in base classes). <a href="#ftn.boost_contract.contract_programming_overview.feature_summary.f6" class="footnote" name="boost_contract.contract_programming_overview.feature_summary.f6"><sup class="footnote">[18]</sup></a> 1935 </li> 1936</ul></div> 1937</div> 1938<div class="footnotes"> 1939<br><hr style="width:100; text-align:left;margin-left: 0"> 1940<div id="ftn.boost_contract.contract_programming_overview.assertions.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.assertions.f0" class="para"><sup class="para">[6] </sup></a> 1941 The nomenclature of wide and narrow contracts has gained some popularity 1942 in recent years in the C++ community (appearing in a number of more 1943 recent proposals to add contract programming to the C++ standard, see 1944 <a class="link" href="bibliography.html" title="Bibliography">Bibliography</a>). This 1945 nomenclature is perfectly reasonable but it is not often used in this 1946 document just because the authors usually prefer to explicitly say 1947 "this operation has no preconditions..." or "this operation 1948 has preconditions..." (this is just a matter of taste). 1949 </p></div> 1950<div id="ftn.boost_contract.contract_programming_overview.assertions.f1" class="footnote"><p><a href="#boost_contract.contract_programming_overview.assertions.f1" class="para"><sup class="para">[7] </sup></a> 1951 <span class="bold"><strong>Rationale:</strong></span> Contract assertions for 1952 exception guarantees were first introduced by this library, they are 1953 not part of <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> or other references 1954 listed in the <a class="link" href="bibliography.html" title="Bibliography">Bibliography</a> 1955 (even if exception safety guarantees have long been part of C++ STL 1956 documentation). 1957 </p></div> 1958<div id="ftn.boost_contract.contract_programming_overview.assertions.f2" class="footnote"><p><a href="#boost_contract.contract_programming_overview.assertions.f2" class="para"><sup class="para">[8] </sup></a> 1959 <span class="bold"><strong>Rationale:</strong></span> Static and volatile class 1960 invariants were first introduced by this library (simply to reflect 1961 the fact that C++ supports also static and volatile public functions), 1962 they are not part of <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> or 1963 other references listed in the <a class="link" href="bibliography.html" title="Bibliography">Bibliography</a>. 1964 </p></div> 1965<div id="ftn.boost_contract.contract_programming_overview.assertions.f3" class="footnote"><p><a href="#boost_contract.contract_programming_overview.assertions.f3" class="para"><sup class="para">[9] </sup></a> 1966 <span class="bold"><strong>Rationale:</strong></span> <code class="computeroutput"><a class="link" href="../BOOST_CO_idm46268585556352.html" title="Macro BOOST_CONTRACT_DISABLE_THREADS">BOOST_CONTRACT_DISABLE_THREADS</a></code> 1967 is named after <code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code>. 1968 </p></div> 1969<div id="ftn.boost_contract.contract_programming_overview.benefits_and_costs.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.benefits_and_costs.f0" class="para"><sup class="para">[10] </sup></a> 1970 Of course, if contracts are ill-written then contract programming is 1971 of little use. However, it is less likely to have a bug in both the 1972 function body and the contract than in the function body alone. For 1973 example, consider the validation of a result in postconditions. Validating 1974 the return value might seem redundant, but in this case we actually 1975 want that redundancy. When programmers write a function, there is a 1976 certain probability that they make a mistake in implementing the function 1977 body. When programmers specify the result of the function in the postconditions, 1978 there is also a certain probability that they make a mistake in writing 1979 the contract. However, the probability that programmers make a mistake 1980 twice (in both the body <span class="emphasis"><em>and</em></span> the contract) is in 1981 general lower than the probability that the mistake is made only once 1982 (in either the body <span class="emphasis"><em>or</em></span> the contract). 1983 </p></div> 1984<div id="ftn.boost_contract.contract_programming_overview.destructor_calls.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.destructor_calls.f0" class="para"><sup class="para">[11] </sup></a> 1985 <span class="bold"><strong>Rationale:</strong></span> Postconditions for 1986 destructors are not part of <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a> 1987 or other references listed in the <a class="link" href="bibliography.html" title="Bibliography">Bibliography</a> 1988 (but with respect to <a class="link" href="bibliography.html#Meyer97_anchor">[Meyer97]</a> 1989 it should be noted that Eiffel does not support static data members 1990 and that might by why destructors do not have postconditions 1991 in Eiffel). However, in principle there could be uses for destructor 1992 postconditions so this library supports postconditions for destructors 1993 (e.g., a class that counts object instances could use destructor 1994 postconditions to assert that an instance counter stored in a 1995 static data member is decreased by <code class="computeroutput"><span class="number">1</span></code> 1996 because the object has been destructed). 1997 </p></div> 1998<div id="ftn.boost_contract.contract_programming_overview.constant_correctness.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.constant_correctness.f0" class="para"><sup class="para">[12] </sup></a> 1999 Note that this is true when using C-style <code class="computeroutput"><span class="identifier">assert</span></code> 2000 as well. 2001 </p></div> 2002<div id="ftn.boost_contract.contract_programming_overview.specifications_vs__implementation.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.specifications_vs__implementation.f0" class="para"><sup class="para">[13] </sup></a> 2003 <span class="bold"><strong>Rationale:</strong></span> Out of curiosity, if C++ <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#45" target="_top">defect 2004 45</a> had not been fixed, this library could have been implemented 2005 to generate a compile-time error when precondition assertions use non-public 2006 members more similarly to Eiffel's implementation (but still, not necessary 2007 the best approach for C++). 2008 </p></div> 2009<div id="ftn.boost_contract.contract_programming_overview.on_contract_failures.f0" class="footnote"><p><a href="#boost_contract.contract_programming_overview.on_contract_failures.f0" class="para"><sup class="para">[14] </sup></a> 2010 <span class="bold"><strong>Rationale:</strong></span> If the evaluation of a contract 2011 assertion throws an exception, the assertion cannot be checked to be true 2012 so the only safe thing to assume is that the assertion failed (indeed the 2013 contract assertion checking failed) and call the contract failure handler 2014 in this case also. 2015 </p></div> 2016<div id="ftn.boost_contract.contract_programming_overview.on_contract_failures.f1" class="footnote"><p><a href="#boost_contract.contract_programming_overview.on_contract_failures.f1" class="para"><sup class="para">[15] </sup></a> 2017 <span class="bold"><strong>Rationale:</strong></span> This customizable failure handling 2018 mechanism is similar to the one used by C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code> 2019 and also to the one proposed in <a class="link" href="bibliography.html#N1962_anchor">[N1962]</a>. 2020 </p></div> 2021<div id="ftn.boost_contract.contract_programming_overview.feature_summary.f4" class="footnote"> 2022<p><a href="#boost_contract.contract_programming_overview.feature_summary.f4" class="para"><sup class="para">[16] </sup></a> 2023 For example, the following pseudocode attempts to emulate old values 2024 in <a class="link" href="bibliography.html#P0380_anchor">[P0380]</a>: 2025</p> 2026<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">scope_exit</span> <span class="special">{</span> <span class="comment">// RAII.</span> 2027 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">F</span><span class="special">></span> 2028 <span class="keyword">explicit</span> <span class="identifier">scope_exit</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">f_</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span> <span class="special">{}</span> 2029 <span class="special">~</span><span class="identifier">scope_exit</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">f_</span><span class="special">();</span> <span class="special">}</span> 2030 2031 <span class="identifier">scope_exit</span><span class="special">(</span><span class="identifier">scope_exit</span> <span class="keyword">const</span><span class="special">&)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span> 2032 <span class="identifier">scope_exit</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">scope_exit</span> <span class="keyword">const</span><span class="special">&)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span> 2033<span class="keyword">private</span><span class="special">:</span> 2034 <span class="identifier">std</span><span class="special">::</span><span class="identifier">function</span><span class="special"><</span><span class="keyword">void</span> <span class="special">()></span> <span class="identifier">f_</span><span class="special">;</span> 2035<span class="special">};</span> 2036 2037<span class="keyword">void</span> <span class="identifier">fswap</span><span class="special">(</span><span class="identifier">file</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">file</span><span class="special">&</span> <span class="identifier">y</span><span class="special">)</span> 2038 <span class="special">[[</span><span class="identifier">expects</span><span class="special">:</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">closed</span><span class="special">()]]</span> 2039 <span class="special">[[</span><span class="identifier">expects</span><span class="special">:</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">closed</span><span class="special">()]]</span> 2040 <span class="comment">// Cannot use [[ensures]] for postconditions so to emulate old values.</span> 2041<span class="special">{</span> 2042 <span class="identifier">file</span> <span class="identifier">old_x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="comment">// Emulate old values with local copies (not disabled).</span> 2043 <span class="identifier">file</span> <span class="identifier">old_y</span> <span class="special">=</span> <span class="identifier">y</span><span class="special">;</span> 2044 <span class="identifier">scope_exit</span> <span class="identifier">ensures</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Check after local objects destroyed.</span> 2045 <span class="keyword">if</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uncaught_exceptions</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// Check only if no throw.</span> 2046 <span class="special">[[</span><span class="identifier">assert</span><span class="special">:</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">closed</span><span class="special">()]]</span> 2047 <span class="special">[[</span><span class="identifier">assert</span><span class="special">:</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">closed</span><span class="special">()]]</span> 2048 <span class="special">[[</span><span class="identifier">assert</span><span class="special">:</span> <span class="identifier">x</span> <span class="special">==</span> <span class="identifier">old_y</span><span class="special">]]</span> 2049 <span class="special">[[</span><span class="identifier">assert</span><span class="special">:</span> <span class="identifier">y</span> <span class="special">==</span> <span class="identifier">old_x</span><span class="special">]]</span> 2050 <span class="special">}</span> 2051 <span class="special">});</span> 2052 2053 <span class="identifier">x</span><span class="special">.</span><span class="identifier">open</span><span class="special">();</span> 2054 <span class="identifier">scope_exit</span> <span class="identifier">close_x</span><span class="special">([&]</span> <span class="special">{</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">close</span><span class="special">();</span> <span class="special">});</span> 2055 <span class="identifier">y</span><span class="special">.</span><span class="identifier">open</span><span class="special">();</span> 2056 <span class="identifier">scope_exit</span> <span class="identifier">close_y</span><span class="special">([&]</span> <span class="special">{</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">close</span><span class="special">();</span> <span class="special">});</span> 2057 <span class="identifier">file</span> <span class="identifier">z</span> <span class="special">=</span> <span class="identifier">file</span><span class="special">::</span><span class="identifier">temp</span><span class="special">();</span> 2058 <span class="identifier">z</span><span class="special">.</span><span class="identifier">open</span><span class="special">;</span> 2059 <span class="identifier">scope_exit</span> <span class="identifier">close_z</span><span class="special">([&]</span> <span class="special">{</span> <span class="identifier">z</span><span class="special">.</span><span class="identifier">close</span><span class="special">();</span> <span class="special">});</span> 2060 2061 <span class="identifier">x</span><span class="special">.</span><span class="identifier">mv</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span> 2062 <span class="identifier">y</span><span class="special">.</span><span class="identifier">mv</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> 2063 <span class="identifier">z</span><span class="special">.</span><span class="identifier">mv</span><span class="special">(</span><span class="identifier">y</span><span class="special">);</span> 2064<span class="special">}</span> 2065</pre> 2066<p> 2067 This requires boiler-plate code to make sure postconditions are correctly 2068 checked only if the function did not throw an exception and in a <code class="computeroutput"><span class="identifier">scope_exit</span></code> RAII object after all 2069 other local objects have been destroyed (because some of these destructors 2070 contribute to establishing the postconditions). Still, it never disables 2071 old value copies (not even if postconditions are disabled in release 2072 builds, this would require adding even more boiler-plate code using 2073 <code class="computeroutput"><span class="preprocessor">#ifdef</span></code>, etc.). 2074 </p> 2075</div> 2076<div id="ftn.boost_contract.contract_programming_overview.feature_summary.f5" class="footnote"> 2077<p><a href="#boost_contract.contract_programming_overview.feature_summary.f5" class="para"><sup class="para">[17] </sup></a> 2078 For example, the following pseudocode attempts to emulation of class 2079 invariants in <a class="link" href="bibliography.html#P0380_anchor">[P0380]</a>: 2080</p> 2081<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> 2082<span class="keyword">class</span> <span class="identifier">vector</span> <span class="special">{</span> 2083 <span class="keyword">bool</span> <span class="identifier">invariant</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="comment">// Check invariants at...</span> 2084 <span class="special">[[</span><span class="identifier">assert</span><span class="special">:</span> <span class="identifier">empty</span><span class="special">()</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)]]</span> 2085 <span class="special">[[</span><span class="identifier">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> 2086 <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> 2087 <span class="special">}</span> 2088 2089<span class="keyword">public</span><span class="special">:</span> 2090 <span class="identifier">vector</span><span class="special">()</span> 2091 <span class="special">[[</span><span class="identifier">ensures</span><span class="special">:</span> <span class="identifier">invariant</span><span class="special">()]]</span> <span class="comment">// ...constructor exit (only if no throw).</span> 2092 <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> 2093 2094 <span class="special">~</span><span class="identifier">vector</span><span class="special">()</span> <span class="keyword">noexcept</span> 2095 <span class="special">[[</span><span class="identifier">expects</span><span class="special">:</span> <span class="identifier">invariant</span><span class="special">()]]</span> <span class="comment">// ...destructor entry.</span> 2096 <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> 2097 2098 <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> 2099 <span class="special">[[</span><span class="identifier">expects</span><span class="special">:</span> <span class="identifier">invariant</span><span class="special">()]]</span> <span class="comment">// ...public function entry.</span> 2100 <span class="special">[[</span><span class="identifier">ensures</span><span class="special">:</span> <span class="identifier">invariant</span><span class="special">()]]</span> <span class="comment">// ...public function exit (if no throw).</span> 2101 <span class="keyword">try</span> <span class="special">{</span> 2102 <span class="special">...</span> <span class="comment">// Function body.</span> 2103 <span class="special">}</span> <span class="keyword">catch</span><span class="special">(...)</span> <span class="special">{</span> 2104 <span class="identifier">invariant</span><span class="special">();</span> <span class="comment">// ...public function exit (if throw).</span> 2105 <span class="keyword">throw</span><span class="special">;</span> 2106 <span class="special">}</span> 2107 2108 <span class="special">...</span> 2109<span class="special">};</span> 2110</pre> 2111<p> 2112 This requires boiler-plate code to manually invoke the function that 2113 checks the invariants (note that invariants are checked at public function 2114 exit regardless of exceptions being thrown while postconditions are 2115 not). In case the destructor can throw (e.g., it is declared <code class="computeroutput"><span class="keyword">noexcept</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span></code>), 2116 the destructor also requires a <code class="computeroutput"><span class="keyword">try</span><span class="special">-</span><span class="keyword">catch</span></code> 2117 statement similar to the one programmed for <code class="computeroutput"><span class="identifier">push_back</span></code> 2118 to check class invariants at destructor exit when it throws exceptions. 2119 Still, an outstanding issue remains to avoid infinite recursion if 2120 also <code class="computeroutput"><span class="identifier">empty</span></code> and <code class="computeroutput"><span class="identifier">size</span></code> are public functions programmed 2121 to check class invariants (because <a class="link" href="bibliography.html#P0380_anchor">[P0380]</a> 2122 does not automatically disable assertions while checking other assertions). 2123 </p> 2124</div> 2125<div id="ftn.boost_contract.contract_programming_overview.feature_summary.f6" class="footnote"><p><a href="#boost_contract.contract_programming_overview.feature_summary.f6" class="para"><sup class="para">[18] </sup></a> 2126 For example, it is not really possible to sketch pseudocode based on 2127 <a class="link" href="bibliography.html#P0380_anchor">[P0380]</a> that emulates subcontracting 2128 in the general case. 2129 </p></div> 2130</div> 2131</div> 2132<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 2133<td align="left"></td> 2134<td align="right"><div class="copyright-footer">Copyright © 2008-2019 Lorenzo Caminiti<p> 2135 Distributed under the Boost Software License, Version 1.0 (see accompanying 2136 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>) 2137 </p> 2138</div></td> 2139</tr></table> 2140<hr> 2141<div class="spirit-nav"> 2142<a accesskey="p" href="getting_started.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="tutorial.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 2143</div> 2144</body> 2145</html> 2146
