Public Functions</a></span></dt>
</dl></div>
<p>
- This section is a guide to basic usages of this library.
+ This section is a guide to basic usage of this library.
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
The <code class="computeroutput"><a class="link" href="../boost/contract/function.html" title="Function function">boost::contract::function</a></code>
function returns an RAII object that must always be assigned to a local variable
of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
- (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870548928.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
+ (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999694064.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
<a href="#ftn.boost_contract.tutorial.non_member_functions.f0" class="footnote" name="boost_contract.tutorial.non_member_functions.f0"><sup class="footnote">[19]</sup></a> Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code>
declarations cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
type must be explicitly specified (otherwise this library will generate a
compile-time error prior C++17 and a run-time error post C++17). <a href="#ftn.boost_contract.tutorial.non_member_functions.f1" class="footnote" name="boost_contract.tutorial.non_member_functions.f1"><sup class="footnote">[20]</sup></a> The function body is programmed right after the declaration of
- the RAII object.
+ this RAII object.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<p>
When preconditions are specified, they are programmed using a functor <code class="literal"><span class="emphasis"><em>r</em></span></code>
passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">)</span></code> that can be called with no parameters as
- <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code>.
+ in <code class="literal"><span class="emphasis"><em>r</em></span></code><code class="computeroutput"><span class="special">()</span></code>.
Contracts that do not have preconditions simply do not call <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code>. Preconditions must appear before postconditions
and exception guarantees when these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>
and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception
<p>
The precondition functor should capture all the variables that it needs to
assert the preconditions. These variables can be captured by value when the
- overhead of copying such variables is acceptable. <a href="#ftn.boost_contract.tutorial.preconditions.f1" class="footnote" name="boost_contract.tutorial.preconditions.f1"><sup class="footnote">[22]</sup></a> In any case, precondition assertions should not modify the value
- of the captured variables, even when those are captured by reference (see
- <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>).
+ overhead of copying such variables is acceptable. <a href="#ftn.boost_contract.tutorial.preconditions.f1" class="footnote" name="boost_contract.tutorial.preconditions.f1"><sup class="footnote">[22]</sup></a> In any case, programmers should not write precondition assertions
+ that modify the value of the captured variables, even when those are captured
+
by reference (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>).
</p>
<p>
Any code can be programmed in the precondition functor, but it is recommended
at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
to program precondition assertions because that enables this library to print
informative error messages when the asserted conditions are evaluated to
- be false (this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
+ be false (
note that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
Macros</a>):
</p>
-<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">bool_cond</span><span class="special">)</span>
-<span class="comment">// Or, if `bool_cond` contains commas `,` not already within parenthesis `()`...</span>
-<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><span class="identifier">bool_cond</span><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
+<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span>
+<span class="comment">// Or, if `boolean-condition` contains commas `,` not already within parenthesis `()`...</span>
+<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
</pre>
<p>
This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/precondition_failure.html" title="Function precondition_failure">boost::contract::precondition_failure</a></code>
if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
- conditions are false and, more in general, if calling the functor specified
+ conditions are false or, more in general, if calling the functor specified
via <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> throws any exception. By default, this
failure handler prints an error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code>
and terminates the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code>
<p>
When postconditions are specified, they are programmed using a functor <code class="literal"><span class="emphasis"><em>s</em></span></code>
passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code> that can be called with no parameters as
- <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code>.
+ in <code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">()</span></code>.
Contracts that do not have postconditions simply do not call <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code>. Postconditions must appear after preconditions
but before exception guarantees when these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>
and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception
<span class="special">}</span>
</pre>
<p>
- The postcondition functor should capture all variables that it needs to assert
- the postconditions. In general, these variables should be captured by reference
- and not by value (because postconditions need to access the value that these
- variables will have at function exit, and not the value these variables had
- when the postcondition functor was first constructed). Postconditions can
- also capture return and old values (see <a class="link" href="tutorial.html#boost_contract.tutorial.return_values" title="Return Values">Return
+ The postcondition functor should capture all the variables that it needs
+ to assert the postconditions. In general, these variables should be captured
+ by reference and not by value (because postconditions need to access the
+ value that these variables will have at function exit, and not the value
+ these variables had when the postcondition functor was first declared). Postconditions
+
can also capture return and old values (see <a class="link" href="tutorial.html#boost_contract.tutorial.return_values" title="Return Values">Return
Values</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.old_values" title="Old Values">Old
- Values</a>). In any case, postcondition assertions should not modify the
- value of the captured variables (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>).
+ Values</a>). In any case, programmers should not write postcondition assertions
+ that modify the value of the captured variables, even when those are captured
+ by reference (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>).
</p>
<p>
Any code can be programmed in the postcondition functor, but it is recommended
at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
to program postcondition assertions because that enables this library to
print informative error messages when the asserted conditions are evaluated
- to be false (this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
+ to be false (
note that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
Macros</a>):
</p>
-<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">bool_cond</span><span class="special">)</span>
-<span class="comment">// Or, if `bool_cond` has commas `,` not already within parenthesis `()`...</span>
-<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><span class="identifier">bool_cond</span><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
+<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span>
+<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span>
+<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
</pre>
<p>
This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/postcondition_failure.html" title="Function postcondition_failure">boost::contract::postcondition_failure</a></code>
if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
- conditions are false and, more in general, if calling the functor specified
+ conditions are false or, more in general, if calling the functor specified
via <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code> throws any exception. By default, this
failure handler prints an error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code>
and terminates the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code>
the program with an error code, etc.).
</p>
<p>
- For non-void virtual public functions and public function overrides, the
- functor <code class="literal"><span class="emphasis"><em>s</em></span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code> is not a nullary functor, instead it is
+ For non-void virtual public functions and non-void public function overrides,
+ the functor <code class="literal"><span class="emphasis"><em>s</em></span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">)</span></code> is not a nullary functor, instead it is
a unary functor taking a variable holding the return value as its one parameter
<code class="literal"><span class="emphasis"><em>s</em></span></code><code class="computeroutput"><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>result</em></span></code><code class="computeroutput"><span class="special">)</span></code> (this is to properly support subcontracting,
see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span>
<span class="special">...</span>
<span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Also capture `result` reference...</span>
- <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">result</span> <span class="special">...);</span> <span class="comment">// ...but should not modify captures.</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">result</span> <span class="special">==</span> <span class="special">...);</span> <span class="comment">// ...but should not modify captures.</span>
<span class="special">...</span>
<span class="special">})</span>
<span class="special">...</span>
<span class="special">;</span>
- <span class="special">...</span> <span class="comment">// Assign `result` at each return.</span>
+ <span class="special">...</span>
+ <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="special">...;</span> <span class="comment">// Assign `result` at each return.</span>
<span class="special">}</span>
</pre>
<p>
be done ensuring that <span class="emphasis"><em>all</em></span> <code class="computeroutput"><span class="keyword">return</span></code>
statements in the function are of the form:
</p>
-<pre class="programlisting"><span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">return_expr</span><span class="special">;</span> <span class="comment">// Assign `result` at each return.</span>
+<pre class="programlisting"><code class="literal"><span class="emphasis"><em>return-type</em></span></code> <span class="identifier">result</span><span class="special">;</span>
+<span class="special">...</span>
+<span class="keyword">return</span> <span class="identifier">result</span> <span class="special">=</span> <code class="literal"><span class="emphasis"><em>return-expression</em></span></code><span class="special">;</span> <span class="comment">// Assign `result` at each return.</span>
</pre>
<p>
The functor used to program postconditions should capture the result variable
by reference and not by value (because postconditions must access the value
the result variable will have at function exit, and not the value the result
- variable had when the postcondition functor was first constructed). The return
+ variable had when the postcondition functor was first declared). The return
value should never be used in preconditions, old value copies, or exception
guarantees (because the return value is not yet correctly evaluated and set
when preconditions are checked, old values are copied, or if the function
Return Values</a>).
</p>
<p>
- Non-void virtual public functions and public function overrides must always
- declare and use a result variable even when postconditions do not directly
- use the function return value (this is to properly support subcontracting,
+ Non-void virtual public functions and non-void public function overrides
+ must always declare and use a result variable even when postconditions do
+ not directly use the function return value (this is to properly support subcontracting,
see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual
Public Functions</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public
Function Overrides</a>).
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">function</span><span class="special">()</span> <span class="comment">// Same for all other contracts.</span>
<span class="special">...</span> <span class="comment">// Preconditions shall not use old values.</span>
<span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference...</span>
- <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(*</span><span class="identifier">old_var</span> <span class="special">...);</span> <span class="comment">// ...but should not modify captures.</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(*</span><span class="identifier">old_var</span> <span class="special">==</span> <span class="special">...);</span> <span class="comment">// ...but should not modify captures.</span>
<span class="special">...</span>
<span class="special">})</span>
<span class="special">.</span><span class="identifier">except</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Capture by reference...</span>
<p>
Old values should not be used in preconditions and this library does not
guarantee that old value pointers are always not null when preconditions
- are checked. <a href="#ftn.boost_contract.tutorial.old_values.f2" class="footnote" name="boost_contract.tutorial.old_values.f2"><sup class="footnote">[26]</sup></a> See <a class="link" href="advanced.html#boost_contract.advanced.old_value_copies_at_body" title="Old Value Copies at Body">Old
- Value Copies at Body</a> for delaying the copy of old values until after
+ are checked. <a href="#ftn.boost_contract.tutorial.old_values.f2" class="footnote" name="boost_contract.tutorial.old_values.f2"><sup class="footnote">[26]</sup></a> See <a class="link" href="advanced.html#boost_contract.advanced.old_values_copied_at_body" title="Old Values Copied at Body">Old
+ Values Copied at Body</a> for delaying the copy of old values until after
class invariants (for constructors, destructors, and public functions) and
- preconditions are checked (this allows to program old value expressions under
- the simplifying assumption that class invariant and precondition assertions
- are satisfied already).
+ preconditions are checked (when necessary, this allows to program old value
+ expressions under the simplifying assumption that class invariant and precondition
+ assertions are satisfied already).
</p>
<p>
<code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> is
Public Functions</a> and <a class="link" href="tutorial.html#boost_contract.tutorial.public_function_overrides__subcontracting_" title="Public Function Overrides (Subcontracting)">Public
Function Overrides</a>). C++11 auto declarations can be used with <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code> for brevity
<code class="computeroutput"><span class="keyword">auto</span> </code><code class="literal">old_<span class="emphasis"><em>variable-name</em></span>
- = BOOST_CONTRACT_OLDOF(<span class="emphasis"><em>expression</em></span>)</code>. See <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No Macros</a>
- to program old values without using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>
+ = BOOST_CONTRACT_OLDOF(<span class="emphasis"><em>expression</em></span>)</code> (but see
+ also <a class="link" href="extras.html#boost_contract.extras.old_value_requirements__templates_" title="Old Value Requirements (Templates)">Old
+ Value Requirements</a>). See <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
+ Macros</a> to program old values without using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>
(e.g., on compilers that do not support variadic macros).
</p>
<div class="note"><table border="0" summary="Note">
<tr><td align="left" valign="top"><p>
This library ensures that old values are copied only once. This library
also ensures that old values are never copied when postconditions and exception
- guarantees are disabled defining both <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870511440.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
+ guarantees are disabled defining both <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999656032.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code>
- (note that both these two macros must be defined, defining only <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870511440.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
+ (note that both these two macros must be defined, defining only <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999656032.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
or only <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code>
is not sufficient to prevent the run-time cost of old value copies).
</p></td></tr>
<p>
When exception guarantees are specified, they are programmed using a functor
<code class="literal"><span class="emphasis"><em>e</em></span></code> passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">)</span></code> that can be called with no parameters as
- <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code>.
+ in <code class="literal"><span class="emphasis"><em>e</em></span></code><code class="computeroutput"><span class="special">()</span></code>.
Contracts that do not have exception guarantees simply do not call <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span></code>. Exception guarantees must appear after
both preconditions and postconditions when these are all present (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a> and
<a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>).
<span class="special">}</span>
</pre>
<p>
- The exception guarantee functor should capture all variables that it needs
- to assert the exception guarantees. In general, these variables should be
- captured by reference and not by value (because exception guarantees need
+ The exception guarantee functor should capture all the variables that it
+ needs to assert the exception guarantees. In general, these variables should
+ be captured by reference and not by value (because exception guarantees need
to access the value that these variables will have when the function throws,
and not the value these variables had when the exception guarantee functor
- was first constructed). Exception guarantees can also capture old values
- (see <a class="link" href="tutorial.html#boost_contract.tutorial.old_values" title="Old Values">Old Values</a>)
- but they should not access the function return value instead (because the
- return value will not be properly set when the function throws an exception).
- In any case, exception guarantee assertions should not modify the value of
- the captured variables (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>).
+ was first declared). Exception guarantees can also capture old values (see
+ <a class="link" href="tutorial.html#boost_contract.tutorial.old_values" title="Old Values">Old Values</a>) but
+ they should not access the function return value instead (because the return
+ value is not be properly set when the function throws an exception). In any
+ case, programmers should not write exception guarantee assertions that modify
+ the value of the captured variables, even when those are captured by reference
+ (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.constant_correctness" title="Constant-Correctness">Constant-Correctness</a>).
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
- In real code, it might be difficult to program meaningful exception guarantees
- without resorting to expensive old value copies that will slow down execution.
- Therefore, the authors recognize that exception guarantees, even if supported
- by this library, might not be used often in practice (and they are not
- used in most of the examples listed in the rest of this documentation).
- In any case, these performance considerations are ultimately left to programmers
- and their specific application domain.
+ In real production code, it might be difficult to program meaningful exception
+ guarantees without resorting to expensive old value copies that will slow
+ down execution. Therefore, the authors recognize that exception guarantees,
+ even if supported by this library, might not be used often in practice
+ (and they are not used in most of the examples listed in the rest of this
+ documentation). In any case, these performance considerations are ultimately
+ left to programmers and their specific application domains.
</p></td></tr>
</table></div>
<p>
slow to check at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
to program exception guarantee assertions because that enables this library
to print informative error messages when the asserted conditions are evaluated
- to be false (this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
+ to be false (
note that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
Macros</a>):
</p>
-<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">bool_cond</span><span class="special">)</span>
-<span class="comment">// Or, if `bool_cond` has commas `,` not already within parenthesis `()`...</span>
-<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><span class="identifier">bool_cond</span><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
+<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span>
+<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span>
+<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
</pre>
<p>
This library will automatically call the failure handler <code class="computeroutput"><a class="link" href="../boost/contract/except_failure.html" title="Function except_failure">boost::contract::except_failure</a></code>
if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
- conditions are false and, more in general, if calling the functor specified
+ conditions are false or, more in general, if calling the functor specified
via <code class="computeroutput"><span class="special">.</span><span class="identifier">except</span><span class="special">(...)</span></code> throws any exception. By default, this
failure handler prints an error message to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code>
and terminates the program calling <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span></code>
</h3></div></div></div>
<p>
Public member functions, constructors, and destructors can be programmed
- to check class invariants. When class invariants are specified, they are
- programmed in a public <code class="computeroutput"><span class="keyword">const</span></code>
+ to also check class invariants. When class invariants are specified, they
+ are programmed in a public <code class="computeroutput"><span class="keyword">const</span></code>
function named <code class="computeroutput"><span class="identifier">invariant</span></code>
taking no argument and returning <code class="computeroutput"><span class="keyword">void</span></code>.
Classes that do not have invariants, simply do not declare the <code class="computeroutput"><span class="identifier">invariant</span></code> function. <a href="#ftn.boost_contract.tutorial.class_invariants.f0" class="footnote" name="boost_contract.tutorial.class_invariants.f0"><sup class="footnote">[27]</sup></a> For example:
and if-statements (to avoid programming complex invariants that might be
buggy and slow to check at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> to program
class invariant assertions because that enables this library to print informative
- error messages when the asserted conditions are evaluated to be false (this
- is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
+ error messages when the asserted conditions are evaluated to be false (note
+
that this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
Macros</a>):
</p>
-<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">bool_cond</span><span class="special">)</span>
-<span class="comment">// Or, if `bool_cond` has commas `,` not already within parenthesis `()`...</span>
-<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><span class="identifier">bool_cond</span><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
+<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span>
+<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span>
+<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
</pre>
<p>
This library will automatically call failure handlers <code class="computeroutput"><a class="link" href="../boost/contract/entry_invariant_failure.html" title="Function entry_invariant_failure">boost::contract::entry_invariant_failure</a></code>
or <code class="computeroutput"><a class="link" href="../boost/contract/exit_invariant_failure.html" title="Function exit_invariant_failure">boost::contract::exit_invariant_failure</a></code>
if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
- conditions are false and, more in general, if the <code class="computeroutput"><span class="identifier">invariant</span></code>
+ conditions are false or, more in general, if the <code class="computeroutput"><span class="identifier">invariant</span></code>
function throws an exception when invariants are checked at function entry
or exit respectively. By default, these handlers print an error message to
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and terminate the program calling
<p>
See <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a>
to avoid making the <code class="computeroutput"><span class="identifier">invariant</span></code>
- member function <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.class_invariants.f1" class="footnote" name="boost_contract.tutorial.class_invariants.f1"><sup class="footnote">[28]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870579312.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>
+ member function <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.class_invariants.f1" class="footnote" name="boost_contract.tutorial.class_invariants.f1"><sup class="footnote">[28]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999724496.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>
to use a name different from <code class="computeroutput"><span class="identifier">invariant</span></code>
(e.g., because <code class="computeroutput"><span class="identifier">invariant</span></code>
clashes with other names in user-defined classes).
and if-statements (to avoid programming complex static invariants that might
be buggy and slow to check at run-time). It is also recommended to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code> to program
the assertions because that enables this library to print informative error
- messages when the asserted conditions are evaluated to be false (this is
- not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
+ messages when the asserted conditions are evaluated to be false (note that
+
this is not a variadic macro, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
Macros</a>):
</p>
-<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">bool_cond</span><span class="special">)</span>
-<span class="comment">// Or, if condition has commas `,` not already within parenthesis `()`...</span>
-<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><span class="identifier">bool_cond</span><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
+<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">)</span>
+<span class="comment">// Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...</span>
+<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">((</span><code class="literal"><span class="emphasis"><em>boolean-condition</em></span></code><span class="special">))</span> <span class="comment">// ...use extra parenthesis (not a variadic macro).</span>
</pre>
<p>
This library will automatically call failure handlers <code class="computeroutput"><a class="link" href="../boost/contract/entry_invariant_failure.html" title="Function entry_invariant_failure">boost::contract::entry_invariant_failure</a></code>
or <code class="computeroutput"><a class="link" href="../boost/contract/exit_invariant_failure.html" title="Function exit_invariant_failure">boost::contract::exit_invariant_failure</a></code>
if any of the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_ASSERT.html" title="Macro BOOST_CONTRACT_ASSERT">BOOST_CONTRACT_ASSERT</a></code>
- conditions are false and, more in general, if the <code class="computeroutput"><span class="identifier">static_invariant</span></code>
+ conditions are false or, more in general, if the <code class="computeroutput"><span class="identifier">static_invariant</span></code>
function throws an exception when invariants are checked at function entry
or exit respectively. By default, these handlers print an error message to
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> and terminate the program calling
<p>
See <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a>
to avoid making <code class="computeroutput"><span class="identifier">static_invariant</span></code>
- member function <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.class_invariants.f3" class="footnote" name="boost_contract.tutorial.class_invariants.f3"><sup class="footnote">[30]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870569600.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>
+ member function <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.class_invariants.f3" class="footnote" name="boost_contract.tutorial.class_invariants.f3"><sup class="footnote">[30]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999714768.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>
to use a name different from <code class="computeroutput"><span class="identifier">static_invariant</span></code>
(e.g., because <code class="computeroutput"><span class="identifier">static_invariant</span></code>
clashes with other names in user-defined classes). <a href="#ftn.boost_contract.tutorial.class_invariants.f4" class="footnote" name="boost_contract.tutorial.class_invariants.f4"><sup class="footnote">[31]</sup></a>
<span class="comment">// Contract for a constructor.</span>
<span class="identifier">unique_identifiers</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">from</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">to</span><span class="special">)</span> <span class="special">:</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">constructor_precondition</span><span class="special"><</span><span class="identifier">unique_identifiers</span><span class="special">>([&]</span> <span class="special">{</span>
- <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">from</span> <span class="special"><=</span> <span class="identifier">to</span><span class="special">);</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">from</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">to</span> <span class="special">>=</span> <span class="identifier">from</span><span class="special">);</span>
<span class="special">})</span>
<span class="special">{</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">constructor</span><span class="special">(</span><span class="keyword">this</span><span class="special">)</span>
It is not possible to specify preconditions using <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code>
for constructors (this library will generate a compile-time error if <code class="computeroutput"><span class="special">.</span><span class="identifier">precondition</span><span class="special">(...)</span></code> is used on the object returned by <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>).
Constructor preconditions are specified using the <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code>
- base class instead (
but considerations from <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>
+ base class instead (
same considerations as the ones made in <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>
apply also to the precondition functor passed to <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code>).
Programmes should not access the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> from constructor preconditions (because
the object does not exists yet before the constructor body is executed).
of its derived classes).
</li>
<li class="listitem">
- It takes the derived class as template parameter (the Curiously Recursive
- Template Pattern (CRTP) is used here to avoid ambiguity resolution errors
- with multiple inheritance). <a href="#ftn.boost_contract.tutorial.constructors.f2" class="footnote" name="boost_contract.tutorial.constructors.f2"><sup class="footnote">[34]</sup></a>
+ It should never be declared as a <code class="computeroutput"><span class="keyword">virtual</span></code>
+ base (because virtual bases are initialized only once across the entire
+ inheritance hierarchy preventing preconditions of other base classes
+ from being checked).
+ </li>
+<li class="listitem">
+ It takes the derived class as template parameter. <a href="#ftn.boost_contract.tutorial.constructors.f2" class="footnote" name="boost_contract.tutorial.constructors.f2"><sup class="footnote">[34]</sup></a>
</li>
</ul></div>
<div class="note"><table border="0" summary="Note">
postconditions (because the object did not exist yet before the constructor
body was executed). <a href="#ftn.boost_contract.tutorial.constructors.f3" class="footnote" name="boost_contract.tutorial.constructors.f3"><sup class="footnote">[35]</sup></a> It is also possible to specify exceptions guarantees for constructors
(see <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception
- Guarantees</a>), but programmers should not access the object <code class="computeroutput"><span class="keyword">this</span></code> or its old value in constructor exception
- guarantees (because the object did not exist before executing the constructor
- body and it was not properly constructed given the constructor body threw
- an exception). <a href="#ftn.boost_contract.tutorial.constructors.f4" class="footnote" name="boost_contract.tutorial.constructors.f4"><sup class="footnote">[36]</sup></a> The <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>
+ Guarantees</a>), but programmers should not access the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> or its
+ old value in constructor exception guarantees (because the object did not
+ exist before executing the constructor body and it was not properly constructed
+
given the constructor body threw an exception). <a href="#ftn.boost_contract.tutorial.constructors.f4" class="footnote" name="boost_contract.tutorial.constructors.f4"><sup class="footnote">[36]</sup></a> The <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>
function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter
(because constructors check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
Invariants</a>).
The <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>
function returns an RAII object that must always be assigned to a local variable
of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
- (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870548928.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
+ (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999694064.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations
cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
type must be explicitly specified (otherwise this library will generate a
compile-time error prior C++17 and a run-time error post C++17). The constructor
- body is programmed right after the declaration of the RAII object.
+ body is programmed right after the declaration of this RAII object.
</p>
<p>
At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
</p>
</td></tr>
</table></div>
+<h5>
+<a name="boost_contract.tutorial.constructors.h0"></a>
+ <span class="phrase"><a name="boost_contract.tutorial.constructors.private_and_protected_constructors"></a></span><a class="link" href="tutorial.html#boost_contract.tutorial.constructors.private_and_protected_constructors">Private
+ and Protected Constructors</a>
+ </h5>
<p>
Private and protected constructors can omit <code class="computeroutput"><a class="link" href="../boost/contract/constructor.html" title="Function template constructor">boost::contract::constructor</a></code>
(because they are not part of the public interface of the class so they are
for destructors (see <a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>,
and also <a class="link" href="tutorial.html#boost_contract.tutorial.static_public_functions" title="Static Public Functions">Static
Public Functions</a> for an example), but programmers should not access
- the object <code class="computeroutput"><span class="keyword">this</span></code> in destructor
- postconditions (because the object no longer exists after the destructor
- body has been executed). <a href="#ftn.boost_contract.tutorial.destructors.f0" class="footnote" name="boost_contract.tutorial.destructors.f0"><sup class="footnote">[37]</sup></a> It is also possible to specify exceptions guarantees for destructors
+ the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
+ in destructor postconditions (because the object no longer exists after the
+
destructor body has been executed). <a href="#ftn.boost_contract.tutorial.destructors.f0" class="footnote" name="boost_contract.tutorial.destructors.f0"><sup class="footnote">[37]</sup></a> It is also possible to specify exceptions guarantees for destructors
(see <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception
Guarantees</a>, even if destructors should usually be programmed to not
- throw exceptions in C++
and in fact they are implicitly declared <code class="computeroutput"><span class="keyword">noexcept</span></code> since C++11). <a href="#ftn.boost_contract.tutorial.destructors.f1" class="footnote" name="boost_contract.tutorial.destructors.f1"><sup class="footnote">[38]</sup></a> The <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>
+ throw exceptions in C++
, in fact destructors are implicitly declared <code class="computeroutput"><span class="keyword">noexcept</span></code> since C++11). <a href="#ftn.boost_contract.tutorial.destructors.f1" class="footnote" name="boost_contract.tutorial.destructors.f1"><sup class="footnote">[38]</sup></a> The <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>
function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter
(because destructors check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
Invariants</a>).
The <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>
function returns an RAII object that must always be assigned to a local variable
of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
- (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870548928.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
+ (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999694064.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations
cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
type must be explicitly specified (otherwise this library will generate a
compile-time error prior C++17 and a run-time error post C++17). The destructor
- body is programmed right after the declaration of the RAII object.
+ body is programmed right after the declaration of this RAII object.
</p>
<p>
At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
</p>
</td></tr>
</table></div>
+<h5>
+<a name="boost_contract.tutorial.destructors.h0"></a>
+ <span class="phrase"><a name="boost_contract.tutorial.destructors.private_and_protected_destructors"></a></span><a class="link" href="tutorial.html#boost_contract.tutorial.destructors.private_and_protected_destructors">Private
+ and Protected Destructors</a>
+ </h5>
<p>
Private and protected destructors can omit <code class="computeroutput"><a class="link" href="../boost/contract/destructor.html" title="Function template destructor">boost::contract::destructor</a></code>
(because they are not part of the public interface of the class so they are
<a name="boost_contract.tutorial.public_functions"></a><a class="link" href="tutorial.html#boost_contract.tutorial.public_functions" title="Public Functions">Public Functions</a>
</h3></div></div></div>
<p>
- Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>.
+ Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
In this section, let's consider public functions that are not static, not
virtual, and do not override any function from base classes. For example
(see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>):
<span class="keyword">bool</span> <span class="identifier">find</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">id</span><span class="special">)</span> <span class="keyword">const</span> <span class="special">{</span>
<span class="keyword">bool</span> <span class="identifier">result</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">public_function</span><span class="special">(</span><span class="keyword">this</span><span class="special">)</span>
+ <span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">id</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span>
+ <span class="special">})</span>
<span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">{</span>
<span class="keyword">if</span><span class="special">(</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(!</span><span class="identifier">result</span><span class="special">);</span>
<span class="special">})</span>
for public functions (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>,
<a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>,
and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception
- Guarantees</a>). When called from non-static public functions, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ Guarantees</a>). When called from non-static public functions, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter
(because public functions check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
Invariants</a>).
</p>
<p>
- The <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ The <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
function returns an RAII object that must always be assigned to a local variable
of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
- (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870548928.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
+ (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999694064.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations
cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
type must be explicitly specified (otherwise this library will generate a
compile-time error prior C++17 and a run-time error post C++17). The public
- function body is programmed right after the declaration of the RAII object.
+ function body is programmed right after the declaration of this RAII object.
</p>
<p>
At construction, the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
</tr>
<tr><td align="left" valign="top">
<p>
- A public function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ A public function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
for efficiency but only when it has no preconditions, no postconditions,
no exception guarantees, it is not virtual, it does not override any virtual
function, and its class has no invariants.
The default copy assignment operator automatically generated by C++ will
not check contracts. Therefore, unless this operator is not public or it
has no preconditions, no postconditions, no exception guarantees, and its
- class has no invariants, programmers should manually define it using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>.
+ class has no invariants, programmers should manually define it using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
Similar considerations apply to all other operators automatically generated
by C++ (e.g., the move operator).
</p>
Public Functions</a>
</h3></div></div></div>
<p>
- Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>.
+ Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
In this section, let's consider public functions that are virtual but that
do not override any function from base classes. For example (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>):
</p>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">public_function</span><span class="special">(</span>
<span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="keyword">this</span><span class="special">)</span> <span class="comment">// Pass `v` and `result`.</span>
<span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">id</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span>
<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(!</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> <span class="comment">// ID cannot be already present.</span>
<span class="special">})</span>
<span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span>
a part from when manipulating the virtual function type directly for function
pointer type-casting, etc.). Programmers must pass the extra virtual parameter
as the very first argument to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>
- and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
calls in the virtual public function definition. <a href="#ftn.boost_contract.tutorial.virtual_public_functions.f1" class="footnote" name="boost_contract.tutorial.virtual_public_functions.f1"><sup class="footnote">[40]</sup></a>
</p>
<p>
- When called from virtual public functions, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ When called from virtual public functions, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
function takes <code class="computeroutput"><span class="keyword">this</span></code> as a parameter
(because public functions check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
Invariants</a>). For virtual public functions returning <code class="computeroutput"><span class="keyword">void</span></code>:
<p>
For virtual public functions not returning <code class="computeroutput"><span class="keyword">void</span></code>,
programmers must also pass a reference to the function return value as the
- second argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>.
+ second argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
In this case, the library will pass this return value reference to the postcondition
functor that must therefore take one single argument matching the return
type, otherwise this library will generate a compile-time error (the functor
<p>
It is the responsibility of the programmers to pass the extra virtual parameter
<code class="computeroutput"><span class="identifier">v</span></code> to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>
- and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
calls within virtual public functions, and also to pass the return value
- reference after <code class="computeroutput"><span class="identifier">v</span></code> to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ reference after <code class="computeroutput"><span class="identifier">v</span></code> to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
for non-void virtual public functions. This library cannot automatically
generate compile-time errors if programmers fail to do so (but in general
this will prevent the library from correctly checking contracts at run-time).
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
When <code class="computeroutput"><span class="identifier">v</span></code> is present, always
- pass it as the first argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ pass it as the first argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>.
</p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
Always pass <code class="computeroutput"><span class="identifier">result</span></code> to
- <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
right after <code class="computeroutput"><span class="identifier">v</span></code> for non-void
functions.
</p></blockquote></div>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
- A virtual public function should always call <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ A virtual public function should always call <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
(even if it has no preconditions, no postconditions, no exception guarantees,
and its class has no invariants), otherwise this library will not be able
to correctly use it for subcontracting.
Function Overrides (Subcontracting)</a>
</h3></div></div></div>
<p>
- Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>.
+ Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
In this section, let's consider public functions (virtual or not) that override
- virtual public functions from one or more public base classes. For example
- (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>):
+ virtual public functions from one or more of their public base classes. For
+
example (see <a href="../../../example/features/public.cpp" target="_top"><code class="literal">public.cpp</code></a>):
<a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f0" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f0"><sup class="footnote">[43]</sup></a>
</p>
<p>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">old_ptr</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">old_size</span> <span class="special">=</span>
<span class="identifier">BOOST_CONTRACT_OLDOF</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">size</span><span class="special">());</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">check</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">public_function</span><span class="special"><</span>
- <span class="identifier">override_push_back</span> <span class="comment">// Pass override plus below function pointer...</span>
+ <span class="identifier">override_push_back</span> <span class="comment">// Pass override type plus below function pointer...</span>
<span class="special">>(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">result</span><span class="special">,</span> <span class="special">&</span><span class="identifier">identifiers</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">,</span> <span class="keyword">this</span><span class="special">,</span> <span class="identifier">id</span><span class="special">)</span> <span class="comment">// ...and arguments.</span>
<span class="special">.</span><span class="identifier">precondition</span><span class="special">([&]</span> <span class="special">{</span> <span class="comment">// Check in OR with bases.</span>
+ <span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">id</span> <span class="special">>=</span> <span class="number">0</span><span class="special">);</span>
<span class="identifier">BOOST_CONTRACT_ASSERT</span><span class="special">(</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">id</span><span class="special">));</span> <span class="comment">// ID can be already present.</span>
<span class="special">})</span>
<span class="special">.</span><span class="identifier">postcondition</span><span class="special">([&]</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span> <span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// Check in AND with bases.</span>
The extra <code class="computeroutput"><span class="keyword">typedef</span></code> declared using
<code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>
is required by this library for derived classes and it is internally used
- detect base classes for subcontracting (see <a class="link" href="tutorial.html#boost_contract.tutorial.base_classes__subcontracting_" title="Base Classes (Subcontracting)">Base
- Classes</a>).
+ to detect base classes for subcontracting (see <a class="link" href="tutorial.html#boost_contract.tutorial.base_classes__subcontracting_" title="Base Classes (Subcontracting)">Base
+ Classes</a>). This library will generate a compile-time error if there
+ is no suitable virtual function to override in any of the public base classes
+ for subcontracting. <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f1"><sup class="footnote">[44]</sup></a>
</p>
<p>
- When called from public function overrides, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ When called from public function overrides, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
function template takes an explicit template argument <code class="computeroutput"><span class="identifier">override_</span></code><code class="literal"><span class="emphasis"><em>function-name</em></span></code>
that must be defined using <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>:
</p>
-<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">func_name</span><span class="special">)</span>
+<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><code class="literal"><span class="emphasis"><em>function-name</em></span></code><span class="special">)</span>
</pre>
<p>
This can be declared at any point in the public section of the enclosing
class (see <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access
Specifiers</a> to use <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>
-
in a non-public section of the class instead). <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>
+
also in a non-public section of the class). <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OVERRIDE.html" title="Macro BOOST_CONTRACT_OVERRIDE">BOOST_CONTRACT_OVERRIDE</a></code>
is used only once in a class for a given function name and overloaded functions
can reuse the same <code class="literal">override_<span class="emphasis"><em>function-name</em></span></code>
definition (see <a class="link" href="advanced.html#boost_contract.advanced.function_overloads" title="Function Overloads">Function
- Overloads</a>). <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123869781472.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>
+ Overloads</a>). <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394998912688.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>
can be used to generate a name different than <code class="literal">override_<span class="emphasis"><em>function-name</em></span></code>
(e.g., to avoid generating C++ reserved names containing double underscores
"<code class="computeroutput"><span class="identifier">__</span></code>" for function
<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_OVERRIDES</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">g</span><span class="special">,</span> <span class="identifier">h</span><span class="special">)</span>
</pre>
<p>
- Is equivalent to: <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f1"><sup class="footnote">[44]</sup></a>
+ Is equivalent to: <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f2"><sup class="footnote">[45]</sup></a>
</p>
<pre class="programlisting"><span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span>
<span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">g</span><span class="special">)</span>
<span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span>
</pre>
<p>
- This library will generate a compile-time error if there is no suitable virtual
- function to override in any of the public base classes for subcontracting.
- <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f2"><sup class="footnote">[45]</sup></a>
- </p>
-<p>
Public function overrides must always list the extra trailing parameter of
type <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> with default value <code class="computeroutput"><span class="number">0</span></code>
(i.e., <code class="computeroutput"><span class="keyword">nullptr</span></code>), even when they
- are not declared <code class="computeroutput"><span class="keyword">virtual</span></code> (because
+ are not declared <code class="computeroutput"><span class="keyword">virtual</span></code>, if
this parameter is present in the signature of the virtual function being
- overridden from base classes). Programmers must pass the extra virtual parameter
+ overridden from base classes. Programmers must pass the extra virtual parameter
as the very first argument to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>
- and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
calls in the public function override definition (see <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual
Public Functions</a>).
</p>
<p>
- When called from public function overrides, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
- function takes a pointer to the enclosing function, the object <code class="computeroutput"><span class="keyword">this</span></code> (because public function overrides check
- class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
+ When called from public function overrides, the <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
+ function takes a pointer to the enclosing function, the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> (because
+
public function overrides check class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
Invariants</a>), and references to each function argument in the order
they appear in the function declaration. <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f3" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f3"><sup class="footnote">[46]</sup></a> For public function overrides returning <code class="computeroutput"><span class="keyword">void</span></code>:
</p>
<span class="special">...</span>
<span class="special">}</span>
-
<span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span>
<span class="special">...</span>
<p>
For public function overrides not returning <code class="computeroutput"><span class="keyword">void</span></code>,
programmers must also pass a reference to the function return value as the
- second argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ second argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
(this library will generate a compile-time error otherwise). <a href="#ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f4" class="footnote" name="boost_contract.tutorial.public_function_overrides__subcontracting_.f4"><sup class="footnote">[47]</sup></a> In this case, the library will pass this return value reference
to the postcondition functor that must therefore take one single argument
matching the return type, otherwise this library will generate a compile-time
error (the functor parameter can be a constant reference <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code> to avoid extra copies of the return
- value):
+ value, similarly to non-overriding non-void <a class="link" href="tutorial.html#boost_contract.tutorial.virtual_public_functions" title="Virtual Public Functions">Virtual
+ Public Functions</a>):
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="special">...</span> <span class="comment">// Assign `result` at each return.</span>
<span class="special">}</span>
-
<span class="identifier">BOOST_CONTRACT_OVERRIDE</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span>
<span class="special">...</span>
<p>
It is the responsibility of the programmers to pass the extra virtual parameter
<code class="computeroutput"><span class="identifier">v</span></code> to all <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>
- and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ and <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
calls within public function overrides, and also to pass the return value
- reference after <code class="computeroutput"><span class="identifier">v</span></code> to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ reference after <code class="computeroutput"><span class="identifier">v</span></code> to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
for non-void public function overrides. This library cannot always generate
compile-time errors if programmers fail to do so (but in general this will
prevent the library from correctly checking contracts at run-time).
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
When <code class="computeroutput"><span class="identifier">override_</span><span class="special">...</span></code>
- is present, always pass it as template parameter to <code class="computeroutput">boost::contract::public_functioon</code>.
+ is present, always pass it as template parameter to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
</p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
When <code class="computeroutput"><span class="identifier">v</span></code> is present, always
- pass it as the first argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ pass it as the first argument to <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_OLDOF.html" title="Macro BOOST_CONTRACT_OLDOF">BOOST_CONTRACT_OLDOF</a></code>.
</p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
Always pass <code class="computeroutput"><span class="identifier">result</span></code> to
- <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
right after <code class="computeroutput"><span class="identifier">v</span></code> for non-void
functions.
</p></blockquote></div>
</li>
</ol></div>
<p>
- This ensures that public function override contracts and subcontracts are
- correctly checked at run-time (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public
+ This ensures that contracts and subcontracts of public function overrides
+ are correctly checked at run-time in accordance with the <a href="http://en.wikipedia.org/wiki/Liskov_substitution_principle" target="_top">substitution
+ principle</a> (see <a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public
Function Calls</a>).
</p>
<p>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
- A public function override should always call <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ A public function override should always call <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
(even if it has no preconditions, no postconditions, no exception guarantees,
and its class has no invariants), otherwise this library will not be able
to correctly use it for subcontracting.
<p>
</p>
<p>
- For convenience, a local macro named <code class="computeroutput"><span class="identifier">BASES</span></code>
+ For convenience, a <span class="emphasis"><em>local macro</em></span> named <code class="computeroutput"><span class="identifier">BASES</span></code>
can be used to avoid repeating the base list twice (first in the derived
class declaration <code class="computeroutput"><span class="keyword">class</span> </code><code class="literal"><span class="emphasis"><em>class-name</em></span></code><code class="computeroutput">
<span class="special">:</span> </code><code class="literal"><span class="emphasis"><em>base-list</em></span></code>
and then again when invoking <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_BASE_TYPES</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>base-list</em></span></code><code class="computeroutput"><span class="special">)</span></code>). Being a local macro, <code class="computeroutput"><span class="identifier">BASES</span></code>
must be undefined using <code class="computeroutput"><span class="preprocessor">#undef</span>
- <span class="identifier">BASES</span></code> after it has been used to
- declare <code class="computeroutput"><span class="identifier">base_types</span></code> (to avoid
-
name clashes and macro redefinition errors). <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f0" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f0"><sup class="footnote">[49]</sup></a>
+ <span class="identifier">BASES</span></code> after it is used to declare
+ the <code class="computeroutput"><span class="identifier">base_types</span></code> <code class="computeroutput"><span class="keyword">typedef</span></code> (to avoid name clashes and macro redefinition
+ errors). <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f0" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f0"><sup class="footnote">[49]</sup></a>
</p>
<p>
<code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>
<p>
See <a class="link" href="advanced.html#boost_contract.advanced.access_specifiers" title="Access Specifiers">Access Specifiers</a>
to avoid making the <code class="computeroutput"><span class="identifier">base_types</span></code>
- member type <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f2" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f2"><sup class="footnote">[51]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870587168.html" title="Macro BOOST_CONTRACT_BASES_TYPEDEF">BOOST_CONTRACT_BASES_TYPEDEF</a></code>
+ member type <code class="computeroutput"><span class="keyword">public</span></code>. <a href="#ftn.boost_contract.tutorial.base_classes__subcontracting_.f2" class="footnote" name="boost_contract.tutorial.base_classes__subcontracting_.f2"><sup class="footnote">[51]</sup></a> See <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999732400.html" title="Macro BOOST_CONTRACT_BASES_TYPEDEF">BOOST_CONTRACT_BASES_TYPEDEF</a></code>
to use a name different from <code class="computeroutput"><span class="identifier">base_types</span></code>
(e.g., because <code class="computeroutput"><span class="identifier">base_types</span></code>
clashes with other names in user-defined classes).
Public Functions</a>
</h3></div></div></div>
<p>
- Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>.
+ Contracts for public functions are programmed using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>.
In this section, let's consider static public functions. For example (see
<a href="../../../example/features/static_public.cpp" target="_top"><code class="literal">static_public.cpp</code></a>):
</p>
for static public functions (see <a class="link" href="tutorial.html#boost_contract.tutorial.preconditions" title="Preconditions">Preconditions</a>,
<a class="link" href="tutorial.html#boost_contract.tutorial.postconditions" title="Postconditions">Postconditions</a>,
and <a class="link" href="tutorial.html#boost_contract.tutorial.exception_guarantees" title="Exception Guarantees">Exception
- Guarantees</a>). When called from static public functions, <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ Guarantees</a>). When called from static public functions, <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
cannot take the object <code class="computeroutput"><span class="keyword">this</span></code>
as a parameter (because there is no object <code class="computeroutput"><span class="keyword">this</span></code>
- in static member functions) so the enclosing class type is is specified as
- an explicit template parameter (the class type is required to check static
- class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
+ in static member functions) so the enclosing class type is specified via
+ an explicit template parameter as in <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code><code class="literal"><<span class="emphasis"><em>class-type</em></span>></code>
+
(the class type is required to check static class invariants, see <a class="link" href="tutorial.html#boost_contract.tutorial.class_invariants" title="Class Invariants">Class
Invariants</a>):
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">u</span> <span class="special">{</span>
<span class="special">};</span>
</pre>
<p>
- The <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ The <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
function returns an RAII object that must be assigned to a local variable
of type <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
- (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870548928.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
+ (otherwise this library will generate a run-time error, see <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999694064.html" title="Macro BOOST_CONTRACT_ON_MISSING_CHECK_DECL">BOOST_CONTRACT_ON_MISSING_CHECK_DECL</a></code>).
Furthermore, C++11 <code class="computeroutput"><span class="keyword">auto</span></code> declarations
cannot be used here and the <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
type must be explicitly specified (otherwise this library will generate a
compile-time error prior C++17 and a run-time error post C++17). The static
- public functions body is programmed right after the declaration of the RAII
+ public functions body is programmed right after the declaration of this RAII
object.
</p>
<p>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
- A static public function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ A static public function can avoid calling <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
for efficiency but only when it has no preconditions, no postconditions,
no exception guarantees, and its class has no static invariants (the class
can still have non-static invariants or base classes instead).
<div id="ftn.boost_contract.tutorial.non_member_functions.f0" class="footnote"><p><a href="#boost_contract.tutorial.non_member_functions.f0" class="para"><sup class="para">[19] </sup></a>
The name of this local variable is arbitrary, but <code class="computeroutput"><span class="identifier">c</span></code>
is often used in this documentation for <span class="quote">“<span class="quote">c</span>”</span>heck or <span class="quote">“<span class="quote">c</span>”</span>aminiti
- <code class="literal">;-)</code>.
+ <code class="literal">;-)</code> .
</p></div>
<div id="ftn.boost_contract.tutorial.non_member_functions.f1" class="footnote"><p><a href="#boost_contract.tutorial.non_member_functions.f1" class="para"><sup class="para">[20] </sup></a>
- <span class="bold"><strong>Rationale:</strong></span> C++17 zero-copy guarantee on
- function return values skips the trick this library uses to force a compile-time
+ <span class="bold"><strong>Rationale:</strong></span> C++17 guaranteed copy elision
+ on function return value voids the trick this library uses to force a compile-time
error when <code class="computeroutput"><span class="keyword">auto</span></code> is incorrectly
used instead of <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>.
- The library is still able to generate a run-time error in this case on
- C++17. In any case, after reading this documentation it should be evident
- to programmers that <code class="computeroutput"><span class="keyword">auto</span></code> should
-
not be used in <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
+ The library still generates a run-time error in this case (also on C++17).
+ In any case, after reading this documentation it should be evident to programmers
+ that <code class="computeroutput"><span class="keyword">auto</span></code> should not be used
+ in <code class="computeroutput"><a class="link" href="../boost/contract/check.html" title="Class check">boost::contract::check</a></code>
declarations so this misuse of <code class="computeroutput"><span class="keyword">auto</span></code>
should not be an issue in practice.
</p></div>
<span class="bold"><strong>Rationale:</strong></span> Old values have to be optional
values because they need to be left uninitialized when they are not used
because both postconditions and exception guarantees are disabled (defining
- <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870511440.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
+ <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999656032.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code>).
- That is to avoid old value copies when old values are not used, so a pointer,
- or better a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>, could have been used for that.
- In addition, old values need to be pointers internally allocated by this
- library so that they are never copied twice even when calling an overridden
- function multiple times to check preconditions, postconditions, etc. to
- implement subcontracting, so a smart pointer class template was used.
+ That is to avoid old value copies when old values are not used, either
+ a pointer or (better) a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>
+ could have been used to achieve that. In addition, old values need to be
+ pointers internally allocated by this library so that they are never copied
+ twice even when calling an overridden function multiple times to check
+ preconditions, postconditions, etc. to implement subcontracting, so a smart
+ pointer class template was used.
</p></div>
<div id="ftn.boost_contract.tutorial.old_values.f2" class="footnote"><p><a href="#boost_contract.tutorial.old_values.f2" class="para"><sup class="para">[26] </sup></a>
For example, old value pointers might be null in preconditions when postconditions
- and exception guarantees are disabled defining <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870511440.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
- and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code>,
- but also when checking an overridden virtual public function contract via
- subcontracting, etc.
+ and exception guarantees are disabled defining <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999656032.html" title="Macro BOOST_CONTRACT_NO_POSTCONDITIONS">BOOST_CONTRACT_NO_POSTCONDITIONS</a></code>
+ and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_NO_EXCEPTS.html" title="Macro BOOST_CONTRACT_NO_EXCEPTS">BOOST_CONTRACT_NO_EXCEPTS</a></code>
+ (but also when checking an overridden virtual public function contract
+ via subcontracting, etc.).
</p></div>
<div id="ftn.boost_contract.tutorial.class_invariants.f0" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f0" class="para"><sup class="para">[27] </sup></a>
This library uses template meta-programming (SFINAE-based introspection
techniques) to check invariants only for classes that declare a member
- function named <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870579312.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>.
+ function named by <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999724496.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>.
</p></div>
<div id="ftn.boost_contract.tutorial.class_invariants.f1" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f1" class="para"><sup class="para">[28] </sup></a>
In this documentation the <code class="computeroutput"><span class="identifier">invariant</span></code>
<div id="ftn.boost_contract.tutorial.class_invariants.f2" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f2" class="para"><sup class="para">[29] </sup></a>
This library uses template meta-programming (SFINAE-based introspection
techniques) to check static invariants only for classes that declare a
- member function named <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870569600.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>.
+ member function named by <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999714768.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>.
</p></div>
<div id="ftn.boost_contract.tutorial.class_invariants.f3" class="footnote"><p><a href="#boost_contract.tutorial.class_invariants.f3" class="para"><sup class="para">[30] </sup></a>
In this documentation the <code class="computeroutput"><span class="identifier">static_invariant</span></code>
to overload a member function based on the <code class="computeroutput"><span class="keyword">static</span></code>
classifier. Therefore, this library has to use different names for the
member functions checking non-static and static class invariants (namely
- for <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870579312.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>
- and for <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123870569600.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>).
+ for <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999724496.html" title="Macro BOOST_CONTRACT_INVARIANT_FUNC">BOOST_CONTRACT_INVARIANT_FUNC</a></code>
+ and for <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394999714768.html" title="Macro BOOST_CONTRACT_STATIC_INVARIANT_FUNC">BOOST_CONTRACT_STATIC_INVARIANT_FUNC</a></code>).
</p></div>
<div id="ftn.boost_contract.tutorial.constructors.f0" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f0" class="para"><sup class="para">[32] </sup></a>
See <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No
</p></div>
<div id="ftn.boost_contract.tutorial.constructors.f2" class="footnote"><p><a href="#boost_contract.tutorial.constructors.f2" class="para"><sup class="para">[34] </sup></a>
<span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><a class="link" href="../boost/contract/constructor_precondition.html" title="Class template constructor_precondition">boost::contract::constructor_precondition</a></code>
- takes the derived class as its template parameter so the instantiated
- template type is unique for each derived class. This always avoids
- base class ambiguity resolution errors even when multiple inheritance
- is used. Note that virtual inheritance could not be used instead of
- the template parameter here to resolve ambiguities (because virtual
+ takes the derived class as its template parameter (using the Curiously
+ Recursive Template Pattern, CRTP) so the instantiated template type
+ is unique for each derived class. This always avoids base class ambiguity
+ resolution errors even when multiple inheritance is used. Note that,
+ as already mentioned, virtual inheritance could not be used instead
+ of the template parameter here to resolve ambiguities (because virtual
bases are initialized only once by the outer-most derived class, and
that would not allow to properly check preconditions of all base classes).
</p></div>
not recommended because of extra boiler-plate code).
</p></div>
<div id="ftn.boost_contract.tutorial.destructors.f1" class="footnote"><p><a href="#boost_contract.tutorial.destructors.f1" class="para"><sup class="para">[38] </sup></a>
- Exceptions guarantees in destructors can access both the object <code class="computeroutput"><span class="keyword">this</span></code> and its old value because the object
- exited before executing the destructor body and it still exists given the
- destructor body failed throwing an exception so the object should still
- be properly constructed and satisfy its class invariants.
+ Exceptions guarantees in destructors can access both the object <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> and
+ its old value because the object existed before executing the destructor
+ body and it still exists given the destructor body failed throwing an exception
+ so technically the object should still be properly constructed and satisfy
+ its class invariants.
</p></div>
<div id="ftn.boost_contract.tutorial.virtual_public_functions.f0" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f0" class="para"><sup class="para">[39] </sup></a>
The name of this extra parameter is arbitrary, but <code class="computeroutput"><span class="identifier">v</span></code>
<span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> parameter is used by this library to determine
that a function is virtual (in C++ it is not possible to introspect if
a function is declared <code class="computeroutput"><span class="keyword">virtual</span></code>).
- Furthermore, this parameter is internally used by this library to pass
- result and old values that are evaluated by the overriding function to
- overridden virtual functions in base classes, and also to check preconditions,
- postconditions, and exception guarantees of overridden virtual functions
- to implement subcontracting.
+ Furthermore, this parameter is internally used by this library to implement
+ subcontracting (specifically to pass result and old values that are evaluated
+ by the overriding function to the contracts of overridden virtual functions
+ in base classes, and also to check preconditions, postconditions, and exception
+ guarantees of overridden virtual functions in <a class="link" href="contract_programming_overview.html#or_anchor"><code class="literal"><span class="emphasis"><em>OR</em></span></code></a>
+ and <a class="link" href="contract_programming_overview.html#and_anchor"><code class="literal"><span class="emphasis"><em>AND</em></span></code></a>
+ with contracts of the overriding virtual function).
</p></div>
<div id="ftn.boost_contract.tutorial.virtual_public_functions.f2" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f2" class="para"><sup class="para">[41] </sup></a>
<span class="bold"><strong>Rationale:</strong></span> The extra function result parameter
taken by the functor passed to <code class="computeroutput"><span class="special">.</span><span class="identifier">postcondition</span><span class="special">(...)</span></code>
is used by this library to pass the return value evaluated by the overriding
- function to all its overridden virtual functions when subcontracting.
+ function to all its overridden virtual functions to support subcontracting.
</p></div>
<div id="ftn.boost_contract.tutorial.virtual_public_functions.f3" class="footnote"><p><a href="#boost_contract.tutorial.virtual_public_functions.f3" class="para"><sup class="para">[42] </sup></a>
<span class="bold"><strong>Rationale:</strong></span> This library does not require
- programmers to specify the function type when using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45123869756752.html" title="Function template public_function">boost::contract::public_function</a></code>
+ programmers to specify the function type when using <code class="computeroutput"><a class="link" href="../boost/contract/public_f_idm45394998885120.html" title="Function template public_function">boost::contract::public_function</a></code>
for non-overriding virtual public functions. Therefore, this library
does not know if the enclosing function has a non-void return type so
it cannot check if the return value reference is passed as required for
not widely supported yet, even by compilers that support C++11 lambda functions).
</p></div>
<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f1" class="para"><sup class="para">[44] </sup></a>
- This library does not provider an equivalent of <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123869781472.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>
- that operates on multiple function names at once (simply because programmers
- will probably not use <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45123869781472.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>
- often in the first place).
- </p></div>
-<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="para"><sup class="para">[45] </sup></a>
The compile-time error generated by the library in this case is similar
in principle to the error generated by the C++11 <code class="computeroutput"><span class="identifier">override</span></code>
specifier, but it is limited to functions with the extra <code class="computeroutput"><a class="link" href="../boost/contract/virtual_.html" title="Class virtual_">boost::contract::virtual_</a></code><code class="computeroutput"><span class="special">*</span></code> parameter and searched recursively only
to <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>
because only those are considered for subcontracting.
</p></div>
+<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f2" class="para"><sup class="para">[45] </sup></a>
+ There is no equivalent of <code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394998912688.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>
+ that operates on multiple function names at once (<code class="computeroutput"><a class="link" href="../BOOST_CO_idm45394998912688.html" title="Macro BOOST_CONTRACT_NAMED_OVERRIDE">BOOST_CONTRACT_NAMED_OVERRIDE</a></code>
+ is not expected to be used often so it can simply be repeated multiple
+ times when needed).
+ </p></div>
<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f3" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f3" class="para"><sup class="para">[46] </sup></a>
<span class="bold"><strong>Rationale:</strong></span> The object <code class="computeroutput"><span class="keyword">this</span></code>
is passed after the function pointer to follow <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind</span></code>'s
syntax. The function pointer and references to all function arguments are
- needed for public function overrides because this library has to call overridden
- virtual public functions to check their contracts for subcontracting (even
- if this library will not actually execute the bodies of the overridden
+ needed for public function overrides because this library has to internally
+ call overridden virtual public functions to check their contracts for subcontracting
+ (even if this library will not actually execute the bodies of the overridden
functions).
</p></div>
<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f4" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f4" class="para"><sup class="para">[47] </sup></a>
</p></div>
<div id="ftn.boost_contract.tutorial.public_function_overrides__subcontracting_.f5" class="footnote"><p><a href="#boost_contract.tutorial.public_function_overrides__subcontracting_.f5" class="para"><sup class="para">[48] </sup></a>
<span class="bold"><strong>Rationale:</strong></span> The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bad_any_cast</span></code>
- exception could not used here because it does not print the from- and to-
+ exception was not used here because it does not print the from- and to-
type names (so it is not descriptive enough).
</p></div>
<div id="ftn.boost_contract.tutorial.base_classes__subcontracting_.f0" class="footnote"><p><a href="#boost_contract.tutorial.base_classes__subcontracting_.f0" class="para"><sup class="para">[49] </sup></a>
<a class="link" href="contract_programming_overview.html#boost_contract.contract_programming_overview.public_function_calls" title="Public Function Calls">Public
Function Calls</a>). <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_BASE_TYPES.html" title="Macro BOOST_CONTRACT_BASE_TYPES">BOOST_CONTRACT_BASE_TYPES</a></code>
inspects each inheritance access level using preprocessor meta-programming
- and removes non-public bases from the list of bases inspected for subcontracting.
- However, this library cannot always detect when programmers forget to
- specify the inheritance access level because, when commas are used to
- separate template parameters passed to base classes, the preprocessor
+ and removes non-public bases from the list of bases internally used for
+ subcontracting. However, this library cannot always detect when programmers
+ forget to specify the inheritance access level because, when commas are
+ used to separate template parameters passed to base classes, the preprocessor
will not be able to correctly use commas to identify the next base class
token in the inheritance list (the preprocessor cannot distinguish between
commas that are not protected by round parenthesis, like the ones used
- in templates). Therefore, this library relies on inheritance access levels
- to program the preprocessor to correctly identify the next base class
- token in the inheritance list (thus inheritance access levels must always
- be explicit specified by programmers).
+ in templates). Therefore, this library uses the inheritance access level
+ keyword <code class="computeroutput"><span class="keyword">public</span></code>, <code class="computeroutput"><span class="keyword">protected</span></code>, or <code class="computeroutput"><span class="keyword">private</span></code>
+ instead of commas <code class="computeroutput"><span class="special">,</span></code> for
+ the preprocessor to correctly find the next base class token in the inheritance
+ list (thus inheritance access levels must always be explicit specified
+ by programmers for each base).
</p></div>
<div id="ftn.boost_contract.tutorial.base_classes__subcontracting_.f2" class="footnote"><p><a href="#boost_contract.tutorial.base_classes__subcontracting_.f2" class="para"><sup class="para">[51] </sup></a>
In this documentation the <code class="computeroutput"><span class="identifier">base_type</span></code>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright © 2008-201
8 Lorenzo Caminiti<p>
+<td align="right"><div class="copyright-footer">Copyright © 2008-201
9 Lorenzo Caminiti<p>
Distributed under the Boost Software License, Version 1.0 (see accompanying
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>)
</p>
projects / platform / upstream / boost.git / blobdiff